Best Practices from Oracle Development's A‑Team

Trigger OIC Integration Using OAuth Client Credentials

Greg Mally
Consulting Solutions Architect

This blog is a supplement to my original blog entitled Trigger OIC Integration Using OAuth, which was the first OAuth offering by OIC.  Although the old blog focused on using the IDCS Grant Type of Authorization Code, the Resource Owner Grant Type also worked.  The difference between those two Grant Types is Authorization Code is intended to be used when a human is involved (3-legged OAuth flow) whereas the Resource Owner is meant for system to system interaction (2-legged OAuth flow).  Most often with OIC, the system to system scenario comes into play and therefore many OIC users would leverage the Resource Owner Grant Type.  There is a challenge with using the Resource Owner in that there is a user name and password that is required to retrieve the access token.  Since users in IDCS are required to periodically change their password (i.e., the password expires), the Resource Owner Grant Type requires a credentials update to all of the OIC clients using OAuth to prevent OIC triggers from failing.  In a recent OIC update (version (200227.0200.34310)), the Client Credentials Grant Type has been made available for integration triggering.  This Grant Type is not tied to a user, so the user credentials expiring does not come into play.  All that is needed to retrieve an access token via the Client Credentials Grant Type is the IDCS Application ID, secret, and scope.  This blog will demonstrate what is necessary for a client (in this example, Postman) can successfully trigger an OIC REST-based integration using the IDCS Client Credentials Grant Type.

High-Level Steps

  1. Configure Custom IDCS Application for use by client application for OIC REST triggering
    1. Must use the IDCS instance associated with the OIC instance
    2. Set Allowed Grant Types to Client Credentials
    3. Set Client Type to Confidential
    4. Set Allowed Operations to On behalf Of
    5. Set Allowed Scopes to https://[IDCS OIC Autogenerated App Host Name]:443urn:opc:resource:consumer::all
    6. Save and Activate Custom Application
  2. Add Custom IDCS Application to the ServiceUser section of the OIC Auto-Generated IDCS Application *** VERY IMPORTANT STEP ***
  3. Configure client application with OAuth using the details from the IDCS application configuration
  4. Verify configuration by running client application

Create Custom IDCS Application

The first thing we will do is to create and configure our custom IDCS Application that will be used by the OIC client application(s) for triggering integrations. To create a new IDCS Application, we need to open the IDCS console and click on the Add Application icon on the IDCS console landing page. You can directly access the IDCS console using the following URL:
https://[IDCS Host Name Associated With Your OIC Instance]/ui/v1/adminconsole/
(e.g., https://idcs-[RandomStuff].identity.oraclecloud.com/ui/v1/adminconsole/)

You are now presented with the create IDCS Application wizard where we will select Confidential Application, provide a name and description for the application, and then simply skip through all the configure sections:

At this point we now have a skeleton of our custom IDCS Application where we will simply focus on the Client Configuration section.  Locate the Configuration tab, click on the Client Configuration section, and select Register Client:

We are now ready to fill out the minimal information necessary to allow the Client Credentials Grant Type to work with your OIC environment.  The details we need to provide are:

  • Allowed Grant Types: Client Credentials
  • Client Type: Confidential
  • Allowed Operations: On behalf Of
  • Resources: + Add Scope

When you click on + Add Scope, you will be presented with a window where you will need to locate the auto-created IDCS Application associated with your OIC instance.  For Gen1 OIC, these applications are prefixed with OICINST_.  Once you locate the OIC IDCS Application, you simply expand the available scopes and pick the one ending in urn:opc:resource:consumer::all

Your Resources section should look something like the following once you have added the appropriate Scope:

Let's now Save and Activate our Application before going to the list of IDCS Applications:

Configure OIC IDCS Application

When an OIC instance is provisioned, an IDCS Application is created for that OIC instance (we found it when adding the scope to our custom Application). We need to locate this application and add the custom Application we created to its Application Roles section.  Let's first locate and open the auto-generated IDCS Application:


We are now in the section where we will add our custom IDCS Application we created earlier to the ServiceUser OIC Application Role. This is done by locating the ServiceUser role in the list of roles and via the menu on the right-hand side, select Assign Application:

You will be presented with a window where you will need to search/locate your custom IDCS Application.  Once you find it, simply check the box next to the Application and press OK. You can verify that it has been added via the Applications Assigned link located on the ServiceUser role:

We are now done configuring IDCS and will move on to verifying our configuration via a test client application.

Verify IDCS Configuration Via Postman

The test client we will be using to verify our IDCS configuration will be Postman.  To help with this, a Postman Environment and Collection have been provided here: trigger_oic_integration_using_oauth_client_credentials.zip

Unzip the contents from the above zip and import the two files into your Postman application.  Once you have imported the two files, you will have a Blogs collection and an environment called Trigger OIC Integration Using OAuth Client Credentials.

Configure Postman With IDCS/OIC Details

The environment that you imported into Postman contains the various variables needed to retrieve an OAuth Access Token from IDCS and trigger a simple Echo integration in OIC (this is typically an example integration that is active after provisioning). These variables consist of:

  • OIC_HOST - The host name used when you are accessing the OIC Console.
  • IDCS_HOST - The host name used when you are accessing the IDCS Console associated with your OIC instance.
  • OAuth2_ID - This is the Client ID for your custom IDCS Application.  It is located in the General Information section under the Configuration tab.
  • OAuth2_Secret - This is the Client Secret for your custom IDCS Application and is located right under the Client ID via the Show Secret button.
  • OAuth2_Scope - This is the scope that was added to your custom IDCS Application in the Client Configuration section under the Configuration tab. It is the whole string from https...:all

Open and edit the Trigger OIC Integration Using OAuth Client Credentials environment and set each variable's Current Value accordingly:

You will notice that the OAuth2_Token is not yet set. Although we can generate the token using Postman, we will use an IDCS REST API to retrieve the JWT token using the values we set above.  In the Blogs collection, open the request called Get Token via Form - OAuth Blog.  Go through each of the request sections like Authorization, Headers, and Body. Hover your mouse over the Postman variables (text in double curly braces colored orange) in the various sections to get a tooltip of the Current Value to verify your Environment configuration. If all looks good, press Send and review the results:

Notice the selected text above.  That is the access token we will need to copy and paste into our OAuth2_Token environment variable. So go ahead and select that token, copy, and paste into your OAuth2_Token variable CURRENT VALUE. The easiest way to access the variable is to click on the eye icon next to the Environments drop down and click on the edit icon next to the variable:

We are all set to verify triggering the Echo integration on our OIC instance.

Trigger Echo Using OAuth Access Token

In the Blogs collection, open the Echo via OAuth Client Credentials - OAuth Blog request. Select the Headers section of the request and hover the mouse over the {{OAuth_Token}} environment variable. The tooltip should show the first part of your access token we set earlier:

We are now ready to send the request. Simply press the Send button and review the results. If everything is setup correctly, you will see something like the following:

You may have noticed that there is another request in the Blogs collection called OIC Environment - OAuth Blog. This is provided to demonstrate that you can also access the OIC REST APIs using the same access token. If you Send that request you should get details back about your environment.
NOTE: If you do not have the Echo integration in your OIC instance this request can be used to validate the IDCS configuration.

As always, I welcome your comments/feedback and will update this blog if anything is missing, inaccurate, and/or confusing.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha