.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _ldap_authentication:

LDAP Authentication
-------------------

This section describes how to use the TQ Data Foundation server with LDAP authentication. 
Currently, only Microsoft Active Directory (AD) on Windows Server is supported.

.. note::
   LDAP authentication is only for use with form or basic authentication.
   Thus TopQuadrant recommends only using LDAP in test environments.
   For interactive end-user login in production environments, use 
   :ref:`oidc_authentication` or :ref:`saml_authentication`, and for 
   programmatic API users, use :ref:`oauth_authentication`.

Enabling LDAP
^^^^^^^^^^^^^

To enable LDAP authentication, create a configuration file for LDAP.  Data Foundation 
will use LDAP authentication if this file exists.  By default, this file 
should be named ``ldap.yaml``, and would be located in the same folder as 
:ref:`setup_file`.  You can customize the name or location of the 
configuration file using the ``ldapConfigFile`` setting in the :ref:`setup file <setup_ldapConfigFile>`::

   ldapConfigFile = /my/folder/myldap.yaml

The ldap.yaml file
^^^^^^^^^^^^^^^^^^

The file uses YAML syntax. It consists of an LDAP configuration record of the following form:

.. code-block:: yaml

   domain: your.example.com
   ldapUrl: ldaps://192.168.1.42
   rootDn: dc=your,dc=example,dc=com
   searchFilter: (&(objectClass=user)(userPrincipalName={0}))

A record consists of these elements:

``domain`` (required)
  Your Active Directory domain name.  If you are unsure what your domain name is, contact your AD administrator.

``ldapUrl`` (required)
  The URL of your LDAP server.

``rootDn`` (required)
  The Distinguished Name of your root LDAP domain.  It should be a comma-separated list of attributes in X.500 syntax.

``searchFilter`` (optional)
  An LDAP search filter to use to look up AD accounts.  If not specified, 
  ``(&(objectClass=user)(userPrincipalName={0}))`` will be used, which should 
  work in most situations.  User IDs are typically of the form ``user@domain``.
  To match the entire user ID, including the domain, use ``{0}``.  To match 
  only the user portion, use ``{1}``.  For example: ``searchFilter: (sAMAccountName={1})``.

.. note::
   Changes made at the LDAP server will not be visible immediately in Data Foundation.  The user must logout
   (or the session expires), and then login again.  Alternately, the session could be 
   :ref:`ended by an administrator <ConcurrentUsersAdminPage>`.