As businesses move to the cloud there is a high demand for securing/protecting their HTTP resources from unauthorized access. There are several approaches to protecting these resources which include SAML for SOAP service, OAuth for REST services, HTTP basic for both, and sometimes home grown proprietary mechanisms. It may not be widely known yet, but all Oracle Integration Cloud (OIC) REST endpoints are OAuth protected and can be triggered from a client using OAuth 2.0 (August 2018 - https://docs.oracle.com/en/cloud/paas/integration-cloud/rest-api/WhatsNew.html). Although there is online Oracle documentation that detail OAuth configuration on Oracle's Identity Cloud Service (IDCS) as well as the aforementioned OIC What's New link, the docs can be confusing especially if you have never used OAuth before. Therefore, this blog will demonstrate what is necessary for a client (in this example, Postman) can successfully trigger an OIC REST-based integration.
When an OIC instance is provisioned, an IDCS Application is created for that OIC instance. If you are looking for this application in IDCS, you can find it via the Oracle Cloud My Services Dashboard:
When you click on the link in the OIC instance window, it will open the IDCS Application that was created for you:
The first thing we need to verify is that the "Is Refresh Token Allowed" option is enabled (checked) under the Configuration > Resources section. Also notice that there is a special Scope predefined (urn:opc:resource:consumer::all), which allows the triggering of OIC integrations using OAuth:
The next step is to add the appropriate user(s) to the various OIC roles. For standard/production configurations, the ServiceUser role should be used. For this example, we will be adding our user to the ServiceDeveloper role (located under the Application Roles tab) which will grant integration triggering for our user in addition to other capabilities in OIC (see Oracle Integration Cloud Roles):
Now that we have the OIC instance setup to be triggered by a particular user, we can configure a new client Application in IDCS that will provide the details necessary for that user to leverage OAuth to trigger an OIC integration.
NOTE: The following configuration is based on the details from the online OIC documentation for Security, Authentication, and Authorization (https://docs.oracle.com/en/cloud/paas/integration-cloud/rest-api/Authentication.html) under the section titled Configure a Trusted Application to Authenticate with OAuth (https://docs.oracle.com/en/cloud/paas/integration-cloud/rest-api/OAuth_prereq.html) ... there is a documentation error as the "Trusted Application" should read "Confidential Application".
In the previous section, we were updating the IDCS Application associated with the OIC instance we will be using. Since we are already in the IDCS console, we can go to the Application section to create our new Application that will allow OIC integration triggering via OAuth. The application we will be adding will be a Confidential Application:
We are presented with and Add Confidential Application wizard, where we will simply fill out the Details section and skip the rest of the wizard steps:
At this point, we will spend most of our time in the Configuration tab of the new IDCS Application we created. Open the application and navigate to the Configuration tab. The first set of things to do for the configuration is to:
1. Select "Refresh Token" and "Authorization Code" for the Allowed Grant Types
2. Set the Redirect URL to the OIC instance host and append /icsapis/agent/oauth/callback to the URL (e.g., https://ateamexample.integration.ocp.oraclecloud.com/icsapis/agent/oauth/callback)
3. Select "Confidential" for the Client Type
4. Select "Specific" for the Authorized Resources
5. Save your changes
* Checking "Authorization Code” means that we want OIC to acquire the token using the 3 legged OAuth flow; meaning that the admin will use their web browser to click through and get the token for OIC.
* Checking “Refresh Token” means that OIC will be able to automatically acquire a new Access Token after the current one expires even if the admin isn’t there to click through.
Now we need to select the appropriate scope that is defined in the IDCS OIC Application that we configured earlier. This is fairly straightforward since the scope is predefined in the Resources section of the IDCS OIC Application. All we need to do is click on "Add Scope" under the Resources area of the Client Configuration, find the IDCS OIC Application, and add the scope containing the urn:opc:resource:consumer::all:
NOTE: Please to remember to save your configuration after every major activity.
The final IDCS Application configuration activity that is needed is to assign a user to the application. Please note that the user being assigned to the application is the same user we added to the IDCS OIC Application role previously. To accomplish this, we need to switch to the Users tab in the application configuration:
At this point we have the IDCS Application ready to be used by some client application. Details we provided for the application configuration will be needed for the client application including the Client ID and Client Secret from the application:
In order to test out our IDCS OAuth configuration, we will be leveraging Postman (https://www.getpostman.com/) as our client application. To setup Postman for triggering an OIC integration, we need an active OIC REST-based integration and the IDCS OAuth details. For this example, an integration has been created in OIC that will take a text message and echo it back. Before triggering this integration using OAuth, it's a good idea to make sure it can be called using basic authentication:
Since we know the integration can be triggered via basic authentication, let's try to do the same trigger using OAuth. To do this we switch to the Authorization section in Postman and select OAuth 2.0 as the TYPE:
The next activity is to request a token to be used for triggering the OIC integration. In Postman, click on Get New Access Token and fill out the dialog with the following information:
1. Provide some name under Token Name
2. Select "Authorization Code" as the Grant Type
3. Callback URL is the Redirect URL provided in the IDCS Application configuration (e.g., https://ateamexample.integration.ocp.oraclecloud.com/icsapis/agent/oauth/callback)
4. Auth URL is the IDCS instance URL with /oauth2/v1/authorize appended to it (e.g., https://idcs-xxxx.identity.oraclecloud.com/oauth2/v1/authorize)
5. Access Token URL is the IDCS instance URL with /oauth2/v1/token appended to it (e.g., https://idcs-xxxx.identity.oraclecloud.com/oauth2/v1/token)
6. Client ID is from the General Information section of the IDCS Application configuration
7. Client Secret is from the General Information section of the IDCS Application configuration
8. Scope is from the Client Configuration section of the IDCS Application configuration (e.g., https://ateamexample.integration.ocp.oraclecloud.com:443urn:opc:resource:consumer::all)
Once all the information has been provided in the GET NEW ACCESS TOKEN dialog for Postman, click on Request Token to retrieve the OAuth token from IDCS for use in the OIC integration trigger:
The process for getting the token requires you to authenticate with IDCS, so a popup window will be presented with the IDCS login screen:
Once you authorize yourself with IDCS, Postman will present the JWT Access Token provided by IDCS.
If you are interested in seeing the details of this token, you can copy and paste the token at https://jwt.io
In the MANAGE ACCESS TOKENS dialog that returned the new access token, scroll to the bottom and select Use Token.
At this point we have all the necessary pieces to trigger the OIC integration using OAuth. In Postman, click on the Preview Request button to populate the Bearer Header in the request:
You can see this header by switching to the Headers section of Postman. We see the header is there, so now we can "Send" the request to OIC via the Send button:
Assuming we did all the correct configurations, you will see the results in Postman under the Body section (where you can see the request/response messages):
Now to prove the test was not just smoke and mirrors, we can view the results in the OIC Console under Monitoring:
The A-Team Echo Integration used for this example has been activated to include the Activity Stream. We can view the payloads in the Activity Stream dialog:
As you can see, the actual triggering of the OIC integration is somewhat straightforward. The bulk of the configuration is in the associated IDCS instance for your OIC environment and setting up the client application for invoking the OIC integration. Hopefully this blog contains details to help you get OAuth triggering to work for your OIC instance.
I would like to thank my colleague and security guru Chris Johnson for assisting with all of the OAuth/IDCS/security details.