The Visual Builder Cloud Service Blog

  • April 8, 2019

Visual Builder Service Connections - Advanced topics

Aparna Gaonkar
Product Manager

Service Connections are Visual Builder objects to represent REST API calls.  They are pretty much intuitive, and if you have used Postman or SOAP UI like tools to test web services, they will seem familiar, and yet there are some differences from these tools.  The aim of this blog post is to lay down some of the more advanced concepts around Service Connections.  For an introduction to Service Connections, refer to this blog

If you have created a Visual Builder application that makes REST calls, you might have used a Service Connection by passing on an endpoint in a “Call Rest Endpoints action” in an action chain, or used them implicitly in a List or a Table that internally uses the same action.  When such an action is performed, there are two broad strategies to connect to REST APIs via Service Connections:

  • Using the browser/client JavaScript to connect to the API
  • Using the out-of-the-box VB Proxy to connect to the API

Using the browser/client JavaScript to connect to the API

In this, the request goes directly from the browser/mobile device to the External service as shown in the below figure:Direct call from client (browser JavaScript) to external API

 It is similar to having Fetch API call from within your application’s client side JavaScript code as below:

For simplicity we will call this browser JavaScript based method as “Direct” in the remainder of this post.

Using the VB Proxy to connect to the API

The VB Proxy is a server component of Visual Builder that can facilitate REST calls.  In this method, for every call, the request first goes to the Proxy, and then to the actual service being called. 

Proxy based call to external API


What to choose : Direct or Proxy?

Now, you may wonder which method to choose when calling a specific external service from Visual Builder.  There are some detriments to using the Proxy; namely it proxies each and every request, hence adding some extra latency.

However there are cases, where Direct might not be the appropriate way to call your service as governed by the following three factors:

  1. Authentication method
  2. CORS support
  3. HTTPS support

1. Choice of Authentication method

Some authentication methods are not suitable for directly calling the server from the browser, because the credentials used by these can be exposed in JavaScript.  For example. if you want to call an external service using Basic authentication, Direct wouldn’t be the right way at all, because the credentials to the service will be exposed to the client side JavaScript.  A quick look at the Network tab will also enable the users of your app get a hold of your external service credentials!

Basic Auth credentials visible




In general, Visual Builder doesn’t allow such combinations, thus protecting your application from any misconfiguration on part of the developer that could inadvertently leak credentials.  If you choose “Basic” in the authentication method of a Service Connection, the requests always go via the proxy (as shown below) and the Basic Auth credentials are applied at the proxy only, never being exposed to the client. 

Basic Auth via Proxy

Authentication methods suitable for Direct

For OAuth 2.0 based mechanisms (Client Credentials, Resource Owner Password, User Assertion OAuth) and for Oracle Cloud Account, you have an additional checkbox “Enable token relay” that specifies if the call is to made directly.    Unlike Basic Auth, these methods are safe to be called directly, because the credentials required for creating the token (username, password, client id, client secret) never travel to the client.  This is facilitated by another VB server side component called the Token Relay, which is in knowledge of these credentials, and creates the appropriate token, but only passes the final token to the client side and never the credentials that were used. 

OAuth via Token Relay

What if you have some custom JavaScript code that gets a bearer token through some process, and your requirement is only to pass the bearer token as-obtained to the Service Connection? In such cases of DIY authorization, you cannot use the VB Proxy as the it is designed strip off any Authorization header that is coming from the client, and re-insert the proxy configured Authorization headers.  To achieve this case, you can use “Direct” and give a dynamic “Authorization” header to the Service Connection endpoint as shown in the figure below.  Here an accessToken is obtained from some custom JavaScript code and then passed in via the dynamic header "Authorization" to the REST API.  Note that in this case the responsibility of maintaining the secrecy of the credentials procuring the token falls on you.  

Configuring Dynamic Authorization using Direct


2. Available CORS support

Further, there is another complication of Cross-Origin requests when calling services directly as opposed to via a proxy.  The browser is considered as an insecure environment, hence it blocks any external services that are being called with a domain that is different from the calling domain.  For example, if your app is running on domain vb.oraclecloud.com and your service is running on domain service.example.com, the browser first checks if the service.example.com domain has deemed JavaScript code served from vb.oraclecloud.com as allowed to call these services.  This is formally known as a CORS pre-flight request and consists of an OPTIONS call from the application to the service which returns several Access-Control-Allow-* headers.  From the value of these headers, the browser draws the conclusion whether or not the call to the external service is allowed (See wikipedia for a full description of CORS). 

