who_ldap 4.0.0

LDAP plugin for repoze.who

who_ldap

LDAP Authentication for repoze.who-v2-enabled WSGI Applications

This project is a fork of the original repoze.who.plugins.ldap to support who api v2 as well as Python 3 (and 2.7)

who_ldap an LDAP plugin for the identification and authentication framework for WSGI applications, repoze.who, which acts as WSGI middleware.

Installing

pip install who_ldap

Installing the mainline development branch

The plugin is hosted in a git branch hosted at github.com. To get the latest source code, run:

git clone [e-mail]:m-martinez/who_ldap.git

Then run the command below:

pip install -e who_ldap/

Setting up repoze.who with the LDAP authenticator

This section explains how to setup repoze.who in order to use the LDAP plugins in your WSGI application. It is based on the documentation for repoze.who.

You can configure your authentication mechanism powered by repoze.who with two methods: With an INI file or with Python code.

In the examples below we are only going to use the main plugin provided by this package: The LDAP authenticator itself (LDAPAuthenticatorPlugin). The other plugins don’t deal with authentication, but are useful to load automatically data related to the authenticated user from the LDAP server.

Using the repoze.who terminology, LDAPAuthenticatorPlugin is an authenticator plugin and the others are metadata provider plugins.

Configuring repoze.who in a INI file

You can configure your repoze.who based authentication via a *.ini file, and then load such settings in your application.

Say we have a file called who.ini with the following contents:

# These contents have been adapted from:
# http://static.repoze.org/whodocs/#middleware-configuration-via-config-file
[plugin:form]
use = repoze.who.plugins.form:make_plugin
rememberer_name = auth_tkt

[plugin:auth_tkt]
use = repoze.who.plugins.auth_tkt:make_plugin
secret = something

[plugin:ldap_auth]
use = who_ldap:LDAPAuthenticatorPlugin
url = ldap://ldap.yourcompany.com
base_dn = ou=developers,dc=yourcompany,dc=com

[general]
request_classifier = repoze.who.classifiers:default_request_classifier
challenge_decider = repoze.who.classifiers:default_challenge_decider

[identifiers]
plugins =
    form;browser
    auth_tkt

[authenticators]
plugins =
        ldap_auth

[challengers]
plugins =
    form;browser

With the settings above, authentication via repoze.who is configured this way: Visitors will login with a form, providing their user name and password; then these credentials will be checked against the LDAP server ldap.yourcompany.com under ou=developers,dc=yourcompany,dc=com. This form will be displayed when your WSGI application issues an HTTP 401 error.

For example, if an user enters jsmith as the user name and valencia as their password, the LDAP authenticator will build their Distinguished Name (DN) as uid=jsmith,ou=developers,dc=yourcompany,dc=com and will try to authenticate them in the ldap.yourcompany.com LDAP server with this DN and valencia as the password.

Finally, you can load these settings by adding the repoze.who middleware to your application:

from repoze.who.config import make_middleware_with_config
app_with_auth = make_middleware_with_config(app, global_confg, '/path/to/who.ini')

In the documentation for repoze.who there is a more detailed explanation for the INI file method.

Framework-specific documentation

You may want to check the following framework-specific documents to learn tips on how to implement repoze.who in the framework you are using:

• Pyramid: pyramid_who.

• Pylons: Authentication and Authorization with repoze.who.

• TurboGears 2: Authentication and Authorization in TurboGears 2 (repoze.who is the default authentication library).

Using the LDAP plugins for repoze.who

LDAPAuthenticatorPlugin

This plugin connects to the specified LDAP server and tries to bind with the Distinguished Name (DN) made by joining the login in the identity dictionary as the naming attribute value and the base_dn specified in the constructor, and then it tries to bind with the password found in the identity dictionary; As a default, the used naming attribute is the user id (uid).

For example, if the login provided by the identifier is carla and the base_dn provided in the constructor is ou=employees,dc=example,dc=org, the resulting DN will be uid=carla,ou=employees,dc=example,dc=org.

If the directory server’s naming attribute were the email attribute, and we provided naming_attribute=’email’ in the constructor, the DN resulting for the identifier [e-mail] would be email=[e-mail],ou=employees,dc=example,dc=org.

To configure this plugin from an INI file, you’d have to include a section like this:

[plugin:ldap_auth]
use = who_ldap:LDAPAuthenticatorPlugin
url = ldap://yourcompany.com
base_dn = ou=employees,dc=yourcompany,dc=com
naming_attribute = uid
start_tls = True

Setting	Default	Description
url		Required Connection URL
base_dn		Location to begin queries
returned_id	dn	Attribute to return on authentication (‘dn’ or ‘login’)
start_tls	False	If set, initiates TLS on the connection
naming_attribute	uid	Naming attribute for directory entries

LDAPSearchAuthenticatorPlugin

This plugin connects to the specified LDAP server and searches an entry residing below the base_dn, whose naming attribute’s value is equal to the supplied login. If such an entry is found, it tries to bind as the entry’s DN with the password found in the identity dictionary; As a default, the used naming attribute is the user id (uid).

The search_scope parameter in the constructor allows to choose whether to search the entry in the whole subtree below base_dn, or just on the level below if set as search_scope='onelevel'.

For example, if the login provided by the identifier is carla and the base_dn provided in the constructor is dc=example,dc=org, with the default settings, the system could find the entry uid=carla,ou=employees,dc=example,dc=org; if we set search_scope='onelevel', the entry would not be found.

