1. Oracle GoldenGate Security Guide
  2. Securing the Microservices Architecture
  3. Network

4 Network

Learn how to secure your network for Oracle GoldenGate.

This chapter describes endpoint protection such as Network Access Control and Network Connection Adapters along with the steps to configure and use Reverse Proxy.

Topics:

Parent topic: Securing the Microservices Architecture

4.1 Network Access Control

The MA configuration of the network connection takes the form of an array or network access control list (ACL).

All configurable ACLs are represented as an array of ACL specifications. In the JSON configuration this array takes the form:

aclArray := '[' <aclSpec> [, <aclSpec>] ']'

There might be cases where access from specific sides is excluded or access from specific sides is allowed. Within Oracle GoldenGate, you are able to adjust the Application network setting so that you can create black or white lists for access points. Similarly, there might be cases, that you want to have the distribution path working on a specific network adapter only. This is feasible within Oracle GoldenGate.

Each ACL specification minimally consists of a permission statement indicating whether the ACL specification allows or denies client connections from the specified address. ACL specifications are processed in order and terminate when the specified address is qualified. If the specified address does not qualify, processes continue with the next ACL specification. Once the address of the client requesting connection is qualified, the ACLs permissions dictate whether the connection is 'allowed' or 'denied'. If the ACL specifications qualify address of the client requesting connection, a default resolution of 'allow is assumed and the client is allowed to connect. The ACL in the configuration take the following syntactic forms:

ipACL := '[' aclSpec [, aclSpec] ']' 
aclSpec := "permission" : [ "deny" | "allow" ] [, "address": [ ipv4Address | ipv4MappedAddress | ipv6Address ] ]

The ipACLs can use IPv4 addresses, ipv6 addresses and IPv4 mapped addresses as described in RFC 4291.

Inbound connection requests are processed uniformly after they are received over a network interface. The network interface configuration dictates the form of addressing. For example, addresses appearing on an IPv6 interface appears as IPv6 addresses. If the IPv6 configuration specifies IPv4 mapping, then the IPv4 client's address is mapped into the IPv6 addressing space. An address appearing on an IPv4 interface appears as an unmapped IPv4 address. Since the ACL qualification focuses on qualifying addresses and all adapters within the host environment have unique addresses, no additional interface information is required.

For hosts that support hot-fail over network interfaces, the fail-over and reassignment of network IP address to adapter MAC addresses is transparent to the application.

Example 4-1 Examples

Deny client connections originating from 192.0.2.254.

"ipACL" : [ { "permission" : "deny",  "address" : "192.0.2.254" } ]

Explicitly allow all client connections. The first ACP by default qualifies all addresses. The second ACL is never processed.

"ipACL" : [ { "permission" : "allow" },
             { "permission" : "deny",  "address" : "192.0.2.254" } ]

Allow client connections originating from 127.0.0.1, but deny connection originating from 192.0.2.254 appearing on an interface configured for IPv6 addressing.

"ipACL" : [ { "permission" : "allow", "address" : "127.0.0.1" },
             { "permission" : "deny",  "address" : "ff::192.0.2.254" } ]

Example 4-2 Example

Allow client connections originating from and IPv6 loopback address (127.0.0.1 represented as ::1 in IPV6 addressing), allow client connections originating from the unmapped IPv4 address 192.0.2.253, allow client connections originating from IPv6 address 2001:db8:85a3:0:0:8a2e:370:7334 and deny client connections originating from mapped IPv4 address ff::192.0.2.254.
"ipACL" : [ { "permission" : "allow", "address" : "::1" },
             { "permission" : "allow", "address" : "192.0.2.254" },
             { "permission" : "allow", "address" : "2001:db8:85a3:0:0:8a2e:370:7334" },
             { "permission" : "deny",  "address" : "ff::192.0.2.254" } ]

Example 4-3 Example

Using REST API Calls

{
    "$schema":"api:standardResponse",
    "links":[
        {
            "href":"http://localhost:11000/services/v2/deployments/Local/services/adminsrvr",
            "mediaType":"application/json",
            "rel":"canonical"
        },
        {
            "href":"http://localhost:11000/services/v2/deployments/Local/services/adminsrvr",
            "mediaType":"application/json",
            "rel":"self"
        }
    ],
    "messages":[
    ]
}

Example 4-4 Example

Using cURL:

Check initial configuration:
curl -s -k -u ggsca:ggsca -X GET https://abc.us.oracle.com:9100/services/v2/deployments/depl_01/services/adminsrvr | json_reformat
Modify service properties:
curl -s -k -u ggsca:ggsca -X PATCH https://abc.us.oracle.com:9100/services/v2/deployments/depl_01/services/adminsrvr' -H Cache-Control: no-cache' -d @"admin_2.json" |
        json_reformat
