Authenticating with LDAP (AEN 4.2.0)
====================================

.. raw:: html

    <p>Anaconda Enterprise Notebooks performs local authentication against accounts
    in the AEN database by default.</p>
    <p>To configure AEN to authenticate against accounts in an LDAP (Lightweight
    Directory Access Protocol) server, follow the instructions below.</p>
    <div class="section" id="installing-openldap-libraries">
    <h2>Installing OpenLDAP libraries<a class="headerlink" href="#installing-openldap-libraries" title="Permalink to this headline">¶</a></h2>
    <p>The system needs OpenLDAP libraries to be installed and accessible by AEN.
    AEN uses the OpenLDAP libraries to establish an LDAP connection to your LDAP
    servers.</p>
    <p>To install OpenLDAP on CentOS or Redhat:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>sudo yum install openldap
    </pre></div>
    </div>
    <p>To install OpenLDAP on Ubuntu or Debian, follow the official
    <a class="reference external" href="https://wiki.debian.org/LDAP/OpenLDAPSetup">OpenLDAP installation instructions</a>.</p>
    </div>
    <div class="section" id="configuring-openldap">
    <h2>Configuring OpenLDAP<a class="headerlink" href="#configuring-openldap" title="Permalink to this headline">¶</a></h2>
    <ol class="arabic">
    <li><p class="first">Open the <code class="docutils literal"><span class="pre">/opt/wakari/wakari-server/etc/wakari/wk-server-config.json</span></code> file.</p>
    </li>
    <li><p class="first">Add the following LDAP settings:</p>
    <div class="highlight-json"><div class="highlight"><pre><span></span><span class="p">{</span>
        <span class="nt">&quot;accounts&quot;</span><span class="p">:</span><span class="s2">&quot;wk_server.plugins.accounts.ldap2&quot;</span><span class="p">,</span>
        <span class="nt">&quot;LDAP&quot;</span> <span class="p">:</span> <span class="p">{</span>
            <span class="nt">&quot;URI&quot;</span><span class="p">:</span> <span class="s2">&quot;ldap://openldap.EXAMPLE.COM&quot;</span><span class="p">,</span>
            <span class="nt">&quot;BIND_DN&quot;</span><span class="p">:</span> <span class="s2">&quot;cn=Bob Jones,ou=Users,DC=EXAMPLE,DC=COM&quot;</span><span class="p">,</span>
            <span class="nt">&quot;BIND_AUTH&quot;</span><span class="p">:</span> <span class="s2">&quot;secretpass&quot;</span><span class="p">,</span>
            <span class="nt">&quot;USER_SEARCH&quot;</span><span class="p">:</span> <span class="p">{</span><span class="nt">&quot;base&quot;</span><span class="p">:</span> <span class="s2">&quot;DC=EXAMPLE,DC=COM&quot;</span><span class="p">,</span>
                            <span class="nt">&quot;filter&quot;</span><span class="p">:</span> <span class="s2">&quot;(| (&amp; (ou=Payroll)</span>
    <span class="s2">                                         (uid=%(username)s))</span>
    <span class="s2">                                      (&amp; (ou=Facilities)</span>
    <span class="s2">                                         (uid=%(username)s)))&quot;</span>
                            <span class="p">},</span>
            <span class="nt">&quot;KEY_MAP&quot;</span><span class="p">:</span> <span class="p">{</span><span class="nt">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;mail&quot;</span><span class="p">,</span>
                        <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;cn&quot;</span>
            <span class="p">}</span>
        <span class="p">}</span>
    <span class="p">}</span>
    </pre></div>
    </div>
    <ul>
    <li><p class="first">URI&#8212;The IP address or hostname of your OpenLDAP server. For SSL/TLS, use the <code class="docutils literal"><span class="pre">ldaps://</span></code> prefix and specify a TLS_CACERT as described in the SSL/TLS configuration section below.</p>
    </li>
    <li><p class="first">BIND_DN&#8212;The full directory path of the user you want AEN server to bind as.</p>
    </li>
    <li><p class="first">BIND_AUTH&#8212;The password of the BIND_DN user.</p>
    </li>
    <li><p class="first">USER_SEARCH:</p>
    <ul class="simple">
    <li>base&#8212;The level at which you want to start the search.</li>
    <li>filter&#8212;The default is to search for the sAMAccountName attribute, and use its value for the AEN server username field.</li>
    </ul>
    </li>
    <li><p class="first">KEY_MAP&#8212;Maps user attributes in AEN server to LDAP user attributes.</p>
    <p>EXAMPLE: The <code class="docutils literal"><span class="pre">mail</span></code> attribute in LDAP maps to the <code class="docutils literal"><span class="pre">email</span></code> attribute in AEN server.</p>
    </li>
    </ul>
    </li>
    <li><p class="first">As soon as LDAP is installed, LDAP authentication takes over, so you need to
    add your admin account again:</p>
    </li>
    </ol>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>/opt/wakari/wakari-server/bin/wk-server-admin superuser --add <span class="s2">&quot;jsmith&quot;</span>
    </pre></div>
    </div>
    </div>
    <div class="section" id="configuring-active-directory">
    <h2>Configuring Active Directory<a class="headerlink" href="#configuring-active-directory" title="Permalink to this headline">¶</a></h2>
    <p>Microsoft Active Directory is a server program that provides directory services and uses the open industry standard Lightweight Directory Access Protocol (LDAP).</p>
    <p>To enable Active Directory support:</p>
    <ol class="arabic">
    <li><p class="first">Open the <code class="docutils literal"><span class="pre">/opt/wakari/wakari-server/etc/wakari/wk-server-config.json</span></code> file.</p>
    </li>
    <li><p class="first">Add the following LDAP settings:</p>
    <div class="highlight-json"><div class="highlight"><pre><span></span><span class="p">{</span>
        <span class="nt">&quot;accounts&quot;</span><span class="p">:</span><span class="s2">&quot;wk_server.plugins.accounts.ldap2&quot;</span><span class="p">,</span>
        <span class="nt">&quot;LDAP&quot;</span> <span class="p">:</span> <span class="p">{</span>
            <span class="nt">&quot;URI&quot;</span><span class="p">:</span> <span class="s2">&quot;ldap://&lt;ad.EXAMPLE.COM&gt;&quot;</span><span class="p">,</span>
            <span class="nt">&quot;BIND_DN&quot;</span><span class="p">:</span> <span class="s2">&quot;CN=Bind User,CN=Users,DC=EXAMPLE,DC=COM&quot;</span><span class="p">,</span>
            <span class="nt">&quot;BIND_AUTH&quot;</span><span class="p">:</span> <span class="s2">&quot;secretpass&quot;</span><span class="p">,</span>
            <span class="nt">&quot;USER_SEARCH&quot;</span><span class="p">:</span> <span class="p">{</span><span class="nt">&quot;base&quot;</span><span class="p">:</span> <span class="s2">&quot;CN=Users,DC=EXAMPLE,DC=COM&quot;</span><span class="p">,</span>
                            <span class="nt">&quot;filter&quot;</span><span class="p">:</span> <span class="s2">&quot;sAMAccountName=%(username)s&quot;</span>
            <span class="p">},</span>
            <span class="nt">&quot;KEY_MAP&quot;</span><span class="p">:</span> <span class="p">{</span><span class="nt">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;mail&quot;</span><span class="p">,</span>
                        <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;cn&quot;</span>
            <span class="p">}</span>
        <span class="p">}</span>
    <span class="p">}</span>
    </pre></div>
    </div>
    <ul>
    <li><p class="first">URI&#8212;The IP address or hostname of your Active Directory server. Replace <code class="docutils literal"><span class="pre">&lt;ad.EXAMPLE.COM&gt;</span></code> with the actual URI. For SSL/TLS, use the <code class="docutils literal"><span class="pre">ldaps://</span></code> prefix and specify a TLS_CACERT as described in the SSL/TLS configuration section below.</p>
    </li>
    <li><p class="first">BIND_DN&#8212;The full directory path of the user you want AEN server to bind as.</p>
    </li>
    <li><p class="first">BIND_AUTH&#8212;The password of the BIND_DN user.</p>
    </li>
    <li><p class="first">USER_SEARCH:</p>
    <ul class="simple">
    <li>base&#8212;the level at which you want to start the search.</li>
    <li>filter&#8212;default is to search for the sAMAccountName attribute, and use its value for the AEN server <code class="docutils literal"><span class="pre">username</span></code> field.</li>
    </ul>
    </li>
    <li><p class="first">KEY_MAP&#8212;Maps user attributes in AEN server to LDAP user attributes.</p>
    <p>EXAMPLE: The <code class="docutils literal"><span class="pre">mail</span></code> attribute in LDAP maps to the <code class="docutils literal"><span class="pre">email</span></code> attribute in AEN server.</p>
    </li>
    </ul>
    </li>
    <li><p class="first">As soon as LDAP is installed, LDAP authentication takes over, so you need to
    add your admin account again:</p>
    </li>
    </ol>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>/opt/wakari/wakari-server/bin/wk-server-admin superuser --add <span class="s2">&quot;jsmith&quot;</span>
    </pre></div>
    </div>
    </div>
    <div class="section" id="configuring-ssl-tls">
    <h2>Configuring SSL/TLS<a class="headerlink" href="#configuring-ssl-tls" title="Permalink to this headline">¶</a></h2>
    <p>AEN uses system-wide LDAP settings, including SSL/TLS support.</p>
    <ul class="simple">
    <li>On Redhat/CentOS systems, these settings are located in the
    <code class="docutils literal"><span class="pre">/etc/openldap/ldap.conf</span></code> file.</li>
    <li>On Ubuntu/Debian systems, these settings are located in the
    <code class="docutils literal"><span class="pre">/etc/ldap/ldap.conf</span></code> file.</li>
    </ul>
    <p>Typically, the only configuration necessary is updating the file
    to read:</p>
    <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">TLS_CACERT</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">CA</span><span class="o">.</span><span class="n">cert</span>
    </pre></div>
    </div>
    <p>NOTE: <code class="docutils literal"><span class="pre">CA.cert</span></code> is the Certificate Authority used to sign the LDAP server&#8217;s
    SSL certificate. In the case of a self-signed SSL certificate, this
    is the path to the SSL certificate itself.</p>
    </div>
    <div class="section" id="testing-ldap-configuration">
    <h2>Testing LDAP configuration<a class="headerlink" href="#testing-ldap-configuration" title="Permalink to this headline">¶</a></h2>
    <p>Test your LDAP configuration using <code class="docutils literal"><span class="pre">flask-ldap-login-check</span></code>:</p>
    <div class="highlight-bash"><div class="highlight"><pre><span></span>/opt/wakari/wakari-server/bin/flask-ldap-login-check <span class="se">\</span>
        wk_server.wsgi:app <span class="se">\</span>
        -u <span class="o">[</span>username<span class="o">]</span> <span class="se">\</span>
        -p <span class="o">[</span>password<span class="o">]</span>
    </pre></div>
    </div>
    <p>NOTE: <code class="docutils literal"><span class="pre">username</span></code> is the username of a valid user and
    <code class="docutils literal"><span class="pre">password</span></code> is that user&#8217;s BIND_AUTH password.</p>
    </div>
