Calling an authentication server (zosConnect-2.0)

You can configure z/OS® Connect to retrieve an access token, such as a JSON Web Token (JWT), from a third-party authentication server to call a secured OpenAPI2 API.

zosConnect-2.0 Applies to zosConnect-2.0.

Figure 1 shows how an access token is obtained and used to call a secured API. In this illustration, the access token is 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 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 z/OS Connect Server. The user credentials include the username 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 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. The z/OS Connect Server can authenticate with the authentication server by using a basic authentication HTTP header, credentials in the request body, or by using two named HTTP headers where one contains the client ID and the other contains the client secret.
  3. The authentication server authenticates the user and returns a JWT to the z/OS Connect Server. You can configure 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 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 an access token

The request that z/OS Connect makes to an authentication server to retrieve an access token has the following format:
HTTP Method
Specify 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 that are supplied elsewhere can be substituted by 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 3.0.70.0 only ${userid} and ${password} might 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 3.0.69.0. In 3.0.69.0. and later releases, it is set to "application/json".
Response accept content types
In releases before 3.0.69.0, no HTTP Accept header is sent on the request. In 3.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 3.0.70, 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 by using the ${<parameter name>} syntax.
Table 1. Options for setting user credentials
zosconnect_authToken> tokenRequest >credentialLocation COBOL application variable

(For PL/I, see Note 1)

 zosconnect_authorizationServer-> basicAuthRef

(See Note 2)

 zosconnect_authToken >tokenRequest >requestBody zosconnect_authToken> tokenRequest >header
Body
BAQ-TOKEN-USERNAME

BAQ-TOKEN-PASSWORD
 Not applicable Must contain $(userid) and $(password), for value substitution. Not applicable
body Not applicable zosconnect_authData user and password attributes Must contain $(userid) and $(password), for value substitution. Not applicable
body Not applicable Not applicable Hardcoded userid and password values Not applicable
header
BAQ-TOKEN-USERNAME

BAQ-TOKEN-PASSWORD
 Not applicable Not applicable Header name(s) (See Note 3) Default: Authorization
header Not applicable zosconnect_authData user and password attributes Not applicable Header name(s) (See Note 3) Default: Authorization
Note:
  1. For PL/I, the variable names have underscore characters in place of the hyphen characters.
  2. Credentials set in server.xml override credentials set in the z/OS application.
  3. From 3.0.70.0, the header attribute can contain two header names, the first for the username, the second for the password. For more information, see zosConnect-2.0 Configuration elements in the Reference section.

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

To enable a z/OS application to call an API that is secured with an access token through z/OS Connect, perform the following actions:

Access token caching

The z/OS Connect Server, by default, caches access tokens that are of type JWT and JWS in the system cache, if they have an expclaim and no jti claim. For more information, see JWT Claims. Optionally, JWTs with a jti claim and an exp claim are stored in the system cache if attribute cacheTokensWithJti="true" is specified on the zosconnect_authToken element in the server.xml configuration file.

From 3.0.86.0, tokens that are opaque or of type JWT and JWE, are cached if a token lifetime is specified by using one of the following methods.
  • If the authentication server response contains a JSON body with a token lifetime, set the tokenLifetimePath attribute on the zosconnect_authToken>tokenResponse configuration element. For more information, see zosconnect_authToken > tokenResponse.
  • Set the tokenLifetime attribute on the zosconnect_authToken configuration element. For more information, see zosconnect_authToken.

If a token lifetime is specified by both methods, the value that is used for the lifetime is that returned in the authentication server response.

A token is reused when the token-related information for a request matches exactly that of the original request for which the token was obtained. Expired tokens are cleared from the system cache periodically. When a token is retrieved from the cache, if the token is expired or has less than a one-second lifetime left, a new token is obtained.

Although a token might be within the expiration period when it is retrieved from the system cache, it might have expired by the time it is received by the API endpoint. In this case, a 401 HTTP response code is returned to the z/OS Connect Server, which then retries the request by using a new token. If this request fails, the error is returned to the client application.

From 3.0.70.0, there is a new optional attribute, tokenRefreshRate on the zosconnect_authToken configuration element that specifies a period of time after which an attempt is made to obtain a new token even if there is a nonexpired cached token. For more information, see zosconnect_authToken.

The token cache can be cleared by using the MVS system MODIFY command. For more information, see The MODIFY command zosConnect-2.0.