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.

Unsigned

# 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 

Signed

# 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
</IfModule>

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
	SSLCipherSuite "EECDH+ECDSA+AESGCM EECDH+aRSA+AESGCM EECDH+ECDSA+SHA384 EECDH+ECDSA+SHA256 EECDH+aRSA+SHA384 EECDH+aRSA+SHA256 EECDH+aRSA+RC4 EECDH EDH+aRSA RC4 !aNULL !eNULL !LOW !3DES !MD5 !EXP !PSK !SRP !DSS"
	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>
		<IfVersion >= 2.4>
				Require all granted
		</IfVersion>
 
    	SetEnv apiomat.config /etc/apiomat/apiomat.yaml
    	SetEnv YII_ENVIRONMENT PRODUCTION
    	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
	</Directory>
	TraceEnable Off
</VirtualHost>

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/
</VirtualHost>

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
</IfModule>

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.

	.....
common:
  hosts:
    # 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
  emails:
	.....

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

Configure SSL on Unix