If you would like to only allow some entries, you may setup a filter by means of the filterstr parameter, which is an string whose format is defined by RFC 4515 - Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters. E.g. we can assert only person entries bearing a telephone number starting with 999111 can login by setting: filterstr='(&(objectClass=person)(telephoneNumber=999111*))' in the constructor.

To configure this plugin from an INI file, you’d have to include a section like this:

[plugin:ldap_auth]
use = who_ldap:LDAPSearchAuthenticatorPlugin
url = ldap://yourcompany.com
base_dn = ou=employees,dc=yourcompany,dc=com
naming_attribute = uid
search_scope = subtree
start_tls = True

Finally, add the plugin to the set of authenticators:

[authenticators]
plugins =
        ldap_auth

Setting	Default	Description
url		Required Connection URL
bind_dn		Operating user
bind_pass		Operating user password
base_dn		Location to begin queries
returned_id	dn	Attribute to return on authentication (‘dn’ or ‘login’)
start_tls	False	If set, initiates TLS on the connection
naming_attribute	uid	Naming attribute for directory entries
search_scope	subtree	Scope of LDAP search (‘subtree’ or ‘onelevel’)
restrict		Optional additional filter for search

LDAPAttributesPlugin

This plugin enables you to load data for the authenticated user automatically and have it available from the WSGI environment — in the identity dictionary, specifically.

attributes represents the list of user’s attributes that you would like to fetch from the LDAP server; it can be an iterable, an string where the attributes are separated by commas, or None to fetch all the available attributes.

By default it loads the attributes available for any entry whose DN is the same as the one found by LDAPAuthenticatorPlugin, which is desired in most situations. However, if you would like to exclude some entries, you may setup a filter by means of the filterstr parameter, which shares the same semantics as the filterstr parameter in LDAPSearchAuthenticatorPlugin.

To configure this plugin from an INI file, you’d have to include a section like this:

[plugin:ldap_attributes]
use = who_ldap:LDAPAttributesPlugin
url = ldap://ldap.yourcompany.com
attributes = cn,sn,mail

If instead of loading the Common Name, surname and email, as with the settings above, you’d prefer to load all the available attributes for the authenticated user, you’d just have to remove the attributes directive.

Finally, add the plugin to the set of metadata providers:

[mdproviders]
plugins =
        ldap_attributes

Setting	Default	Description
url		Required Connection URL
bind_dn		Operating user
bind_pass		Operating user password
base_dn		Location to begin queries
start_tls	False	If set, initiates TLS on the connection
attributes		LDAP attributes to use. Can be a simple comma-delimited list (e.g. uid,cn), or a mapping list (e.g. cn=fullname,mail=email).
filterstr	(objectClass=*)	A filter for the search
flatten	False	Cleans up LDAP values if they are not lists

LDAPGroupsPlugin

This plugin enables you to load all the group memberships of the authenticated user.

Setting	Default	Description
url		Required Connection URL
bind_dn		Operating user
bind_pass		Operating user password
base_dn		Location to begin queries
start_tls	False	If set, initiates TLS on the connection
filterstr		A filter for the search (Default behaviour: (&(objectClass=groupOfUniqueNames)(uniqueMember=%(dn)s)))
name		The property name in the identity to use
search_scope	subtree	Scope of LDAP search (‘subtree’ or ‘onelevel’)
returned_id	cn	Which attribute value of the group entry to return

Changelog

3.2.2 (2017-02-15)

• Properly escape search filter string (http://ldap3.readthedocs.io/searches.html#the-search-operation)

3.2.1 (2016-06-22)

• Alter release workflow

3.2.0 (2016-06-22)

• Use version 2.3 of repoze.who which implements improved userdata heuristics

3.1.0 (2015-02-09)

• Search for users via filter if present [domruf]

• Switch to ldap3 package (which was renamed from python3-ldap) [Cito]

• Convert b64de/encode byte strings to regular strings in Python 3 [Cito]

• Use (objectClass=*) if no filter is specified when scope is base.

3.0.2 (2014-06-11)

• Issue log messages instead of exceptions for invalid credentials. [lovelle]

3.0.1 (2014-05-19)

• Updated documentation

3.0.0 (2014-05-19)

• Major code cleanup

• Deprecated LDAPBaseAuthenticatorPlugin

• No longer accepts ldap_connection since in order to ensure connections are closed.

• Allows to aliasing of LDAP properties

• Switched group naming_attribute to returned_id

2.0.0 (2014-04-29)

• Forked original project (https://pypi.python.org/pypi/repoze.who.plugins.ldap)

• Updated to work with repoze.who v2 API

• Python 3.4 compatibility

• Allows to aliasing of LDAP properties

• Added group metadata provider

1.2 Alpha 2 (unreleased)

• Fixed installation problems under Windows (Bug #608622).

1.1 Alpha 1 (2010-01-03)

• Changed the license to the Repoze license.

• Provided start_tls option both for the authenticator and the metadata provider.

• Enable both pattern-replacement and subtree searches for the naming attribute in _get_dn().

• Enable configuration of the naming attribute

• Enable the option to bind to the server with privileged credential before doing searches

• Add a restrict pattern to pre-authentication DN searches

• Let the user choose whether to return the full DN or the supplied login as the user identifier

1.0 (2008-09-11)

The initial release.

• Provided the LDAP authenticator, which is compatible with identifiers that define the ‘login’ item in the identity dict.

• Included the plugin to load metadata about the authenticated user from the LDAP server.

• Documented how to install and use the plugins.

• Included Turbogears 3 demo project, using the plugin. There is also a section in the documentation to explain how the demo works.