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.

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``
#. Copy the cert and key files to ``/etc/nginx``
#. 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.
#. 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

#. Restart Anaconda Enterprise Notebooks services on each of the nodes
   with the appropriate command for the service, *Server*, *Gateway*, or
   *Compute*:

   ::

        service wakari-server restart
        service wakari-gateway restart
        service wakari-compute restart

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

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

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

::

    {
        EXISTING_CONFIGURATION,
        "https": {
            "key": "/path/to/certs/server.key",
            "cert": "/path/to/certs/server.crt"
        }
    }

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:

::

    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.

Using private root CA or self-signed certs
------------------------------------------

If you configure the *Gateway* to use SSL certificates that are
self-signed or are signed by a private CA root you must do the following
things on the *Server*.

Copy the certificate chain used to sign the SSL cert on *Gateway* to the
*Server*

Add the following line to
``/opt/wakari/wakari-server/etc/wakari/wk-server-config.json`` on the
*Server*

::

    "verify_gateway_certificate": "/path/to/gateway/cert/file"

Be sure to include a comma at the end of the line before this one (or at
the end of this line if it is the first).

This will allow for the *Server* to verify that the certificate
presented by the *Gateway* is a valid certificate

If you configure SSL on the *Server* using self-signed or private
certificates, you must manually register the *Gateway* with the server.
This is done through the Admin web interface.

Using the ca entry for SSL certs from the AEN Server - AEN Gateway as a client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AEN handle a single certificate file (most likely a self-signed cert)
and multiple certificate files in the **ca** entry.

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

::

    {
      EXISTING_CONFIGURATION,
      "https": {
          EXISTING_CONFIGURATION,
          "ca": ["/path/to/certs/ca1", "/path/to/certs/ca2"]
      }
    }

**Note**: AEN doesn't handle a single cert file with multiple
certificates in it.

.. toctree::
   :hidden:

   wakari_https_conf