Admin.json file:
-- 8< -- File Content from admin.json -------
    {"config": {
            "network": {
                "ipACL": [
                    {
                        "address": "10.196.9.33 ",
                        "permission": "allow"
                    },
                    {
                        "address": "10.90.136.97",
                        "permission": "allow"
                    },
                    {
                        "address": "10.209.243.80",
                        "permission": "deny"
                    }
                ],
                "serviceListeningPort": 9101
            }
        }
    }

Example 4-5 Example

Using oggServiceConfig:
-- Check initial configuration
oggServiceConfig  https://abc.us.oracle.com:9100 depl_01 adminsrvr  --user ggsca --password ggsca 
oggServiceConfig  https://abc.us.oracle.com:9100 depl_01 adminsrvr  --user ggsca --password ggsca --path /network
oggServiceConfig  https://abc.us.oracle.com:9100 depl_01 adminsrvr  --user ggsca --password ggsca --path /network/ipACL


-- Modify Service Properties
oggServiceConfig  https://abc.us.oracle.com:9100 depl_01 adminsrvr  --user ggsca --password ggsca --path /network/ipACL --value '[{ "permission" : "allow", "address" : "10.196.9.33 " },{ "permission" : "allow", "address" : "10.90.136.97" },{ "permission" : "deny",  "address" : "10.209.243.80" } ]'
             
    Current value of "/network/ipACL" for "depl_01/adminsrvr" is <not defined>.
    Setting new value and restarting service.
    New value of "/network/ipACL" for "depl_01/adminsrvr" is 

-- Check final configuration
oggServiceConfig  https://abc.us.oracle.com:9100 depl_01 adminsrvr  --user ggsca --password ggsca 
oggServiceConfig  https://abc.us.oracle.com:9100 depl_01 adminsrvr  --user ggsca --password ggsca --path /network
oggServiceConfig  https://abc.us.oracle.com:9100 depl_01 adminsrvr  --user ggsca --password ggsca --path /network/ipACL

    [
    {
        "address": "10.196.9.33 ", 
        "permission": "allow"
    }, 
    {
        "address": "10.90.136.97", 
        "permission": "allow"
    }, 
    {
        "address": "10.209.243.80", 
        "permission": "deny"
    }
    ]
ipACL   := '[' aclSpec [, aclSpec] ']' 
aclSpec :=   "permission" : [ "deny" | "allow" ] 
          [, "address": [ ipv4Address | ipv4MappedAddress | ipv6Address ] ]

Parent topic: Network

4.2 Network Connection Adapter

Learn about how to specify your network connection configuration.

Network Interface Use Control as Network Connection Adapter is the name of an internal implementation class. When there are more than one network interface that are configured in an environment where the host is multi-homed, then it is known as multiple networks. For example, handling connection requests on different addresses through different network interface adapters.

The NetworkConnectionSpecs themselves are members of an array associated with the serviceListeningPort configuration element. For example, using the serviceListeningPort configuration entry, a network specification may take any of the following syntactic forms: 

1. portValue |  portValueString
2. networkSpec
3. '[' networkSpec [, networkSpec ...] ']'

You can use the following syntax in your network specification:

  portValue         := [1234567890]+
  portValueString   := '"' portValue '"'
  networkSpec       := '{' portSpec [, ipaddressSpec | nameSpec] [, interfaceSpec] [, networkOptionSpec] '}'
  portSpec          := "port" : portValue |  portValueString
  ipaddressSpec     := "address" : ipv4Address | ipv6Address | "ANY"
  nameSpec          := '"' :alphanum: '"'
  interfaceSpec     := "interface" : '"' :alphanum: '"'
  networkOptionSpec := "options" : IPV4_ONLY | IPV6_ONLY

Regardless of the form your specification takes, the internal representation is normalized into the 3rd form:

1. portValue | portValueString == networkSpec 
2. portValue                    == '{' "port" : portValue '}'
3. portValueString              == '[' '{' "port" : portValueString '}' ']'

The first form retains compatibility with existing network port specifications where only the portValue or portValueString is provided.

The second form assigns the networkSpec as a single value. This form still only defines a single network specification and allows greater control and flexibility in identifying network values and options.

The third form defines an array of networkSpec instances. It allows you to specify different network configurations based upon either address or network interface.

Example 4-6 Example

With the following simplified host network interface configuration:

$/sbin/ip addr show
lo: LOOPBACK,UP,LOWER_UP mtu 16436 qdisc noqueue state UNKNOWN
      link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
      inet 127.0.0.1/8 scope host lo
