How to configure a third-party JWT

Follow these instructions to configure an API requester to use the IBM® z/OS® Connect JWT support if your authentication server does not comply with the OAuth 2.0 specification.

Alternatively, to configure an API requester with the OAuth 2.0 support when the request is part of an OAuth 2.0 flow, see Calling an API secured with OAuth 2.0. If you do not know which support you need to use, see Calling an API secured with a JSON Web Token (JWT).

The credentials that the IBM z/OS Connect server needs to authenticate with the JWT authentication server can be specified in either the z/OS application or in the server.xml configuration file. If specified in both, then the values in the server.xml file take precedence.

Figure 1 shows how to configure the JWT authentication information for an endpoint connection, where the credentials to authenticate with the authentication server are specified in the server.xml configuration file.

Figure 1. Configure the JWT authentication information for the endpoint with authentication server credentials in server.xml.


<zosconnect_endpointConnection id="conn"       
        host="https://api.server.com"
        port="8000"
        authenticationConfigRef="myJWTConfig"/>
<zosconnect_authToken id="myJWTConfig" authServerRef="myJWTserver" 
        header="myJWT-header-name" >
        <!--Configure the tokenRequest element by referring to Example 1 and Example 2 -->
        <tokenRequest />
        <!--Configure the tokenResponse element by referring to Example 3 and Example 4 --> 
        <tokenResponse />
</zosconnect_authToken>
<zosconnect_authorizationServer id="myJWTserver" 
        tokenEndpoint="https://jwt.server.com:9443/JWTTokenGenerator/getJwtToken" 
        basicAuthRef="tokenCredential"
        sslCertsRef="defaultSSLConfig" />
<zosconnect_authData id="tokenCredential"
      user="jwtuser"
      password="jwtpassword"/>

