===============
Configuring SSL
===============


The server node uses NGINX to proxy all incoming http(s) requests
to the server running on a local port, and uses NGINX for SSL termination. The
default setup uses http---non-SSL---since cert files are required
to configure SSL and each enterprise will have their own cert
files.


The ``www.enterprise.conf`` file is the default ``nginx.conf``
file used for AEN. It is copied to the ``/etc/nginx/conf.d``
directory during server installation.

NOTE: This section describes setting up SSL after your gateway
node has been installed and registered with the server node.


Copying the required files
==========================


To configure SSL on AEN, you will need the following files:

*  Server certificate and key
*  Server CA bundle
*  Gateway certificate and key
*  Gateway CA bundle

Configure SSL on AEN:

#. Copy the Gateway certificate and key to ``/opt/wakari/wakari-gateway/etc/`` on
   the Gateway as ``gateway.crt`` and ``gateway.key``.

#. Copy the Gateway CA bundle to ``/opt/wakari/wakari-server/etc/`` on the Server.

#. Copy the Server certificate and key to ``/etc/nginx`` on the Server as
   ``server.crt`` and ``server.key``.

#. Copy the Server CA bundle to ``/opt/wakari/wakari-gateway/etc/`` on the Gateway.

If you have a certificate that was signed by a private root CA
and/or an intermediate authority:

*  The Gateway CA bundle can contain the root CA, any intermediate authority
   and the certificate.

*  The Server CA bundle must be separated into individual files for the
   root CA, any intermediate and the certificate.

Configuring SSL on the server node
==================================

The ``www.enterprise.https.conf`` is an NGINX configuration file
for SSL. It is set up to use the ``server.crt`` and
``server.key`` cert files.

CAUTION: You must change these values to point to the signed cert
files for your domain.

NOTE: Self-signed certs or those signed by a private root CA
require additional configuration.

Perform the following steps as root:

#. Stop NGINX:

   .. code-block:: bash

      service nginx stop

#. Move the ``/etc/nginx/conf.d/www.enterprise.conf`` file to a
   backup directory.

#. Copy the
   ``/opt/wakari/wakari-server/etc/nginx/conf.d/www.enterprise.https.conf``
   file to ``/etc/nginx/conf.d``.

   NOTE: ``/etc/nginx/conf.d`` may have ``www.enterprise.conf`` or
   ``www.enterprise.https.conf`` but it may not have both.

#. Edit the
   ``/etc/nginx/conf.d/www.enterprise.https.conf``
   file and change the ``server.crt`` and ``server.key`` values
   to the names of the real cert and key files if they are
   different.

#. Restart NGINX by running:

   .. code-block:: bash

      service nginx start

#. Update the WAKARI_SERVER and CDN settings to use https instead
   of http in the following configuration files:

   .. code-block:: bash

      /opt/wakari/wakari-server/etc/wakari/config.json
      /opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json
      /opt/wakari/wakari-compute/etc/wakari/config.json

#. Copy the gateway certificate, ``gateway.crt`` to ``/opt/wakari/wakari-server/etc/``.

#. In an editor, open ``/opt/wakari/wakari-server/etc/wakari/wk-server-config.json``
   and add::

      "verify_gateway_certificate": "/opt/wakari/wakari-server/etc/gateway.crt"

#. Restart AEN services on the server by running:

   .. code-block:: bash

      service wakari-server restart

   NOTE: This step may return an error since the gateway has
   not yet been configured for SSL.

#. In AEN, verify that the browser uses https. On the Admin
   Settings page, under Data Centers, click Gateway, then select
   https:

   .. figure::  /img/aen-install-https.png

      ..

   |



Configuring SSL on the gateway
==============================

#. For all types of SSL certificates,
   in ``/opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json``, add::

      {
          EXISTING_CONFIGURATION,
          "https": {
              "key": "/opt/wakari/wakari-gateway/etc/gateway.key",
              "cert": "/opt/wakari/wakari-gateway/etc/gateway.crt"
          }
      }

#. For a server certificate signed by a private root
   CA or signed by an intermediate authority, add:

   .. code:: json

      {
         EXISTING_CONFIGURATION,
         "https": {
             "key": "/opt/wakari/wakari-gateway/etc/gateway.key",
             "cert": "/opt/wakari/wakari-gateway/etc/gateway.crt",
             "ca": ["/opt/wakari/wakari-gateway/etc/server.crt"]
          }
       }

   NOTE: The ca key must contain separate values for the paths
   to the CA root, any intermediates and the certificate for the
   Server.

#. For a gateway certificate that is encrypted using a passphrase,
   add:

   .. code:: json

      {
         EXISTING_CONFIGURATION,
         "https": {
             "key": "/opt/wakari/wakari-gateway/etc/gateway.key",
             "cert": "/opt/wakari/wakari-gateway/etc/gateway.crt",
             "passphrase": "mysecretpassphrase"
          }
       }

   NOTE: Alternatively, the passphrase can be passed using an environment variable or
   entered when the wakari-gateway service is manually started.

   EXAMPLES:

   .. code:: bash

      # using an environment variable
      AEN_GATEWAY_SSL_PASSPHRASE='mysecretpassphrase' wk-gateway

   .. code:: bash

      # starting wakari-gateway manually
      sudo service wakari-gateway start --ask-for-passphrase
      Passphrase?


#. Restart the gateway:

   .. code-block:: bash

      sudo service wakari-gateway restart


Configuring SSL on compute nodes
================================

Anaconda Enterprise does not support direct SSL on Compute Nodes.
If you need SSL on Compute Nodes, you must install each
Compute Node on the same server as a Gateway
using ``http://localhost:5002`` for the URL value
while adding it as a resource, and you must use a Gateway for
each and every Compute Node.


Security reminder
=================

The permissions on the cert files must be set correctly to
prevent them from being read by others. Since NGINX is run by the
root user, only the root user needs read access to the cert files.

EXAMPLE: If the cert files are called ``server.crt`` and
``server.key``, then use the root account to set permissions:

.. code-block:: bash

   chmod 600 server.key
   chmod 600 server.crt


Enabling or disabling the Strict-Transport-Security header
==========================================================

By default, Strict-Transport-Security (STS) is enabled in
the ``www.enterprise.https.conf`` file:

.. code-block:: bash

    add_header Strict-Transport-Security max-age=31536000;

It can remain enabled if either of the following is true:

* The gateway is running on a different host than the server.

  or

* SSL has been enabled for the gateway.

You must comment out this line if both of the following are true:

* The gateway is running on the same host as the server.

  and

* SSL has not been enabled for the gateway.

Leaving STS enabled when these conditions are true will
cause a mismatch in protocols between the server and gateway,
causing your apps to fail to launch correctly.
