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
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
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
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.
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 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.
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.
As we shall see, IDCS can be used to configure inbound security at the API gateway level.
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
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
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.
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.
Note that the NATGW's public IP can now be used for whitelisting traffic on the on-prem network firewall
Next, create a public API gateway as shown below by selecting the VCN and Public subnet created in the previous step.
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.
Add a request policy to the API deployment for the header transformation.
The below diagram shows transformations which do the following
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.
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.
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
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
At this stage, one can issue a curl command similar to below to test that a valid access token is returned from IDCS
The scope value passed in here is the concatenation of Primary Audience and Scope values configured in IDCS Client Application.
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
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.
Finally, the NATGW's public IP can be used for whitelisting traffic on the on-prem network firewall.
This is usually done by a network admin of the on-prem network
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.
Once the Skill jar is imported into ODA, edit the dialog flow and make the following changes
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
Code snippet shown in screenshot below
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
Also, remember to change the "next" transition of getConversion component to "oauth2Client"
In this section, the below code change is made to send the request to API Gateway instead of directly to fixer.io
These complete the ODA custom component code changes to repoint the callout from ODA custom component to API Gateway !
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.
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
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.
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.