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 authentication 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 communication stub 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. Alternatively, you can set the user credentials in the server.xml file.
  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 a 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 an 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
MethodSpecify GET/PUT/POST in 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 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.
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. See Table 1 for options for setting user credentials. 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 prior to V3.0.69.0, and set to "application/json" in V3.0.69.0 and later releases.
Response accept content types
In releases prior to 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
Values for these parameters can be specified in the z/OS application by using the BAQ-TOKEN-CUSTOM-PARMS-PTR and BAQ-TOKEN-CUSTOM-HEADERS-PTR fields in the BAQRINFO 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 applicationvariable (see Note 1)(For PL/I, see Note 1) zosconnect_authorizationServer-> basicAuthRef (See Note 1) zosconnect_authToken >tokenRequest >requestBody zosconnect_authToken> tokenRequest >header
body
BAQ-TOKEN-USERNAME
BAQ-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
BAQ-TOKEN-USERNAME
BAQ-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.69.0, the header attribute can contain two header names, the first for the userid, 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 and Configuration elements in the Reference section.
  • 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 JWT parameters. For how to specify user credentials in the server.xml file, see How to provide user credentials to the authentication server in server.xml.
  • Provide any custom parameters and headers in your z/OS application. Custom parameters are substituted in the request body when the $ syntax is used.