External Connector with OAuth Authentication

When setting external APS connectors based on the OAuth authentication, the recommended way to arrange the interaction between the APS controller and those APS connectors is the use of a proxy server for both inbound and outbound requests.

Deployment Schema

In the platform, the APS controller is installed on the OSS management node (MN). Normally, MN has one physical interface connected to the Backnet and isolated from the Internet. The APS controller is available on TCP port 6308 via HTTPS. For APS application instances bound to the Backnet, the APS controller is available through its endpoint https://<mn_ip>:6308/aps/2/, where <mn_IP> is the management node IP address on the Backnet.

To arrange interaction of the APS controller with the external APS connectors, the provider needs a proxy with internal firewall, called APS Proxy or APS Controller Proxy as in the following diagram.

The APS proxy must represent the APS controller in the Internet by exposing a public IP address <inbound_IP>. The APS controller must be aware of the host domain name (along with the TCP port) resolved to this public IP address in order to use it in the APS-Controller-URI header when sending REST requests.

The APS proxy processes and transfers packets between the APS controller and an APS application instance located in the Internet using the following rules.

1. When the APS controller gets a request with the aps.network.proxy configuration, as in the above diagram, and a respective request must be forwarded to an external APS connector, the APS controller will send such a request through the APS proxy <outbound_IP>:<outbound_port>.
2. When the APS proxy receives on its Backnet interface a TCP packet coming from the APS controller and addressed to a host in the Internet, it does the following:
   • Forwards the packet to the public interface.
   • Masquerades the source local IP address <mn_IP> with the source public IP address <apsc_public_IP>.
   • Sends the packet to the destination host.
3. When the APS proxy receives on its public interface <inbound_IP>:<inbound_port> a TCP packet, it does the following:
   • Translates the destination IP address and TCP port to the management node local IP address, that is <mn_IP>, and TCP port (typically 6308).
   • Forwards the packet to the Backnet interface.
   • Sends the packet to the updated destination IP address.

APS Controller Configuration

As mentioned earlier, the APS controller must be aware of both outbound (on Backnet) and inbound (in the Internet) proxy connections.

Configure it using the following steps:

1. Login to the provider control panel.

2. Navigate to System > Settings and then follow the APS Connection: Proxy settings link.

3. Click Edit to start the configuration.

   

4. Check the Enable proxy for APS applications box.

5. Set the following parameters in the Outbound Proxy section:

   • In the Hostname and port field, enter the IP address and TCP port of the proxy interface on Backnet.
   • If the proxy requires authentication, check the Proxy authentication required and then enter the valid login and password.

   If the APS controller receives a REST request with the "aps"{"network":"proxy"} section, it forwards the request to the application through the outbound proxy.

6. In the Inbound Proxy section, enter the APS controller public URL as configured in the proxy server. The APS controller will assign this URL to the APS-Controller-URI header when sending a REST request to an APS application endpoint located in the Internet.

7. Click Submit to save the new configuration.

Setting External Application Instance

Since in the same hosting system a provider may have some APS application endpoints available on the Backnet and the other in the Internet, the APS controller needs to know the location of each of them. By default, the APS controller considers each new APS application instance to be installed on the Backnet. Therefore, when installing an APS application instance in the Internet and to make the APS controller use the outbound proxy, the POST request must contain the "network":"proxy" property and the "auth":{"oauth":...} section as in the following example:

POST /aps/2/applications

{
   "aps": {
      "package": {
         "type": "http://event-mgmt.demo.apsdemo.org/vpscloud"
      },
      "endpoint": "https://endpoint.isv1.example.com:443/vpsclouds",
      "network": "proxy",
      "auth": {
         "oauth": {
            "key": "c4b3510e-a432-4e2c-940c-d151e05b68fg",
            "secret": "b57247b4-8174-420c-aa0f-1f7f863bb616"
         }
      }
   },
   ...
}

To send such a request for creating an APS application instance on behalf of the provider staff, use a REST client.

In the request, the body must contain the aps section and JSON representation of the APS resource to be created.

← External Connector with SSL Authentication

Docker based Deployment →