The Visual Builder Cloud Service Blog

  • May 13, 2020

Visual Builder Identity Propagation Setup with SaaS

Aparna Gaonkar
Product Manager

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:

  • Identity Propagation - refers to the ability of the application (mobile or web) to pass on the identity of the user who has logged in to the application to a service being called.  At a very high level this is made possible by the two applications (client and the resource) trusting each other and 'asserting' the user's identity whenever required.  Identity Propagation is different to Fixed Credentials in which the service being called sees the same credentials no matter who has logged in, which is illustrated in the below figure

  • OAuth 2.0 - is an authorization protocol that allows a client application to get access to resource applications services either on behalf of the client application or on behalf of a particular user by orchestrating a flow of interactions between the client application/user and the resource application.  The access is typically encoded in a JWT token format.  OAuth 2.0 consists of a number of grants which allow a variety of use cases.  A client application in OAuth 2.0 is typically recognized by its client id and optionally has a client secret.  Another important construct in OAuth is the scope, which limits the access that the client application is allowed - i.e. "profile/me" allows access to the me endpoint only, "/sales" allows access to the entire sales resource.
  • Visual Builder relies on Identity Cloud Service (IDCS) for all its identity propagation use cases and these are carried out by various OAuth flows - especially one known as "JWT Assertion/User Assertion" flow. 

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 :

  • SSO setup (using SAML)
  • OAuth federation setup
  • Extra OAuth federation step for VB
  • Synchronization of users and optionally roles between IDCS and SaaS

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 )


SSO setup

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.

OAuth based federation setup

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

Extra OAuth step for VB

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.  


Synchronization between IDCS and SaaS

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

  • Not able to download the IDCS signing certificate - By default, you will not be allowed to download the IDCS signing certificate.  In order to allow this, go to IDCS -> Settings -> Default settings -> Enable Access Signing Certificate
  • Not able to see option to add the scope to the VB instance - this is basically your user lacking Application Administrator privileges in IDCS.  Once you get these, you should be able to see the relevant button
  • Getting a scope related error while testing Service Connection  - This indicates that the Visual Builder instance either doesnt have the correct scope OR the resource applications that represent the scope are not correctly configured.  Things to check are as below:
    • Make sure that the resource applications (FA1 and FA1:443 in our examples) do not have the forward slash '/' in their primary audience, and have the '/' in the scope
    • Both resource applications should have been made "Trusted" and the OWSM certificate given by Oracle support should be added to both
    • Make sure that the Visual App in which you are testing the Service Connection is created after the whole setup was done







Join the discussion

Comments ( 1 )
  • Sunil Polineni Tuesday, May 26, 2020
    Nice Article
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.