External Connectors 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 to use 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, the MN has one physical interface connected to the Backnet and isolated from the Internet. The APS controller is available on the TCP port 6308 through 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 an internal firewall, called APS Proxy or APS Controller Proxy as in the following diagram.

../../../../../../_images/apsc-proxy.png

The APS proxy must represent the APS controller in the Internet through a public IP address (inbound_IP). The APS controller must know 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 performs the following tasks:

    • Forwards the packet to the public interface.

    • Masquerades the source local IP address <mn_IP> using its 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 performs the following tasks:

    • 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

The APS controller must be aware of both outbound (in the Backnet) and inbound (in the Internet) proxy connections.

Configure the APS controller 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.

    ../../../../../../_images/proxy-config.png
  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 the 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

Due to the possibility of a provider’s platform having some APS application endpoints available on the Backnet and the others on 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 as being installed on the Backnet. Therefore, when installing an APS application instance on 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.