Networking Configuration

Digital Self Service - Transactions requires a real-time connection to an Oracle Customer Information System including Oracle Utilities Customer Care and Billing, Oracle Utilities Customer to Meter, or Oracle Customer Cloud Service system. The supported networking configurations are provided below.

In this section:

• Networking Configuration
• Prerequisites
• Supporting mTLS Configuration
• Supporting Private Endpoint Configuration
• Supporting Oracle Utilities Customer Cloud Service Configuration

Prerequisites

The following prerequisites are applicable to both mTLS and private endpoint networking configuration options:

• Ports: Oracle Utilities recommends all network traffic between Digital Self Service - Transactions and external Customer Integrated Systems goes through port 443, which is the standard port for HTTPS. Support is also available for ports within the range of 5000 to 26000. Configurations using ports other than 443 must be requested as a service request, as described in Contacting Your Delivery Team.
• Certificates: Certificates are required for Digital Self Service - Transactions. Target hosts, including development, test, and production environments must have a valid, publicly-trusted SSL certificate.

Supporting mTLS Configuration

The Mutual Transport Layer Security (mTLS) authentication protocol is supported. For mTLS-based connectivity, Digital Self Service - Transactions acts as an API client which needs to exchange certificates with a Utility system that acts as an API server.

A Utility must provide a valid certificate, which is signed using a proper Certificate Authority. Digital Self Service - Transactions verifies the Utility certificate at run-time as part of an mTLS hand shake.

As part of this mTLS handshake Oracle Utilities provides a certificate to the utility. The Utility must install the certificate with their Customer Care and Billing or Customer to Meter system, and verify the certificate at run-time as part of mTLS hand shake. There are various options to install the certificate with the Customer Care and Billing or Customer to Meter System. A common configuration is to install on a network device such as a load balancer which supports the Customer Information Systems. A Utility must work with their networking team to determine the correct installation of the certificate with their Customer Information System.

After networking configuration is complete for both Oracle Utilities and the Utility, the mTLS handshake can be verified. If coordination of this testing is required, create a service request, as described in Contacting Your Delivery Team

Back to Top

Supporting Private Endpoint Configuration

An Oracle Cloud Infrastructure Cloud Account Administrator must setup the required networking objects in the utility's Oracle Cloud Infrastructure tenancy to establish a secure connection between the Oracle Utilities network supporting Digital Self Service - Transactions, and the utility's network.

Note: The procedures provided below offer high-level guidance to configure your Oracle Cloud Infrastructure networking components for Digital Self Service - Transactions. Refer to the Oracle Cloud Infrastructure documentation for additional details on how to create networking components.

Prerequisites

• Oracle Cloud Infrastructure Cloud Account: An administrative level cloud account for Oracle Cloud Infrastructure is required.
• Tenancy Setup: A tenancy must be available, and the tenancy must use the Ashburn region. This requirement is met if your tenancy is configured with Ashburn as its home region. If a different home region is used, ensure the tenancy is subscribed to the Ashburn region.

Create a Compartment

Within your Oracle Cloud Infrastructure tenancy that uses the Ashburn region, you must create a compartment that contains all the other objects necessary for your networking connection. Documentation on managing and creating compartments is available at Managing Compartments. When creating the compartment, take note of the name you use for the compartment as it is used in other parts of this setup.

Back to Top

Create a Policy

A new policy must be added to the tenancy, which allows the required private endpoint and reverse connection endpoints to be created. Documentation on creating policies is available at Managing Policies. The following requirements must be met when creating the policy:

• Default Policies: A new policy is created to support Digital Self Service - Transactions, default policies are not modified.
• Compartment: Ensure that the policy is created within the compartment you created earlier.
• Policy Statement: Use the Customize (Advanced) option to create the policy. The following policy statement must be used:
  
  Allow service ORACLE_INDUSTRY_SAAS to use network-security-groups in [compartmentName]
Allow service ORACLE_INDUSTRY_SAAS to use subnets in compartment [compartmentName]
Allow service ORACLE_INDUSTRY_SAAS to use vnics in compartment [compartmentName]
Allow service ORACLE_INDUSTRY_SAAS to inspect work-requests in compartment [compartmentName]
  
  Replace [compartmentName] with the name of your compartment.
  

Back to Top

