========================
Authenticating with LDAP
========================

Anaconda Enterprise Notebooks performs 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 the instructions below.

Installing OpenLDAP libraries
=============================

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.

To install OpenLDAP on CentOS or Redhat:

.. code-block:: bash

   sudo yum install openldap

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

Configuring OpenLDAP
====================

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

#. Add the following LDAP settings:

   .. code-block:: 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---The 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.

     EXAMPLE: The ``mail`` attribute in LDAP maps to the ``email`` attribute in AEN server.

#. Restart AEN server to load new settings.

#. Log in with the admin account. This creates the admin user in the local database.

#. As soon as LDAP is installed, LDAP authentication takes over, so you need to
   add your admin account again:

.. code-block:: bash

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


Configuring Active Directory
============================

Microsoft Active Directory is a server program that provides directory services and uses the open industry standard Lightweight Directory Access Protocol (LDAP).

To enable Active Directory support:

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

#. Add the following LDAP settings:

   .. code-block:: 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"
                },
                "KEY_MAP": {"email": "mail",
                            "name": "cn"
                }
            }
        }



   * 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.

   * KEY\_MAP---Maps user attributes in AEN server to LDAP user attributes.

     EXAMPLE: The ``mail`` attribute in LDAP maps to the ``email`` attribute in AEN server.

#. Restart AEN server to load new settings.

#. Log in with the admin account. This creates the admin user in the local database.

#. As soon as LDAP is installed, LDAP authentication takes over, so you need to
   add your admin account again:

.. code-block:: bash

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


Configuring SSL/TLS
===================

AEN uses system-wide LDAP settings, including SSL/TLS support.

* On Redhat/CentOS systems, these settings are located in the
  ``/etc/openldap/ldap.conf`` file.

* On Ubuntu/Debian systems, these settings are located in the
  ``/etc/ldap/ldap.conf`` file.

Typically, the only configuration necessary is updating the file
to read:

::

   TLS_CACERT /path/to/CA.cert

NOTE: ``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.

Testing LDAP configuration
==========================

Test your LDAP configuration using ``flask-ldap-login-check``:

.. code-block:: bash

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

NOTE: ``username`` is the username of a valid user and
``password`` is that user's BIND_AUTH password.
