.. 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 EDG 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.  EDG 
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 EDG.  The user must logout
   (or the session expires), and then login again.  Alternately, the session could be 
   :ref:`ended by an administrator <ConcurrentUsersAdminPage>`.