Integrate Oracle Utilities Cloud Services Using Web Services
This channel of integration uses web service APIs on both the Oracle Utilities Cloud services and the external applications. Industry standard best practices, protocol and authentication methods have to be used for integration using web services. In order to establish integration between an external application and Oracle Utilities Cloud Services, appropriate networking needs to be setup, so the applications can access each other's APIs securely. The subsequent sections detail various networking options that can be used for setting up the web service-based communication.
You can select any of three architectural options for integrating Oracle Utilities Cloud services with an application hosted in your data center or in a third-party data center. Each of the architecture options provide different levels of security and bandwidth, along with other variations. The below architecture options apply to forward flow - communication from external applications to Oracle Utilities Cloud Services, and reverse flow - communication from Oracle Utilities Cloud Services to external systems.
Architecture 1: Integrating Through Public (Internet) Web Service APIs
In its simplest form integration between application's hosted in your private/corporate network and Oracle Utilities Cloud services can be achieved over the public internet.
Forward Flow
The REST APIs on the Oracle Utilities Cloud services are exposed securely to the public internet through the Akamai content delivery network, so if an on-premise application needs to access the REST APIs, it can do so, as long as the application has access to the public internet, unless VPN Connect or FastConnect are being used.
Akamai is a content delivery network provider with geographically distributed servers that speed up the delivery of web content by bringing it closer to where users are. It currently handles 15-30% of the world's web traffic. Access to Oracle Utilities Cloud Services through Akamai networking adds a layer of security that thwarts malicious attacks such as Distributed Denial-of-Service (DDoS), at the edge, before they reach infrastructure. All communication coming into Oracle Utilities Cloud Services is automatically directed through Akamai network. The DNS of Oracle Utilities Cloud Services automatically resolve to the respective Akamai network end points through which the communication is routed. No additional setup if required in the external application to use Akamai and there is no additional cost to customers of Oracle Utilities Cloud Services, for using Akamai content delivery network.
In order to send communication to Oracle Utilities Cloud services application's web service APIs from an external system hosted outside Oracle Utilities Cloud services, the calling application/service needs to meet these criteria:
• Access to the web service APIs of Oracle Utilities Cloud services applications
The web service APIs of Oracle Utilities Cloud Services can be accessed via public internet. So, an external application trying to connect to Oracle Utilities Cloud Services should have access to the webservice APIs through public internet, unless VPN Connect of FastConnect are being used.
• OCI IAM Identity Domain token-based authentication or basic Authentication over HTTPS
The web service APIs of Oracle Utilities Cloud Services support OCI IAM Identity Domain token based and basic authentication over https to authenticate an incoming request from external applications. Either of the authentication methods can be used for sending a request to Oracle Utilities Cloud Service's web service APIs.
• Inbound Allowlists for Forward Flow Communications
The allow-list option allows you to specify the sources from which communication is allowed into Oracle Utilities Cloud Services. By default communication is allowed from all sources with valid authentication information. You can change this behavior by adding sources to the allowlist. The addition/removal of sources can be done by raising a support ticket to DevOps to update the allow-list (Please refer to DevOps guide for more information). Optionally, you can even specify the resources that one or more sources has access to.
• A source of forward flow request can be identified by:
• IP address ranges defined as CIDR blocks
• Both IP and VCN OCID; optionally, you can create and name groups of CIDR blocks and/or VCN OCID through the use of a support ticket.
• A resource to be accessed can be identified by:
• Paths depending on the application. For example: /web for online web application; /sql for ORDS, /rest for rest services etc
• Groups of paths that start with a particular subpath. For example: /rest/ busSvc/K1 for all K1-owned rest service
• Specific paths. For example: /rest/busSvc/F1-HealthCheck can be configured to be accessible by set of sources Optionally, you can create and name groups of paths through the use of a support ticket.
DevOps define the inbound allowlist based on the information provide as an Allow Rule. An allow rule would be a mapping between sources and paths i.e., which source/sources has access to which path/paths. Each rule is made up of a path group and one or more sources that can access it. Optionally, the customers can request to create and name groups of paths via support ticket.
Note: For creating, updating or removing an allow-list rule, a support ticket needs to be raised.
Important Note:
Errors that the Akamai content delivery network encounters, including traffic that was blocked, will be reported as follows:
When Akamai content delivery network reports an error, you'll get a Reference ID in the following format:
18.4c96df17.1644609140.2a155db
If there is a need, a Service Request (SR) can be raised via My Oracle Support by providing the Reference ID as part of the SR Description.
The first digits before the period give the reason for the error. The most common of those are outlined in the table below:
Error Code | Description |
|---|---|
1 | Request timed out |
18 | Request was blocked by WAF |
25 | Max Redirect Chase. This happens if a request gets in a loop of 3xx redirects |
30 | Forward SSL Handshake. This happens when Akamai tries to go forward to the origin, but cannot complete the SSL handshake for some reason (usually the origin cert has expired or SNI isn't configured properly) |
102 | No good forward IP. This happens when Akamai is trying to go forward to the origin, but the origin isn't resolving in DNS |
Reverse Flow
Similarly, Oracle Utilities Cloud services can access web service end points that are exposed to the public internet (public IP) i.e., if the on-premise application's web service end points are exposed to the public internet, then these can be consumed by Oracle Utilities Cloud services. A firewall in your corporate network may be configured to expose any application's end points to the public internet. Although this forms the simplest possible communication channel, transiting over the public internet requires close consideration of the security, availability, and reliability that the public internet can provide.
For Oracle Utilities Cloud services to make either an outbound call to an external system, the following criteria should be met by the web service APIs of the external system:
• Accessible API
For a request to be made from Oracle Utilities Cloud services to the web service APIs of the external system, those APIs should be accessible via public IP addresses. If your external application APIs are not yet public, the networking administrators on your IT team/partner/implementer should be able to set up and configure appropriate components so the private APIs are exposed through public IPs. Following are a couple of examples that can help expose the private web service APIs of an external system through public APIs:
a. Expose the APIs of the external application to public internet, by setting up rules in the firewall.
b. Use reverse proxy in the data center where the external application resides. A single reverse proxy can be used to expose multiple applications/APIs
• Valid CA-signed Certificate
The web service APIs of the external application should have valid CA issued TLS certificate. There is a TLS handshake to check that certificate matches what is on Oracle Utilities Cloud service's outbound allowlist, and if it meets the criteria then Oracle Utilities Cloud services can post outbound requests to the external application.
If the external application's web service APIs use self-signed certificates, then you need to configure the APIs to support CA-signed certificate. Following are some examples of how this can be done:
a. Use valid CA-signed certificate
b. Use a reverse proxy with a valid CA-signed certificate in the external application's data center, which can act as a gateway indirectly exposing the external application APIs. A single proxy may be used for multiple web services or applications, based on the configuration.
c. A reverse proxy can be set up on OCI for the same purpose. In this case VPN Connect may be required depending on whether the external application's web service APIs are public or not.
• Basic authentication/OAuth Client Credentials over HTTPS protocol
Oracle Utilities Cloud Service can send requests to external applications that support either basic authentication or OAuth client based authentication over https. So, the external application's APIs need to support either of the authentication options for web services.
• SSL Port Number 443
If the API of the external application does not have 443 as the port number, then you might have to consider changing the port to 443 or in cases where the port number cannot be changed, you might consider adding additional infrastructure/software as a mediator; for example, adding a reverse proxy that listens on port 443. Oracle Utilities Cloud Service is designed to make calls ONLY to the port 443 as part of all web service reverse flow communication.
• Outbound Allowlists for Reverse Flow Communications
The allow-list option allows you to specify the targets to which communication may be allowed from Oracle Utilities Cloud Services. By default, communication to external interfaces is disabled. You can change this behavior by adding targets to the allowlist. The addition/removal of targets can be done by raising a support ticket for DevOps to update the outbound allow-list (Please refer to DevOps guide for more information).
The following information needs to be made available in the support ticket:
• The named DNS OR URL along with the justification for its allowance.
Architecture 2. Integrating Through VPN Connect
In this architecture, the external application makes web service API calls through the public internet, protected by an extended VPN, which creates a secured IPSec tunnel between your corporate private network and your VCN on Oracle Cloud Infrastructure (OCI). The same setup may be used for securely accessing Oracle Utilities Cloud services and to limit the Oracle Utilities Cloud services access via customer corporate network only.
Note: The end-to-end VPN and other requisite setups can be done by networking administrators in your IT team/partner/implementer.
Refer to When to Use VPN Connect for more information.
Forward Flow
For forward flows, VPN Connect requires setting up of CPE (Customer Premise Equipment), which interfaces with VPN DRG (Dynamic Routing Gateway) creating a IPSEC Encryption Tunnel over the internet, securing all information flowing through the tunnel. Once the VPN Connect is setup between the external application's data center and your VCN(Virtual Cloud Network) on OCI, communication is routed through the CPE device at the data center of the external application and through the Dynamic Routing Gateway(DRG). Your OCI VCN is not the same as the VCN that hosts Oracle Utilities Cloud Services. So, appropriate setup is required to establish networking between your VCN on OCI and Oracle Utilities Cloud Services VCN, which can be done using a service gateway. Service Gateway is one of the available gateways in OCI VCN that allows for traffic to be routed between two VCNs within OCI.
In order to send communication to Oracle Utilities Cloud services application's web service APIs from an external system hosted outside Oracle Utilities Cloud services, the calling application/service needs to meet the following criteria:
• Access to the web service APIs of Oracle Utilities Cloud services applications
The web service APIs of Oracle Utilities Cloud Services can be accessed via VPN Connect through the use of service gateway in your VCN. The DNS resolution of service gateway should be set so that the service domain names resolve to home region IPs of Oracle Utilities Cloud Services and NOT that of Akamai content delivery network. The home region IP is the IP of the main data region selected for the tenancy in which the cloud service is deployed. When a cloud account is created, a Home Region is assigned to it. This is the main data region that is linked to that account. Customers are required to raise Service Request via My Oracle Support to get the Home Region IP addresses.
• OCI IAM Identity Domain token-based authentication or basic authentication over HTTPS
The web service APIs of Oracle Utilities Cloud Services support OCI IAM Identity Domain token based and basic authentication over https to authenticate an incoming request from external applications. Either of the authentication methods can be used for sending a request to Oracle Utilities Cloud Service's web service APIs.
• Inbound Allowlists for Forward Flow Communications
The allow-list option allows you to specify the sources from which communication is allowed into Oracle Utilities Cloud Services. By default communication is allowed from all sources with valid authentication information. You can change this behavior by adding sources to the allowlist. The addition/removal of sources can be done by raising a support ticket to update the allow-list. Optionally, you can even specify the resources that one or more sources has access to.
Create a support ticket for adding VCN OCID to the allowlist of Oracle Utilities Cloud Service so that communication coming into Oracle Utilities Cloud Services from only your VCN's service gateway is allowed.
• A source of forward flow requests can be identified by:
• IP address ranges defined as CIDR blocks (for access from, other than service gateway)
• VCN OCID; which is used only for sources that access the resources via the OCI service gateway.
• Both IP and VCN OCID; optionally, you can create and name groups of CIDR blocks and/or VCN OCID through the use of a support ticket.
• A resource to be accessed can be identified by:
• Paths depending on the application. For example: /web for online web application; /sql for ORDS, /rest for rest services etc
• Groups of paths that start with a particular subpath. For example: /rest/ busSvc/K1 for all K1-owned rest service
• Specific paths. For example: /rest/busSvc/F1-HealthCheck can be configured to be accessible by set of sources Optionally, you can create and name groups of paths through the use of a support ticket.
The Cloud Operations team defines the inbound allowlist based on the information provide as an Allow Rule. An allow rule would be a mapping between sources and paths i.e., which source/sources has access to which path/paths. Each rule is made up of a path group and one or more sources that can access it. Optionally, the customers can request to create and name groups of paths via support ticket.
Note: For creating, updating or removing an allow-list rule, a support ticket needs to be raised.
Reverse Flow
The Oracle Utilities Cloud service makes web service calls to the external application by using Oracle Utilities Cloud service supported authentication methods such as basic authentication/OAuth client credentials. Note that Oracle Utilities Cloud services can make API calls only to public IP addresses, if the external APIs are private, you need the appropriate set up to ensure that the external APIs have public IPs; for example: use of a reverse/customer proxy mentioned in the preceding architecture diagram to expose your private API end points through public IP.
If your external application's TLS certificates are not issued by a public certificate authority, you can use a single reverse proxy, with a valid CA signed TLS certificate, to proxy for multiple applications in your data center.
For Oracle Utilities Cloud services to make either an outbound call to an external system, the following criteria should be met by the web service APIs of the external system
• Accessible API
For a request to be made from Oracle Utilities Cloud services to the web service APIs of the external system through VPN Connect, those APIs should be accessible via public IP addresses. If your external application APIs are not yet public, the networking administrators on your IT team/partner/implementer should be able to set up and configure appropriate components so the private APIs are exposed through public IPs. Following are a couple of examples that can help expose the private web service APIs of an external system through public APIs:
a. Use reverse proxy in the data center where the external application resides. A single reverse proxy can be used to expose multiple applications/APIs
b. Use reverse proxy in your OCI VCN that routes requests to the external application through VPN Connect. A single reverse proxy can be used to expose multiple applications/APIs. You can set up the proxy by using a separately provisioned OCI VM in your OCI VCN.
You can install and configure an appropriate reverse proxy software on this OCI VM so it can accept requests coming in from Oracle Utilities Cloud Services and then forward these to the external applications. The reverse proxy should be set up with a public IP address, so Oracle Utilities Cloud Service can send outbound communication to the reverse proxy.
Note: OCI VM is not included as standard offering of Oracle Utilities Cloud Services Subscription.
• Valid CA-signed Certificate
The web service APIs of the external application should have valid CA issued TLS certificate. There is a TLS handshake to check that certificate matches what is on Oracle Utilities Cloud service's outbound allowlist, and if it meets the criteria then Oracle Utilities Cloud services can post outbound requests to the external application.
If the external application's web service APIs use self-signed certificates, then you need to configure the APIs to support CA-signed certificate. Following are some examples of how this can be done:
a. Use valid CA-signed certificate
b. Use a reverse proxy with a valid CA-signed certificate in the external application's data center or in your OCI VCN, which can act as a gateway indirectly exposing the external application APIs. A single proxy may be used for multiple web services or applications, based on the configuration.
c. A reverse proxy can be set up on OCI for the same purpose.
• Basic authentication/OAuth Client Credentials over HTTPS protocol
Oracle Utilities Cloud Service can send requests to external applications that support either basic authentication or OAuth client based authentication over https. So, the external application's APIs need to support either of the authentication options for web services.
• SSL Port Number 443
If the API of the external application does not have 443 as the port number, then you might have to consider changing the port to 443 or in cases where the port number cannot be changed, you might consider adding additional infrastructure/software as a mediator; for example, adding a reverse proxy that listens on port 443. Oracle Utilities Cloud Service is designed to make calls ONLY to the port 443 as part of all web service reverse flow communication.
• Outbound Allowlists for Reverse Flow Communications
The allow-list option allows you to specify the targets to which communication may be allowed from Oracle Utilities Cloud Services. By default, communication to external interfaces is disabled. You can change this behavior by adding targets to the allowlist. The addition/removal of targets can be done by raising a support ticket for DevOps to update the outbound allow-list (Please refer to DevOps guide for more information).
The following information needs to be made available in the support ticket:
• The named DNS OR URL along with the justification for its allowance.
Architecture 3. Integrating Through FastConnect for Private Web Service APIs
Forward Flow
Reverse Flow
Another private routing option of FastConnect may also be used to connect your private/corporate network with OCI network(OCI VCN). FastConnect provides an entry point in to OCI for a dedicated private line between your data center and the OCI to enable high bandwidth data transfer over a highly secured channel. FastConnect communication requires FastConnect DRG to be setup on your OCI VCN along with a dedicated line that can connect the CPE with the FastConnect DRG to be set up, which in turn interfaces with the service gateway or the proxy (if available) within you VCN, depending on the direction of the communication. Within OCI networking, communication between Oracle Utilities Cloud Service's VCN (Virtual Cloud Network) and your VCN uses the service gateway or your proxy depending on the direction of the API Call.
The requirements for connecting external application to Oracle Utilities Cloud Services through FastConnect remain the same as the ones mentioned under the architecture option using VPN Connect. To set up a FastConnect private line between an external data center and OCI, See Understanding Oracle Cloud Infrastructure FastConnect.