SSL (AEN 4.1.2)
===============

.. raw:: html

    <p>The Anaconda Enterprise Notebooks (AEN) Server uses <code class="docutils literal"><span class="pre">NGINX</span></code> 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.</p>
    <p>SSL certs with passphrases are not currently supported.</p>
    <p>The <code class="docutils literal"><span class="pre">www.enterprise.conf</span></code> file is the default <code class="docutils literal"><span class="pre">NGINX</span></code> <code class="docutils literal"><span class="pre">.conf</span></code> file
    used for Anaconda Enterprise Notebooks. It is copied to the
    <code class="docutils literal"><span class="pre">/etc/nginx/conf.d</span></code> directory during Server install.</p>
    <p>Note: This document is for the case where you are setting up SSL after the Gateway
    has been installed and registered with the Server.</p>
    <div class="section" id="required-files">
    <h2>Required files<a class="headerlink" href="#required-files" title="Permalink to this headline">¶</a></h2>
    <p>To configure SSL on AEN, you will need the following files</p>
    <ul class="simple">
    <li>Server certificate and key</li>
    <li>Server CA bundle</li>
    <li>Gateway certificate and key</li>
    <li>Gateway CA bundle</li>
    </ul>
    <p>Configure SSL on AEN:</p>
    <ol class="arabic simple">
    <li>Copy the Gateway certificate and key to <code class="docutils literal"><span class="pre">/opt/wakari/wakari-gateway/etc/</span></code> on
    the Gateway as <code class="docutils literal"><span class="pre">gateway.crt</span></code> and <code class="docutils literal"><span class="pre">gateway.key</span></code>.</li>
    <li>Copy the Gateway CA bundle to <code class="docutils literal"><span class="pre">/opt/wakari/wakari-server/etc/</span></code> on the Server</li>
    <li>Copy the Server certificate and key to <code class="docutils literal"><span class="pre">/etc/nginx</span></code> on the Server as
    <code class="docutils literal"><span class="pre">server.crt</span></code> and <code class="docutils literal"><span class="pre">server.key</span></code></li>
    <li>Copy the Server CA bundle to <code class="docutils literal"><span class="pre">/opt/wakari/wakari-gateway/etc/</span></code> on the Gateway</li>
    </ol>
    <p>If you have a certificate that was signed by a private root CA and/or an intermediate
    authority the following must be true:</p>
    <ul class="simple">
    <li>The Gateway CA bundle can contain the root CA, any intermediate
    authority and the certificate</li>
    <li>The Server CA bundle must be separated into individual files for the
    root CA, any intermediate and the certificate</li>
    </ul>
    </div>
    <div class="section" id="configure-ssl-on-the-server">
    <h2>Configure SSL on the Server<a class="headerlink" href="#configure-ssl-on-the-server" title="Permalink to this headline">¶</a></h2>
    <p>The <code class="docutils literal"><span class="pre">www.enterprise.https.conf</span></code> is an <code class="docutils literal"><span class="pre">NGINX</span></code> configuration file for SSL
    configurations. It uses <code class="docutils literal"><span class="pre">server.crt</span></code> and <code class="docutils literal"><span class="pre">server.key</span></code> cert files,
    but these value <em>must</em> be changed to point to signed cert
    files for your domain.</p>
    <p><strong>NOTE: Self-signed certs or certs signed by a
    private root CA require additional configuration.</strong></p>
    <p>Perform the following steps as <code class="docutils literal"><span class="pre">root</span></code>:</p>
    <ol class="arabic">
    <li><p class="first">Stop <code class="docutils literal"><span class="pre">NGINX</span></code>: <code class="docutils literal"><span class="pre">service</span> <span class="pre">nginx</span> <span class="pre">stop</span></code></p>
    </li>
    <li><p class="first">Move the <code class="docutils literal"><span class="pre">/etc/nginx/conf.d/www.enterprise.conf</span></code> file to a backup
    directory</p>
    </li>
    <li><dl class="first docutils">
    <dt>Copy the <code class="docutils literal"><span class="pre">/opt/wakari/wakari-server/lib/python2.7/site-packages/</span></code></dt>
    <dd><p class="first last"><code class="docutils literal"><span class="pre">wk_server/config/www.enterprise.https.conf</span></code> file to <code class="docutils literal"><span class="pre">/etc/nginx/conf.d</span></code></p>
    </dd>
    </dl>
    <p>NOTE: Only one of <code class="docutils literal"><span class="pre">www.enterprise.conf</span></code> or <code class="docutils literal"><span class="pre">www.enterprise.https.conf</span></code> can be in <code class="docutils literal"><span class="pre">/etc/nginx/conf.d</span></code></p>
    </li>
    <li><p class="first">Edit the
    /etc/nginx/conf.d/<a class="reference internal" href="wakari_https_conf.html"><span class="doc">www.enterprise.https.conf</span></a>
    file and change the <code class="docutils literal"><span class="pre">server.crt</span></code> and <code class="docutils literal"><span class="pre">server.key</span></code> values to the
    names of the real cert and key files if they are different</p>
    </li>
    <li><p class="first">Start <code class="docutils literal"><span class="pre">NGINX</span></code>: <code class="docutils literal"><span class="pre">service</span> <span class="pre">nginx</span> <span class="pre">start</span></code></p>
    </li>
    <li><p class="first">Update the <code class="docutils literal"><span class="pre">WAKARI_SERVER</span></code> and <code class="docutils literal"><span class="pre">CDN</span></code> settings in the config files
    to use https instead of http. The config files that need to be
    changed are:</p>
    <div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">opt</span><span class="o">/</span><span class="n">wakari</span><span class="o">/</span><span class="n">wakari</span><span class="o">-</span><span class="n">server</span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">wakari</span><span class="o">/</span><span class="n">config</span><span class="o">.</span><span class="n">json</span>
    <span class="o">/</span><span class="n">opt</span><span class="o">/</span><span class="n">wakari</span><span class="o">/</span><span class="n">wakari</span><span class="o">-</span><span class="n">gateway</span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">wakari</span><span class="o">/</span><span class="n">wk</span><span class="o">-</span><span class="n">gateway</span><span class="o">-</span><span class="n">config</span><span class="o">.</span><span class="n">json</span>
    <span class="o">/</span><span class="n">opt</span><span class="o">/</span><span class="n">wakari</span><span class="o">/</span><span class="n">wakari</span><span class="o">-</span><span class="n">compute</span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">wakari</span><span class="o">/</span><span class="n">config</span><span class="o">.</span><span class="n">json</span>
    </pre></div>
    </div>
    </li>
    <li><p class="first">Edit <code class="docutils literal"><span class="pre">/opt/wakari/wakari-server/etc/wakari/wk-server-config.json</span></code> and add</p>
    <div class="highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;verify_gateway_certificate&quot;</span><span class="p">:</span> <span class="s2">&quot;/opt/wakari/wakari-server/etc/gateway.crt&quot;</span>
    </pre></div>
    </div>
    </li>
    <li><p class="first">Restart Anaconda Enterprise Notebooks services on the Server:</p>
    <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">service</span> <span class="n">wakari</span><span class="o">-</span><span class="n">server</span> <span class="n">restart</span>
    </pre></div>
    </div>
    </li>
    <li><p class="first">Browse to Anaconda Enterprise Notebooks and verify that the browser
    uses <code class="docutils literal"><span class="pre">https</span></code>.</p>
    </li>
    <li><p class="first">In the Admin settings, under <code class="docutils literal"><span class="pre">Data</span> <span class="pre">Centers</span></code> select <code class="docutils literal"><span class="pre">Gateway</span></code> and check the <code class="docutils literal"><span class="pre">https</span></code> box.</p>
    <img alt="../../../_images/ae-notebooks/4.1.2/install/https.png" src="../../../_images/ae-notebooks/4.1.2/install/https.png" />
    </li>
    </ol>
    <p>NOTE: This step may return an error since the Gateway has not yet been configured for SSL.</p>
    </div>
    <div class="section" id="configure-ssl-on-the-gateway">
    <h2>Configure SSL on the Gateway<a class="headerlink" href="#configure-ssl-on-the-gateway" title="Permalink to this headline">¶</a></h2>
    <ol class="arabic">
    <li><p class="first">Edit <code class="docutils literal"><span class="pre">/opt/wakari/wakari-compute/etc/wakari/config.json</span></code> to change http to https</p>
    </li>
    <li><p class="first">Modify the <code class="docutils literal"><span class="pre">/opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json</span></code> configuration file and add:</p>
    <div class="code json highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span>
       <span class="n">EXISTING_CONFIGURATION</span><span class="p">,</span>
       <span class="s2">&quot;https&quot;</span><span class="p">:</span> <span class="p">{</span>
           <span class="s2">&quot;key&quot;</span><span class="p">:</span> <span class="s2">&quot;/opt/wakari/wakari-gateway/etc/gateway.key&quot;</span><span class="p">,</span>
           <span class="s2">&quot;cert&quot;</span><span class="p">:</span> <span class="s2">&quot;/opt/wakari/wakari-gateway/etc/gateway.crt&quot;</span>
        <span class="p">}</span>
     <span class="p">}</span>
    </pre></div>
    </div>
    </li>
    <li><p class="first">If you have a Server cert that was signed by a private root CA (and/or intermediate authority)
    add the following to the <code class="docutils literal"><span class="pre">https</span></code> key</p>
    <div class="code json highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;ca&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;/opt/wakari/wakari-gateway/etc/server.crt&quot;</span><span class="p">]</span>
    </pre></div>
    </div>
    <p>NOTE: The <code class="docutils literal"><span class="pre">ca</span></code> key must contain separate values for the paths to the CA root, any
    intermediate and the certificate for the Server</p>
    </li>
    <li><p class="first">Restart the Gateway: <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">service</span> <span class="pre">wakari-gateway</span> <span class="pre">restart</span></code></p>
    </li>
    </ol>
    </div>
    <div class="section" id="ssl-on-compute-nodes">
    <h2>SSL on Compute Nodes<a class="headerlink" href="#ssl-on-compute-nodes" title="Permalink to this headline">¶</a></h2>
    <p>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 <code class="docutils literal"><span class="pre">http://localhost:5002</span></code> for the URL value
    while adding it as a resource, and you must use a Gateway for
    each and every Compute Node.</p>
    </div>
    <div class="section" id="security-reminder">
    <h2>Security reminder<a class="headerlink" href="#security-reminder" title="Permalink to this headline">¶</a></h2>
    <p>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 <code class="docutils literal"><span class="pre">NGINX</span></code> is run by root.</p>
    <p>Assuming the cert files are called <code class="docutils literal"><span class="pre">server.crt</span></code> and <code class="docutils literal"><span class="pre">server.key</span></code>,
    use the <code class="docutils literal"><span class="pre">root</span></code> account to set the permissions as follows:</p>
    <div class="code bash highlight-default"><div class="highlight"><pre><span></span><span class="n">chmod</span> <span class="mi">600</span> <span class="n">server</span><span class="o">.</span><span class="n">key</span>
    <span class="n">chmod</span> <span class="mi">600</span> <span class="n">server</span><span class="o">.</span><span class="n">crt</span>
    </pre></div>
    </div>
    </div>
    <div class="section" id="strict-transport-security-header">
    <h2>Strict transport security header<a class="headerlink" href="#strict-transport-security-header" title="Permalink to this headline">¶</a></h2>
    <p>Strict-Transport-Security is enabled by default in the
    <code class="docutils literal"><span class="pre">www.enterprise.https.conf</span></code> file.</p>
    <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">add_header</span> <span class="n">Strict</span><span class="o">-</span><span class="n">Transport</span><span class="o">-</span><span class="n">Security</span> <span class="nb">max</span><span class="o">-</span><span class="n">age</span><span class="o">=</span><span class="mi">31536000</span><span class="p">;</span>
    </pre></div>
    </div>
    <p>It can remain enabled if <em>either</em> of the following is true.</p>
    <ul class="simple">
    <li>The Gateway is running on a different host than the Server; or</li>
    <li>SSL has been enabled for the Gateway</li>
    </ul>
    <p>It is necessary that you comment out this line if <em>both</em> the
    following conditions are true:</p>
    <ul class="simple">
    <li>The Gateway is running on the same host as the Server; and</li>
    <li>SSL has not been enabled for the Gateway</li>
    </ul>
    <p>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.</p>
    <div class="toctree-wrapper compound">
    </div>
    </div>

.. toctree::
   :hidden:

   wakari_https_conf
