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 private network (as explained in demo projects), the interaction sessions between the APS controller and the APS connector are secure, as that framework implements the SSL authentication method transparently and in accordance with the security requirements.
In this document:
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:
Connections from an application UI JavaScript code embedded to a platform control panel (CP).
Connections to an APS application instance.
Connections from an APS application instance.
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 following sections.
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 built-in platform mechanism.
When the APS controller forwards a request to an application, it specifies the identified user ID in the APS-Identity-ID header.
As specified in Security Model, by default, the APS controller and APS applications authenticate each other by sending their own X509 certificates.
The APS authentication environment is initialized by the following steps:
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.
The 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.
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 (containing 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 methods:
Store the full 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.
The APS controller interacts with APS applications as follows:
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.
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.
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.
An application must send its own SSL server certificate and validate the APS controller client certificate of incoming HTTPS connection requests. The APS controller certificate is self-signed, meaning 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");
}
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 an 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 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());
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 an OAuth key and secret pair that will be used by the APS controller and APS connector to authenticate each other.
The provider staff must initiate the 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.
The provider can allow a 3rd party system to get access to the APS bus and grant that system permissions for certain 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 consumer key and secret pair and grant the required permissions as explained in the Set Up the 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.