Authenticate with OAuth 2.0

This topic explains how to use the OAuth 2.0 specification to authenticate with the Oracle Unity APIs.

Introduction

OAuth 2.0 enables the safe retrieval of secure resources while protecting user credentials. Learn more about the OAuth 2.0 Specifications. OAuth is a flexible and secure protocol that relies on SSL (Secure Sockets Layer) to ensure data between web servers and browsers remain private.

Use cases

Design programs to obtain authentication tokens from Oracle Identity Cloud Service (IDCS) and then use these tokens to send requests to Oracle Unity APIs, safely and securely.

Workflow

The sequence of steps required for processing Oracle Unity REST API requests is:

Client obtains an authentication token.

Client sends a request to an Oracle Unity API endpoint. For example:

Authorization: Bearer <token>
Content-Type: application/json
GET https://oracle-tenant.cxunity.ocs.oc.com/api-metadata/v1/e2a7a0df2410470d85ef69c8dad2bdb8/metadata/tables

To authenticate using OAuth 2.0

Oracle Unity supports the Resource Owner Password Credentials grant flow to obtain access on behalf of a resource owner:

Before you begin:

Get your Client ID and Client Secret from Oracle Identity Cloud Service (IDCS). You can find your Client ID and Client Secret in the Admin Console by selecting your application and looking under Configuration > General Information.
You will need your Oracle Identity Cloud Service (IDCS) URL and Oracle Unity app's Primary Audience URL. If you do not know yours, contact your instance administrator.
The user account accessing the API must have the Instance admin role in Oracle Unity. For instructions on how to add a user, see Adding Users.

Learn more by watching the video

To authenticate using a resource owner password credentials grant:

Request an access token using the https://<IDCS_URL>/oauth2/v1/token endpoint. Where <IDCS_URL> is the path to your Oracle IDCS instance.

Authorization

This request must authenticate using HTTP basic. Use your IDCS Client ID as the username and the Client Secret as the password, encode the string with base-64 encoding, and pass it as an Authorization header. The format is client_id:client_secret.

'Authorization: Basic <base64Encoded client_id:client_secret>'

Request URL

POST https://<IDCS_URL>/oauth2/v1/token
Content-Type: application/x-www-form-urlencoded

Request Body

The request should include a x-www-form-urlencoded body with the following parameters:

Parameter	Value	Required?
`grant_type`	Must be `password`.	Yes
`scope`	The Primary Audience URL of your IDCS application, followed by "cxunity". You can find this URL in your IDCS instance under Configuration > Resources > Primary Audience. Syntax: https://<idcs-primary-audience-url>cxunity Example: https://cxunity.ocs.ocloudcxunity (Optional) To include a refresh token in the response, specify `offline_access` as a prefix. For example: offline_access https://cxunity.ocs.ocloudxunity	Yes
`username`	Your IDCS username (URL encoded).	Yes
`password`	Your IDCS password (URL encoded).	Yes

Example

http
curl

POST https://<IDCS_URL>/oauth2/v1/token
Content-Type: application/x-www-form-urlencoded

"grant_type":"password",
"scope":"offline_access <idcs-primary-audience-url>cxunity",
"username":"<username>",
"password":"<password>"

curl --location --request POST ‘https://<IDCS_URL>/oauth2/v1/token’ \

--header 'Authorization: Basic <base64Encoded client_id:client_secret>’ \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<username>' \
--data-urlencode 'password=<password>' \
--data-urlencode 'scope=offline_access <idcs-primary-audience-url>cxunity’

An access token and refresh token will be returned in the response.

