SSL
===

The Anaconda Enterprise Notebooks (AEN) Server uses ``NGINX`` to proxy
all incoming http(s) requests to the Server running on a local port,
as well as 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.

SSL certs with passphrases are not currently supported.

The ``www.enterprise.conf`` file is the default ``NGINX`` ``.conf`` file
used for Anaconda Enterprise Notebooks. It is copied to the
``/etc/nginx/conf.d`` directory during Server install.

Note: This document is for the case where you are setting up SSL after the Gateway
has been installed and registered with the Server.

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 following must be true:

*  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


Configure SSL on the Server
---------------------------

The ``www.enterprise.https.conf`` is an ``NGINX`` configuration file for SSL
configurations. It uses ``server.crt`` and ``server.key`` cert files,
but these value *must* be changed to point to signed cert
files for your domain.

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

Perform the following steps as ``root``:

#. Stop ``NGINX``: ``service nginx stop``
#. Move the ``/etc/nginx/conf.d/www.enterprise.conf`` file to a backup
   directory
#. Copy the ``/opt/wakari/wakari-server/lib/python2.7/site-packages/``
    ``wk_server/config/www.enterprise.https.conf`` file to ``/etc/nginx/conf.d``

   NOTE: Only one of ``www.enterprise.conf`` or ``www.enterprise.https.conf`` can be in ``/etc/nginx/conf.d``

#. Edit the
   /etc/nginx/conf.d/\ :doc:`www.enterprise.https.conf <wakari_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
#. Start ``NGINX``: ``service nginx start``
#. Update the ``WAKARI_SERVER`` and ``CDN`` settings in the config files
   to use https instead of http. The config files that need to be
   changed are:

   ::

       /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

#. Edit ``/opt/wakari/wakari-server/etc/wakari/wk-server-config.json`` and add
   ::

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

#. Restart Anaconda Enterprise Notebooks services on the Server:

   ::

       service wakari-server restart

#. Browse to Anaconda Enterprise Notebooks and verify that the browser
   uses ``https``.

#. In the Admin settings, under ``Data Centers`` select ``Gateway`` and check the ``https`` box.

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

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


Configure SSL on the Gateway
------------------------------

#. Edit ``/opt/wakari/wakari-compute/etc/wakari/config.json`` to change http to https

#. Modify the ``/opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json`` configuration file and add:

   .. code:: json

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

#. If you have a Server cert that was signed by a private root CA (and/or intermediate authority)
   add the following to the ``https`` key

   .. code:: json

       "ca": ["/opt/wakari/wakari-gateway/etc/server.crt"]

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

#. Restart the Gateway: ``sudo service wakari-gateway restart``

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 need to set correctly to prevent them
from being read by others. Only the root user needs read access to
the cert files since ``NGINX`` is run by root.

Assuming the cert files are called ``server.crt`` and ``server.key``,
use the ``root`` account to set the permissions as follows:

.. code:: bash

    chmod 600 server.key
    chmod 600 server.crt

Strict transport security header
--------------------------------

Strict-Transport-Security is enabled by default in the
``www.enterprise.https.conf`` file.

::

    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

It is necessary that you comment out this line if *both* the
following conditions are true:

* The Gateway is running on the same host as the Server; and

* SSL has not been enabled for the Gateway

Leaving it enabled when these conditions are true will cause a mismatch
in protocols between the Server and Gateway and apps will fail to
launch correctly.

.. toctree::
   :hidden:

   wakari_https_conf
