How to configure OAuth 2.0 with JWT authentication

When a z/OS® application calls a REST API that is protected by OAuth 2.0 on an API endpoint, the z/OS Connect server must be configured to obtain the OAuth 2.0 access token from an authorization server. This can be done using authentication with a JWT generated by z/OS Connect.

Before you begin

  • You should be familiar with the information in Calling an API secured with OAuth 2.0.
  • You must know which grant type you want to use.
  • You must know what claims are required in the JWT to be generated for authentication and how the JWT is to be signed.
  • You must know the information to be provided by the z/OS application, and which information is to be provided in server.xml.
  • You must have write access to the server.xml configuration file.

About this task

You configure the z/OS Connect server to generate a JWT with the "sub" (Subject) claim set to the OAuth 2.0 client ID that is configured in server.xml. Any client ID set by the z/OS application is not used.

To configure the generation of a JWT for authentication, you must update the server.xml configuration file to:
  • Configure a jwtBuilder and a zosconnect_oAuthTokenConfig element to define the parameters that are used to generate a JWT, these include the client ID.
  • Configure a zosconnnect_oAuthConfig element to reference the zosconnect_oAuthTokenConfig element.
  • Optionally, configure the client ID is to be set in the body of the request sent to the authorization server, as well as in the "sub" claim of the JWT. By default it is not set.


  1. Configure a jwtBuilder element to specify the required registered claims and specify how the JWT is to be signed.
    For example,
        jwkEnabled="true" />

    By default the "iss" (Issuer) claim is set to https://<host_name>:<ssl_port>/jwt/<jwtBuilderId> where host_name and ssl_port are the hostname and HTTPS port of the IBM® z/OS Connect server and jwtBuilderId is the id attribute value of the jwtBuilder element. To specify an alternative value for the "iss" (Issuer) claim, configure the issuer attribute of the jwtBuilder element. For more information about how to configure the jwtBuilder element, see JWT Builder (jwtBuilder) in the WebSphere Application Server for z/OS Liberty documentation.

    In this example, the JWT builder is configured to sign the JWT token with a JSON Web Key (JWK) by setting the jwkEnabled attribute to "true". This is only applicable when the JWT is signed using the RS256 algorithm. For more information, see Signing JWTs. If your OAuth 2.0 authorization server does not support JWK, then replace the jwkEnabled attribute with a keyStoreRef and keyAlias attributes to specify the certificate to be used to sign the JWT.

    • The claims attribute on the jwtBuilder allows only existing user attributes that are defined for the subject of this JWT in the user registry to be included as claims in the JWT. To specify public and private claim name value pairs, use the claims subelement on the zosconnect_oAuthTokenConfig element as shown in Step 2.
    • The value for the registered claim "iat" (Issued At) is automatically set when the JWT is generated locally by the IBM z/OS Connect server.
  2. Configure the zosconnect_oAuthTokenConfig element to specify the client ID, any public or private claims required in the JWT, and reference the relevant jwtBuilder element.
    For example,
    <zosconnect_oAuthTokenConfig id="myJWTAuthConfig"  
    • The tokenGeneratorRef attribute references the jwtBuilder element with the ID value myJWTAuthBuilder that is defined in Step 1.
    • The tokenSubject attribute specifies the client ID to be set in the "sub" claim of the JWT.
    • The claims subelement specifies the public and private claims as a JSON string.

    For more information about the zosconnect_oAuthTokenConfig element, see zosconnect_oAuthTokenConfig in the configuration elements section.

    • The claims subelement is intended to specify only public and private claims. If registered claims, such as "aud" (Audience), are specified on the claims subelement, then these values overwrite the corresponding values that are configured on the jwtBuilder element that is referenced by the tokenGeneratorRef attribute of the zosconnect_oAuthTokenConfig element. If the "sub" claim is specified on the claims subelement, its value is overwritten by the IBM z/OS Connect server with the client ID specified in the tokenSubject attribute. Registered claims are defined in the IANA JSON Web Token Claims Registry.
    • If the JSON string value of the claims subelement contains XML markup characters, such as <, > and &, then include the JSON string inside a CDATA section. For more information, see zosconnect_oAuthTokenConfig.
  3. Define a zosconnect_authorizationServer element.
    For example,
    <zosconnect_authorizationServer id="myAuthServer" 
       sslCertsRef="defaultSSLConfig" />
    • The tokenEndpoint attribute specifies the URL and port of the authorization server. This example uses a TLS connection to the authorization server.
    • The sslCertsRef attribute references the TLS configuration for the authorization server connection. If sslCertsRef is omitted, the default SSL configuration for the IBM z/OS Connect server is used. The default is an SSL element with the ID "defaultSSLConfig", or an sslDefault element that specifies the SSL element to be used as the default.
  4. Define a zosconnect_oAuthConfig element.
    For example,
    <zosconnect_oAuthConfig id="myoAuthConfig"
    • If you are using the resource owner credentials grant type, set the grantType attribute to "password".
    • The jwtAuthenticationTokenRef attribute references the zosconnect_oAuthTokenConfig element with the ID value myJWTAuthConfig that is defined in Step 2.
    • The jwtAuthenticationSetClientId attribute indicates that the client ID is also to be included separately in the body of the request to obtain an access token.
    • The authServerRef attribute references the zosconnect_authorizationServer with ID value myAuthServer defined in Step 3.
  5. Configure the zosconnect_endpointConnection element.
    For example,
    <zosconnect_endpointConnection id="conn"
        authenticationConfigRef="myOAuthConfig" />
    • The authenticationConfigRef attribute references the zosconnect_oAuthConfig element with the ID value myoAuthConfig that was defined in Step 4.


In this task, you configured IBM z/OS Connect to request an OAuth 2.0 access token from an authorization server using JWT authentication. Ensure that the z/OS application program sets any additional parameters that are required by the authorization server.