1. Oracle Integration REST APIREST API for Oracle Integration
  2. Security, Authentication and Authorization
  3. Use OAuth with REST API Calls

Use OAuth with REST API Calls

To use OAuth with REST API calls, you need to get an authorization code and access token from Oracle Identity Cloud Service, then specify the access token when making calls to Oracle Integration REST APIs.

Prerequisites:

Steps

1. Get an Authorization Code

2. Base64 Encode the Client ID and Client Secret

3. Use the Authorization Code to Get an Access Token

4. Use the Access Token in REST API Calls to Oracle Integration

1. Get an Authorization Code

What you need:

  • Identity Cloud Service URL: the URL of your Oracle Identity Cloud Service instance. For example: idcs-c2881.identity.myhost.example.com

  • Client ID: the client ID you retrieved when you registered the trusted application in Identity Cloud Service. You can find the client ID in Oracle Identity Cloud Service, in your application. Select the Configuration tab, General Information section of the trusted application you configured in Oracle Identity Cloud Service.

  • Response type: Specify response_type=code for Authorization code grant type.

  • Scope: the scope value associated with your Oracle Integration instance registered in your trusted application. You can find this information in the trusted application you registered in Oracle Identity Cloud Service in the Configuration tab, Accessing APIs from Other Applications section, under Allowed Scopes, in the scope that you added. The scope looks like something similar to this: https://CA6ABF5D.myhost.example.com:443urn:opc:resource:consumer::all

  • Redirect URL: URL to which the response will be sent. Make sure your redirect URL is the same URL specified in the trusted application you configured in Oracle Identity Cloud Service. You can find the redirect URL in Oracle Identity Cloud Service in the Configuration tab, Client Configuration section of the trusted application you configured in Oracle Identity Cloud Service.

Using a browser, request an authorization code from Oracle Identity Cloud Service.

Make sure to add offline_access to the scope separated by a space.

Format:

https://<idcs_URL>/oauth2/v1/authorize?client_id=<client_ID>&response_type=code&scope=<scope> offline_access&redirect_uri=<URL_to_receive_response>

Example:

https://idcs-c2881.identity.myhost.example.com/oauth2/v1/authorize?client_id=f82f71efefcaff5ce&response_type=code&scope=https://F7E102440.myhost.example.com:443urn:opc:resource:consumer::all offline_access&redirect_uri=https://www.example.com/oauth2/callback

You'll be prompted to log in to Oracle Identity Cloud service. Use the user name and password for Oracle Integration.

For the response, you'll see the browser path replaced with something like the following. The code= is what you need to request an access token. Copy the retrieved code to a file. Note that the access code expires in a very short time.

For example:

https://www.example.com/oauth2/callback?code=iEipsLiGBfl-fpyqvguBMlBxIp7wZMTEUllQCAAQIDBST9=

2. Base64 Encode the Client ID and Client Secret

You must encode the client ID and client secret when you include it in a request for an access token.

Example - Windows

There are many utilities to base64 encode on Windows, including plugins in Notepad++ for example. Use the tool that best fits your needs.

  1. Create a file in Notepad and copy the client ID and client secret on one line, separated by a colon, and save the file. For example:
    ff8c2aff5ce:b8fe45-97ff-bae8d558f

  2. Open a command prompt and use the certutil command to encode the client ID and client secret. Specify your original file, and a new encoded file:

    For example:

    certutil -encode original_creds.txt encoded_creds.txt
  3. Open your encoded file, for example, encoded_creds.txt and copy the encoded client and secret to use in your REST API calls.

    Important:

    For security reasons, delete the original_creds.txt and the encoded_creds.txt files after you finish.

Example - Mac and Linux

  1. Create a file in a text editor and copy the client ID and client secret on one line, separated by a colon, and save the file. For example:
    ff8c2aff5ce:b88fe45-97ff-bae8d558f

  2. Copy the client and secret.

  3. Launch a terminal and enter the following command, replacing clientid:clientsecret with the value that you just copied to the clipboard. 

    echo -n "clientid:clientsecret" | base64 -w 0

    Note:

    If returned value is broken into more than one line, fix this in your text editor to make sure the results are on a single line with no text wrapping.

  4. Copy the value that is returned. You will need to specify it to get an access token.

3. Use the Authorization Code to Get an Access Token

Use the client ID and client secret for the trusted application to request the access token from Oracle Identity Cloud Service. You'll specify the access token when making REST API calls to Oracle Integration. There is one access token per user.

  1. Launch a command prompt.

  2. Enter the cURL command in the following format, replacing the text in brackets ( < > ) with the appropriate values:

    Format:

    curl -i  -H 'Authorization: Basic <base64_encoded_client_id:client_secret>' --request POST 'https://<idcs_url>/oauth2/v1/token' -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=authorization_code&code=<authorization_code_value>'
    curl -i  -H 'Authorization: Basic NzGVjMmZkNDYjYyYMS0GEtOlNjkxZWQ0' --request POST ’https://idcs-a0287b.identity.myhost.example.com/oauth2/v1/token' -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=authorization_code&code=G0bbfB0bA-9Sa2h-DyuKpB7djF9'

    You will receive an access token that you can use in your REST API calls. Copy what you receive to a file, including the refresh token. The access token is valid for 1 hour(3600 seconds) by default. You'll need to use the included refresh token to refresh your token when it expires. Copy the access_token value from the response to use in REST API calls to Oracle Integration.

4. Use the Access Token in REST API Calls to Oracle Integration

Make your API call and specify the access token in the authorization header.

The header has the form:

Authorization: Bearer access_token

For example, to retrieve a list of integrations:

curl -X GET https://myhost.example.com/ic/api/integration/v1/integrations   -H 'Authorization: Bearer eyJiO.eyJzdZ.tQ8_-9Jor5'