SSL (AEN 4.0)
=============

.. raw:: html

    <p>The Anaconda Enterprise Notebooks (AEN) <em>Server</em> uses <code class="docutils literal"><span class="pre">nginx</span></code> to proxy
    all incoming http(s) requests to the <em>Server</em> running on a local port.
    Also, <code class="docutils literal"><span class="pre">nginx</span></code> 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.</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 <em>Server</em> install.</p>
    <p>Note: This document is for the case where you are setting up SSL after the <em>Gateway</em>
    has been installed and registered with the <em>Server</em>.</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><em>Server</em> certificate and key</li>
    <li><em>Server</em> CA bundle</li>
    <li><em>Gateway</em> certificate and key</li>
    <li><em>Gateway</em> CA bundle</li>
    </ul>
    <ol class="arabic simple">
    <li>Copy the <em>Gateway</em> certificate and key to <code class="docutils literal"><span class="pre">/opt/wakari/wakari-gateway/etc/</span></code> on
    the <em>Gateway</em> 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 <em>Gateway</em> CA bundle to <code class="docutils literal"><span class="pre">/opt/wakari/wakari-server/etc/</span></code> on the <em>Server</em></li>
    <li>Copy the <em>Server</em> certificate and key to <code class="docutils literal"><span class="pre">/etc/nginx</span></code> on the <em>Server</em> 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 <em>Server</em> CA bundle to <code class="docutils literal"><span class="pre">/opt/wakari/wakari-gateway/etc/</span></code> on the <em>Gateway</em></li>
    </ol>
    <p>If you have a certificate that was signed by a private root CA and/or an intermediate authority
    then the following must be true</p>
    <ul class="simple">
    <li>The <em>Gateway</em> CA bundle needs to contain the root CA, any intermediate and the certificate.</li>
    <li>The <em>Server</em> CA bundle needs to be separate 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 <em>Server</em><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 a nginx configuration file for SSL
    configurations. It is setup to use cert files called <code class="docutils literal"><span class="pre">server.crt</span></code> and
    <code class="docutils literal"><span class="pre">server.key</span></code> but these value <em>must</em> be changed to point to signed cert
    files for your domain. <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 Nginx: <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>
    </li>
    </ol>
    <p>Note: that 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>
    <ol class="arabic">
    <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 nginx: <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 the <em>Server</em>:</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 Data Centers select the <em>Gateway</em> and check the https box.</p>
    <img alt="../../../_images/ae-notebooks/4.0/install/https.png" src="../../../_images/ae-notebooks/4.0/install/https.png" />
    </li>
    </ol>
    <p>Note: this step may return an error since the <em>Gateway</em> has not yet been configured for SSL.</p>
    </div>
    <div class="section" id="configure-ssl-on-the-gateway">
    <h2>Configure SSL on the <em>Gateway</em><a class="headerlink" href="#configure-ssl-on-the-gateway" title="Permalink to this headline">¶</a></h2>
    <ol class="arabic simple">
    <li>Edit <code class="docutils literal"><span class="pre">/opt/wakari/wakari-compute/etc/wakari/config.json</span></code> to change http to https.</li>
    </ol>
    <p>#. Modify the configuration file
    <code class="docutils literal"><span class="pre">/opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json</span></code> 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>
    <ol class="arabic simple">
    <li>If you have a <em>Server</em> 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</li>
    </ol>
    <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 <em>Server</em></p>
    <p>Restart the <em>Gateway</em>: <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>
    </div>
    <div class="section" id="ssl-on-compute-nodes">
    <h2>SSL on <em>Compute</em> Nodes<a class="headerlink" href="#ssl-on-compute-nodes" title="Permalink to this headline">¶</a></h2>
    <p>Anaconda Enterprise does not provide for SSL on the compute nodes
    directly. We recommend installing the <em>Compute</em> on the same machine as
    the <em>Gateway</em> and using <code class="docutils literal"><span class="pre">http://localhost:5002</span></code> for the URL value
    while adding it as a resource.</p>
    <p>You would need a <em>Gateway</em> for each and every <em>Compute</em> 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 to be able to read
    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>
    <ol class="arabic simple">
    <li>The <em>Gateway</em> is running on a different host than the <em>Server</em>; or</li>
    <li>SSL has been enabled for the <em>Gateway</em></li>
    </ol>
    <p>It is necessary that you comment out this line if <em>both</em> of the
    following conditions are true:</p>
    <ol class="arabic simple">
    <li>The <em>Gateway</em> is running on the same host as the <em>Server</em>; and</li>
    <li>SSL has not been enabled for the <em>Gateway</em></li>
    </ol>
    <p>Leaving it enabled when these conditions are true will cause a mismatch
    in protocols between the <em>Server</em> and <em>Gateway</em> and apps will fail to
    launch correctly.</p>
    <div class="toctree-wrapper compound">
    </div>
    </div>
