1. Network Connectivity options for integrating Oracle Utilities Cloud services with external applications
  2. Understand Available Integration Channels

Understand Available Integration Channels

Oracle Utilities Cloud services support web service based and file transfer-based channels to move the data between Oracle Utilities Cloud services and external applications that are hosted on-premises or on Oracle PaaS or on Oracle IaaS or third party data centers, outside of Oracle Utilities Cloud services.

Based on the channel being used for integration, the external applications/APIs need to meet certain criteria for integrating with Oracle Utilities Cloud services.

Integrate Utilities by 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. As a rule of thumb, all communication has to be https protocol-based. Depending on whether the request is going out from Oracle Utilities Cloud services or if the request is coming into Oracle Utilities Cloud services, the following concepts apply.

Learn About Outbound Communications

This information applies to the communication/request going out of Oracle Utilities Cloud services and in to your application that is external to Oracle Utilities Cloud services.

For Oracle Utilities Cloud services to make either an outbound or inbound web service call to an external system, the following criteria should be met by the web service APIs of the external system:
  • Accessible API.
  • Valid CA-signed certificate.
  • Support for basic authentication/OAuth Client Credentials over HTTPS protocol.
  • The 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.
Understand the Accessible API

Web service APIs belonging to the external application should be accessible to the Oracle Utilities Cloud services, thus, 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 few examples that can help expose the private web service APIs of an external system through public APIs.
  • Expose the APIs of the external application to public internet, by setting up rules in the firewall and using a reverse proxy in the data center where the external application resides. A single reverse proxy can be used to expose multiple applications/APIs.
  • Have the API made accessible through – Oracle VPN Connect & a reverse proxy. This is applicable if the external application is within a private network and cannot/does not expose the APIs to public internet. Oracle Utilities Cloud services cannot be integrated with private APIs of an external application. So, along with the VPN, a reverse proxy on OCI would be needed for the integration. The reverse proxy would mediate between Oracle Utilities Cloud services and the external application through the VPN. The DNS name must be on the "allowlist", for the SaaS application to be able to make a call to the reverse proxy.
  • Expose the APIs via FastConnect Public Peering, in which case no reverse proxy would be needed. FastConnect allows you to connect to Oracle Cloud Infrastructure through a dedicated private line from the data center of the external application.
  • Another option may be to use a middleware software such as Oracle Integration Cloud, which has an on-premise agent that can connect to the Oracle Integration Cloud without the need for extensive firewall configurations or VPN.
Understand CA-Signed Certificates

The web service APIs of the external application should have valid CA issued certificate. There is a TLS handshake to check that certificate matches what is on Oracle Utilities Cloud services’ allowlist, and if good 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:
  • Use valid CA-signed certificate.
  • 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.
  • 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.

Learn About Inbound Communications

When a request/communication comes to Oracle Utilities Cloud services application’s web service APIs from an external system hosted outside Oracle Utilities Cloud services, the calling application/service need to meet these criteria:

  • Access to the web service APIs of Oracle Utilities Cloud services applications.
  • The calling application must support IDCS token-based authentication or basic authentication over HTTPS.
External Application's Access to the Web Service APIs of Oracle Utilities Cloud Services Applications

Web service APIs for inbound communication to Oracle Utilities Cloud services applications are available over the public internet. If the external application can access the public internet, then the web service API's should be accessible.

If the external application/service does not have access to the public internet, then appropriate setup needs to be done to allow the external application to send messages to Oracle Utlities Cloud Services. Following are some example setups:
  • A proxy in the external application’s data center to allow the external application to access the public APIs of Oracle Utilities Cloud services applications.
  • Use Oracle VPN Connect to extend the external application’s/datacenter’s private network to the OCI VCN and route requests to the Oracle Utilities Cloud services VCN so that the APIs become accessible to the external application.
  • Use FastConnect to set up communication through a dedicated private line between the OCI data center and the external application’s data center.
  • Use integration software such as Oracle Integration Cloud service to act as a bridge between the external application and the Oracle Utilities Cloud services application.

Integrate Utilities by Using File Transfers

Along with the web services-based integration, Oracle Utilities Cloud services applications also support integration by using file transfers; that is, you can also move data between the Oracle Utilities Cloud services application and the external application by transferring files.

Usually, the Oracle Utilities Cloud services applications process both inbound and outbound files by using batch programs via built-in file adapters to Oracle Object Storage Cloud Service. So, all inbound and outbound file transfers are supported only through Oracle Object Storage Cloud Service. An external application needing to integrate with Oracle Utilities Cloud services application using files should have the capability to push and pull files from the Oracle Object Storage Cloud Service.

Allow Inbound-Outbound Communication by Using File Transfers

The criteria/methods for moving files to and from Oracle Utilities Cloud services application as part of an integration with external applications is more or less the same. Oracle Object Storage Cloud Service has to be used for pushing and pulling files to and from Oracle Utilities Cloud services application.

The external application needs to be able to integrate with the Oracle Object Storage Cloud Service. Oracle Object Storage Cloud Service has REST APIs available over public internet that can be used by the external application to pull or push files to Oracle Object Storage Cloud Service. If the external application does not support REST API based file transfers, then an intermediary setup needs to be done to push and pull files from Object Storage. Following are some sample setups for file-based integration, in the absence of REST API capability in the external application::
  • If the external application supports SFTP based file transfers, then you can build a custom adapter between the SFTP storage being used by the external application and Oracle Object Storage Cloud Service. The custom adapter can use the Oracle Object Storage Cloud Service’s REST APIs to move the files between Oracle Object Storage Cloud Service and the SFTP storage server.
  • You can use the Managed File Transfer Cloud Service, which is part of SOA cloud service. Managed File Transfer Cloud Service has built in adapters to Oracle Object Storage Cloud Service. The external application can interface with Managed File Transfer Cloud Service using SFTP.
  • Use Oracle Integration Cloud Service for file-based integrations

Understand the Allow List

The allow-list option allows you to specify the targets to and sources from which communication is allowed in Oracle Utilities Cloud Services.

For outbound communication:

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 behaviour by adding targets to the allow list. The addition/removal of targets can be done by raising a support ticket to update the allow-list. The following information needs to be made available in the support ticket:
  • The named DNS OR URL along with the justification for its allowance. As already mentioned in the previous sections on outbound communication:
  • The SSL port 443 must be used.
  • The hosts must have a valid TLS certificate signed by a trusted public certificate authority

For inbound communication:

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 behaviour by adding sources to the allow list. The addition/removal of sources can be done by raising a support ticket to update the allow-list. You can even specify the resources that one or more sources has access to.
  • A source can be identified by:
    • IP address ranges defined as CIDR blocks
    • 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 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 services
    • 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.
An allow rule would be a mapping between sources and paths i.e., which sources/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. There is an option to create and name a group of allow rules through the use of a support ticket.

Note:

For creating, updating or removing an allow-list rule, a support ticket needs to be raised.