JWT parameters

When you develop a CICS, IMS or z/OS® application to call an API that is secured with a JSON Web Token (JWT), you can include the information for the JWT parameters in the request.

IBM® z/OS Connect supplies a sample COBOL program called BAQJWT in the hlq.SBAQSAMP data set. The sample demonstrates how to call an API that are protected by JWT using IBM z/OS Connect .

This information is applicable when using the IBM z/OS Connect API requester JWT support as described in Calling an API secured with a JSON Web Token (JWT).

Parameters for JWT in the request

IBM z/OS Connect provides a data structure to specify the JWT parameters in the request. Two versions of the data structure are provided, a COBOL version called BAQRINFO in hlq.SBAQCOB and a PL/I version 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 JWT. 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. Parameters defined for JWT
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.69.0, 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 "${<custom name>}" in the request body, see Note 1.
BAQ-TOKEN-CUSTOM-PARMS-LEN BAQ_TOKEN_CUSTOM_PARMS_LEN From V3.0.69.0, size of the storage for the custom parameters variable.
BAQ-TOKEN-CUSTOM-HEADERS-PTR BAQ_TOKEN_CUSTOM_HEADERS_PTR

From V3.0.69.0, 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.69.0, 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.
    • 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.