zosconnect_authToken access token related parameters

When you develop a CICS®, IMS, or z/OS® application to call an API that is protected by an access token obtained from an authentication server that is not OAuth 2.0 compliant, you can include parameters required to obtain the access token in your application that supplement the zosconnect_authToken configuration in server.xml.

IBM® z/OS Connect supplies a sample COBOL program that is called BAQJWT in the hlq.SBAQSAMP data set. This sample demonstrates how to call an API that requires a JSON Web Token (JWT) for authentication, by using IBM z/OS Connect

This information is applicable when obtaining an access token from an authentication server that is not OAuth 2.0 compliant, as described in Calling an authentication server.

Access token parameters set in the application

IBM z/OS Connect provides a data structure to specify the access token parameters in the request. Two versions of the data structure are provided, a COBOL version that is called BAQRINFO in hlq.SBAQCOB and a PL/I version that is called BAQRINFP in hlq.SBAQPLI.

Ensure that the communication stub request data structure is set with a compatibility level dependent upon the parameters that are to be included. For more information about compatibility levels, see Table 2 in Developing z/OS applications to call APIs. The compatibility level value is defined for COBOL by the BAQ-REQUEST-INFO-COMP-LEVEL variable or for PL/I by the BAQ_REQUEST_INFO_COMP_LEVEL variable.

The following table shows the parameters that are defined for access token configuration when using the zosconnect_authToken configuration element in server.xml. For COBOL, these parameters are defined in BAQ-REQUEST-INFO; for PL/I, these parameters are defined in BAQ_REQUEST_INFO. You can specify values for the parameters as required.
Table 1. Access token parameters
Variables for COBOL Variables for PL/I Description
BAQ-TOKEN-USERNAME BAQ_TOKEN_USERNAME The user name that is used for the authentication server to authenticate the user. The value is substituted for the string "${userid}" in the request body, see Note 1.
BAQ-TOKEN-USERNAME-LEN BAQ_TOKEN_USERNAME_LEN The length of the user name. The maximum value is 256.
BAQ-TOKEN-PASSWORD BAQ_TOKEN_PASSWORD The password that is used for the authentication server to authenticate the user. The value is substituted for the string "${password}" in the request body, see Note 1.
BAQ-TOKEN-PASSWORD-LEN BAQ_TOKEN_PASSWORD_LEN The length of the password. The maximum value is 256.
BAQ-TOKEN-CUSTOM-PARMS-PTR BAQ_TOKEN_CUSTOM_PARMS_PTR
From V3.0.70.0, a pointer to the storage for an application declared custom parameters variable. Specify the custom parameters in the following format:
<parm1>=<value1>[,<parmn>=<valuen>]

Where <parm1> is the name of the first custom parameter and <value1> is the value of the first custom parameter. See Note 2. Each custom value is substituted for the corresponding string "${<parmn>}" in the request body, see Note 1.
BAQ-TOKEN-CUSTOM-PARMS-LEN BAQ_TOKEN_CUSTOM_PARMS_LEN From V3.0.70.0, the size of the storage for the custom parameters variable.
BAQ-TOKEN-CUSTOM-HEADERS-PTR BAQ_TOKEN_CUSTOM_HEADERS_PTR

From V3.0.70.0, a pointer to the storage for an application declared custom headers variable. Specify the custom headers in the following format:

<header1>:<value1>[,<headern>:<valuen>]

Where <header1> is the name of the first custom header and <value1> is the value of the first custom header. See Note 3.
BAQ-TOKEN-CUSTOM-HEADERS-LEN BAQ_TOKEN_CUSTOM_HEADERS_LEN From V3.0.70.0, the size of the storage for the custom headers variable.
Note:
  1. The request body is specified in the requestBody attribute of the zosconnect_authToken > tokenRequest element in server.xml. For more information, see zosconnect_authToken > tokenRequest.
  2. When specifying custom parameter names and values be aware of the following restrictions:
    • Custom parameter names and all custom parameter values are case-sensitive.
    • When specifying a custom parameter that has multiple values, if the values are comma-separated, then these commas must be escaped with a backslash. For example: custom1=valueA\,valueB,custom2=value
    • Do not specify custom parameters with names "userid" or "password". Use the BAQ-TOKEN-USERNAME and BAQ-TOKEN-PASSWORD variables for these values.
    • If duplicate custom parameters are specified, only one instance is used in the request to the authentication server.
  3. Do not specify a custom header with the name "Authorization" or any name that is specified in the header attribute of the zosconnect_authToken element.

Example: Developing a COBOL application to call an API secured with a JWT

The following example demonstrates how to develop a COBOL application to call an API that is secured with a JWT.

In this example, the names of the generated artifacts are as follows:
  • The request copybook: API00Q01
  • The response copybook: API00P01
  • The API information file: API00I01
The following information for JWT is included:
  • User name: jwtuser
  • Password: jwtpassword
Include the BAQRINFO data structure
COPY BAQRINFO
Include copybooks

01 REQUEST.
      COPY API00Q01.
01 RESPONSE.
      COPY API00P01.
01 API-INFO.
      COPY API00I01.
Declare variables for the request and response

01 BAQ-REQUEST-PTR             USAGE POINTER.
01 BAQ-REQUEST-LEN             PIC S9(9) COMP-5 SYNC.
01 BAQ-RESPONSE-PTR            USAGE POINTER.
01 BAQ-RESPONSE-LEN            PIC S9(9) COMP-5 SYNC.
77 COMM-STUB-PGM-NAME          PIC X(8) VALUE 'BAQCSTUB'.
Populate values for the request

MOVE 'How are you' TO Xtext.

MOVE "jwtuser" TO BAQ-TOKEN-USERNAME.
MOVE 7 TO BAQ-TOKEN-USERNAME-LEN.
MOVE "jwtpassword" TO BAQ-TOKEN-PASSWORD.           
MOVE 11 TO BAQ-TOKEN-PASSWORD-LEN.
Prepare the data for call

SET BAQ-REQUEST-PTR TO ADDRESS OF REQUEST.           
MOVE LENGTH OF REQUEST TO BAQ-REQUEST-LEN.           
SET BAQ-RESPONSE-PTR TO ADDRESS OF RESPONSE.           
MOVE LENGTH OF RESPONSE TO BAQ-RESPONSE-LEN.
Call the communication stub

CALL COMM-STUB-PGM-NAME USING 
      BY REFERENCE API-INFO
      BY REFERENCE BAQ-REQUEST-INFO
      BY REFERENCE BAQ-REQUEST-PTR
      BY REFERENCE BAQ-REQUEST-LEN
      BY REFERENCE BAQ-RESPONSE-INFO    
      BY REFERENCE BAQ-RESPONSE-PTR
      BY REFERENCE BAQ-RESPONSE-LEN.