Authenticate and Authorize

Oracle Access Governance REST API leverages OAuth 2.0 protocol as its authorization framework. Authentication and Authorization in Oracle Access Governance APIs is managed by OCI IAM Authorization REST APIs.

You need to generate an access token for authorization using the OCI IAM (formerly known as Oracle Identity Cloud Service IDCS) token REST API (oauth2/v1/token) with suitable parameters.

At a high-level, perform the following:

Configure the key prerequisites for configuration and save the application details. For more details, see Prerequisites for configuration
Get your Oracle Access Governance SI details.
Get your OCI IAM URL
Authorize by generating an access token using the following grant types:

Step 1: Get Oracle Access Governance Service Instance Details

Fetch your Oracle Access Governance service instance details:

In your Oracle cloud account, navigate to Identity & Security, and click Access Governance.
Choose a compartment where your Oracle Access Governance service instance is located, and then select the service instance.
Select the Service instance link to view details.
Copy and save the URL till https://<service-instance-url>.com. You need the host details for sending API requests.

Step 2: Fetch Confidential OAuth Application Details for Authorization

You must create a confidential OAuth application and assign Oracle Access Governance application role, as explained in the Prerequisites for configuration topic.

Open the Confidential OAuth integrated application that you created.
Select the OAuth configuration tab.
Under the Resources section, copy and save the application scope. For example, <oracle-access-governance-service-instance>/urn:opc:agcs:all.
Under the General Information section, copy and save Client ID and Client Secret.
Encode the Client ID and Client Secret to Base64 Encoded Format for Authorization in the format client_id:client_secret.

Note:
If you are using REST API Client tool, add the values under Authorization—it handles encoding automatically.

Save this encoded value for later use.

Authorization: Basic <base64Encoded (client_id:client_secret)>

Step 3: Get the OCI IAM Domain URL for Authorization

To fetch the OCI IAM URL to fetch the Authorization Bearer Token:

Navigate to Identity & Security, and click Domains.
Apply a compartment filter and then select the domain.
On the Details tab, copy the authentication host in the Domain URL field without the port number. For example, https://idcs-<unique identifier>.identity.example.com.
Your authentication URL will be constructed:
```
https://<oci-iam-identifier>.identity.example.com/oauth2/v1/token
```

Step 4a: Get the Bearer Token for Authorization using Client Credentials

Use this method if you selected Client credentials as your grant type. You need to call the OCI IAM REST API to get an Authorization Bearer Token. Here, we will use only client credentials for generating an access token.

Call the OCI IAM REST API to Get a Bearer Token

REST APIs use HTTP methods to send and receive content. You can test REST APIs using any programming language or tool that supports sending and receiving HTTP messages. For example, cURL command line utility or standalone client, such as Postman or Advanced REST Client.

Use the following cURL command to generate an access token

Format

curl  -i -X POST \
-H "Content-Type:application/x-www-form-urlencoded" \
-H "Authorization:Basic <base64Of(client_id:client_secret)>" \
-d "scope=${service-instance-url}/<application scope>" \
-d "grant_type=client_credentials" \
'${OCIIAMurl}/oauth2/v1/token'

For example:

curl -i -X POST \
-H "Content-Type:application/x-www-form-urlencoded"\
-H "Authorization:Basic
      eynsjMTE0NDBlN2M="\
-d "scope=https://myaccess-governance.com/urn:opc:agcs:all"\
-d "grant_type=client_credentials"\
'${OCIIAMurl}/oauth2/v1/token'

You can use standalone clients, third-party browser extensions, or add-ons, such as the Advanced REST Client, to send HTTP requests.

Figure - Access Token Generation: Authorization Request using REST API Client Tool

Operation	Value
Method	POST
Request URL	`https://<oci iam-identifier>.identity.example.com/oauth2/v1/token`
Headers	Content-Type: `application/x-www-form-urlencoded` Authorization: `Basic <Base 64 encoded (client_id:client_secret)>`
Body	Select x-www-form-urlencoded format type in the Body and enter the following key values: `{ scope = ${service-instance-url}/<application scope> grant_type = client_credentials }`

Step 4b: Get the Bearer Token for Authorization using Password Credentials

If you selected Resource owner, use password as the grant type for generating an access token. However, we do not recommend this method and doesn't work when Multi-Factor Authentication (MFA) is enabled for your cloud account.

Format

curl -i -X \
 POST \
   -H \
 "Authorization:Basic <base64Of(ClientID:ClientSecret)>" \
   -H \
 "Content-Type:application/x-www-form-urlencoded" \
   -d "grant_type=password" \
   -d "username=${username}" \
   -d "password=${password}" \
   -d "scope=${service-instance-url}/application scope" \
 '${OCIIAMurl}/oauth2/v1/token'

Generating Access Token using REST Client

Figure - Access Token Generation: Password Grant Type Authorization Token using REST API Client Tool

Access Token Generation using Password Grant Type.

Refresh Token

Note:

We do not utilize refresh tokens, so after token expiration, you need to run the API again to generate a new token.

Step 4c: Get Bearer Access Token using the OAuth 2.0 Authorization Code

If you selected Authorization code grant Type. Follow the process, as explained to fetch Authorization token and then generate an access Token.

Sample curl to fetch Authorization Token

curl -X GET "${OCIIAMurl}/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=${service-instance-url}/<application scope>"

The authorization code is received as a query parameter in the redirect URI. Once you have the authorization code, make a POST request to the token endpoint.

curl -X POST "${OCIIAMurl}/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=YOUR_AUTHORIZATION_CODE" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=YOUR_REDIRECT_URI" \
     -d "scope=${service-instance-url}/<application scope>"

Get Access Token using the OAuth 2.0 Authorization Code in Postman

Using the REST Client Tool simplifies this process.

Note:

For explanation and demonstration, we have used the Postman REST Client tool to generate an Authorization code. For more details, refer OAuth 2.0. Based on your client tool, the steps may vary but the conceptual information remains the same.

Open Postman and go to the Authorization tab in your request.
Choose OAuth 2.0 in the Auth type field.

Fill the following information in the field:

Field	Description or Action
Header Prefix	Enter `Bearer`
Token Name	Enter a meaningful authorization token name
Grant Type	Select Authorization Code
Callback URL	Enter the redirect URL for your client, configured in your confidential application settings. For example, for Postman, you may use: `https://oauth.pstmn.io/v1/callback`
Auth URL	Enter your OCI IAM Domain URL in the following format: `${OCIIAMurl}/oauth2/v1/authorize`
Access Token URL	Enter your OCI IAM Domain URL in the following format: `${OCIIAMurl}/oauth2/v1/token`
Client ID	Add your application's Client ID.
Client Secret	Enter the application's Client Secret.
Scope	Enter application's scope in the following format: `${service-instance-url}/<application scope>` For example: `https://myaccess-governance.com/urn:opc:agcs:all`

Select Get New Access Token.
In a browser, enter your Oracle Access Governance username and password.
Once you request a token, the details are sent as an authorization code along with client credentials to the Authorization server for verification. Once the server verifies the code and credentials, it issues a new Access Token.
Select Use Token to use this token for invoking REST API requests.