LDAP configuration
==================

Anaconda Enterprise Notebooks does local authentication against accounts
in the AEN database by default. To configure AEN to authenticate against 
accounts in an LDAP (Lightweight Directory Access Protocol) 
server, follow these instructions.

For more information about configuring AEN, please see the documentation on
:doc:`configuration files <../admin/configuration-files>`.

Install OpenLDAP libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~

The system needs the OpenLDAP libraries installed and accessible by
Anaconda Enterprise Notebooks. Anaconda Enterprise Notebooks uses the
OpenLDAP libraries to establish an LDAP connection to your LDAP servers.

CentOS/Red Hat
^^^^^^^^^^^^^^

To install ``openldap`` on CentOS or Red Hat, run the following commands:

.. code:: bash

    sudo yum install openldap

Ubuntu/Debian
^^^^^^^^^^^^^

To install ``openldap`` on Ubuntu or Debian, follow the official
OpenLDAP installation instructions:
https://wiki.debian.org/LDAP/OpenLDAPSetup

OpenLDAP
~~~~~~~~

Next, edit the
``/opt/wakari/wakari-server/etc/wakari/wk-server-config.json`` 
file. Add the LDAP settings as shown:

.. code:: json

        {
            "accounts":"wk_server.plugins.accounts.ldap2",
            "LDAP" : {
                "URI": "ldap://openldap.EXAMPLE.COM",
                "BIND_DN": "cn=Bob Jones,ou=Users,DC=EXAMPLE,DC=COM",
                "BIND_AUTH": "secretpass",
                "USER_SEARCH": {"base": "DC=EXAMPLE,DC=COM",
                                "filter": "(| (& (ou=Payroll)
                                                 (uid=%(username)s))
                                              (& (ou=Facilities)
                                                 (uid=%(username)s)))"
                                },
                "KEY_MAP": {"email": "mail",
                            "name": "cn"
                        }
            }
        }

URI
^^^

*  The IP address or hostname of your OpenLDAP server. For
   SSL/TLS, use the ``ldaps://`` prefix and specify a ``TLS_CACERT`` as
   described in the SSL/TLS configuration section below.

BIND\_DN
^^^^^^^^

*  The full directory path of the user you want AEN Server to bind as

BIND\_AUTH
^^^^^^^^^^

*  The password of the BIND\_DN user

USER\_SEARCH
^^^^^^^^^^^^

*  base: the level at which you want to start the search
*  filter: default is to search for the **sAMAccountName** attribute,
   and use its value for the AEN *Server* *username* field

KEY\_MAP
^^^^^^^^

*  Maps user attributes in AEN Server to LDAP user attributes 
   (for example, the ``mail`` attribute in LDAP maps to the ``email`` 
   attribute in AEN Server)

Active Directory
~~~~~~~~~~~~~~~~

Edit the ``/opt/wakari/wakari-server/etc/wakari/wk-server-config.json``
file.

Add the LDAP settings as shown:

.. code:: json

        {
            "accounts":"wk_server.plugins.accounts.ldap2",
            "LDAP" : {
                "URI": "ldap://<ad.EXAMPLE.COM>",
                "BIND_DN": "CN=Bind User,CN=Users,DC=EXAMPLE,DC=COM",
                "BIND_AUTH": "secretpass",
                "USER_SEARCH": {"base": "CN=Users,DC=EXAMPLE,DC=COM",
                                "filter": "sAMAccountName=%(username)s"
                }
            }
        }

URI
^^^

*  The IP address or hostname of your Active Directory server. 
   Replace ``<ad.EXAMPLE.COM>`` with the actual URI. For
   SSL/TLS, use the ``ldaps://`` prefix and specify a ``TLS_CACERT`` as
   described in the SSL/TLS configuration section below.

BIND\_DN
^^^^^^^^

*  The full directory path of the user you want AEN Server to bind as.

BIND\_AUTH
^^^^^^^^^^

*  The password of the BIND\_DN user

USER\_SEARCH
^^^^^^^^^^^^

*  base: the level at which you want to start the search
*  filter: default is to search for the **sAMAccountName** attribute,
   and use its value for the AEN Server ``username`` field

As soon as LDAP is installed, LDAP authentication takes over, so add your
admin account again:

::

    /opt/wakari/wakari-server/bin/wk-server-admin superuser --add "jsmith"

SSL/TLS configuration
~~~~~~~~~~~~~~~~~~~~~

Anaconda Enterprise Notebooks uses system-wide LDAP settings, including
SSL/TLS support.

*  On Red Hat/CentOS systems, these settings are located in ``/etc/openldap/ldap.conf``
*  On Ubuntu/Debian systems, these settings are located in ``/etc/ldap/ldap.conf``

Typically, the only required option is:

::

    TLS_CACERT /path/to/CA.cert

Where ``CA.cert`` is the Certificate Authority used to sign the LDAP server's SSL certificate.
In the case of a self-signed SSL certificate, this is the path to the
SSL certificate itself.

Test configuration with Flask-LDAP check
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Finally, test the LDAP configuration with the ``flask-ldap-login-check``
command:

.. code:: bash

    /opt/wakari/wakari-server/bin/flask-ldap-login-check \
        wk_server.wsgi:app \
        -u [username] \
        -p [password]

Where *``username``* is the username of a valid user and *``password``*
is that user's **BIND\_AUTH** password.
