Session Management

This document provides important information for developers of APS applications to ensure their applications comply with security requirements in the APS environment.

Note

If an APS application connector is installed in the APS PHP framework on the Backnet (private network), for example, as explained in demo projects, there is no worry about the security process, as that framework implements the SSL authentication method transparently and in accordance with the security requirements.

Secure Data Transportation

For all connections on the APS bus, the network security is implemented by means of the Transport Layer Security (TLS) protocol and the related cryptography standards used by it.

Warning

On the APS bus, non-secure HTTP (that is non-HTTPS) connections are not allowed.

The APS ecosystem allows the following types of connections between the APS controller and other participants:

1. Connections from an application UI JavaScript code embedded to a platform control panel (CP).
2. Connections to an APS application instance.
3. Connections from an APS application instance.
4. Connections from a 3rd party system (can be implemented by a script or a GUI REST client).

All incoming and outgoing APS REST requests are authenticated as explained in the next sections.

Authentication of UI Requests

Once a user logs in to the platform control panel (CP) and then uses an application UI, the REST requests from the application JavaScript code go through the UI node to the APS controller. The UI node and the APS controller identify the user by means of the platform built-in mechanism.

When the APS controller forwards a request to an application, it specifies the identified user ID in the APS-Identity-ID header.

SSL Authentication of Application Instances

SSL Certification

As specified in Security Model, by default the APS controller and APS applications authenticate each other by sending their own X509 certificates.

APS authentication environment is initialized by the following steps:

1. To enable the issue of SSL certificates and keys for APS application instances, the APS controller contains its own Certificate Authority (APS CA). To set up the authority, a root certificate (APS CA certificate) with the corresponding pair of encryption keys is generated during the APS controller installation. The ca.pem file contains the root certificate itself and the CA private key.
2. APS controller issues a self-signed certificate for itself. The controller.pem file contains the SSL certificate of the APS controller and its private key.
3. Every time when a new APS application instance is being deployed, the application will get the following components from the APS controller as described in Application Deployment:
   • Its own SSL certificate (also contains the public key) and the private key issued by the APS CA
   • The APS controller certificate

An application can process the APS controller client SSL certificate using one of the following ways:

• Store the whole APS controller certificate to compare it with the certificate received during an SSL handshake process. This is implemented in the APS PHP runtime.
• Compute and store the SHA hash (finger-print) of the certificate. During the SSL handshake process, the application computes the hash of the received certificate and compares it against the stored hash.

Message Flows in APS Environment

The APS controller interacts with APS applications as follows:

1. On the private network (backnet), the APS controller exposes its secure endpoint on TCP port 6308 to accept HTTPS requests authenticated by an SSL certificate from an application. The APS controller internally stores the APS CA (ca.pem) and its own (controller.pem) certificates.
2. The APS controller establishes an HTTPS connection with an application by using its own SSL certificate in the handshake process. The application uses the stored APS controller certificate or its SHA finger-print to identify the APS controller.
3. An application can establish an HTTPS connection with the APS controller using its own SSL certificate in the handshake process. The application stores its certificate in a file. If the APS PHP runtime is used, the certificate is stored in the <app1>/config/<app-id>.pem file, where:
   • <app1> is the path to the folder where the APS application connector is deployed.
   • <app-id> is a unique ID of the APS application instance.

Authentication on Application Side

Incoming Connections

An application must send its own SSL server certificate and validate the APS controller client certificate on incoming HTTPS connections. Since the APS controller certificate is self-signed, the authentication can be configured in one of the following ways:

• Add the self-signed APS controller certificate to the list of known CA certificates. For example, if the OpenSSL package is used, this can be done by means of the openssl utility. The web server must require validation of SSL client certificates. For example, in Apache, the SSLVerifyClient mod_ssl option must be set to required.

• Turn off certificate validation by Apache and validate it by an application script. For example, in Apache, the SSLVerifyClient mod_ssl option must be set to optional_no_ca. In this case, the application will be able to get the received certificate in environment variables, for example, the $_SERVER array in PHP. To simplify certificate processing, configure the web server to pass the received certificate as a single unit by adding the +ExportCertData SSL option. For example, the mentioned options can look as follows in the /etc/httpd/conf.d/ssl.conf file:

  SSLVerifyClient optional_no_ca
  SSLOptions +StdEnvVars +ExportCertData
  

  Received client certificates are processed as in the following excerpt from the handleHttpRequest method in the runtime.php script shipped within the APS PHP runtime:

  $currCert = openssl_x509_parse($_SERVER['SSL_CLIENT_CERT']);
  if ($savedCert != $currCert) {
      throw new \Exception("Unauthorized access. Saved controller certificate and received are different");
  }
  

Outgoing Connections

When establishing a connection with the APS controller, an application must validate the SSL server certificate of the APS controller and send its own SSL client certificate to the APS controller during SSL handshake. For this purpose, the application can use the cURL package configured as in the following excerpts from the sendRequest method in the apsc.php script shipped within the APS PHP runtime.

• Send own SSL certificate:

  curl_setopt($this->ch, CURLOPT_SSLCERT, TypeLibrary::getConfFile().".pem");
  

• Do not validate host name in the SSL server certificate received from the APS controller:

  curl_setopt($this->ch, CURLOPT_SSL_VERIFYHOST, false);
  

• Validate the SSL server certificate received from the APS controller:

  curl_setopt($this->ch, CURLOPT_SSL_VERIFYPEER, true);
  

• Use the stored APS controller certificate as if it is the CA certificate. This makes cURL validate the SSL server certificate received from the APS controller against the stored APS controller certificate:

  curl_setopt($this->ch, CURLOPT_CAINFO, TypeLibrary::getAPSCCertFile());
  

OAuth Authentication of Application Instances

An ISV can require the APS controller to use the OAuth authentication method for their APS connector instead of the default SSL authentication. For this purpose, the provider staff must get a pair of OAuth key and secret that will be used by the APS controller and APS connector to authenticate each other.

The provider staff must initiate installation of an APS application instance by sending to the APS controller a REST request containing the authentication section similar to the following:

POST /aps/2/applications

{
   "aps": {
      "endpoint": "<endpoint URL>",
      "auth": {
         "oauth": {
            "key": "c4b3510e-a432-4e2c-940c-d151e05b68fg",
            "secret": "b57247b4-8174-420c-aa0f-1f7f863bb616"
         }
      }
   },
   ...
}

The request must be sent from a script or REST client authenticated by the APS controller as explained in the next section.

Authentication of External Management Systems

The provider can allow a 3rd party system to get access to the APS bus and grant that system permissions for some operations on the APS bus. For that system, the provider must create a new user or use an existing one in order to generate a pair of consumer key/secret and grant the required permissions as explained in the Set up User’s Credentials section.

The external system must be able to use the supplied pair of OAuth parameters to generate the Authorization HTTP header in accordance with the OAuth Core 1.0 Revision A specification, for example:

Authorization: OAuth
oauth_consumer_key="LFkJjlAjluEfL57dRxNnsi6WWMDduxEl",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1508234992",
oauth_nonce="kUO2sQ",
oauth_version="1.0",
oauth_signature="nYuf8bT3rOOMaMJR9ZosPKoNupo%3D"

The APS controller will validate the incoming request by the OAuth signature.

← Protocols

HTTP Headers →