Configuring SSL (AEN 4.2.0)
===========================

.. raw:: html

    <p>The server node uses NGINX to proxy all incoming http(s) requests
    to the server running on a local port, and uses NGINX for SSL termination. The
    default setup uses http&#8212;non-SSL&#8212;since cert files are required
    to configure SSL and each enterprise will have their own cert
    files.</p>
    <p>NOTE: 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.conf</span></code>
    file used for AEN. It is copied to the <code class="docutils literal"><span class="pre">/etc/nginx/conf.d</span></code>
    directory during server installation.</p>
    <p>NOTE: This section describes setting up SSL after your gateway
    node has been installed and registered with the server node.</p>
    <div class="section" id="copying-the-required-files">
    <h2>Copying the required files<a class="headerlink" href="#copying-the-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:</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="configuring-ssl-on-the-server-node">
    <h2>Configuring SSL on the server node<a class="headerlink" href="#configuring-ssl-on-the-server-node" title="Permalink to this headline">¶</a></h2>
    <p>The <code class="docutils literal"><span class="pre">www.enterprise.https.conf</span></code> is an NGINX configuration file
    for SSL. It is set up to use the <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.</p>
    <p>CAUTION: You must change these values to point to the signed cert
    files for your domain.</p>
    <p>NOTE: Self-signed certs or those signed by a private root CA
    require additional configuration.</p>
    <p>Perform the following steps as root:</p>
    <ol class="arabic">
    <li><p class="first">Stop NGINX:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>service nginx stop
    </pre></div>
    </div>
    </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><p class="first">Copy the
    <code class="docutils literal"><span class="pre">/opt/wakari/wakari-server/etc/nginx/conf.d/www.enterprise.https.conf</span></code>
    file to <code class="docutils literal"><span class="pre">/etc/nginx/conf.d</span></code>.</p>
    <p>NOTE: <code class="docutils literal"><span class="pre">/etc/nginx/conf.d</span></code> may have <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> but it may not have both.</p>
    </li>
    <li><p class="first">Edit the
    <code class="docutils literal"><span class="pre">/etc/nginx/conf.d/www.enterprise.https.conf</span></code>
    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">Restart NGINX by running:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>service nginx start
    </pre></div>
    </div>
    </li>
    <li><p class="first">Update the WAKARI_SERVER and CDN settings to use https instead
    of http in the following configuration files:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>/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
    </pre></div>
    </div>
    </li>
    <li><p class="first">Copy the gateway certificate, <code class="docutils literal"><span class="pre">gateway.crt</span></code> to <code class="docutils literal"><span class="pre">/opt/wakari/wakari-server/etc/</span></code>
    on the server.</p>
    </li>
    <li><p class="first">In an editor, open <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 AEN services on the server by running:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>service wakari-server restart
    </pre></div>
    </div>
    <p>NOTE: This step may return an error since the gateway has
    not yet been configured for SSL.</p>
    </li>
    <li><p class="first">In AEN, verify that the browser uses https. On the Admin
    Settings page, under Data Centers, click Gateway, then select
    https:</p>
    <div class="figure">
    <img alt="../../../../../_images/ae-notebooks/4.2.0/aen-install-https.png" src="../../../../../_images/ae-notebooks/4.2.0/aen-install-https.png" />
    </div>
    <div class="line-block">
    <div class="line"><br /></div>
    </div>
    </li>
    </ol>
    </div>
    <div class="section" id="configuring-ssl-on-the-gateway">
    <h2>Configuring SSL on the gateway<a class="headerlink" href="#configuring-ssl-on-the-gateway" title="Permalink to this headline">¶</a></h2>
    <ol class="arabic">
    <li><p class="first">In <code class="docutils literal"><span class="pre">/opt/wakari/wakari-gateway/etc/wakari/wk-gateway-config.json</span></code>, add:</p>
    <div class="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 or signed by an intermediate authority, 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="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>
        <span class="p">}</span>
     <span class="p">}</span>
    </pre></div>
    </div>
    <p>NOTE: The ca key must contain separate values for the paths
    to the CA root, any intermediates and the certificate for the
    Server.</p>
    </li>
    <li><p class="first">Restart the gateway:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>sudo service wakari-gateway restart
    </pre></div>
    </div>
    </li>
    </ol>
    </div>
    <div class="section" id="configuring-ssl-on-compute-nodes">
    <h2>Configuring SSL on compute nodes<a class="headerlink" href="#configuring-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 must be set correctly to
    prevent them from being read by others. Since NGINX is run by the
    root user, only the root user needs read access to the cert files.</p>
    <p>EXAMPLE: If 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>, then use the root account to set permissions:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>chmod <span class="m">600</span> server.key
    chmod <span class="m">600</span> server.crt
    </pre></div>
    </div>
    </div>
    <div class="section" id="enabling-or-disabling-the-strict-transport-security-header">
    <h2>Enabling or disabling the Strict-Transport-Security header<a class="headerlink" href="#enabling-or-disabling-the-strict-transport-security-header" title="Permalink to this headline">¶</a></h2>
    <p>By default, Strict-Transport-Security (STS) is enabled in
    the <code class="docutils literal"><span class="pre">www.enterprise.https.conf</span></code> file:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>add_header Strict-Transport-Security max-age<span class="o">=</span><span class="m">31536000</span><span class="p">;</span>
    </pre></div>
    </div>
    <p>It can remain enabled if either of the following is true:</p>
    <ul>
    <li><p class="first">The gateway is running on a different host than the server.</p>
    <p>or</p>
    </li>
    <li><p class="first">SSL has been enabled for the gateway.</p>
    </li>
    </ul>
    <p>You must comment out this line if both of the following are true:</p>
    <ul>
    <li><p class="first">The gateway is running on the same host as the server.</p>
    <p>and</p>
    </li>
    <li><p class="first">SSL has not been enabled for the gateway.</p>
    </li>
    </ul>
    <p>Leaving STS enabled when these conditions are true will
    cause a mismatch in protocols between the server and gateway,
    causing your apps to fail to launch correctly.</p>
    </div>
