Metadata-Version: 2.1
Name: devpi-ldap
Version: 1.2.2
Summary: devpi-ldap: LDAP authentication for devpi-server
Home-page: https://github.com/devpi/devpi-ldap
Maintainer: Florian Schulze
Maintainer-email: florian.schulze@gmx.net
License: MIT
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: PyYAML
Requires-Dist: devpi-server (>=2.0.0)
Requires-Dist: ldap3 (>=0.9.8.6)

devpi-ldap: LDAP authentication for devpi-server
================================================

.. image:: https://img.shields.io/pypi/v/devpi-ldap.svg?style=flat
    :target: https://pypi.python.org/pypi/devpi-ldap/
    :alt: Latest Version

For use with devpi-server >= 2.1.0.

Installation
------------

``devpi-ldap`` needs to be installed alongside ``devpi-server``.

You can install it with::

    pip install devpi-ldap

For ``devpi-server`` there is no configuration needed to activate the plugin, as it will automatically discover the plugin through calling hooks using the setuptools entry points mechanism. However, you need to pass a path with a YAML config file to ``devpi-server``, via the ``--ldap-config`` command-line option.

Details about LDAP configuration below.

Configuration
-------------

A script named ``devpi-ldap`` can be used to test your LDAP configuration.

To configure LDAP, create a yaml file with a dictionary containing another dictionary under the ``devpi-ldap`` key with the following options:

``url``
  The url of the LDAP server.
  Using ``ldaps://`` enables SSL.
  No certificate validation is performed at the moment.

``user_template``
  The template to generate the distinguished name for the user.
  If the structure is fixed, this is faster than specifying a ``user_search``, but ``devpi-server`` can't know whether a user exists or not.

``user_search``
  If you can't or don't want to use ``user_template``, then these are the search settings for the users distinguished name.
  You can use ``username`` in the search filter.
  See specifics below.

``group_search``
  The search settings for the group objects of the user.
  You can use ``username`` and ``userdn`` (the distinguished name) in the search filter.
  See specifics below.

``referrals``
  Whether to follow referrals.
  This needs to be set to ``false`` in many cases when using LDAP via Active Directory on Windows.
  The default is ``true``.

``reject_as_unknown``
  Report all failed authentication attempts as ``unknown`` instead of
  ``reject``. This is useful e.g. if using the provided credentials to bind
  to ldap, in which case we cannot distinguish authentication failures from
  unknown users. ``unknown`` is required to let other auth hooks attempt to
  authenticate the user.

``tls``
  Parameters to the `ldap3.Tls object
  <http://ldap3.readthedocs.org/ssltls.html#the-tls-object>`_ for
  Transport Layer Security, used with LDAPS connections.

The ``user_search`` and ``group_search`` settings are dictionaries with the following options:

``base``
  The base location from which to search.

``filter``
  The search filter.
  To use replacements, put them in curly braces.
  Example: ``(&(objectClass=group)(member={userdn}))``

``scope``
  The scope for the search.
  Valid values are ``base-object``, ``single-level`` and ``whole-subtree``.
  The default is ``whole-subtree``.

``attribute_name``
  The name of the attribute which should be extracted from the search result.

``userdn``
  The distinguished name of the user which should be used for the search operation.
  For ``user_search``, if you don't have anonymous user search or for ``group_search`` if the users can't search their own groups, then you need to set this to a user which has the necessary rights.

``password``
  The password for the user in ``userdn``.

The YAML file should then look similar to this:

.. code-block:: yaml

    ---
    devpi-ldap:
      url: ldap://example.com
      user_template: CN={username},CN=Partition1,DC=Example,DC=COM
      group_search:
        base: CN=Partition1,DC=Example,DC=COM
        filter: (&(objectClass=group)(member={userdn}))
        attribute_name: CN

An example with user search and Active Directory might look like this:

.. code-block:: yaml

    ---
    devpi-ldap:
      url: ldap://example.com
      user_search:
        base: CN=Partition1,DC=Example,DC=COM
        filter: (&(objectClass=user)(sAMAccountName={username}))
        attribute_name: distinguishedName
      group_search:
        base: CN=Partition1,DC=Example,DC=COM
        filter: (&(objectClass=group)(member={userdn}))
        attribute_name: CN


Changelog
=========

1.2.2 - 2018-05-28
------------------

- More ldap3 2.x fixes.
  [fschulze]


1.2.1 - 2018-05-25
------------------

- Fix compatibility with ldap3 2.x.
  [fschulze, abrasive (James Laird-Wah)]

- Stopped testing with Python 2.6, but no changes made which break compatibility.


1.2.0 - 2016-03-25
------------------

- Add support for TLS parameters in the config.
  [jaraco (Jason R. Coombs)]

- Allow invocation via ``python -m devpi-ldap`` and fix cli for Python 3.
  [jaraco]

- Add exit codes to testing script when authentication fails.
  [jaraco]


1.1.1 - 2016-01-28
------------------

- set minimum version of ldap3 library, which adds hiding of password in debug
  logging.
  [cannatag (Giovanni Cannata), rodcloutier (Rodrigue Cloutier), fschulze]

- change dependency for the ldap library, which was renamed.
  [kumy]

- fix issue #5: dn and distinguishedName may appear as a top level response
  attribute instead of the attributes list.
  [kainz (Bryon Roché)]

- fix issue #24: Ignore additional search result data.
  [bonzani (Patrizio Bonzani), fschulze]


1.1.0 - 2014-11-10
------------------

- add ``reject_as_unknown`` option
  [davidszotten (David Szotten)]


1.0.1 - 2014-10-10
------------------

- fix the plugin hook
  [fschulze]


1.0.0 - 2014-09-22
------------------

- initial release
  [fschulze (Florian Schulze)]


