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.
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>] <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. |
- Custom parameter names and all 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=valueC
- 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.
- 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.
- The request copybook:
API00Q01
- The response copybook:
API00P01
- The API information file:
API00I01
- 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.