{
  "access_token": "eyJ4NXQjUzI1NiI6Ik50empwWEpKTkZxRFBWcjFVcFlMNUZ3cVR6MEltN0hZeUQ1WVhXX3BhVGsiLCJ4NXQiOiJHTS1HWGMwN0doLXF1dTJ2SGZuLThsWVVydVkiLCJraWQiOiJTSUdOSU5HX0tFWSIsImFsZyI6IlJTMjU2In0.eyJ1c2VyX3R6IjoiQW1lcmljYVwvQ2hpY2FnbyIsInN1YiI6InNhdXJhYmguc2hhc3RyaUBvcmFjbGUuY29tIiwidXNlcl9sb2NhbGUiOiJlbiIsInVzZXIudGVuYW50Lm5hbWUiOiJpZGNzLWQyMTAyZGI3MzcxYzRiYmZiMTNlOWUwODA4ZjFmNDYxIiwiaXNzIjoiaHR0cHM6XC9cL2lkZW50aXR5Lm9yYWNsZWNsb3VkLmNvbVwvIiwidXNlcl90ZW5hbnRuYW1lIjoiaWRjcy1kMjEwMmRiNzM3MWM0YmJmYjEzZTllMDgwOGYxZjQ2MSIsImNsaWVudF9pZCI6IjU3ZDNjYmExY2MwYTQ0NWE4YzRhZTEzNmI0MzBmZjdjIiwic3ViX3R5cGUiOiJ1c2VyIiwic2NvcGUiOiJjeHVuaXR5IG9mZmxpbmVfYWNjZXNzIiwiY2xpZW50X3RlbmFudG5hbWUiOiJpZGNzLWQyMTAyZGI3MzcxYzRiYmZiMTNlOWUwODA4ZjFmNDYxIiwidXNlcl9sYW5nIjoiZW4iLCJleHAiOjE2MDc0NDk2MjQsImlhdCI6MTYwNzQzMTYyNCwiY2xpZW50X2d1aWQiOiI4YmIxMTUyN2QzNjk0MTliYjljZTExMTI3ZjI3MjQ3MiIsImNsaWVudF9uYW1lIjoidGVuYW50Mi5pbnRlZ3JhdGlvbiIsInRlbmFudCI6ImlkY3MtZDIxMDJkYjczNzFjNGJiZmIxM2U5ZTA4MDhmMWY0NjEiLCJqdGkiOiIxMWViMzk1Mzc5MGYwYzFkOTlkOGNiODQ3MGZjNDJkZCIsImd0cCI6InJvIiwidXNlcl9kaXNwbGF5bmFtZSI6IlNhdXJhYmggU2hhc3RyaSIsInN1Yl9tYXBwaW5nYXR0ciI6InVzZXJOYW1lIiwicHJpbVRlbmFudCI6dHJ1ZSwidG9rX3R5cGUiOiJBVCIsImNhX2d1aWQiOiJjYWNjdC01MjhjYTMzMWU1ZjM0NjZjOGMxNDBiYTBlOGY2NTdhZCIsImF1ZCI6Imh0dHBzOlwvXC90ZW5hbnQyLmRldi1pbnRnLmN4dW5pdHkub2NzLm9jLXRlc3QuY29tXC8iLCJ1c2VyX2lkIjoiMDUwNDkyZjhiMzk1NDkyMTk3N2M1OTQ2YTJiNjM0OTAiLCJydF9qdGkiOiIxMWViMzk1Mzc5MGYwYzFjOTlkODJmNmFjODc2NmQ5OCIsInRlbmFudF9pc3MiOiJodHRwczpcL1wvaWRjcy1kMjEwMmRiNzM3MWM0YmJmYjEzZTllMDgwOGYxZjQ2MS5pZGVudGl0eS5jOWRldjIub2M5cWFkZXYuY29tOjQ0MyIsInJlc291cmNlX2FwcF9pZCI6IjhiYjExNTI3ZDM2OTQxOWJiOWNlMTExMjdmMjcyNDcyIn0.GRuYE3ojuuCuJ8GcdyHFnSVzZSMn_au-SX1hSRl8BCSc-m_OblUKiBU-RRIyooYvuLtLJKDyXhhUI0tMNTDugAd-urwYpKtVXKivJqykr0QC7ASa7i93PWQ1EAieyaLyYFPsn9JQsZKrYSMGORehmK-4uzrznn952w_isEoSJYBG7FSy7xLQOfLlP1hhm-nMRniJAZF1_G7Kxd-jiKN1zOPmPW00BGJRQAeBNheUGTydQoH-_074kKB-z1OSuElNKE-u6UGpXM16vnJDASK2yQOOa2Ou_HVp8tP4AxSRFBzsZ23D7cHAsXRZSdIJFymeuwW1DpOlrwZvLqDeRCVfOg",
  "token_type": "Bearer",
  "expires_in": 18000,
  "refresh_token": "AgAgZjJkNDEyMTgxZGEzNDQyMzlmZmI0OTVmOWFiMTcxYzEIABCL_cz1r9_ZzYeNFqi0ak_oAAAAMLrM8e7XrVqza2xNXBfSrw6bTJuy5lfl62e7M_HHCdVaqrzpUaRIPmZ_2NLtY8uOwg=="
}

Note: The token expiration time is set in your Oracle IDCS instance under Configuration > Resources for an app.

If the access token has expired, send a request to the same endpoint in step 1 to obtain a new access token. However this time in the request payload, remove the scope , username, password, and change the grant_type to refresh_token. A successful response will return a new access token.

Example

http
curl

POST https://<IDCS_URL>/oauth2/v1/token
Authorization: Basic <base64Encoded client_id:client_secret>
Content-Type: application/x-www-form-urlencoded

"grant_type":"refresh_token",
"refresh_token":"<refresh_token>"

curl --location --request POST '<IDCS_URL>/oauth2/v1/token' \
--header 'Authorization: Basic <base64Encoded client_id:client_secret>’\
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=<refreshtoken> '

The response is a JSON body containing a new access token.

