. . .

Configure SSL on Unix

This page describes which settings you need to configure when you want to install SSL / HTTPS for ApiOmat on a Linux Sever. Before configuring Apache/HTTPD and apiomat.yaml you need to install certificates, which will be used in the Apache settings. So before starting the installation it is recommended to have OpenSSL installed (Linux: "apt-get install openssl" / "yum install openssl"), so you can use the console command "openssl" as it is described in the following section.

Creating a certificate with OpenSSL

You can either create an unsigned or a signed certificate.


# generate private key
mkdir -p /etc/ssl/private
openssl genrsa -out /etc/ssl/private/apiomat.key 2048
# generate certificate with key
mkdir -p /etc/ssl/certs
openssl req -new -x509 -key /etc/ssl/private/apiomat.key -days 365 -sha256 -out /etc/ssl/certs/apiomat.crt


# generate private key
mkdir -p /etc/ssl/private
openssl genrsa -out /etc/ssl/private/apiomat.key 2048
# generate certificate with key
mkdir -p /etc/ssl/certs
openssl req -new -key /etc/ssl/private/apiomat.key -out ~/apiomat.csr
# The common name must be assigned here with your domain name (for example: example.com).

A csr file is used to request a signed certificate (Certificate Signing Request).

How to proceed with this csr file depends on the respective certificate authority (CA). It should be explained in their documentation. The created signed certificates from the CA must now be stored on the server (for example, under /etc/ssl/certs/apiomat.crt).

Enable SSL in Apache

In order to use SSL, Apache has to listen on port 443. This setting can be found under ports.conf in the Apache main folder:

<IfModule mod_ssl.c>
Listen 443

Now Apache needs to be reloaded, the SSL module activated and Apache restarted:

sudo service apache2 reload
sudo a2enmod ssl
sudo service apache2 force-reload

Configure SSL for the Dashboard

Create a new file named ssl.conf under /etc/apache2/sites-available/

HSTS Header

The recommended HSTS configuration is: Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

But you need to be aware of its consequences:

  • includeSubdomains: This will affect all subdomains, even the ones that aren't managed by this Apache. For example, when you configure HSTS for "dashboard.example.com" and use the includeSubdomains option, it will also affect "intranet.example.com". Now if you don't have SSL configured for "intranet.example.com", some browsers might not allow users to access that URL anymore.

  • preload: This enables the domain to be included in the HSTS preload list that's included in browsers by their vendors (like Google for Chrome) and it can take very long for the list to be changed, so when combined with includeSubdomains and making a configuration error, not only might "intranet.example.com" not be accessible, but it can take a month to make it accessible again.

But that shouldn't be a reason not to set HSTS, because it's important against MITM attacks. Just be cautious with the includeSubdomains and preload options.

You can read more about this here: https://www.owasp.org/index.php/HTTP_Strict_Transport_Security_Cheat_Sheet

<VirtualHost *:443>
SSLEngine on
SSLCertificateFile /etc/ssl/certs/apiomat.crt
SSLCertificateKeyFile /etc/ssl/private/apiomat.key
SSLProtocol all -SSLv2 -SSLv3
SSLHonorCipherOrder on
Header always set Strict-Transport-Security "max-age=31536000"
ServerAlias server.domain
ServerName server.domain
Alias / "<path to dashboard>/"
<Directory "<path to dashboard>">
AllowOverride All
DirectoryIndex index.php
<IfVersion < 2.4>
Order deny,allow
<IfVersion >= 2.4>
Require all granted
SetEnv apiomat.config /etc/apiomat/apiomat.yaml
php_value date.timezone Europe/Berlin
php_value memory_limit 1024M
php_value max_execution_time 600
php_value max_input_time 300
php_value upload_max_filesize 1024M
php_value post_max_size 2048M
php_value default_socket_timeout 300
php_value session.cookie_httponly 1
Options -Indexes
TraceEnable Off

Now the page only needs to be activated:

sudo a2enmod headers
sudo a2ensite ssl.conf
sudo service apache2 force-reload

Deactivate HTTP (only https mode)

If you want to allow only HTTPS, you can reach this via two ways. You can set the HSTS header (see SSL example) or edit the "normal" dashboard Apache configuration and replace it with the following content:

# Redirect for server.domain from http to https, using Apache
<VirtualHost *:80>
ServerName server.domain
Redirect permanent / https://server.domain/

If you use the second way, the SSL site must have been activated and checked. To apply the changes, Apache should be restarted.

sudo service apache2 force-reload

Configure YAMBAS

Check if the AJP proxy to yambas is intact.

curl -kv https://localhost/yambas/rest
# Should output the following: Yambas REST interface vx.x.x-xxxE on xxx.xxx.xxx.xxx:xxx

If the AJP proxy does not work anymore

  • Check if the 001-yambas.conf exists in Apache's site-available directory.

<IfModule mod_proxy.c>
ProxyPreserveHost on
ProxyPass /yambas ajp://localhost:8009/yambas
ProxyPassReverse /yambas ajp://localhost:8009/yambas
ProxyPass /apidocs ajp://localhost:8009/apidocs
ProxyPassReverse /apidocs ajp://localhost:8009/apidocs
ProxyPass /docs ajp://localhost:8009/docs
ProxyPassReverse /docs ajp://localhost:8009/docs
ProxyPass /installer ajp://localhost:8009/installer
ProxyPassReverse /installer ajp://localhost:8009/installer
  • Check if the AJP module is enabled in Apache.

sudo a2enmod proxy_ajp
sudo service apache2 restart
  • Check if the AJP connector is enabled in Tomcat. Go to the server.xml in the Tomcat directory and search for the following line:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

Configure apiomat.yaml to use Apache AJP proxy

After the AJP connector works, the apiomat.yaml needs to be adjusted.

# the internal address yambas and the dashboard uses to reach itself
admin: http://localhost:8080
# the public address for the live system, used e.g. in sdks or app-configuration
live: https://server.domain
# the public address for the staging system, used e.g. in sdks or app-configuration
staging: https://server.domain
# the public address for the test system, used e.g. in sdks or app-configuration
test: https://server.domain

Changes in existing applications

If any applications / backends were already created before, they will only work partially. Reason for this:

Each application has the URLs for Live, Staging and Test stored in the MongoDB.

You have to adjust these URLs manually using the Apidocs. These URLs need to be customized:

"liveClusterBaseURL" : "https://server.domain",
"testClusterBaseURL" : "https://server.domain",
"stagingClusterBaseURL" : "https://server.domain",

You can also change the values directly in the MongoDB manually. But this is only recommended to experienced users.

If the URLs have been adapted, yambas needs to be restarted.

sudo service aom-yambas restart