Figure 1 shows that the API being called is secured on a request endpoint (https://api.server.com:8000) by using JWT. To enable the IBM z/OS Connect server to request a JWT from the authentication server (https://jwt.server.com:9443), the authenticationConfigRef attribute on the zosconnect_endpointConnection element is associated with the zosconnect_authToken element. The credentials used to authenticate with the authentication server are specified in the user and password attributes of the zosconnect_authData element, which is referenced by the basicAuthRef attribute of the zosconnect_authorizationServer element.

Figure 2 shows how to configure the JWT authentication information for an endpoint connection, when the credentials to authenticate with the authentication server are specified in the z/OS application.

Figure 2. Configure the JWT authentication information for the endpoint with authentication server credentials in z/OS application.


<zosconnect_endpointConnection id="conn"       
        host="https://api.server.com"
        port="8000"
        authenticationConfigRef="myJWTConfig"/>
<zosconnect_authToken id="myJWTConfig" authServerRef="myJWTserver" 
        header="myJWT-header-name" >
        <!--Configure the tokenRequest element by referring to Example 1 and Example 2 -->
        <tokenRequest />
        <!--Configure the tokenResponse element by referring to Example 3 and Example 4 --> 
        <tokenResponse />
</zosconnect_authToken>
<zosconnect_authorizationServer id="myJWTserver" 
        tokenEndpoint="https://jwt.server.com:9443/JWTTokenGenerator/getJwtToken" 
        sslCertsRef="defaultSSLConfig" />

Figure 2 shows that the API being called is secured on a request endpoint (https://api.server.com:8000) by using JWT. To enable the IBM z/OS Connect server to request a JWT from the authentication server (https://jwt.server.com:9443), the authenticationConfigRef attribute on the zosconnect_endpointConnection element is associated with the zosconnect_authToken element. The credentials to authenticate with the authentication server, for example BAQR-JWT-USERNAME and BAQR-JWT-PASSWORD and their associated length fields, are specified in the z/OS application, so are not referenced in the server.xml configuration file.

How to use zosconnect_authToken

The zosconnect_authToken element defines the following JWT configuration information by using the following attributes and subelements:

Use the header attribute to specify the name of the header that contains the JWT that is sent on the request to the API endpoint. If you do not specify the header attribute, the HTTP Authorization header is used by default.
Use the authServerRef attribute to specify the authentication server. This attribute is associated with the zosconnect_authorizationServer element.
Use the useBearerScheme attribute to specify whether the value of the HTTP header that contains the JWT sent on the request to the API endpoint contains the Bearer scheme. If you do not specify the useBearerScheme attribute, the Bearer scheme is included by default.
Use the tokenRequest element to specify the format of the request to the authentication server for a JWT.
Use the tokenResponse element to specify the format of the response from the authentication server.

The following examples show how to configure the tokenRequest and tokenResponse elements based on different requirements:

Example 1: User credentials are sent in a specified header
Example 2: User credentials are sent in the request body
Example 3: The JWT is returned in the specified header
Example 4: The JWT is returned in the response body

Example 1: User credentials are sent in a specified header


<tokenRequest
      credentialLocation="header" 
      header="Authorization" 
      requestMethod="GET" />

When user credentials are sent in a header on the request for a JWT, you must set the credentialLocation attribute to header and specify a header name for the header attribute. If you don't specify the header attribute, the HTTP Authorization header is used by default. From V3.0.69.0, the username and password can be sent to the authentication server in separate headers. For more information, see zosconnect_authToken.

Example 2: User credentials are sent in the request body


<tokenRequest
      credentialLocation="body" 
      requestMethod="POST"
      // Use XML escaped characters in requestBody
      requestBody="{&quot;apiuser&quot;:&quot;${userid}&quot;,&quot;apipassword&quot;:&quot;${password}&quot;}" />

When user credentials are sent in the body of the request for a JWT, you must set the credentialLocation attribute to body, and set the requestBody attribute to a JSON string with characters such as ", <, > and & replaced by using the XML escape characters. For more information, see: XML escape characters in the WebSphere® Application Server Liberty documentation.

The requestBody attribute value has two formats: one directly contains the user credentials; the other one uses the $ syntax as the example shows. For more information about how to set this attribute, see requestBody.

Note: The requestMethod attribute must be set when user credentials are sent in a header or in the body of the request for a JWT. The acceptable values are GET, PUT, or POST.

Example 3: The JWT is returned in the header


<tokenResponse
      tokenLocation="header"
      header="JWTAuthorization" />

When the JWT is returned in the header on the response from the authentication server, you must set the tokenLocation attribute to header and specify a header name for the header attribute. If you don't specify the header attribute, the HTTP Authorization header is used by default.

Example 4: The JWT is returned in the response body


<tokenResponse
      tokenLocation="body"
      responseFormat="JSON"
      tokenPath="$.tokenname" />

When the JWT is returned in the response body from the authentication server, you must set the tokenLocation attribute to body and set the responseFormat attribute.

The responseFormat attribute can be set to Text, JSON, or from V3.0.69.0, JWT. If the responseFormat attribute is set to Text or JWT, IBM z/OS Connect considers the response body to be the JWT. If the responseFormat attribute is set to JSON, you must specify a JSONPath expression for the tokenPath attribute so that IBM z/OS Connect can locate and get the JWT from the returned JSON string. For more information about how to set the tokenPath attribute, see tokenPath.

For more information about the attributes and subelements of the zosconnect_authToken element, see zosconnect_authToken in Configuration elements.

How to provide user credentials to the authentication server in server.xml

The user credentials include the username and password that are used for basic authentication between the IBM z/OS Connect server and the authentication server. You can provide the user credentials in the server.xml file in the following two ways:

Specify the user credentials in the zosconnect_authData element and associate the element with the basicAuthRef attribute on the zosconnect_authorizationServer element. This method can be used to send the user credentials to the authentication server as an HTTP header or in the request body.
Note: If the user credentials are sent in the request body, you must also set the requestBody attribute to a JSON string that uses the $ syntax as shown in Example 2. Thus, the user credentials that are specified on the zosconnect_authData element can be replaced into the JSON string and passed in the request body to the authentication server.
Include user credentials explicitly in the JSON string that is specified for the requestBody attribute on the tokenRequest element. Only use this method when the user credentials are sent in the request body.