Accessing private resources with Oracle Digital Assistant

With the introduction of Oracle Digital Assistant release 23.04 it is now possible for a Digital Assistant instance to access resources which are not publicly accessible from the Internet.

Such resources can be located in an Oracle Cloud Infrastructure Virtual Cloud Network (VCN) or running in an on-premise environment or within other data centers.

Like other public services running in Oracle Cloud Infrastructure, Oracle Digital Assistant now supports the private endpoint feature. At this moment Digital Assistant provides outbound connectivity to private resources. However, unlike other services supporting the private endpoint feature, exposing a Digital Assistant instance itself as the private resource in a VCN for inbound calls is not yet supported.

 For more information

About ODA Private Endpoints

An ODA private endpoint is a private resource provisioned within your VCN and represents the Oracle Digital Assistant in this VCN. The Digital Assistant service sets up the private endpoint in a subnet of your choice within the VCN. You can think of the private endpoint as just another VNIC in your VCN. You can control the access to it like you would for any other VNIC: by using security rules. However, the service sets up this VNIC and maintains its availability on your behalf. You only need to maintain the subnet and the security rules. ODA private endpoint also supports specifying Network Security Groups when creating private endpoint. Use a private endpoint to connect to REST services running on-premises or within Oracle Cloud Infrastructure VCN using built-in Call REST Service component.

You can create an ODA private endpoint, associate it to one or multiple ODA instances and create SCAN proxies by means of any of the following:

• OCI Console
• One of the available OCI SDKs – there are SDKs for Java, Python, and a few other languages
• OCI CLI (Command Line Interface)
• Terraform using OCI Provider

Set Up a Private Endpoint

To set up a private endpoint for Digital Assistant, you follow these general steps:

1. Make sure that you have the required permissions to configure private endpoints and attach them to Digital Assistant instances.
2. If you don’t already have them in place, on the OCI Console, create a virtual cloud network (VCN) and its associated resources, including:
   • At least one subnet.
   • Route tables to route the traffic through the subnet to its destinations.
   • Security lists or network security groups to establish a set of ingress and egress security rules that you’ll use for the private endpoint.
   • Optionally, an Internet gateway to give Internet access to the VCN.
   • Optionally, an NAT (Network Address Translation) gateway, which gives resources that don’t have public IP addresses access to the Internet without exposing them to incoming Internet connections.
   See the OCI documentation for VCNs and subnets.
3. Create the private endpoint and associate it with your Digital Assistant instance.
4. In Digital Assistant, configure a data service or REST service that points to the endpoint.

Permissions for Private Endpoints

To set up private endpoints, you need to have the proper permissions in the Infrastructure Console. There are two resource types for private endpoints that encompass these required permissions:

• oda-private-endpoints – enables you to configure private endpoints and SCAN proxies.
• oda-private-endpoint-attachments – enables you to attach a private endpoint a Digital Assistant instance.

Permissions for those resource types are also part of the oda-family resource type. So if you are covered by a policy statement to manage oda-family resource types in the compartment where your private endpoint is, you don’t have to create separate policies for your private endpoints.

The following are examples of broad policies to enable creation and configuration of private endpoints and attach them to Digital Assistant instances.

allow group to manage oda-private-endpoints in compartment
allow group to manage oda-private-endpoint-attachments in compartment

 For more detail on how policies work, see Digital Assistant Policies.

Create a Policy to Access a Private Endpoint

1. In the Infrastructure Console, click on the top left to open the navigation menu, select Identity & Security, and then click Policies.
   • A list of the policies in the compartment you’re viewing is displayed.
2. From the list of compartments, select the compartment to which you want to attach the policy. This controls who can later modify or delete the policy (see Policy Attachment).
3. Click Create Policy.
4. Complete the wizard, making sure that they name you provide is unique across all policies in your tenancy.

Create a Private Endpoint

1. In the Infrastructure Console, click on the top left to open the navigation menu, select Analytics & AI, and select Digital Assistant (which appears under the AI Services category on the page).
2. In the left navigation of the AI Services page that appears, click Private endpoints.
3. If you haven’t already done so, create the compartment where you want to keep the private endpoint and, optionally, add the VCN and subnet you will be using to that compartment.See Understanding Compartments and Managing Compartments.
4. Click Create private endpoint and fill in the required fields, including the VCN and private subnet.
5. Once the endpoint is created, click Associate ODA Instance, select the compartment that contains the Digital Assistant instance that you want to be able to use the private endpoint, and then select that instance.

 Add a Service for the Private Endpoint in Digital Assistant