eth0: BROADCAST,MULTICAST,UP,LOWER_UP mtu 1500 qdisc pfifo_fast state UP qlen 1000
      link/ether 00:16:3e:52:6e:27 brd ff:ff:ff:ff:ff:ff
      inet 192.0.2.39/21 brd 10.240.111.255 scope global eth0
      inet6 2001:db8:85a3:0:0:8a2e:370:6666 brd ff02::1 scope link eth0
eth1: BROADCAST,MULTICAST mtu 1500 qdisc pfifo_fast state UP qlen 1000
      link/ether 00:16:3e:1f:99:bc brd ff:ff:ff:ff:ff:ff
      inet 192.0.2.98/21 brd 10.100.99.98 scope link eth1
      inet6 2001:db8:85a3:0:0:8a2e:370:7334 brd ff02::1 scope link eth1
      inet6 2001:db8:85a3:0:0:8a2e:370:6666

The following specification is derived:

1. "serviceListeningPort: "9000"

2. "serviceListeningPort:  9000

3. "serviceListeningPort: { "port" :  9000  }


4. "serviceListeningPort: { "port" : "9000" }
5. "serviceListeningPort: { "port" : "9000",   "address" : "192.0.2.254" }

6. "serviceListeningPort: { "port" : "9000", "name" : "server1" }

7. "serviceListeningPort: { "port" : "9000", "interface" : "eth1"}
8. "serviceListeningPort: [
      { "port" : "9000", "interface" : "lo"                                    }
      { "port" : "9000",   "address" : "192.0.2.39", "option" : "IPV4_ONLY" }
      { "port" : "9000", "interface" : "eth1",       "option" : "IPV6_ONLY" }

These forms are described as:

Form 1 - 4

Listens on port 9000 on ANY address over ALL interfaces.

Form 5

Listens on port 9000 on address 192.0.2.254 only.

Form 6

Listens on port 9000 on the address associates with server1.

Form 7

Listens on port 9000 on the address associates with interface eth1 and accepts IPV4 address connections using the mapped IPV4.

Form 8

Listens on port 9000 on the address associates with interface lo, on port 9000 address 192.0.2.39 accepting only IPV4 addresses, and on port 9000 with addresses associated with interface eth1 accepting onlyIPV6 addresses.

Most of this logic handles selecting the network interface adapter based on the network interface adapter’s identifying name or the address. The interface can be searched for based on the requested address.

Specifying multiple adapters means that each network specification resolves to only a subset of adapters. Precedence processing allows the specification of ANY address and ALL interfaces for the last network specification as a pool specification when the platform networking interfaces support mapping subset interface matches.

Parent topic: Network

4.3 Configure Reverse Proxy with NGINX to Access Oracle GoldenGate Microservices

Learn how to configure reverse proxy service using NGINX for accessing Oracle GoldenGate Microservices without using port numbers.

Reverse proxy enables accessing microservices using one single port (443) in a deployment. This enables encapsulation of the URL for microservices over an unsecure deployment.

Note:

Reverse proxy is optional, however, Oracle recommends that you ensure easy access to microservices and provide enhanced security.

You can run microservices in an unsecure deployment on loopback address and front it with an HTTP reverse proxy using the NGINX installation.

When sending trail files from Oracle GoldenGate Classic to Microservices environment that is configured with a reverse proxy, use a pump Extract from Oracle GoldenGate Classic with SOCKSPROXY option. When sending trail files from Oracle GoldenGate Microservices to Classic Architecture use the ogg protocol in the Distribution Service configuration.

See Connecting Classic to MA and Connecting MA to Classic in Administering Oracle GoldenGate.

Reverse Proxy Support

You can configure Oracle GoldenGate Microservices Architecture to use a reverse proxy. Oracle GoldenGate MA includes a script called ReverseProxySettings that generates configuration file for only the NGINX reverse proxy server.

For example, the Administration Service is available on http://goldengate.example.com:9001 and the Distribution Service is on http://goldengate.example.com:9002. With reverse proxy, each of the microservices can simply be accessed from the single address. For example, http://goldengate.example.com/distsrvr for the Distribution Service. The URL is different for each service and is by name instead of by port.

You can use these options by running the ReverseProxySettings utility. Here are the options available with this utility: 

-o or --output

The output file name. The default file name is ogg.conf.

-P or --password

A password for a Service Manager account.

-l or --log

Log file name and initiates logging. The default is no logging.

--trailOnly

Configure only for inbound trail data.

-t or --type

The proxy server type. The default is Nginx.

-s or --no-ssl

Configure without SSL.

-h or --host

The virtual host name for reverse proxy.

-p or --port

The reverse proxy port number. The defaults are 80 or 443.

-? or --help

Display usage information.

-u or --user

Name of the Service Manager account to use.

-v or --version

