Calling an API secured with a JSON Web Token (JWT)
JSON Web Token (JWT) is an open standard that defines a compact and URL-safe way to securely transmit information as a JSON object between parties. A JWT is often used to secure RESTful APIs because it can be used to authenticate a client that wants to access the APIs.
- Use the OAuth 2.0 support when the request is part of an OAuth 2.0 flow.
If a JWT is returned as an access token from an authentication server, the access token is sent in an API request by IBM z/OS Connect in the HTTP authorization header. See Calling an API secured with OAuth 2.0.
- When you need to send a JWT that is obtained from an authentication server in a custom flow,
use the JWT support described in Calling an API secured with a third-party JWT. For example:
- When you need to specify the HTTP verb that is used in the request to the authentication server.
- When you need to specify how the JWT is returned from the authentication server (for example, in an HTTP header or in a custom field in a JSON response message).
- When you need to use a custom header name for sending the JWT to the request endpoint.
Use the locally generated JWT support when you need to send a JWT that is generated by the IBM z/OS Connect server. The generated JWT contains the
z/OS application asserted user ID in the
"sub" (Subject)claim. The z/OS application asserted user ID is passed to the IBM z/OS Connect server by the communication stub. For more information, see Calling an API secured with a locally generated JWT.
JSON Web Token (JWT) caching
The IBM z/OS Connect server stores JWTs in the
system cache, if they have an
exp claim and no
jti claim. For more information, see
Claims. Optionally, JWTs with a
jti claim and an
exp claim are stored in the
system cache if attribute
cacheTokensWithJti="true" is specified on the
zosconnect_authToken element in the server.xml configuration
file. A JWT is reused when the JWT-related information for a request matches exactly that of the
original request for which the token was obtained. Expired access tokens are cleared from the system
cache periodically. When a JWT is retrieved from the cache, the expiration time is checked, and if
the JWT has expired, a new token is obtained.
Although a JWT might be within the expiration period when it is retrieved from the system cache, it might have expired by the time it is received by the API endpoint. In this case, a 401 HTTP response code is returned to the IBM z/OS Connect server, which then retries the request using a new JWT. If this request fails, the error is returned to the client application.
zosconnect_authTokenLocalserver.xml configuration file elements are changed, then the token cache should be cleared.