OAuth 2.0 parameters

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

For information about 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. A data structure is provided for COBOL, called BAQ-REQUEST-AREA structure in a BAQHAREC copybook in hlq.SBAQCOB.

The following table shows the values that can be set in the BAQ-REQ-PARM-NAME variable for an instance of BAQ-REQ-PARMS to pass OAuth 2.0 values to the IBM z/OS Connect server.

Table 1. BAQ-REQ-PARM-NAME values for OAuth 2.0 parameters.
BAQ-REQ-PARM-NAME Description Description

BAQR-OAUTH-CLIENT-ID

 Client ID value used for the authorization server to authenticate the client.
BAQR-OAUTH-CLIENT-SECRET Client secret value used for the authorization server to authenticate the client.
BAQR-OAUTH-USERNAME Username value used for the authorization server to validate the resource owner's credentials.
BAQR-OAUTH-PASSWORD Password used for the authorization server to validate the resource owner's credentials.
BAQR-OAUTH-AUDIENCE An application declared audience value.
BAQR-OAUTH-RESOURCE An application declared resource value.
BAQR-OAUTH-SCOPE An application declared scope value.
BAQR-OAUTH-CUSTOM-PARMS Application-declared custom parameter values.
Note:
  1. Custom parameter names and all parameter values are case-sensitive.
  2. 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.
  3. When you specify a custom parameter that has multiple values and the values are comma-separated, then these commas must be escaped with a backslash. For example, custom1=valueA\,valueB,custom2=valueC.
  4. The parameters audience, client_assertion, client_assertion_type, client_id, client_secret, grant_type, password, resource, scope, and username cannot be specified in the custom parameters variable, use the relevant specific variables for these parameters.
  5. If duplicate custom parameters are specified, only one instance is used in the request to the authorization server.

For more information about specifying these parameters, see the following example. For information about which parameters can alternatively be set in server.xml, see Calling an API secured with OAuth 2.0.

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

Before the BAQEXEC call makes a request to a IBM z/OS Connect server, define OAuth 2.0 request parameters in the structure BAQ-REQUEST-AREA.

The BAQ-REQUEST-AREA structure contains a nested BAQ-REQ-PARMS structure that can occur up to 64 times. Create an instance of the BAQ-REQ-PARMS structure for each OAuth 2.0 value to be passed to the IBM z/OS Connect server on the Host API BAQEXEC call. Each instance of BAQ-REQ-PARMS requires the following three fields to be set:
  • BAQ-REQ-PARM-NAME, the parameter name.
  • BAQ-REQ-PARM-ADDRESS, the address of the working storage that contains the value.
  • BAQ-REQ-PARM-LENGTH, the length of the value.
For example, to pass the client_id and client_secret parameters:
...
       WORKING-STORAGE SECTION. 
      * API requester Host API required copybooks 
       COPY BAQHAREC. 
       COPY BAQHCONC.
...
      * OAuth 2.0 Client credentials 
       01 OAUTH-CC-CLIENT-ID PIC X(10) VALUE 'myClientID'. 
       01 OAUTH-CC-CLIENT-SECRET PIC X(14) VALUE 'myClientSecret'.
...
       PROCEDURE DIVISION.
...
      * Set OAuth 2.0 Client credentials  
           MOVE BAQR-OAUTH-CLIENT-ID 
             TO BAQ-REQ-PARM-NAME OF BAQ-REQ-PARMS(1) 
           SET BAQ-REQ-PARM-ADDRESS OF BAQ-REQ-PARMS(1) 
             TO ADDRESS OF OAUTH-CC-CLIENT-ID 
           MOVE LENGTH OF OAUTH-CC-CLIENT-ID 
             TO BAQ-REQ-PARM-LENGTH OF BAQ-REQ-PARMS(1) 
           MOVE BAQR-OAUTH-CLIENT-SECRET 
             TO BAQ-REQ-PARM-NAME OF BAQ-REQ-PARMS(2) 
           SET BAQ-REQ-PARM-ADDRESS OF BAQ-REQ-PARMS(2) 
             TO ADDRESS OF OAUTH-CC-CLIENT-SECRET 
           MOVE LENGTH OF OAUTH-CC-CLIENT-SECRET 
             TO BAQ-REQ-PARM-LENGTH OF BAQ-REQ-PARMS(2) 
      * Make the BAQEXEC call
...

Repeat for each required OAuth 2.0 parameter, remembering to increment the BAQ-REQ-PARMS index value.

Make the BAQEXEC call and the Host API passes the OAuth 2.0 parameters to IBM z/OS Connect to use for endpoint authentication.