This is a small library for connecting Django's authentication system to an LDAP directory. Unlike other similar libraries, it and its dependencies are pure-Python and do not require any special system headers to run, making it perfect for running in a hosted virtualenv.
It has a sane default configuration that requires minimal customization, and has been tested against OpenLDAP and Microsoft's Active Directory.
It is licensed under the BSD license.
It is known to work with:
- Python 2.7, 3.3-3.5
- Django 1.6.10, 1.7-1.9
Note at some point in the future, support for Python 2.7/3.3 and Django 1.6/1.7 will be dropped (see issue #15).
The easiest way is to install from PyPi using pip:
$ pip install django_auth_ldap3
Alternatively you may install from the latest commit on the master branch:
$ pip install -e git+https://github.com/sjkingo/django_auth_ldap3.git#egg=django_auth_ldap3
A full configuration reference of all settings is available.
-
First, add the LDAP backend to Django's
AUTHENTICATION_BACKENDStuple insettings.py:AUTHENTICATION_BACKENDS = ( 'django_auth_ldap3.backends.LDAPBackend', 'django.contrib.auth.backends.ModelBackend', )We specify
ModelBackendhere as a fallback in case any superusers are defined locally in the database. -
Point the configuration to the directory server with only two required settings:
AUTH_LDAP_URI = 'ldap://localhost:389' AUTH_LDAP_BASE_DN = 'dc=example,dc=com'
There are two methods of authenticating against an LDAP directory.
This is by far the easiest method to use, and requires minimal configuration.
In this method, the username and password provided during authentication are
used to bind directly to the directory. If the bind fails, the
username/password combination (or AUTH_LDAP_BIND_TEMPLATE [1]) is incorrect.
[1] When direct binding, there is no way to distinguish between an incorrect username/password and the bind template being incorrect, since both result in an invalid bind.
Only one extra setting is required for direct binding to an OpenLDAP directory:
AUTH_LDAP_BIND_TEMPLATE: the template to use when constructing the user to bind. For example:uid={username},ou=People. It must contain{username}somewhere which will be substituted for the username that is being authenticated.
Alternatively you may wish to change the attribute that matches the Django username - by default it is uid:
AUTH_LDAP_UID_ATTRIB: the attribute used for a unique username (e.g.uidorsAMAccountName)
The key requirement for direct binding is that a distinguished name is able to be constructed from a given username, for instance:
- username
'jsmith'is known with a distinguished name of'uid=jsmith,ou=People,dc=example,dc=com'in the directory
A point to note here is that if you are using Active Directory, you may tell
the backend to bind with a full user principal instead, such as DOMAIN\user
or user@domain. This can be accomplished by setting one of the following
settings:
AUTH_LDAP_USERNAME_PREFIX: e.g.DOMAIN\AUTH_LDAP_USERNAME_SUFFIX: e.g.@domain.com
If using either of these settings, set AUTH_LDAP_BIND_TEMPLATE to None. You
will almost certainly want to change the AUTH_LDAP_UID_ATTRIB to
sAMAccountName.
The second method is more flexible but requires more directory-specific configuration: it allows you to filter users by any valid LDAP filter, across a directory tree.
It is yet to be implemented in this library. See issue #2.
Sometimes it is desirable to restrict authentication to users that are members
of a specific LDAP group. This may be accomplished by setting the
AUTH_LDAP_LOGIN_GROUP setting. By default it is set to '*'; any valid user
may authenticate. If you wish to restrict this, change the setting to the
distinguished name of a group, for example:
AUTH_LDAP_LOGIN_GROUP = 'cn=Web Users,ou=Groups,dc=example,dc=com'
You may also allow a subset of users to authenticate to the Django admin
interface by setting the AUTH_LDAP_ADMIN_GROUP setting. By default this is
set to None, indicating no user may have access to the admin. If you wish to
allow access, change the setting to the distinguished name of a group, for
example:
AUTH_LDAP_ADMIN_GROUP = 'cn=Admin Users,ou=Groups,dc=example,dc=com'
Should you wish to map LDAP groups to Django groups, you can use the AUTH_LDAP_GROUP_MAP
setting. By default it is set to None, indicating that no mapping will occur. The mapping is
done in the form of a dict where the keys are LDAP group DNs and the values are sequences of Django groups,
for example:
AUTH_LDAP_GROUP_MAP = {
'cn=Admin Users,ou=Groups,dc=example,dc=com': ('site_admins', 'editors'),
'cn=Authors,ou=Groups,dc=example,dc=com': ('editors',)
}
Note that any Django groups you list will be controlled by this mapping, and can't be manually managed, because users will be added or removed from the groups according to their LDAP group memberships at login. Any Django groups not included in the mappings will be unaffected.
AUTH_LDAP_URI = 'ldap://localhost:389'
AUTH_LDAP_BASE_DN = 'ou=People,dc=example,dc=com'
AUTH_LDAP_BIND_TEMPLATE = 'uid={username},{base_dn}'
The last line is only required if the bind template differs from the default.
AUTH_LDAP_URI = 'ldap://DC1.example.com:389'
AUTH_LDAP_BASE_DN = 'dc=example,dc=com'
AUTH_LDAP_BIND_TEMPLATE = None
AUTH_LDAP_USERNAME_PREFIX = 'DOMAIN\\'
AUTH_LDAP_UID_ATTRIB = 'sAMAccountName'
Default: 'dc=example,dc=com'
Required. The base container to perform any subtree searches from.
Default: 'uid={username},{base_dn}'
Required. Template used to construct the distinguished name of the user to authenticate.
Valid substitution specifiers are:
{username}(required): the username being authenticated{base_dn}: will be substituted forAUTH_LDAP_BASE_DN
Default: 'ldap://localhost'
Required. A valid LDAP URI that specifies a connection to a directory server.
TLS has been supported since v0.9.5 with AUTH_LDAP_TLS.
Default: None
Optional. Distinguished name of the group of users allowed to access the admin area, or None
to deny all.
Default: None
Optional. Dictionary of LDAP groups to Django groups to perform mapping on. See Group membership, above, for more details.
Added in version 0.9.4
Default: '*'
Optional. Restrict authentication to users that are a member of this group
(distinguished name). '*' indicates any user may authenticate.
Default: 'uid'
Optional. The unique attribute in the directory that stores the username. For
Active Directory this will be sAMAccountName.
Default: None
Optional. String to prefix the username before binding. This is used for DOMAIN\user principals.
You must set AUTH_LDAP_BIND_TEMPLATE to None when using this option.
Default: None
Optional. String to suffix the username before binding. This is used for user@domain principals.
You must set AUTH_LDAP_BIND_TEMPLATE to None when using this option.
Added in version 0.9.5
Optional. Flag to enable LDAP over TLS. Further options can be configured through AUTH_LDAP_TLS_CA_CERTS,
AUTH_LDAP_TLS_VALIDATE, AUTH_LDAP_TLS_PRIVATE_KEY, and AUTH_LDAP_TLS_LOCAL_CERT.
Default: False
Optional. String to the location of the file containing the certificates of the certification authorities.
It's checked only if AUTH_LDAP_TLS_VALIDATE is set to True.
Default: It will use the system wide certificate store.
Optional. Specifies if the server certificate must be validated.
Default: True
Optional. Specifies the location for the file with the private key of the client.
Optional. Specifies the location for the file with the certificate of the server.
When using this library, it is strongly recommended to not manually
modify the usernames in the Django user table (either through the admin or modifying a
User.username field). See issues #7 and #9 for more details.