Calling an API secured with a third-party JWT

You can configure IBM® z/OS® Connect to retrieve a JSON Web Token (JWT) from a third-party authorization server and pass it on a request to an API endpoint.

Figure 1 shows how a JWT is obtained and used to call an API that is secured with a JWT.

Figure 1. Illustration of how a JWT is retrieved and included in an API request
Diagram showing how a JWT is used by IBM z/OS Connect for the API request authentication.
  1. The Host API transfers an API request that contains user credentials from the z/OS application to the IBM z/OS Connect server. The user credentials include the user name and password that are required to authenticate with the authentication server to obtain a JWT. You can set the user credentials in the z/OS application or the server.xml file.
    Note: If user credentials are supplied by the z/OS application and are configured in server.xml file, the user credentials that are specified in the server.xml file are used.
  2. The IBM z/OS Connect server builds an HTTPS request for a JWT based on the configuration in server.xml and sends the request to the authentication server. Basic authentication is the only supported method for authenticating the IBM z/OS Connect connection to the authentication server. The user credentials are passed to the authentication server in the header or in the request body on the HTTPS request.
  3. The authentication server authenticates the user and returns a JWT to the IBM z/OS Connect server. You can configure IBM z/OS Connect to expect the JWT to be returned in a header or response body, depending on the authentication server you are using to provide a JWT.
  4. The IBM z/OS Connect server sends an HTTP (or HTTPS) request for the API to the request endpoint, passing the JWT in the HTTP header. By default, the HTTP Authorization header is used and the HTTP header value contains the Bearer scheme. To exclude the Bearer scheme, configure the attribute useBearerScheme="false" on the zosconnect_authToken element in the server.xml configuration file.
  5. The request endpoint returns an HTTP (or HTTPS) response.

Format of authentication server request for a JWT

The request that IBM z/OS Connect makes to an authentication server to retrieve a JWT has the following format:
HTTP Method
Specify GET/PUT/POST in the requestMethod attribute of the zosconnect_authToken > tokenRequest element in the server.xml file.
Request body
If required, specify the contents of the request body in the requestBody attribute of the zosconnect_authToken > tokenRequest element in the server.xml file. Values in the request body can be hardcoded or values that are supplied elsewhere can be substituted using the ${<parameter name>} syntax. Substitution values can be supplied in the z/OS application, or in the zosconnect_authData element referenced by the zosconnect_authorizationServer element.
Note: Before V3.0.70.0 only ${userid} and ${password} could be substituted and the request body was only sent to the authentication server if credentialLocation="body".
User credentials.
A userid (client ID) and password (client secret) can be supplied in the z/OS application or in the server.xml file and sent to the authentication server in a request body, in a single header, or in a pair of headers. For more information, see Table 1. If no user credentials are required on the request, specify a credential location of "body" and omit any credential parameters.
Request body content type
If there is a request body, the HTTP Content-type header is set to "application/json;charset=UTF-8”, in releases before V3.0.69.0, and set to "application/json" in V3.0.69.0 and later releases.
Response accepts content types
In releases before V3.0.69.0, no HTTP Accept header is sent on the request. In V3.0.69.0 and later releases, if the tokenLocation attribute on the zosconnect_authToken > tokenResponse element is set to body, an HTTP Accept header is sent on the request, the value of which is determined by the setting of the responseFormat attribute on the zosconnect_authToken > tokenResponse element. For example,
  • JSON: "application/json"
  • Text: "text/plain”
  • JWT: "application/jwt”
Custom request body parameters and custom headers
From V3.0.70.0, values for these parameters can be specified in the z/OS application by using the BAQR-TOKEN-CUSTOM-PARMS and BAQR-TOKEN-CUSTOM-HEADERS fields in the BAQ-REQ-PARM-NAME of BAQ-REQ-PARMS in the BAQHAREC copybook. For custom parameters, the request body must specify the substitution location using the ${<parameter name>} syntax.
Table 1. Options for setting user credentials
zosconnect_authToken> tokenRequest >credentialLocation COBOL application variable (see Note 1) (For PL/I, see Note 1) zosconnect_authorizationServer-> basicAuthRef (See Note 1) zosconnect_authToken >tokenRequest >requestBody zosconnect_authToken> tokenRequest >header
body
BAQR-TOKEN-USERNAME
BAQR-TOKEN-PASSWORD
 - Must contain $(userid) and $(password), for value substitution. -
body - zosconnect_authData user and password attributes Must contain $(userid) and $(password), for value substitution. -
body -   Hardcoded userid and password values -
header
BAQR-TOKEN-USERNAME
BAQR-TOKEN-PASSWORD
 - - Header name(s) (See Note 3) Default: Authorization
header - zosconnect_authData user and password attributes - Header name(s) (See Note 3) Default: Authorization
Note:
  1. Credentials set in server.xml override credentials set in the z/OS application.
  2. For PL/I, the variable names have underscore characters in place of the hyphen characters.
  3. From V3.0.70.0, the header attribute can contain two header names, the first for the username, the second for the password.
  4. For more information, see Configuration elements in the Reference section.

How to enable a z/OS application to call an API secured with a JWT

To enable a z/OS application to call an API that is secured with a JWT through IBM z/OS Connect, perform the following actions:
  • Configure the IBM z/OS Connect server to retrieve a JWT from the authentication server and access the API with the JWT in the server.xml file. For more information about configuring the IBM z/OS Connect server, see How to configure a third-party JWT.

  • Provide user credentials that are used to retrieve a JWT by including the user credentials in your z/OS application or specifying them in the server.xml file.

    For how to modify your z/OS application to include user credentials in the API request, see JSON Web Token (JWT) in Calling secured APIs.

    Important:
    • The method of including user credentials in your z/OS application is available for both cases where the user credentials are sent in a header or in the body of the request to the authentication server. If the user credentials are sent in an HTTP header, IBM z/OS Connect just passes the user credentials from the z/OS application in the header that is specified on the header attribute of the tokenRequest element in server.xml. If the user credentials are sent in a request body, you must ensure the JSON string that is specified for the requestBody attribute on the tokenRequest element uses the $ syntax. Then, IBM z/OS Connect replaces the user credentials into the JSON string and pass them in the request body. For more information about setting the value of the requestBody attribute in this case, see Configuration elements in the Reference section.
    • If both the z/OS application and the server.xml file are set up with user credentials for a JWT, the user credentials that are specified in the server.xml file are used.