For such Cross-Origin requests to be allowed, you should have set the domain vb.oraclecloud.com in the CORS whitelist of service.example.com.  Note that this is a setting purely to be done on the remote server and not on Visual Builder.  If you have not set the Visual Builder domain (vb.oraclecloud.com for our example) in the CORS whitelist of the external service, you would get a pre-flight error in the browser console as follows “Access to fetch at 'https://service.example.com/service' from origin 'https://vb.oraclecloud.com' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource”.  The behavior of such a Service in the Test tab and the full CORS preflight error in the JavaScript console are shown below

CORS error

CORS Preflight error


Most modern resource servers support some sort of CORS configuration, or you could also set them programmatically.   However, in the case your external service doesn’t support CORS (or if you are unable to do this for some reason), you would need to call the service via a proxy.

As an example, the Oracle Content and Experience Cloud have a facility in which an administrator can configure Allowed Origins.  In the example below, the Visual Builder domain is vb.oraclecloud.com, and that it is allowed to call REST APIs belonging to this Content and Experience Cloud Instance servers directly.  You should consult the documentation for the API being called to know it supports CORS.

Example CORS settings from Content and Experience Cloud whitelisting VB domain


This is one of the differences between calling a Service via Postman or SOAP UI and via VB Service connections.  You will never get a CORS pre-flight error from Postman, as you are not calling from one domain to another.  Mobile apps (native/hybrid) installed on a device are also exempt from CORS,


3. HTTPS Support

Another requirement of direct calls is that they must be strictly HTTPS.  Though Visual Builder recommends HTTPS based Service connections only, for development purposes it is possible to use HTTP connections if their authentication mechanism that can be proxied.   Direct calls using HTTP will result in errors.

If your external service has an HTTPS certificate that doesn’t have a fully valid CA (like a self-signed certificate), it will reject requests, results in errors.  This is a common scenario during development.   In case of direct connections, the browser will give out an error, and the resolution requires the browser to trust the certificate (import certificate into every browser where you test this app).  If the connection is via a proxy, you can import the certificate into Visual Builder.  An example scenario is shown here.


Configuring Direct/Proxy

Configuring either of these two alternatives is not really a direct setting on the Service Connections, but actually a function of the selected authentication mechanism and some other bits, as shown below:

* On the table below, “May have CORS issues” refers to the CORS-related scenarios explained above - i.e., when JavaScript code running on the browser makes a Rest call to a server that is not configured to allow such calls.


Service Connection Authentication settings

Direct / Proxy

Typical Scenario

No defined authentication


  • No Authentication
  • May have CORS issues
  • Requires HTTPS



  • No Authentication
  • Avoids CORS issues
  • Allows HTTP



  • Basic Authentication
  • Avoids CORS issues
  • Allows HTTP

Oracle Cloud Account, Token relay unchecked


  • Authentication for calling services from the Service Catalog
  • Avoids CORS issues
  • Allows HTTP

Oracle Cloud Account, Token relay checked


  • Authentication for calling services from the Service Catalog
  • May have CORS issues
  • Requires HTTPS

Any OAuth 2.0 methods, Token relay unchecked


  • OAuth 2.0 Authentication
  • Avoids CORS issues
  • Allows HTTP

Any OAuth 2.0 methods, Token relay checked


  • OAuth 2.0 Authentication
  • May have CORS issues
  • Requires HTTPS

Direct – Bypass proxy


  • No Authentication or authentication handled by the client code
  • May have CORS issues
  • Requires HTTPS

Propagate Current User identity


  • Authentication for calling services from the from the pre-defined catalog, using the OAuth Implicit flow
  • May have CORS issues
  • Requires HTTPS

Join the discussion

Comments ( 4 )
  • Ashok Tuesday, June 11, 2019
    Interms of using the VBCS proxy, is there a max throughput/concurrent connections limitation that one should be aware of?
  • Shay Wednesday, June 19, 2019
    There isn't a hard coded or licensing imposed restriction on the number of connections.
  • Radha Tuesday, June 2, 2020

    I am trying to configure the service connection (REST API) with a third party custom application and it only accepts the 'Bearer Token' as the authentication method.
    As per this document, I created service connection with Dynamic Header to pass the Authorization, but it does not work. gives this error

    Cannot process service scope \"{Server}/\" in IDCS


    gives the below error.
  • Aparna Gaonkar Wednesday, June 3, 2020
    Hi Radha,

    When we say "Bearer token" authentication we indicate that an auth token is passed into the HTTP Authorization header in the call to the REST API. However, there is also a process by which the auth token is obtained, typically through OAuth 2.0 grant types. If you go to Service Connections -> Server -> Authentication, you should be able to see a number of OAuth 2.0 grant types, and you should choose one which your REST API supports. These will automatically inject the auth token in the Authorization header when the REST call is made. For more information/questions on this you can connect with us on https://cloudcustomerconnect.oracle.com/ -> Forums -> IaaS And PaaS -> Visual Builder
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.