Create a Virtual Cloud Network

A Virtual Cloud Network (VCN) must be created. Documentation on creating VCNs is available at Overview of VCNs and Subnets. The following requirements must be met when creating a VCN:

• Region: Ensure that the VCN is created in the Ashburn region.
• Compartment: Ensure that the VCN is created within the compartment you created earlier.
• CIDR Block: This is the size of the VCN that is created. A range of IP addresses is provided. Contact your Oracle Utilities Delivery Team to determine an appropriate IP address range for your Class Inter-Domain Routing (CIDR) block.

Back to Top

Create a Route Table

A route table must be created, which is responsible for routing traffic to the Customer Information System. Documentation on creating route tables is available at Route Tables. The following requirements must be met when creating a route table:

• Default Route Tables: A new route table is created to support Digital Self Service - Transactions, default route tables are not modified.
• Compartment: Ensure that the route table is created within the compartment you created earlier.
• VCN: Ensure that the route table is created within the VCN you created earlier.
• Route Rules: Use the + Another Route Rule option to create route rules for the route table. Create a rule for each CIDR that requires routing. Be aware of the following when creating the route rules:
  • Target Type: Determine if your system uses a dynamic routing gateway or local peering gateway to select the proper target type. Local peering gateways can be used if the Customer Information system is hosted in OCI.
  • Destination CIDR: Use the CIDR block range defined when creating a VCN.

Back to Top

Create a Security List

A security list must be created, which contains egress rules to the CIDRs for the Customer Information System. Documentation on creating security lists is available at Security Lists. The following requirements must be met when creating a security list:

• Compartment: Ensure that the security list is created within the compartment you created earlier.
• Egress Rules: Use the + Another Egress Rule option to create egress rules for the security list. Be aware of the following when creating the egress rules:
  • Stateless or Stateful: Egress rules are defined as stateful by default since most connections are stateful.
  • Destination CIDR: Use the CIDR block range defined when creating a VCN.
  • Source Port Range: Use the default that accepts all ports.
  • Destination Port Range: Provide the ports that will accept the connections. A range of ports can be provided.

Back to Top

Create a Subnet

The final network object that must be created is a regional subnet for the private endpoint and the reverse connection endpoint to be created. Documentation on creating subnets is available at Overview of VCNs and Subnets. The following requirements must be met when creating a security list:

• Region: Ensure that the subnet is created in the Ashburn region.
• VCN: Ensure that the subnet is created within the VCN you created earlier.
• Compartment: Ensure that the subnet is created within the compartment you created earlier.
• Subnet Type: The subnet must be created as a regional subnet.
• CIDR Block: Provide the CIDR block used when creating the VCN. It is recommended to end this block with /28, which translates to 16 IP addresses.
• Route Table: Ensure that the route table created earlier is selected for this subnet.
• Subnet Access: The subnet must be created as a private subnet.
• DNS Resolution: Use the default, which has the Use DNS Hostnames in this Subnet option selected.
• DNS Label: Be aware that there is a 15-character limit for the DNS label.
• DNS Domain Name: Use the default read only configuration.
• DHCP Options Compartment: Select the compartment you created earlier.
• Security Lists: Select the security list you created earlier.

Back to Top

Configuring Authentication

After completing the networking configuration above, the next step is to configure authentication to make calls to the Oracle Utilities customer system webservices endpoint.

Digital Self Service - Transactions supports the following methods of authentication:

• Basic Authentication
• Oauth 2.0 Authentication

Basic Authentication

Basic authentication uses the following syntax:

curl -k -v -u [username]:[password] 'https://[host]:[port]/[api]'

• The [username] and [password] are the credentials for the user account created as part of the Complete Environment Connection step in the checklist provided in the Configuration Checklist.
• The host is the IP address of the server hosting the API.
• The port is the port used for the API, which can be excluded if the default port is used.
• The api is the syntax required to call the API and is dependent on the API being used, such as CXGetCCBAlerts.

Verifying API Connection for Basic Authentication

You can verify that the API can be reached from the subnet that was created. This verification confirms that the networking configuration is accurate and that the API is functioning as expected.

From the subnet that was created, create a basic Oracle Linux instance and upload your public key. Once the instance has completed provisioning, log on to the instance using the private key. Documentation on creating instances is available at Creating an Instance.

