OAuth 2.0 parameters

When you develop a CICS, IMS or z/OS® application to call an API that is protected by OAuth 2.0, you can include parameters required by the authorization server, in the request.

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 OAuth 2.0 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 API secured with OAuth 2.0.

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 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 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 OAuth 2.0. 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. Variables defined for OAuth 2.0
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 owner's 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 owner's 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 example below. 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.