Identity Propagation - VBCS > IC > Fusion Apps

This blog was a collaborative effort between Greg Mally and Mike Muller of the A-Team and a working example can be found on GitHub:

https://github.com/oracle/vbcs-oic-fs-identity-propagation-sample

One of the big challenges that Oracle Integration Cloud developers face is any outbound REST calls from Integration Cloud (IC) to Fusion Applications (FA) APIs require a user’s identity.  On the surface this seems pretty trivial because the IC REST connections allow for configuring the connection with basic authentication or OAuth 2 JSON Web Token (JWT). However, this configuration is tied to a single user and many use cases/flows require the identity of the person making the FA REST call due to access restrictions, security, auditing, etc. This blog will present a pattern that has been implemented to accomplish identity propagation from a client application, through IC, and to FA.

Problem Statement

How can an Oracle Integration Cloud developer ensure that the invoking user’s identity gets passed along to a Fusion Application call?

The Use Case and Challenge

For this blog, we have chosen a use case where an application developed in Visual Builder Cloud Service (VBCS, or VB for short) triggers an integration in IC which then makes  several calls to FA. The results will be collected and returned back to the VB application for display. Here are the steps involved:

1. User logs into the VB application
2. VB requires data that can be obtained from an IC integration via a REST API
3. VB triggers integration using an API configured from the VB Service Catalog
4. Integration invokes FA REST API Using OAuth
5. Results returned to VB application
6. VB application displays results

NOTE:    The Identity of the Logged in VB User Must Flow End-to-End. Also, there must be an effort to utilize as many out-of-the-box features available in IC.

In order to accomplish the above, we are faced with the following challenges:

1. FA REST APIs require an OAuth JSON Web Token (JWT) with a subject (“sub”) claim
2. IC does not expose the inbound authentication header in integrations (e.g., JWT or Basic Authentication)
3. Cloud adapters/connections do not support dynamic authentication

The Solution

In a recent release of IC, the identity of the caller of the integration is available at runtime as part of the instance metadata.  We can use this identity to request an OAuth token on this subject’s behalf to invoke FA with.  This is somewhat complicated, requires some custom coding and a fair amount of configuration, but is feasible.

The key component to this solution is the creation of a trusted OAuth client which will make the access token request on behalf of the caller’s identity.  Oracle’s Identity Cloud Service (IDCS) provides a user assertion OAuth flow for this purpose.  However, IC does not currently have out-of-the-box functionality to support this so some custom coding is required to utilize it.

The diagram below highlights the steps involved to make the complete flow work:

Identity Propagation Pattern

Let’s review these steps in more detail.

1. A Visual Builder application has been configured to invoke an integration that was located via the Service Catalog.  When the application is executed, VB manages obtaining an OAuth access token to invoke the integration behind the scenes and invokes the IC API.
2. The IDCS user assertion flow requires a request payload be presented to the IDCS token API with 2 main pieces of information, one being the identity of the trusted IDCS client that is requesting the token and the other being the identity of the user on whose behalf IC is requesting a new OAuth token for invoking FA APIs.
3. A call is then made to the IDCS API with that information, and if approved, IDCS returns the appropriate JWT token.
4. IC then calls the FA API, passing the JWT in the Authorization header.
5. FA validates the token and returns the results.

Configurations

The following information describes the steps needed to configure and code the above identity propagation pattern.

IDCS Federation

The IDCS instance associated with your FA POD has to be federated with the IDCS instance associated with your OIC instance so that a user’s identity is common to both instances.  Federation enables single sign-on (SSO) between the two systems, providing a seamless user experience.  In this case, FA IDCS would be configured as the identity provider and OIC IDCS is a service provider.

The steps for federating the IDCS instances are described here.

OIC IDCS

In this scenario, the OIC Integration will act as a trusted application by the FA IDCS instance.  The integration will assert the identity of the user associated with the integration instance and request an access token on that user’s behalf.  This token is then used to invoke the FA endpoint.

Details on how to configure a trusted application in IDCS can be found here.

VB

When configuring VB to trigger OIC integrations, there are several Service Connection options and authentications that can be used.  In our example, we chose to Create a Service Connection from the Catalog.  This option provides everything we need in terms of triggering an OIC integration with the least amount of complexity/setup. The key takeaway for any Service Connection configuration in VB is that the connection is using an Identity Propagation Authentication Mechanisms.  If you look at the Server configuration for the Service Catalog connection you created, you will see it is using OAuth 2.0 User Assertion. This will allow us to access the calling VB user’s ID in the integration (details in the IC Integration section below).

At this point, all that is needed is to create a VB application and leverage the Service Catalog connection to trigger the OIC integration(s) that interact with FA.

OCI Function

The custom code to create the payload for the User Assertion flow has to be hosted somewhere and in this case we chose to use a serverless function.  The inputs to this function are the client identity that the access is being requested on behalf of as well as the scope that is being requested.

The function then uses these inputs to build the user assertion request payload.  Refer to the following documentation for additional information:

https://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/csimg/user-assertion-workflow.html

The main components of the user assertion request payload are two JWTs - one that confirms the identity of the calling trusted application and a second that conveys the user identity for the requested access token.  Both of these JWTs are signed by the trusted application.  This signature is authenticated by IDCS to confirm the legitimacy of the token request.

One consideration when creating this code is where to securely store the private key and certificate used to sign JWT tokens. One obvious choice when using OCI Functions is the OCI Vault service. 

IC Integration

When developing an integration that will need to propagate the calling user’s identity to FA, there will be a common set of steps:

1. Call the OCI function that generates the IDCS payload for User Assertion
2. Call the IDCS REST API with the payload from step 1 to obtain the User Assertion JWT
3. Call FA with the JWT from step 2

The call to the OCI function will require the user’s identity, and we can get that from a feature in IC Maps called Integration Metadata. Every IC instance contains a source in the Map Action with Metadata Details that include Integration Details, Runtime Details, and Environment Details:

In the Runtime Details you will see an Invoke By:

This Map Source contains the ID of the caller, or in this case, the logged in VB user. The Invoke By value will be passed to the OCI function to generate the IDCS payload for the IDCS User Assertion call:

When the payload is returned from the function, it is a string that is formatted appropriate for making the IDCS REST call (see example payload via cURL example here).  However, making a REST API call from OIC with a plain text payload may not be completely obvious.  Therefore, we have provided the following link to a blog that walks through the details on how to Invoke REST Endpoint With Plain Text Payload.

The IDCS call will return the JWT and the token is mapped in the FA REST API call to the HTTPHeaders > Authorization Target as a Bearer token:

All that is left is to call the FA REST API and you should receive the appropriate payload back from your invoke.  Your integration may require multiple calls to FA for the integration response, so the same JWT can be used for all REST API calls to FA.

Conclusion

While there is a bit of complexity involved in configuring this solution, including a bit of custom code, the end result to solve the use case is achievable.  One topic not included in this blog but should be a consideration for any implementation of this pattern is a JWT cache.  That is, whenever a user assertion JWT is requested the cache should be checked for a valid/non-expired JWT before making the IDCS call.  This will provide performance gains in IC and put less stress on IDCS.