zosconnect_oAuthConfig 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 that is obtained from an OAuth 2.0 compliant authorization server, you can include parameters that are required to obtain the access token in your application that supplement the zosconnect_oAuthConfig configuration in server.xml.

IBM® z/OS Connect supplies sample programs in the hlq.SBAQSAMP data set. These samples demonstrate how to call an API that is protected by an OAuth 2.0 access token by using IBM z/OS Connect. For COBOL, the sample program is BAQAUTHO; for PL/I, the sample program is BAQAUTHP.

For information on which parameters are required for the different grant types and where they can be set, see Calling an OAuth 2.0 authorization server.

OAuth 2.0 parameters set in the application

IBM z/OS Connect provides a data structure to specify parameters in the application. 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 details of the compatibility levels see Table 2 of 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_oAuthConfig 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. For information on using these parameters, see the notes below.

Table 1. OAuth 2.0 access token parameters
Variables for COBOL Variables for PL/I Description
BAQ-OAUTH-USERNAME BAQ_OAUTH_USERNAME Username value used for the authorization server to validate the resource owners credentials.
BAQ-OAUTH-USERNAME-LEN BAQ_OAUTH_USERNAME_LEN Length of username. The maximum value is 256.
BAQ-OAUTH-PASSWORD BAQ_OAUTH_PASSWORD Password used for the authorization server to validate the resource owners credentials.
BAQ-OAUTH-PASSWORD-LEN BAQ_OAUTH_PASSWORD_LEN Length of password. The maximum value is 256.
BAQ-OAUTH-CLIENTID BAQ_OAUTH_CLIENTID Client ID value used for the authorization server to authenticate the client.
BAQ-OAUTH-CLIENTID-LEN BAQ_OAUTH_CLIENTID_LEN Length of client ID. The maximum value is 256.
BAQ-OAUTH-CLIENT-SECRET BAQ_OAUTH_CLIENT_SECRET Client secret value used for the authorization server to authenticate the client.
BAQ-OAUTH-CLIENT-SECRET-LEN BAQ_OAUTH_CLIENT_SECRET_LEN Length of client secret. The maximum value is 256.
BAQ-OAUTH-SCOPE-PTR BAQ_OAUTH_SCOPE_PTR Pointer to the storage for an application declared scope variable. The scope limits the degree of access to OAuth 2.0 protected resources.
BAQ-OAUTH-SCOPE-LEN BAQ_OAUTH_SCOPE_LEN Size of the storage for the scope variable.
BAQ-OAUTH-RESOURCE-PTR BAQ_OAUTH_RESOURCE_PTR Pointer to the storage for an application declared resource variable.
BAQ-OAUTH-RESOURCE-LEN BAQ_OAUTH_RESOURCE_LEN Size of the storage for the resource variable.
BAQ-OAUTH-AUDIENCE-PTR BAQ_OAUTH_AUDIENCE_PTR Pointer to the storage for an application declared audience variable.
BAQ-OAUTH-AUDIENCE-LEN BAQ_OAUTH_AUDIENCE_LEN Size of the storage for the audience variable.
BAQ-OAUTH-CUSTOM-PARMS-PTR BAQ_OAUTH_CUSTOM_PARMS_PTR Pointer to the storage for an application declared custom parameters variable. Specify the custom parameters in the 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.
BAQ-OAUTH-CUSTOM-PARMS-LEN BAQ_OAUTH_CUSTOM_PARMS_LEN Size of the storage for the custom parameters variable.
Note:
  1. Custom parameter names and all parameter values are case-sensitive.
  2. 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=valueC
  3. The parameters audience, client_assertion, client_assertion_type, client_id, client_secret, grant_type, password, resource, scope, and username can not be specified in the custom parameters variable, use the relevant specific variables for these parameters.
  4. If duplicate custom parameters are specified, only one instance is used in the request to the authorization server.

For more information on specifying these parameters, see the following example. For information on which parameters can alternatively be set in server.xml, see Calling secured RESTful APIs.

Developing a COBOL application to call an API protected by OAuth 2.0

The following example demonstrates how to develop a COBOL application to call an API that is protected by OAuth 2.0.

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 information for OAuth 2.0 that needs to be included is as follows:
  • Resource owner's user name: oauthuser1
  • Resource owner's password: oauthpassword1
  • Client ID: clientid1
  • Client secret: clientsecret1
  • Scope: /getAccount
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-OAUTH-SCOPE             PIC X(255).
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 "oauthuser1" TO BAQ-OAUTH-USERNAME.
MOVE 10 TO BAQ-OAUTH-USERNAME-LEN.
                      
MOVE "oauthpassword1" TO BAQ-OAUTH-PASSWORD.           
MOVE 14 TO BAQ-OAUTH-PASSWORD-LEN.                      

MOVE "clientid1" TO BAQ-OAUTH-CLIENTID.           
MOVE 9 TO BAQ-OAUTH-CLIENTID-LEN.                        

MOVE "clientsecret1" TO BAQ-OAUTH-CLIENT-SECRET.            
MOVE 13 TO BAQ-OAUTH-CLIENT-SECRET-LEN.                 

MOVE "/getAccount" TO BAQ-OAUTH-SCOPE.           
SET BAQ-OAUTH-SCOPE-PTR TO ADDRESS OF BAQ-OAUTH-SCOPE.           
MOVE 11 TO BAQ-OAUTH-SCOPE-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.