Engagement Cloud - Outbound REST Using IDCS OAUTH

Introduction

Engagement Cloud 19A introduces the ability to call IDCS oauth protected REST services. This article explains the setup required in IDCS and Engagement Cloud, using Oracle Blockchain as the service provider.

Note - details on how to call and parse REST services from Engagement Cloud groovy are covered here: Calling REST services from Oracle Engagement Cloud

The following components have been used:

• Engagement Cloud Release 19A
• IDCS 18.4.2
• Oracle Blockchain Platform 18.3.5 (IDCS is the IdP for this)

High Level Process

The stages to setup and call an IDCS Oauth protected REST service from Engagement Cloud are:

• Verify users and obtain signing certificate
• In IDCS, configure the source application APIs that need to be OAuth protected
• In IDCS, add Engagement Cloud as a Confidential Application and give access to the protected APIs defined above
• Configure the REST service in Engagement Cloud
• Call the service

1. Verify users and obtain signing certificate

The users that make the calls from Engagement Cloud to the protected resources must exist in both Engagement Cloud and IDCS with the same user name. For example, if the username in Engagement Cloud is john.dunbar and this user needs to call an IDCS protected service, then you also need a user in IDCS with username john.dunbar. 

Get the Oracle Fusion Applications Cloud Service OWSM signing certificate for your Engagement Cloud environment  - file a Service Request with My Oracle Support to obtain this.

2. In IDCS, configure the application APIs that need to be protected by OAuth

Both the application providing the REST APIs and the calling client are defined as Applications in IDCS. The application APIs that need to be OAuth protected are configured in the IDCS Application that represents the service provider. In this example Oracle Blockchain is being used as the service provider, but the process is the same for any IDCS OAuth protected application. In the screenshot below the Blockchain Application is called OABCSINST_tjbbcs and the protected resources are defined under the Resources section of the Configuration tab:

Engagement Cloud will be calling https://<hostname>/restproxy3/bcsgw/rest/v1/transaction/query so verify that this endpoint is included in the Scopes as illustrated above.

3. In IDCS, add Engagement Cloud as a Confidential Application and give access to the protected APIs defined above

In this stage, an IDCS Application representing the Engagement Cloud client is created and the resources that can be access are defined. In IDCS, navigate to Applications -> Add -> Confidential Application.

Give the application a name and click Next.

Select Configure this application as a client now. In the Allowed Grant Types, select JWT Assertion.

Select Trusted Client and import the Oracle Fusion Applications Cloud Service OWSM signing certificate obtained in stage #1.

Select Add Scope, find the Resource configured in stage #2 and add it:

The Client configuration screen should appear as below:

Click Next through the Resources and Web Tier Policy, then click Finish. A confirmation screen will display, showing the Client Id and Client Secret - copy these for the next stage.

The IDCS configuration is now complete. Engagement Cloud is now able to act as a client to (i.e. can call) the Blockchain services configured in the IDCS application created in this stage.

4. Define the service in Engagement Cloud

In Engagement Cloud, activate a sandbox and navigate to Application Composer -> Web Services. Create a new REST service, give it a name, and enter the service URL. In this example, the Oracle Blockchain REST endpoint is:

https://<hostname>/restproxy3/bcsgw/rest/v1/transaction/query

In order to use this service for multiple blockchain endpoints, the URL can be entered as:

https://<hostname>/restproxy3/bcsgw/rest/v1/transaction/##action##

(see Calling REST services from Oracle Engagement Cloud for details on defining service URLs)

Select Call using IDCS OAUTH

Add a new Client Credential Key - give the key a name (in this example ZATT_FA_Oauth_Client) and enter the Client Id and Client Secret saved from stage 3 above as the User Name and Password.

Enter the Token URI - this will be the Token URI of the IDCS instance. The format will be:

https://<idcshostname>/oauth2/v1/token

Enter the Scope. This will be the same as the Resource that was added to the IDCS client application in stage 3:

Select Subject Precedence.

The Subject Precedence flag determines which user will be used when calling the service - if Subject Precedence is true, then the user logged into Engagement Cloud will be used. If Subject Precedence is left empty (false), then the user defined in Credential Key will be used. If Subject Precedence is left empty, then it is mandatory to add a Credential Key (the UI does not currently enforce this). The screen below shows the Credential Key being used:

Note - if a Credential Key is used, the user defined in the key must also exist in both IDCS and Engagement Cloud. The user's password in the Credential Key is the Engagement Cloud password, not the IDCS password.

5. Call the service

Having defined the service it is called from Groovy in the same way as any other REST service. For reference, the  code used to call the above service is:

println("Call Blockchain")
def action = "query"
def param =
[
method :"queryContactHistory",
chaincodeVer :"V3",
chaincode :"contactPrefences",
channel :"default",
args:
["bart.simpson@whatamess.com"]
]
try {
def resp = adf.webServices.Blockchain.POST(action, param)
println("Blockchain: " + resp)
}
catch(e)
{
println("Error: " + e)
}

That completes the setup!

Final comment

This post sets out the minimum steps required to call IDCS OAuth protected resources from Engagement Cloud. The above setup is much simpler than documentation that conflates the setup of SSO and inbound oauth with this much simpler outbound use case, so if you come across documentation that appears much more complex than the above, check that it is for the same use case.