A Simple Guide to Connecting ODA Custom Component to On-prem APIs

September 24, 2020 | 14 minute read
Shreenidhi Raghuram
Consulting Solutions Architect
Text Size 100%:


Often there are requirements from customers to connect their Oracle Digital Assistant (ODA) skills running on Oracle Cloud Infrastructure (OCI) to an on-premise API endpoint. 
This could be required for various use cases like 

  1. An ODA Skill to fetch user information from on-prem HRMS system like Oracle E-Business Suite (EBS)
  2. A chatbot to interact with on-prem ERP system like Oracle E-Business Suite (EBS)
  3. Integrate ODA Skills with APIs secured behind customer firewall for invoking specific business functions
  4. a skill that securely connects to on-prem banking system protected by custom authentication

There can be many more such scenarios where a chatbot needs to integrate in a hybrid environment. ODA provides Custom Components for users to connect their ODA skills to external endpoints. However, ODA requires that such endpoints are publicly available for ODA to connect.

In this blog, we will discuss the networking and security aspects of integrating ODA with on-prem endpoints. We will also see how OCI Networking and API Gateway provide tools to cater to various use-cases while securely integrating ODA custom components with on-prem APIs. These include

  • whitelisting access to on-prem APIs
  • legacy on-prem authentication
  • throttling requests to on-prem APIs
  • filtering on-prem API headers from ODA

Problems to address

  1. Whitelisting ODA source IP address on customer network's firewall
  2. Authenticating against on-prem API endpoint
  3. Protecting on-prem API endpoint by throttling requests

ODA IP Address Whitelisting 

The API endpoints that ODA needs to connect to could be residing in customer's on-prem network/datacenter behind a network firewall. These endpoints can be made accessible to specific sources by IP Address whitelisting on the network firewall.
However since ODA is an Oracle managed service, it runs within the Oracle Services Network. Hence, a single source IP address specific to an ODA service instance is not available for whitelisting. A region wide IP address can be used for whitelisting, however this may be too wide in scope. This limits the ability for customers to whitelist traffic originating from their specific ODA instance 

Authenticating against on-prem API endpoint

The on-prem APIs could be protected using basic authentication, OAuth, access-key validation or any other custom authentication. The objective is to connect the digital assistant to these legacy on-prem endpoints by using the API modernization features of the API Gateway in between.

The Solution

Now let us jump straight to the solution!
We will see how we can use OCI Networking constructs, API Gateway and IDCS to securely integrate ODA custom components to on-premise endpoints. Also, we will see that the solution is completely configuration based and does not require to write any additional custom code!

Figure below shows the overall solution 


The salient points of this solution are listed below for quick reference - 

  • The invocation from ODA Custom component to on-prem API is routed through API Gateway


  • VCN with Internet Gateway (IGW)and NAT gateway (NATGW) is created
  • API gateway is created on public subnet in the above VCN


  • Routing rules are configured to route egress traffic from API gateway to on-prem API endpoint only through the NATGW
  • The NATGW IP Address can be used to whitelist the traffic at customer network firewall
  • The remaining public internet traffic is routed by default through the Internet Gateway (IGW) 


  • API Gateway endpoint is protected by JWT Token validation using default IDCS instance as the OAuth Auth server
  • ODA uses System.OAuth2Client Builtin component to retrieve Oauth access token from IDCS 
  • ODA custom component passes the Oauth access token in its request to API gateway endpoint
  • API gateway strips off the Auth header after token is validated against IDCS
  • API gateway injects required basic auth or access-key credentials in the outbound request to on-prem backend endpoint

The subsequent chapters provide the details of the solution implementation
Continue to read on for the complete solution or feel free to jump to a specific section for reference.

Details of the Solution


We will build upon the existing ODA tutorial to demonstrate a solution using API Gateway to address these hybrid integration concerns.

The tutorial uses concepts from the ODA Backend Integration documentation.

The pic below shows how the interaction happens from ODA to public API over public internet


In the tutorial, an ODA custom component deployed in node-js container makes an http request call to fixer.io Currency Conversion API. The fixer.io API is protected using access-key validation.

The fixer.io Currency Conversion API is publicly available. However, we will use it as an example of on-prem API for simplicity in the extended tutorial solution of this blog.

The components required for the solution / Prerequisites 

As we shall see, IDCS can be used to configure inbound security at the API gateway level.

Details of implementing the solution 

As we saw in the overall solution above, an API Gateway is used to proxy the ODA custom component request invocations to on-premise endpoint. This is shown in the below diagram

basic solution


OCI Networking - setup

We will need a VCN and a public subnet to house the API gateway instance.

For simplicity, let us create the VCN using the VCN Wizard. Choose to create a "VCN with Internet connectivity"
This will automatically create a VCN that includes all of these

  •     VCN
  •     Public subnet
  •     Private subnet
  •     Internet gateway (IG)
  •     NAT gateway (NAT)
  •     Service gateway (SG)