Once you have created a private endpoint, you need to add a service for that private endpoint to use it in Digital Assistant.

• To add a REST service for the private endpoint, see Add a REST Service for an Endpoint.

SCAN Proxies for Private Endpoints

If you are using your private endpoint for a RAC-enabled database, you also need to configure a SCAN proxy for the private endpoint.

To set up a SCAN proxy:

1. Get the SCAN DNS name and port number for the database.
   • If the database is an on-premises database, get it from the database administrator.
   • If the database is on OCI, do the following in the Infrastructure Console:
     • Navigate to the DB System Details page for the database and select the DB system information tab.
     • In the Network section of the page, copy the SCAN DNS name and paste it in a convenient place.
     • Note the Port Number.
2. In the Infrastructure Console, click on the top left to open the navigation menu, select Analytics & AI, and select Private endpoints (which appears under the AI Services category on the page).
3. Select your private endpoint.
4. In the Resources section of the page, select SCAN proxies.
5. Click Add SCAN proxy.
6. In the Add SCAN proxy dialog, select the type (FQDN (for fully-qualified domain name) or IP address) and then fill in the rest of the required fields.
   • If you have selected FQDN as the proxy type, use the database’s SCAN DNS name for the Host name and the database’s port number as the Port.
   • If you have selected IP address as the proxy type, click Add SCAN Listener to add IP addresses and port numbers for one or more SCAN listeners in the database.

If you are unsuccessful creating a SCAN proxy through the Infrastructure Console, you can do so with Digital Assistant’s management APIs, which you can invoke using the OCI Command-Line Interface (CLI). See Using the OCI CLI to Configure SCAN Proxies.

Using the OCI CLI to Configure SCAN Proxies

You can use the OCI CLI to configure SCAN proxies for a Digital Assistant private endpoint.

See https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm for info on getting the CLI set up.

See https://docs.oracle.com/en-us/iaas/tools/oci-cli/3.47.0/oci_cli_docs/cmdref/oda.html for the command reference for Digital Assistant APIs.

Here are some example CLI commands:

• Get a list of SCAN proxies for an existing Digital Assistant private endpoint:

$ oci oda management oda-private-endpoint-scan-proxy list --oda-private-endpoint-id --region --auth security_token --profile oc1_boat

This should return an empty list if no SCAN proxies have been created.

• Create a SCAN proxy for an IP-based SCAN Listener address

 $ oci oda management oda-private-endpoint-scan-proxy create --scan-listener-type IP --protocol TCP --scan-listener-infos '[{"scan-listener-fqdn": null, "scan-listener-ip": "2.2.2.2", "scan-listener-port": 1521}]' --oda-private-endpoint-id --region --auth security_token --profile oc1_boat

• Create a SCAN proxy for an FQDN-based SCAN Listener address

$ oci oda management oda-private-endpoint-scan-proxy create --scan-listener-type FQDN --protocol TCP --scan-listener-infos '[{"scan-listener-fqdn": "myhost.example.com", "scan-listener-ip": null, "scan-listener-port": 1521}]' --oda-private-endpoint-id --region --auth security_token --profile oc1_boat

The above examples include the --auth security_token and --profile oc1_boat, arguments but they might not be necessary, depending on how you have configured authentication for your CLI installation.

Zero Trust Packet Routing (ZPR) and Private Endpoints

You can use OCI’s Zero Trust Packet Routing (ZPR) feature to implement fine-grained, least-privilege access control over interactions between private endpoints and other OCI resources.

ZPR is especially useful in environments where sensitive data or critical operations are distributed across multiple OCI resources, and strict separation and control of resource access is required. Using ZPR helps you to mitigate risks associated with unauthorized access and ensure that only explicitly permitted traffic flows between protected resources, supporting both compliance needs and organizational security policies.

