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.

IBM® z/OS® Connect provides three ways of calling an API secured with a JWT:
  • 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.
Note: Only JWS type tokens are supported, not tokens of type JWE.

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 JWT 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.

The token cache can be cleared using the MVS system MODIFY command, for more details see The MODIFY command.
Note: If you are using locally generated JWTs and the attribute values of the jwtBuilder or zosconnect_authTokenLocal server.xml configuration file elements are changed, then the token cache should be cleared.