Generating a JWT within IBM z/OS Connect

You can configure z/OS® Connect to generate a JSON Web Token (JWT) and pass it on a request to an API endpoint. The generated JWT contains a subject claim that is the z/OS application asserted user ID passed from the communication stub.

zosConnect-2.0 Applies to zosConnect-2.0.

Before you begin, ensure that you are familiar with the JWT and JWT claim specifications as defined in the Opens in a new tab or window: JSON Web Token (JWT) IETF documentation.

The ability to create a locally generated JWT requires SAF authorization to be configured in the z/OS Connect server. For more information about SAF authorization, see API requester authorization.

The z/OS Connect server can generate a JWT with the "sub" (Subject) claim set to the z/OS application asserted user ID, and send that JWT in the specified HTTP header on the request to the RESTful API.

The user ID asserted by the z/OS application depends on the application type:

For CICS® applications, it is the task owner ID.
For IMS applications, it is the transaction owner ID.
For other z/OS applications, it is the job owner ID.

The z/OS Connect server generates JWTs using the JSON Web Signature (JWS) serialization, as described in Opens in a new tab or window: JSON Web Signature (JWS) IETF documentation.

Figure 1 shows the data flow when a z/OS application calls an API with a locally generated JWT that contains the z/OS application asserted user ID as the "sub" claim.

Diagram showing how a local JWT is generated with an ID that is passed from the communication stub, and how the JWT is used by z/OS Connect for the API request authentication. — Figure 1. Illustration of how a local JWT is generated and included in an API request

The communication stub extracts the z/OS application asserted user ID from the z/OS application environment.
Typically, the z/OS subsystem that calls the z/OS Connect server is authenticated by using basic authentication or client authentication. The authenticated link user ID requires authorization to connect to the z/OS Connect server. Either the authenticated link user ID, or the z/OS application asserted user ID, requires authorization to the API requester, depending on whether identity assertion is configured.
The z/OS Connect server performs a SAF SURROGAT profile check to ensure that the authenticated link user ID associated with the API requester request is allowed to generate a JWT on behalf of the z/OS application asserted user ID. If there is no authenticated link user ID, then the check is performed against the SAF unauthenticated user ID. For more information, see SAF unauthenticated user ID. If the surrogate check is successful, then the z/OS Connect server generates a JWT based on the parameters that are configured in server.xml, and sets the z/OS application asserted user ID as the "sub" (Subject) claim of the JWT. The parameters include the registered claims, for example, the "aud" (Audience) claim, that is specified on the jwtBuilder element, and the public and private claims that are specified on the zosconnect_authTokenLocal element. For more information about how to configure the two elements, see How to configure a locally generated JWT.
The z/OS Connect server sends the request to the RESTful API, passing the JWT in an HTTP header. By default, the HTTP Authorization header is used. The HTTP header includes the "Bearer" scheme keyword followed by the JWT.

Note: It is recommended that the SAF unauthenticated user ID is authorized to use only the minimum number of SAF resources.

The locally generated JWT support is independent of API requester identity assertion. However, they can be configured to work together if you also want to invoke an API requester with the z/OS application asserted user ID before generating the JWT. In both scenarios, the same z/OS application asserted user ID and same link user ID are used, but the names of the SURROGAT profiles are different (BAQTOKEN and BAQASSRT). For more information about API requester identity assertion, see Identity assertion for API requesters.

JSON Web Token (JWT) caching

The z/OS Connect server stores JWTs in the system cache, if they have an exp claim and no jti claim. For more information, see Opens in a new tab or window: JWT Claims. 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, if the JWT is expired or has less than a one-second lifetime left, 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 z/OS Connect server, which then retries the request by using a new JWT. If this request fails, the error is returned to the client application.

The token cache can be cleared by using the MVS system MODIFY command. For more information, see The MODIFY command zosConnect-2.0.

Note: If the attribute values of the jwtBuilder or zosconnect_authTokenLocal server.xml configuration file elements are changed, then the token cache should be cleared.