Visual Builder is commonly used to build applications leveraging REST APIs from Oracle (Fusion Application) SaaS like HCM, CRM and ERP. A frequent scenario we come across in this space is the Identity Propagation from Visual Builder to SaaS via REST APIs. In this blog we discuss on a high level the setup that goes into configuring this, which is mostly done in IDCS and SaaS.
EDIT - Note that if your SaaS instance has been pre-provided with an Identity Cloud Service, and your VB instance is also using the same Identity Cloud service, all the configuration needed for identity propagation between SaaS and VB will be automatically configured. You would only need to add any synchronization (see Synchronization between IDCS and SaaS section in the blog) and configure the SaaS instance as a backend in the VB Tenant Catalog
The remainder of the blog assumes that you dont have a pre-configured IDCS instance. This is not meant to be a detailed step-by-step documentation (which is already published here ), but is meant to demystify certain parts of the setup and serve as a checklist, so that the developer knows the different purposes of the configuration.
First, a few concepts:
Now we start our setup to achieve Identity Propagation between VB and SaaS. Note we refer to SaaS and FA (Fusion Apps) interchangeably in this blog.
Broadly the setup is divided into four areas :
It is recommended to read this entire blog to have a high level picture first and then implement the detailed steps given in the official documentation
Before we begin, we are considering the following fictitious example:
SaaS instance - https://abc.fa.oraclecloud.com
SaaS REST API which we want to connect from VB - https://abc.fa.oraclecloud.com/crmRestApi/resources/latest/accounts
IDCS instance which we want to federate with SaaS - https://idcs-def.identity.oraclecloud.com
VB instance we want to achieve the federation in - https://vb1-tenant1.builder.ocp.oraclecloud.com (in case of VB available through Oracle Integration Cloud / OIC, this would be the same as the OIC instance - e.g. https://ic1-tenant1.builder.ocp.oraclecloud.com )
Single Sign-on (also called Web based SSO) allows us to use a single login and authentication provider for multiple sites and systems. The most popular way to do this is by using SAML (Security Assertion Markup Language) in which one system is designated as an Identity Provider (IDP) and the other system is known as the Service Provider (SP, also called Relying Party in some literature). Put simply, the SP will allow a user to access its resources like web pages, if the user is deemed to have been authenticated by the IDP. This mechanism relies on cookies and browser redirects to move information from SP to IDP and back to the SP once authentication is done. The SAML based setup requires some metadata and certificates to be exchanged between the SP and IDP - i.e. the SP metadata needs to be uploaded in the IDP and the IDP's metadata needs to be uploaded in the SP
In our case, we have two distinct systems, IDCS (and thereby VB) and SaaS, which has its own Identity Provider. Most of the customers opt for a setup with SaaS as the IDP and IDCS as the SP for SAML setup (although the reverse is also possible)
The high level flow for this setup is as shown below. Each step is carried out in either IDCS, SaaS, VB which is also shown in the diagram
Note the final step requires that you create an SR to hand the further steps to Oracle Support. The OAuth Federation setup also requires a similar SR, so it is recommended you log a single SR for both (as given in the official documentation)
After the SR is completed, you can Activate the federation and also setup synchronization between SaaS and IDCS. Note that you would need to setup the synchronization to at least have some users to test the same.
SAML based SSO is good, but it requires cookies and redirects - that is, it always needs to be carried out in a browser based environment. What if you need to call a REST API from one app to another without relying on a browser redirect? Here is where OAuth based federation comes to our rescue. This is different that SAML based SSO in that it doesnt require the flow to execute on a browser. This is achieved by an "access token" (typically an JWT token) which is added to the Authorization HTTP header while calling the REST API. The access token is special it that it encodes the information about the user as well as a signature that ensures that a given Identity Provider has authenticated this user.
VB requires that you configure OAuth setup with SaaS as well. Below is the diagram that shows high level steps to do so
At this point (step 5b) you need to log an SR (it can be the same SR logged earlier) to add the IDCS signing certificate in SaaS to establish trust between SaaS and IDCS. Once the SR is complete, you will receive an OWSM certificate which you need to upload to the FA1 IDCS application
There is an extra step needed specifically for VB and SaaS integration. You need to create an IDCS OAuth Resource + Client application similar to FA1 with a small change in the Primary audience - instead of https://abc.fa.oraclecloud.com, you should have https://abc.fa.oraclecloud.com:443 (i.e. :443 appended at the end of the SaaS base URL). Make this a trusted application too, uploading the same OWSM certifcate
Almost done! After both FA1 and FA1:443 are made trusted applications and activated, configure the Tenant catalog in VB by logging as an administrator and going to (tenant) Settings -> Services and adding an "Oracle Cloud Applications" backend (see Case 3 in this blog) with authentication "Oracle Cloud Account". If you do the optional settings of adding the VB origin (https://vb1-tenant1.builder.ocp.oraclecloud.com in our example) to the CORS allowed-origins in SaaS. you can use the connection type - "Dynamic supports CORS", else you would need to use the other two connection types. (To know more about CORS, 'Direct' and 'Proxy' based flows in VB, refer to this documentation)
With this setup complete, you can start creating Visual Applications with Service Connections to SaaS configured with "Oracle Cloud Account" provided you have some federated users in IDCS to login and test. If you dont have federated users, go to the synchronization task.
The last step that we need to do is to create a bridge between SaaS and IDCS which will synchronize all relevant users and roles to IDCS. For this we need to create a new IDCS OAuth client application which has admin privileges i.e. can create users and roles within IDCS. Then we configure SaaS with the ability to use this client application (by providing its client id and credentials) in a Task that is scheduled to run immediately or repeatedly based on your use case
Once this is done, all relevant users in SaaS will start appearing in IDCS as federated identities. Roles in SaaS will be migrated to IDCS as groups.
Note that synchronization can be also configured from IDCS to SaaS, which we are not depicting here. You can refer to the official documentation for more details.
Now that you have a high level idea, you can follow the detailed step-by-step guide for establishing SSO and federation between IDCS and SaaS. Note that the documentation doesn't have the extra step for VB mentioned here, which you would need to do as well.
To test the setup, you would need to create a Service Connection to a SaaS REST API either from a Catalog, or an endpoint or using the specification, and set its authentication as "Oracle Cloud Account". We recommend a Connection Type of "Dynamic - supports CORS" - which will work if you had followed the best practice of adding the VB origin to the CORS allowed-origins in SaaS, else you can set it up to "Dynamic - does not support CORS". Reminder, creating the Service Connection from Catalog requires you to setup backends first.
Here are some of the issues commonly encountered during this setup