You can use ZPR along with or in place of network security groups to manage network access to OCI resources. To do this, define ZPR policies that govern how resources communicate with each other, and then add security attributes to those resources. See Zero Trust Packet Routing for detailed information on ZPR.

To set up ZPR with private endpoints, you need to complete the following steps:

• Create a security attribute namespace. See Creating a Security Attribute Namespace.
• Create an IAM policy to grant the group to which you belong permission to use the security attribute namespace that will contains the security attributes. For example:

Allow group private-endpoint-admins to use security-attribute-namespaces in tenancy

• Add security attributes to the security attribute namespace. See Creating a Security Attribute for details.
• Create a ZPR policy to specify the OCI resources that methods in the private endpoint implementation can access.
  • If security attributes have also been added to the other resources, you can create a ZPR policy that explicitly allows functions to access resources with those security attributes. If security attributes have not been added to the other resources that you want functions to access, you can use 'osn-services-ip-addresses' as the endpoint to create a more permissive ZPR policy.
  • Without a suitable ZPR policy, the private endpoint’s access to other resources is blocked at the network level.
  • Such a ZPR policy takes the following format:

in VCN allow endpoints to connect to endpoints

where:

• <vcn-security-attribute> is a security attribute (and value) that has been added to the VCN in which the application’s subnet resides. For example, VCN-Network:myVCN.
• <application-security-attribute> is the security attribute (and value) that you have added to the private endpoint. For example, my-private-endpoint:myPrivEndpointMethodA
• <destination-security-attribute> is a security attribute (and value) that has been added to the resource that you want functions in the application to access. For example, DB-Server:App1.

For more information about ZPR policies, syntax, and examples, see Zero Trust Packet Routing Policy in the ZPR documentation.

Here are a few important notes on working with ZPR-enabled private endpoints:

• To see the applications to which security attributes have been added, use the ZPR Console page (see Listing Protected Resources in the ZPR documentation.). The ZPR Console page also displays VNICs created by OCI Functions, with the display name of each VNIC set to the OCID of the owning application.
• You can use the Network Path Analyzer to help debug any network connectivity issues encountered by functions in the application.
• If you have added a security attribute to an application, and the ZPR Console, CLI, or API is subsequently used to delete the security attribute from the security attribute namespace, you have to manually remove the security attribute from the application. If you do not remove the deleted security attribute from the application, 502 errors are returned when functions in the application are invoked.

Troubleshooting

Sometimes your request to create an ODA private endpoint or SCAN proxy can fail. How can you debug why did it fail and what needs to be fixed?

 First of all, you need to identify the OCID of the work request which has failed. You can do this either in the OCI console (by opening the Work Requests tab under the Resources panel) or using the OCI CLI. The following command will return the list of all work requests submitted for the given ODA private endpoint and sorted by submission time in ascending order so the last submitted work requests will be at the end of the list:

Get the summary of the specific work request:

 Get log entries (usually informational messages) about the work request:

 Get errors associated with specific work request:

Typical reason for failures while creating a private endpoint

To create a private endpoint you should have “manage” permission for oda-family or oda-private-endpoints

The same policy is required if you want to create or delete SCAN proxies.

If you want to use a private endpoint from the ODA UI, you need to associate the private endpoint with the ODA instance. To do that you should have “manage” permission for oda-private-endpoint-attachment (oda-family also works):

If you need to get the list of work request IDs or read the specific one you would need, at least,

“oda-family” should also work instead of “oda-instances” in the policies above.

Since the process whereby ODA creates private endpoints requires making changes in a subnet, you’ll need to create a corresponding policy:

If your private endpoint is created in a compartment different from the subnet compartment, then additionally you should create another policy:

If you prefer to define more granular policies, you can use the following:

Not enough private IPs in the private endpoint subnet

You need to make sure you have at least 3 unused IPs in the subnet in which you provision the ODA private endpoint.

Creating a private endpoint in a subnet which has a IPv6 prefix block assigned. Currently IPv6 is not supported with ODA private endpoint.

Learn more about IPv6 support in Oracle Cloud Infrastructure here: https://docs.oracle.com/en-us/iaas/Content/Network/Concepts/ipv6.htm

Subnet is not in Available state, e.g. if it is still being provisioned or updated. You can check the subnet state in OCI Console.

 For more information