Using OAuth 2.0 based authentication for client applications

The Open Authorization (OAuth) 2.0 describes several ways in which a resource owner can grant access to its protected resources. IBM® Cloud Pak for Business Automation as a Service supports only the resource owner password credentials (ROPC) grant type for authenticating client application access to the cloud environment.

Note: OAuth 2.0 based authentication is not enabled by default on cloud subscriptions. If you'd like to use it, submit a request through the IBM Support Portal.

ROPC grant type

In OAuth 2.0 terms, Cloud Pak for Business Automation as a Service client applications are confidential clients. For the ROPC grant type, they require a set of client credentials (consisting of a client ID and a client secret) and a resource owner user name and password. To obtain the client credentials, use the Credentials API to generate them. For the user name and password, log into the cloud portal as the Account Administrator, generate a set of service credentials, then assign them the permissions the client application requires. The permissions are used to control OAuth 2.0 token-based access to the cloud environments.

For more information about OAuth and the ROPC grant type, see The OAuth 2.0 Authorization Framework. For information about the Credentials API, see Example: Credentials REST API for OAuth 2.0 based authentication and for obtaining service credentials, see Creating and managing service accounts.

Managing OAuth 2.0 client credentials

OAuth 2.0 clients must provide client credentials to identify the calling client context. You decide how many sets of credentials you need. For example, you could use one set for all OAuth 2.0 clients or have a separate set of credentials for each client.

To use OAuth 2.0 authentication in your client application, your application must include the following interactions.

Important: The following calls might return a Set-Cookie command for the PD-S-SESSION-ID and PD-ID cookies as part of the response. Do not use these cookies in subsequent calls.

Get an OAuth 2.0 access token.
Use the OAuth 2.0 /token endpoint to acquire an access token including the client (client ID and client secret) and service credentials (user name and password). For example:
```
curl -k -v -X POST -H 'content-type: application/x-www-form-urlencoded' 
-d grant_type=password -d client_id=<clientId> -d client_secret=<clientSecret>
-d username=<serviceCredId> -d password=<svcCredSecret>
https://www.bpm.ibmcloud.com/mga/sps/oauth/oauth20/token
```
The call returns the access token to be used in subsequent cloud operations API calls, a refresh token for refreshing the access token, and an expiry duration for the access token. Be aware that access tokens are usually valid for minutes or hours, whereas refresh tokens can be valid for days. Scoping is not supported.
```
{"access_token":"CJ7yDymDAfSRz03W7zdX","refresh_token":"fGAv2qzuLnM030Brs8KFaIuY1Kd2P87sLFXI85lH","scope":"","token_type":"bearer","expires_in":1799}*
```
If the call is successful, the HTTP response code 201 is returned. If the client or service credentials are invalid, the call returns the HTTP response code BAD_REQUEST (400).
Use the token to access the cloud operations APIs.
Include the returned access token from the previous step in the Authorization header of the cloud operations API call. For example:
```
curl -k -v -H "Authorization: Bearer CJ7yDymDAfSRz03W7zdX" https://<tenantHost>/baw/dev/rest/bpm/wle/v1/user/current
```
If the access token is invalid or has expired, the call returns the HTTP response code 302.

Refresh the access token by using a refresh token.

Use the OAuth 2.0 /token endpoint.

curl -k -v -X POST -H 'content-type: application/x-www-form-urlencoded' 
-d grant_type=refresh_token -d refresh_token=fGU3UjAHG0XKTdnInU8ihqTLf48XJIzQtRUjNFVo
-d client_id=<clientId> -d client_secret=<clientSecret>
https://www.bpm.ibmcloud.com/mga/sps/oauth/oauth20/token

The call returns a new set of tokens.

{"access_token":"DkhN7gg7mk2gsBjGi8ay","refresh_token":"ToY13V2yfoYaeVbBjTwFLhzwX7GiKd7Y801VfjGC","scope":"","token_type":"bearer","expires_in":1799}

The call returns the HTTP BAD_REQUEST (400) response code if the refresh token is invalid or it was already used, or if the client credentials are invalid, for example, because they were deleted.

Revoke refresh and access tokens at the end of the client application processing
When client application processing is finished, it is a good practice to revoke both tokens by using the OAuth 2.0 /revoke endpoint. Revoke the refresh token before you revoke the access token.
For example, use the following call to revoke the refresh token:
```
curl -k -v -X POST -H 'content-type: application/x-www-form-urlencoded' 
-d client_id=<clientId> -d client_secret=<clientSecret>
-d token=ToY13V2yfoYaeVbBjTwFLhzwX7GiKd7Y801VfjGC
https://www.bpm.ibmcloud.com/mga/sps/oauth/oauth20/revoke
```
The call always returns a successful HTTP response code, for example, 200.
Attention: After an API is accessed, the access token remains valid until it expires.

Limitations

There is a system-defined daily limit of several hundreds of concurrent valid grants (access and refresh token pairs). The grants are tracked by client application and the resource owner user name. It is expected that the grant limit will never be reached. However, if you see a message indicating that the grant limit has been reached, check the grant creation design in your client applications or contact IBM Support.