This wizard will auto create the routing rules and security lists for internet connectivity through the Internet gateway (IGW)

During creation, make sure to create the VCN in the same OCI region as the ODA instance. This will ensure all traffic between services routes through the OCI backbone network.

Route Rules and NAT Gateway

The route rules for the VCNs routing table should be updated. The idea is to route all traffic destined for the on-prem endpoint via the NAT gateway. All other public internet traffic can continue to route through the Internet gateway. Sample route rules to achieve this are shown below.

NATGW routing

Note that the NATGW's public IP can now be used for whitelisting traffic on the on-prem network firewall
NATGW public IP address


API Gateway - creation

Next, create a public API gateway as shown below by selecting the VCN and Public subnet created in the previous step.

create gateway

Within the API gateway, create an API deployment to accept requests from ODA skill and forward them on to the backend API. For demonstration purposes, we will choose a publicly available Forex conversion API from fixer.io as our backend endpoint.

Here is how a simplest API deployment will look like.

basic API Deployment


Backend authentication using API gateway request transformation

Add a request policy to the API deployment for the header transformation.

The below diagram shows transformations which do the following

  1. Block the incoming Authorization Header at API gateway  
  2. Add a new query parameter to embed fixer.io access-key in the outgoing request to on-prem API

This change is required for the tutorial example. For the tutorial example, the fixer.io access-key is injected in API Gateway using this header transformation.

API gateway request query parameter and header transformation policy

In case the backend API is protected using basic authentication, then a Set Header with Overwrite policy as below can be used to block the incoming credentials and embed backend credentials in the outgoing request.

API request policy for basic auth header injection

Note that these request response policies are part of the new API gateway feature for performing Request Response Transformations.
Learn more about this feature at - APIGW Request Response Transformation


IDCS Client App 

Let us now configure IDCS Client Application. 
The Client app configuration will be used by ODA to retrieve a valid JWT Access token for authentication of requests into API gateway. For the purpose of this extended tutorial, we will use the client credentials grant type. Other Oauth flows are left as an exercise for the reader.

Refer - Adding a Confidential Application to create a client app on IDCS. Choose the required grant types. For this example, Client Credentials Grant type is chosen for retrieving JWT access tokens.

Shown below are relevant screenshots of IDCS Client App configuration

IDCS Client App - Client Configuration

IDCS Client Aplliaction - Resources section

At this stage, one can issue a curl command similar to below to test that a valid access token is returned from IDCS

curl -u "CLIENT_ID:CLIENT_SECRET" -X POST 'https://IDCS_HOSTNAME/oauth2/v1/token' -d 'grant_type=client_credentials&scope=PRIMARY_AUDIENCE+IDCS_SCOPE'



The scope value passed in here is the concatenation of Primary Audience and Scope values configured in IDCS Client Application.

ODA Authentication Service

With the IDCS client app configured and tested, we are now ready to wire this information with ODA so the skill can retrieve an access token at runtime from IDCS. This is done by configuring an Authentication Service in ODA console.
Navigate to Settings-> Authentication Services and create a new Service.

The values needed for the Authentication Service are all available from the IDCS Client App configured in previous step.
See Screenshot below for a reference of ODA Authentication service

ODA Authentication Service for Client Credentials flow

JWT Authentication of API gateway endpoint

Next we need to secure the APIGW endpoint using JWT validation. Refer here to learn more about API gateway's JSON Web Token (JWT) validation authentication policy and how it can be applied to API deployments - JWT Authentication policy

The JWT Authentication policy works with various identity providers. Here we use the IDCS as the identity provider. The Authentication policy requires IDCS configuration to be able to validate the JWT token issued by IDCS. Screenshot below shows configuration of a JWT Authentication policy for the API deployment created earlier.

API Gateway JWT Authentication Policy


Finally, the NATGW's public IP can be used for whitelisting traffic on the on-prem network firewall.

NATGW public IP address can be used for whitelisting at customer network firewall

This is usually done by a network admin of the on-prem network

ODA Code changes to tutorial sample code

At this point we can go ahead and complete the coding steps of the "Create Custom Components to Integrate with Backend Services" ODA tutorial.

Note these key code changes from the original tutorial while implementing the below sections for this extended tutorial.

1> section "Import the Tester Skill"

Once the Skill jar is imported into ODA, edit the dialog flow and make the following changes 

  • Add Context variable "idcsAccessTokenValue" of type string to the Context Variables

This context variable is used to hold the value of Oauth Access token retrieved from IDCS.
Refer to the screenshot below which shows the dialog flow snippet before and after adding the context variable