From the instance, verification is completed by calling an API using a Linux curl command. The first test is performed in anonymous mode and the basic syntax is as follows:

curl -k -vvv 'https://[host]:[port]/[api]'

• The host is the IP address of the server hosting the API.
• The port is the port used for the API, which can be excluded if the default port is used.
• The api is the syntax required to call the API and is dependent on the API being used. Test the following API endpoints:
  • CXGetCCBAlerts: Test this endpoint by including ouaf/webservices/CXGetCCBAlerts?wsdl
  • F1-HealthCheck: Test this endpoint by including ouaf/webservices/F1-HealthCheck?wsdl

Example calls are provided below, which can be modified for relevant host and port information. The first call returns a list of available alerts to display, as defined in the self-service master configuration.

curl -k -vvv 'https://123.4.5.6:789/ouaf/webservices/CXGetCCBAlerts?wsdl'

This second call returns a code of 200 when the call is a success.

curl -k -vvv 'https://123.4.5.6:789/ouaf/webservices/F1-HealthCheck?wsdl'

If the API calls do not return the expected successful results, troubleshooting can begin by confirming the URLs for the calls are correct, including host and port information. If the URLs are correct, consider the following when verifying the API connection with anonymous calls:

• If anonymous calls to both API endpoints fail, then the issue is most likely related to the network setup. Confirm networking configurations including the security list and the routing configuration as the next troubleshooting step.
  
• If only one anonymous call fails but another one succeeds, then this issue is most likely that the service for the failed API endpoint call is not running on Customer Care and Billing.

If both anonymous calls succeed you can continue your testing with authenticated calls. Example calls are provided below, which can be modified for relevant user, host, port, and API information.

curl -k -v -u admin:passwordexample 'https://123.4.5.6:789/ouaf/webservices/CXGetCCBAlerts?wsdl'

curl -k -v -u admin:passwordexample 'https://123.4.5.6:789/ouaf/webservices/F1-HealthCheck?wsdl'

If both authenticated calls fail, then the issue is most likely an error with the provided credentials, or the user is not a member of ALL_SERVICES group in Customer Care and Billing.

After API connection is verified, the next step is to test with the Fully Qualified Domain Name (FQDN) if a FQDN is used.

Oauth 2.0 Authentication

Oauth 2.0 is an authorization protocol which requires the following values:

• The URL is the URL of the token endpoint that provides the access token in exchange for clientId:clientSecret.
• The clientId is a public identifier for the Digital Self Service - Transactions application.
• The clientSecret is the secret that matches the application's clientId.
• The grantType value must be defined as client_credentials.
• The scopes are any scopes required to define access to specific APIs.

Verifying API Connectiong for OAuth Authentication

You can verify that the API can be reached from the subnet that was created. This verification confirms that the networking configuration is accurate and that the API is functioning as expected.

Example calls are provided below, which can be modified for relevant host and port information.

Get the access token:

curl --request POST \

--url 'https://[yourDomain]/oauth/token' \

--header 'content-type: application/x-www-form-urlencoded' \

--data grant_type=client_credentials \

--data client_id=[clientID] \

--data client_secret=[clientSecret]

Make a call to the webservice endpoint:

curl --request POST \

--url https://[host]:[port]/ouaf/webservices/CXGetCCBAlerts \

--header 'authorization: Bearer [accessToken]' \

After API connection is verified, the next step is to test with the Fully Qualified Domain Name (FQDN) if a FQDN is used.

Back to Top

Required Information

Be aware that the following information is needed by Oracle Utilities to complete the networking configuration:

• Tenancy Name
• Tenancy OCID
• The compartment name
• The compartment OCID
• VCN Name
• VCN OCID
• The DNS of the VCN
• The CIDR Range of the VCN
• The subnet name
• The OCID of the subnet
• The CIDR range of the subnet
• The IPs of the servers hosting the APIs
• The domain of the APIs, if the APIs are accessed using a FQDN

Back to Top

Supporting Oracle Utilities Customer Cloud Service Configuration

If you use Oracle Utilities Customer Cloud Service as your Customer Information System, the networking configuration is configured and maintained by Oracle Utilities. A support request can be created to confirm support of this network configuration, as described in Contacting Your Delivery Team.

Back to Top