{
  "access_token": "eyJ4NXQjUzI1NiI6Ik50empwWEpKTkZxRFBWcjFVcFlMNUZ3cVR6MEltN0hZeUQ1WVhXX3BhVGsiLCJ4NXQiOiJHTS1HWGMwN0doLXF1dTJ2SGZuLThsWVVydVkiLCJraWQiOiJTSUdOSU5HX0tFWSIsImFsZyI6IlJTMjU2In0.eyJ1c2VyX3R6IjoiQW1lcmljYVwvQ2hpY2FnbyIsInN1YiI6InNhdXJhYmguc2hhc3RyaUBvcmFjbGUuY29tIiwidXNlcl9sb2NhbGUiOiJlbiIsInVzZXIudGVuYW50Lm5hbWUiOiJpZGNzLWQyMTAyZGI3MzcxYzRiYmZiMTNlOWUwODA4ZjFmNDYxIiwiaXNzIjoiaHR0cHM6XC9cL2lkZW50aXR5Lm9yYWNsZWNsb3VkLmNvbVwvIiwidXNlcl90ZW5hbnRuYW1lIjoiaWRjcy1kMjEwMmRiNzM3MWM0YmJmYjEzZTllMDgwOGYxZjQ2MSIsImNsaWVudF9pZCI6IjU3ZDNjYmExY2MwYTQ0NWE4YzRhZTEzNmI0MzBmZjdjIiwic3ViX3R5cGUiOiJ1c2VyIiwic2NvcGUiOiJjeHVuaXR5IG9mZmxpbmVfYWNjZXNzIiwiY2xpZW50X3RlbmFudG5hbWUiOiJpZGNzLWQyMTAyZGI3MzcxYzRiYmZiMTNlOWUwODA4ZjFmNDYxIiwidXNlcl9sYW5nIjoiZW4iLCJleHAiOjE2MDc0NDY4MzUsImlhdCI6MTYwNzQyODgzNSwiY2xpZW50X2d1aWQiOiI4YmIxMTUyN2QzNjk0MTliYjljZTExMTI3ZjI3MjQ3MiIsImNsaWVudF9uYW1lIjoidGVuYW50Mi5pbnRlZ3JhdGlvbiIsInRlbmFudCI6ImlkY3MtZDIxMDJkYjczNzFjNGJiZmIxM2U5ZTA4MDhmMWY0NjEiLCJqdGkiOiIxMWViMzk0Y2ZhZDBkNjA2OTI4NGFmMDk4OTQxNTg3YyIsImd0cCI6InJ0IiwidXNlcl9kaXNwbGF5bmFtZSI6IlNhdXJhYmggU2hhc3RyaSIsInN1Yl9tYXBwaW5nYXR0ciI6InVzZXJOYW1lIiwicHJpbVRlbmFudCI6dHJ1ZSwidG9rX3R5cGUiOiJBVCIsImNhX2d1aWQiOiJjYWNjdC01MjhjYTMzMWU1ZjM0NjZjOGMxNDBiYTBlOGY2NTdhZCIsImF1ZCI6Imh0dHBzOlwvXC90ZW5hbnQyLmRldi1pbnRnLmN4dW5pdHkub2NzLm9jLXRlc3QuY29tXC8iLCJ1c2VyX2lkIjoiMDUwNDkyZjhiMzk1NDkyMTk3N2M1OTQ2YTJiNjM0OTAiLCJydF9qdGkiOiIxMWViMzk0Y2ZhZDBkNjA1OTI4NDRkNDY0NTIyOTE4NyIsInRlbmFudF9pc3MiOiJodHRwczpcL1wvaWRjcy1kMjEwMmRiNzM3MWM0YmJmYjEzZTllMDgwOGYxZjQ2MS5pZGVudGl0eS5jOWRldjIub2M5cWFkZXYuY29tOjQ0MyIsInJlc291cmNlX2FwcF9pZCI6IjhiYjExNTI3ZDM2OTQxOWJiOWNlMTExMjdmMjcyNDcyIn0.Tx4SLAsRokl_mcT_YBX1O8XN2fi8MKQkYnHMus1tDQm8QHJi60R1oPfJZTk6AUbZoqnPXXy9wIqLLATJm9yubzkVzXHQvQhqq1m9_JjXv7DlBPC52zDujk_C9IYWDMr-eI-tbP10fBMx0Z7WaXsxFtlAuCBRPOQWLNRoV8Esp6sCsoBQkhCyjV7EiGFdE4VOC_CQwDHOcBvnkUgJAPu7oFwGZrjmpn_RX6pTI9hHwfp6fguBtNCBJNnx2g1RB4kftiIAi8xXkQcWk-_eFAFZVVpTsMV--Sk2sMaAVRMtaPo1d-EFzxEEioKN-GD4G3f3NXuZwj3C0_MuinYoYV0--Q",
  "token_type": "Bearer",
  "expires_in": 18000,
  "refresh_token": "AgAgZjJkNDEyMTgxZGEzNDQyMzlmZmI0OTVmOWFiMTcxYzEIABBtpeJfb0SFnEiraGkWgfwUAAAAMOxgh6JC281_-8tRpPl5t7Bon9YmUXpMrl_-_hlsX3lHAkygEiIiwoH0hLYgYxcYcQ=="
}

Send a request to a resource using the access token using bearer authentication. Refer to the respective API endpoint category to understand the API request details.

Example request
```
Authorization: Bearer <access_token>
Content-Type: application/json
GET https://<unity_tenant_url>/api-metadata/v1/<access_key>/metadata/tables				
```

Next steps

Sending API Requests