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 by 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 API secured with OAuth 2.0.
- You must know which grant type you want to use.
- You must know the information to be provided by the 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 that are described in the following procedure, refer to Configuration elements.
zosconnect_authDataelement in server.xml, and specify the client ID and client secret.For example,
<zosconnect_authData id="clientInfo" user="clientID1" password="clientSecret1" />
<zosconnect_authorizationServer id="myAuthServer" tokenEndpoint="https://authorization.server.com:8001" sslCertsRef="defaultSSLConfig" basicAuthRef="clientInfo" />Where:
tokenEndpointattribute specifies the URL and port of the authorization server. This example uses a TLS connection to the authorization server.
sslCertsRefattribute references the TLS configuration for the authorization server connection. If
sslCertsRefis 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
sslDefaultelement that specifies the SSL element to be used as the default.
basicAuthRefattribute references the
zosconnect_authDataelement that specifies the client ID and client secret, which are used by the authorization server to authenticate the client. If the
basicAuthRefattribute 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.
zosconnect_oAuthConfigelement 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
grantTypeattribute 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
clientSecretInBodyattribute to "true".
Add a reference to the OAuth 2.0 configuration data to the
zosconnect_endpointConnectionelement. 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"/>