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.

1. Configure a jwtBuilder element to specify the required registered claims and specify how the JWT is to be signed.
   For example,

   
   <jwtBuilder
       id="myJWTAuthBuilder"
       scope="scope1"
       audiences="myApp1"
       signatureAlgorithm="RS256"
       expiresInSeconds="30m"
       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.

   Note:

   • 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"  
       tokenGeneratorRef="myJWTAuthBuilder"
       tokenSubject="oauth20_cc_client_2345"
       <claims>{"branch":"Eastern",
                "dept":"insurance"}</claims>
   </zosconnect_oAuthTokenConfig>

   Where:

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

   Note:

   • 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" 
      tokenEndpoint="https://authorization.server.com:8001" 
      sslCertsRef="defaultSSLConfig" />

   Where:

   • 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"
         grantType="client_credentials"
         jwtAuthenticationTokenRef="myJWTAuthConfig"
         jwtAuthenticationSetClientId="true"
         authServerRef="myAuthServer"/>

   Where:

   • 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"
       host="https://api.server.com" 
       port="9443"
       authenticationConfigRef="myOAuthConfig" />

   Where:

   • The authenticationConfigRef attribute references the zosconnect_oAuthConfig element with the ID value myoAuthConfig that was defined in Step 4.