SSL
===

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

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

#. 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
then the following must be true

-  The *Gateway* CA bundle needs to contain the root CA, any intermediate and the certificate.
-  The *Server* CA bundle needs to be separate files for the root CA, any intermediate and the certificate.


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

The ``www.enterprise.https.conf`` is a nginx configuration file for SSL
configurations. It is setup to use cert files called ``server.crt`` and
``server.key`` 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: that 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-sever/etc/wk-server-config.json`` and add

   ::

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

#. Restart Anaconda Enterprise Notebooks services 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 the *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 configuration file
``/opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json`` 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 provide for SSL on the compute nodes
directly. We recommend installing the *Compute* on the same machine as
the *Gateway* and using ``http://localhost:5002`` for the URL value
while adding it as a resource.

You would need 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 to be able to read
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* of 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
