How to configure OAuth 2.0 with basic authentication

When a z/OS® application calls a REST API that is protected by OAuth 2.0 on an API endpoint, the IBM® z/OS Connect server must be configured to request the OAuth 2.0 access token from an authorization server. This request can be made using basic authentication in the form of a client ID and secret.

Before you begin

You should be familiar with the information in Calling an OAuth 2.0 authorization server.
You must know which grant type you want to use.
You must know the information to be provided by the CICS, IMS, or z/OS application, and which information is to be provided in server.xml.
You must have write access to the server.xml configuration file.

About this task

The example in this task configures an IBM z/OS Connect server to request an OAuth 2.0 access token from an authorization server by using the client credentials grant type and basic authentication with the credentials in the Authorization header. The client ID and secret are set in server.xml, rather than in the z/OS application. For more information about the elements and attributes described below, refer to Configuration elements.

Procedure

Define a zosconnect_authData element in server.xml, and specify the client ID and client secret.

For example,

<zosconnect_authData id="clientInfo"
      user="clientID1"                        
      password="clientSecret1" />

Define a zosconnect_authorizationServer element.
For example,
```
<zosconnect_authorizationServer id="myAuthServer" 
   tokenEndpoint="https://authorization.server.com:8001" 
   sslCertsRef="defaultSSLConfig" 
   basicAuthRef="clientInfo" />
```
Where:
- The tokenEndpoint attribute specifies the URL and port of the authorization server. This example uses a TLS connection to the authorization server.
- The sslCertsRef attribute references the TLS configuration for the authorization server connection. If sslCertsRef is omitted, the default SSL configuration for the IBM z/OS Connect server is used. The default is an SSL element with the ID "defaultSSLConfig", or an sslDefault element that specifies the SSL element to be used as the default.
- The basicAuthRef attribute references the zosconnect_authData element that specifies the client ID and client secret, which are used by the authorization server to authenticate the client. If the basicAuthRef attribute is omitted, you must set client ID and client secret in your z/OS application program. If the client credentials are set in both the application and the server.xml, the credentials set in server.xml are used in the request to the authorization server. If both client ID and client secret are required, either they must both be configured in server.xml, or both be set in the z/OS application.
Define a zosconnect_oAuthConfig element that specifies the grant type and references the authorization server definition.
For example,
```
<zosconnect_oAuthConfig id="myoAuthConfig"
      grantType="client_credentials"
      authServerRef="myAuthServer"/>
```
If you are using the resource owner password credentials grant type, set the grantType attribute to "password". If the client ID and client secret need to be sent to the authorization server in the request body, rather than in the Authorization header, set the clientSecretInBody attribute to "true".
Add a reference to the OAuth 2.0 configuration data to the zosconnect_endpointConnection element. The reference defines the API endpoint that requires an OAuth 2.0 access token.
For example,
```
<zosconnect_endpointConnection id="conn"
      host="https://api.server.com"              
      port="8000"
      authenticationConfigRef="myoAuthConfig"/>
```

Results

In this task, you configured IBM z/OS Connect to request an OAuth 2.0 access token from an authorization server. Ensure that the z/OS application program sets any additional parameters that are required by the authorization server.