Displays the version.

These values are used when connecting to the Service Manager and are required when authentication is enabled.

Prerequisites

You can use any reverse proxy service with MA. The following example provides a process that you can follow to configure other reverse proxy services in conjunction with the documentation for your proxy server.

The following prerequisites provide details on the minimum requirements to configure an NGINX Reverse Proxy. Similar requirements may be required for your environment and reverse proxy if not using NGINX. Consult the documentation for your reverse proxy.

  1. Install NGINX, see Install the NGINX Web Server and Proxy on Oracle Linux. For Oracle Linux, the command to install NGINX is:

    yum —y install NGINX

  2. Check the JRE version to be JRE 8 or higher.

  3. Install Oracle GoldenGate MA.

  4. Create one or more active MA deployments.

  5. Ensure that the Oracle user has sudo permissions.

  6. Configure the PATH environment variable to include the NGINX installation directory path.

Configuring NGINX Reverse Proxy

An Oracle GoldenGate MA installation includes the ReverseProxySettings utility. The ReverseProxySettings utility is located in the $OGG_HOME/lib/utl/reverseproxy directory. To identify additional commands that can be used with the ReverseProxySettings utility, run the utility with the --help option: 

$OGG_HOME/lib/utl/reverseproxy/ReverseProxySettings --help

To add the NGINX certificate to the Distribution Service’s client wallet as a trusted certificate, see Trusted Certificates.

  1. To generate a configuration file for NGINX Reverse Proxy, navigate to the location of the ReverseProxySettings utility: 

    cd $OGG_HOME/lib/utl/reverseproxy
  2. Run the ReverseProxySetting utility:
    ReverseProxySettings -u adminuser -P adminpwd -o ogg.conf http://localhost:9100

    In this code snippet, adminuser is the deployment user name and adminpwd is the deployment user password used to login to the deployment.

  3. Replace the existing NGINX configuration with the configuration that was generated using the ReverseProxySetting utility for your MA deployment: 

    sudo mv ogg.conf /etc/nginx/conf.d/nginx.conf

    However, this NGINX configuration isn't complete without the events section, and enclosing the map and server sections in http.

    Optionally, you can use the default nginx.conf file and add the generated ogg.conf by adding an include statement similar to this:

    include /etc/nginx/conf.d/ogg.conf;

    In this case, you must comment out the other servers section.

  4. Generate a self-signed certificate for NGINX:

    sudo sh /etc/ssl/certs/make-dummy-cert /etc/nginx/ogg.pem

    For distribution paths to go through the reverse proxy, you need to use a valid certificate. It's better to specify the same certificate that the deployment is using to process incoming requests, otherwise, starting the path will fail with the next error in Distribution Service:

    2019-03-26T11:26:00.324-0700 ERROR| ERROR   OGG-10351  Oracle GoldenGate Distribution
 Service for Oracle:  Generic error -1 noticed. Error description - Certificate validation
 error: Unacceptable certificate from test00abc: application verification failure. (A4)

  5. Validate the NGINX configuration:

    sudo NGINX -t
    The output would show the following, if the command is successful:
    
NGINX: the configuration file /etc/NGINX/NGINX.conf syntax is ok
NGINX: configuration file /etc/NGINX/NGINX.conf test is successful

  6. Reload NGINX with the new configuration:

    sudo NGINX -s reload

    If the changes for the configuration file are not loaded, stop and restart the proxy.

  7. To test if you can access the microservices after NGINX is set up successfully, open the web browser.

  8. Enter the proxy URL for the Service Manager using port number 443, similar to the following:

    http://dc.example.com:443

    This would open the Service Manager login page, from where you can access the other microservices also. If you want to directly access a microservice, you can enter the proxy URL for that microservice, as given in the ogg.conf file, generated previously.

Also see this video on configuring the NGINX reverse proxy.

SSL Termination

When there is an unsecure connection between the reverse proxy, which uses a TLS-based connection, and the origin server, it is referred to as reverse proxy SSL-termination.

Note:

In SSL-Termination the connections between the reverse proxy and the origin servers are unsecure.

However, SSL-bridging is also supported where the connections between the client and reverse proxy is secured and the connection between the reverse proxy and the origin server is also secured.

Parent topic: Network

4.4 Network Communication

An MA server is the originator of all the response messages sent to the client when a request is sent to the server.

An MA server neither serves as a proxy nor supports tunneling of response messages generated by other applications. Secured network communications use TLS 1.2 or DTLS (Datagram Transport Layer Security) libraries. MA Oracle platforms uses the Oracle SSL toolkit (NZ), which includes Oracle Wallet integration.

For heterogeneous platforms, the Oracle SSL toolkit is used where available.

Parent topic: Network