When building applications in Oracle Visual Builder, you may often need to connect to REST APIs exposed by other Oracle Cloud services. While Basic Authentication (using a static username and password) is straightforward and supported in Visual Builder by configuring a Backend with Basic auth, it is generally not recommended for production scenarios. For REST APIs that are governed by Oracle Identity Cloud Service (IDCS) / Identity Domain, a more secure and robust approach is to use OAuth 2.0 based authentication, which is the recommended best practice for token-based, standards-compliant access.
Visual Builder supports multiple OAuth grant types (Resource Owner Password Credentials, Client Credentials, User Assertion), but here we will focus on OAuth 2.0 Resource Owner Password Credentials, which is popularly supported by most cloud services like Oracle Integration Cloud, Oracle Process Automation etc. OAuth 2.0 Resource Owner also doesnt require that VB and the REST system are in the same identity domain unlike OAuth 2.0 User Assertion. This blog will guide you through the process of setting up OAuth 2.0 Resource Owner Password Credentials (ROPC) for accessing another Oracle service's REST API from Oracle Visual Builder, using Oracle Identity Cloud Service (IDCS) or the Identity Domain Console. The methods of OAuth 2.0 Client Credentials and OAuth 2.0 User Assertion would be slightly different and are discussed at the end of the blog
1. Understand OAuth clients and OAuth resources
Within IDCS/Identity domain, OAuth is configured through applications which can be represented as OAuth clients, OAuth resources or both.
- OAuth clients can have client id/secret, various grant types they support – like OAuth 2.0 Resource Owner or OAuth 2.0 Client Credentials, and fully qualified scopes they are allowed to get a token for.
- OAuth resources represent REST API audiences and scopes. The primary audience and the scope together form the fully qualified scopes that OAuth clients connect to.
Thus for an OAuth client in IDCS/Identity domain to connect to an OAuth resource, the fully qualified scope of that resource should be added to the OAuth client.
2. Locate the OAuth resource in IDCS/Identity domain
With that background in mind, let's say you need to connect to an Oracle Integration Cloud (OIC) instance's REST API with OAuth 2.0 Resource Owner Password. (Note that OIC is just an example here, any Cloud service that is governed by Identity domain/IDCS can be connected to in a similar fashion. For OIC specifically, in most cases, OIC and the VB runtime instance will be co-provisoned and use the inbuilt authentication method Oracle Cloud Account, where there is no need of any manual setup). First navigate to the Identity domain (or IDCS) of this OIC instance. You will need Identity domain administrator privileges to do this. In this Identity domain, the OIC instance should be represented as an application provisioned by Oracle. You can find this in the "Oracle Cloud Services" section of the console. For manually created resources, you may have to look in the "Integrated Applications" section of the Identity Domain
Typically, the Oracle auto-provisioned applications should be represented as an OAuth resource and an OAuth client. You can find this by clicking edit and then navigating to "Edit OAuth configuration"
Expanding the resource server section will show you a primary audience and a scope
The primary audience and the scope together make the fully qualified scope that the OAuth resource advertises to the clients.
Fully qualified scope in the example = https://2FxxxxxEF.integration.ocp.oraclecloud.com:443urn:opc:resource:consumer::all
In the OAuth configuration, the general information section would show you details about the OAuth client that this application is configured to be. You can see the client id, secret and the grants it can use
3. Create an OAuth Confidential client application for ROPC (Recommended)
Now, you may use the auto-configured application's client id/secret to use in VB, and it would work; however using the auto-provisioned client id/secret for use from other applications is a not recommended. If you want to deactivate the client for any reason, you would effectively need to deactivate the entire OIC instance. Therefore it is prudent to create a new OAuth client specifically for the purposes of connecting to this REST resource from VB
From the Integrated Applications section, create a new application (select type Confidential), and register it as an OAuth client. Dont register it as an OAuth resource.
Allow the grant types – OAuth 2.0 Resource Owner Password, OAuth 2.0 OAuth Client Credentials. Typically most Oracle cloud services work well with OAuth 2.0 Resource owner password; consult the relevant cloud service documentation for more.
In the token issuance section, check "Add resources". Then click on "Add scope" and proceed to add the scope(s) that you are interested in, typically the "urn:opc:resource:consumer:all" scope is what is needed, or you may have a narrower scope.
Once this is added save the application and activate it.
Navigate to the OAuth configuration section, and note down the client id and secret
4. Test the OAuth token generation
At this point, you have the below:
client Id, secret – from step 3
scope – from step 3
Token URL – typically https://<idcs-host>/oauth2/v1/token. (Note the IDCS host could be different than the OCI IAM host)
For ROPC, you will also need the username and password of a valid user who can access the REST API in question.
With all of these available, check if you can generate a token from postman or by using the curl.
POST https://<idcs-host>/oauth2/v1/token Content-Type: application/x-www-form-urlencoded Authorization: Basic <base64(client_id:client_secret)> grant_type=password& username=<USERNAME>& password=<PASSWORD>& scope=<scope>
A successful 200 response will have an output similar to
{
"access_token" : "eyJ4N...",
"token_type" : "Bearer",
"expires_in" : 3600
}
5. Test whether the REST system accepts the OAuth token
Next step is to check whether a simple REST API (from OIC in this example) accepts the token and returns a successful response.
GET https://<OIC-host>/<rest_of_path> Authorization: Bearer <access_token>
6. Configure Backend in VB
Once you establish that (a) IDCS is able to generate a token for the required scope and (b) the REST API accepts the generated token, you are ready to use the same in VB. Navigate to Services -> Backend and create a backend representing the REST system you are connecting to. Here we are connecting to OIC, so we will create a backend of type "Integration Applications" (in other cases you can use "custom" backend), URL = OIC host URL (just the host URL is recommended for the backend), Authentication = OAuth 2.0 Resource Owner Password, and provide the other attributes of this authentication type (client id, secret, token URL, scope, username, password). Now you can create any service connection on this backend.
Using OAuth 2.0 Client Credentials
OAuth 2.0 Client Credentials doesnt need a username and password and is mean for app-to-app authentication. Some REST resources may not work with a token obtained with this grant type as there is no user in context.
For using OAuth 2.0 Client Credentials, the steps remain the same as ROPC, with the following differences
Step 3 – Allow the OAuth client application to use OAuth 2.0 Client Credentials grant type
Step 4 – The token generation would differ according to the Client Credentials grant
POST https://<idcs-host>/oauth2/v1/token Content-Type: application/x-www-form-urlencoded Authorization: Basic <base64(client_id:client_secret)> grant_type=client_credentials& scope=<scope>
A successful 200 response will have an output similar to
{
"access_token" : "eyJ4N...",
"token_type" : "Bearer",
"expires_in" : 3600
}
For more details on Client Credentials, consult here
Step 5 – Like ROPC, always check if the generated token works for the REST API in question.
Using OAuth 2.0 User Assertion
OAuth 2.0 User Assertion can only be used when VB and the REST resource are in the same Identity domain
In this case, there is no need to create a client application since User Assertion will automatically use the visual app's client details. You can directly use the scope after Step 2, and any client id / secret, token URL should not be provided. The easiest way to test this is directly from VB via a Service Connection and see if it works.