Add Context Variable to dialog flow

  • Add an additional property "idcsCCToken" for complete.training.CurrencyConverter custom component as shown below

   Code snippet shown in screenshot below 

Add new property to custom component in dialog flow

2> Add the "Oauth2 Client Credentials" Component to dialog flow

On the dialog flow editor page of the Currency Converter skill, choose "+Component" button to add a new component to the dialog flow. Choose Security for type of component. Select the "Oauth2 Client Credentials". Insert the new snippet after "getConversion" component
Change the code snippet in the wizard to refer to the new context variable "idcsAccessTokenValue". Also add a new transition to transition to "Converter" component, as shown below
Add Security Component to dialog flow

    component: "System.OAuth2Client"
      # authenticationService (required) is the name of the Authentication Service to be used.
      authenticationService: "idcs_wt_validation"
      # accessTokenVariableName (optional) allows you to override the name of the variable holding access token. If not set, access token will be stored in variable called clientAccessToken, by default.
      accessTokenVariableName: "idcsAccessTokenValue"
    next: "converter"

Also, remember to change the "next" transition of getConversion component to "oauth2Client"

3> section "Build the fixer.io Request URL"

In this section, the below code change is made to send the request to API Gateway instead of directly to fixer.io

  • Include the new property for access token in the propety declarations 
idcsCCToken: {required: true,type: 'string'}
  • Assign the new property with value from the context variable idcsAccessTokenValue
const { idcsCCToken } = conversation.properties(&quot;idcsAccessTokenValue&quot;);
  •     Modify the request URl to point to API gateway deployment created i previous section.
//var reqUrl = "http://data.fixer.io/api/latest?access_key="+fixerIoAPIKey + "&base=EUR&symbols=" + tmpTargetCurrencies;
var reqUrl = "https://<API-Gateway-hostname>/<deployment-context root>/<route>?base=EUR&symbols=" + tmpTargetCurrencies;
  •     Make sure to replace the API gateway hostname, deployment and route to complete the API url in the above code snippet.
    • Tip: The API Gateway deployment url can be externalized to the ODA skill's Custom Parameters. Refer documentation - Custom Parameters
  •     Make change to pass the Oauth access token as a Bearer token in Authorization header, as below
//request(reqUrl, {json: true }, (err, res, body) => {
request(reqUrl, {json: true , auth : {'bearer' : idcsCCToken, 'sendImmediately' : true} }, (err, res, body) => {

These complete the ODA custom component code changes to repoint the callout from ODA custom component to API Gateway !

ODA Skill test

With the above changes incorporated in the ODA Backend integration tutorial, we are now ready to test the Currency Converter skill using the Skill tester. The sample conversation shown below demonstrates ODA retrieving a valid Oauth JWT access token from IDCS, passing it to the backend invocation to API gateway.
The API gateway authenticates the JWT token and routes the request to legacy on-prem backend API endpoint which could be behind a customer firewall. The API gateway also helps transform the request (headers and query parameters) by injecting the required credentials to authenticate against the on-prem endpoint.

ODA skill tester screenshot


We have seen in this blog how using OCI constructs along with ODA, we are able to securely call on-prem endpoints from a Digital Assistant's conversation. It is particularly powerful to be able to integrate legacy on-prem endpoints with modern conversational interface to execute business functions.



Let us now briefly discuss a few side topics we touched upon in the blog above

Throttling requests to on-prem endpoints

The API gateway can be used to protect the on-prem backend APIs by limiting the rate of requests. This can be done by suitably configuring throttling policies on the API gateway deployments. Refer here for limiting number of requests to API gateway back ends.

Invoking private on-prem endpoints from ODA using Oracle Integration Cloud (OIC)

As we saw, the discussion in this blog is mainly to cater to APIs hosted within customer's network, assuming these are accessible publicly behind a network firewall. 

This section provides a brief outline for options to connect on-prem private endpoints with ODA.

Oracle Integration Cloud (OIC)  can be used to connect ODA to an on-prem private endpoint running within customer network. Here, an OIC connectivity agent is installed within customer network. The agent executes by pulling down requests from OIC, executing them locally and then passing back the response to OIC, which eventually flows back to the digital assistant.

This is shown in the diagram below.

OIC for private endpoint connectivity


Shreenidhi Raghuram

Consulting Solutions Architect

As a member of Cloud Solution Architects A-Team, my area of work involves SaaS, PaaS4SaaS and IaaS. My work focuses on Solution architecture involving Fusion Supply Chain Management (SCM), Integration, Extensions, High Availability, Security, Infrastructure, Hybrid Cloud and Networking aspects of Oracle cloud solutions.

Previous Post

How to bring Azure AD users and groups into IDCS

Manasi Vaishampayan | 2 min read

Next Post

User and role synchronization options for Oracle Applications Cloud

Mani Krishnan | 1 min read