1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
Metadata-Version: 2.4
Name: django-auth-ldap
Version: 5.2.0
Summary: Django LDAP authentication backend
Author-email: Peter Sagerson <psagers@ignorare.net>
Maintainer-email: François Freitag <mail@franek.fr>
License: BSD
Project-URL: Homepage, https://github.com/django-auth-ldap/django-auth-ldap
Project-URL: Documentation, https://django-auth-ldap.readthedocs.io/
Project-URL: Source, https://github.com/django-auth-ldap/django-auth-ldap
Project-URL: Tracker, https://github.com/django-auth-ldap/django-auth-ldap/issues
Project-URL: Changelog, https://github.com/django-auth-ldap/django-auth-ldap/releases/
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory :: LDAP
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: python-ldap>=3.1
Dynamic: license-file
================================
Django Authentication Using LDAP
================================
.. image:: https://readthedocs.org/projects/django-auth-ldap/badge/?version=latest
:target: https://django-auth-ldap.readthedocs.io/en/latest/
.. image:: https://img.shields.io/pypi/v/django-auth-ldap.svg
:target: https://pypi.org/project/django-auth-ldap/
.. image:: https://github.com/django-auth-ldap/django-auth-ldap/workflows/Test/badge.svg
:target: https://github.com/django-auth-ldap/django-auth-ldap/workflows/Test/badge.svg
.. image:: https://img.shields.io/pypi/l/django-auth-ldap.svg
:target: https://raw.githubusercontent.com/django-auth-ldap/django-auth-ldap/master/LICENSE
This is a Django authentication backend that authenticates against an LDAP
service. Configuration can be as simple as a single distinguished name
template, but there are many rich configuration options for working with users,
groups, and permissions.
* Documentation: https://django-auth-ldap.readthedocs.io/
* PyPI: https://pypi.org/project/django-auth-ldap/
* Repository: https://github.com/django-auth-ldap/django-auth-ldap
* License: BSD 2-Clause
.. _`python-ldap`: https://pypi.org/project/python-ldap/
Installation
============
Install the package with pip:
.. code-block:: sh
$ pip install django-auth-ldap
It requires `python-ldap`_ >= 3.1. You'll need the `OpenLDAP`_ libraries and
headers available on your system.
To use the auth backend in a Django project, add
``'django_auth_ldap.backend.LDAPBackend'`` to ``AUTHENTICATION_BACKENDS``. Do
not add anything to ``INSTALLED_APPS``.
.. code-block:: python
AUTHENTICATION_BACKENDS = [
'django_auth_ldap.backend.LDAPBackend',
]
``LDAPBackend`` should work with custom user models, but it does assume that a
database is present.
.. note::
``LDAPBackend`` does not inherit from ``ModelBackend``. It is possible to
use ``LDAPBackend`` exclusively by configuring it to draw group membership
from the LDAP server. However, if you would like to assign permissions to
individual users or add users to groups within Django, you'll need to have
both backends installed:
.. code-block:: python
AUTHENTICATION_BACKENDS = [
'django_auth_ldap.backend.LDAPBackend',
'django.contrib.auth.backends.ModelBackend',
]
.. _`OpenLDAP`: https://www.openldap.org/
Example Configuration
=====================
Here is a complete example configuration from ``settings.py`` that exercises
nearly all of the features. In this example, we're authenticating against a
global pool of users in the directory, but we have a special area set aside for
Django groups (``ou=django,ou=groups,dc=example,dc=com``). Remember that most
of this is optional if you just need simple authentication. Some default
settings and arguments are included for completeness.
.. code-block:: python
import ldap
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType
# Baseline configuration.
AUTH_LDAP_SERVER_URI = 'ldap://ldap.example.com'
AUTH_LDAP_BIND_DN = 'cn=django-agent,dc=example,dc=com'
AUTH_LDAP_BIND_PASSWORD = 'phlebotinum'
AUTH_LDAP_USER_SEARCH = LDAPSearch(
'ou=users,dc=example,dc=com',
ldap.SCOPE_SUBTREE,
'(uid=%(user)s)',
)
# Or:
# AUTH_LDAP_USER_DN_TEMPLATE = 'uid=%(user)s,ou=users,dc=example,dc=com'
# Set up the basic group parameters.
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
'ou=django,ou=groups,dc=example,dc=com',
ldap.SCOPE_SUBTREE,
'(objectClass=groupOfNames)',
)
AUTH_LDAP_GROUP_TYPE = GroupOfNamesType(name_attr='cn')
# Simple group restrictions
AUTH_LDAP_REQUIRE_GROUP = 'cn=enabled,ou=django,ou=groups,dc=example,dc=com'
AUTH_LDAP_DENY_GROUP = 'cn=disabled,ou=django,ou=groups,dc=example,dc=com'
# Populate the Django user from the LDAP directory.
AUTH_LDAP_USER_ATTR_MAP = {
'first_name': 'givenName',
'last_name': 'sn',
'email': 'mail',
}
AUTH_LDAP_USER_FLAGS_BY_GROUP = {
'is_active': 'cn=active,ou=django,ou=groups,dc=example,dc=com',
'is_staff': 'cn=staff,ou=django,ou=groups,dc=example,dc=com',
'is_superuser': 'cn=superuser,ou=django,ou=groups,dc=example,dc=com',
}
# This is the default, but I like to be explicit.
AUTH_LDAP_ALWAYS_UPDATE_USER = True
# Use LDAP group membership to calculate group permissions.
AUTH_LDAP_FIND_GROUP_PERMS = True
# Cache distinguished names and group memberships for an hour to minimize
# LDAP traffic.
AUTH_LDAP_CACHE_TIMEOUT = 3600
# Keep ModelBackend around for per-user permissions and maybe a local
# superuser.
AUTHENTICATION_BACKENDS = (
'django_auth_ldap.backend.LDAPBackend',
'django.contrib.auth.backends.ModelBackend',
)
Contributing
============
If you'd like to contribute, the best approach is to send a well-formed pull
request, complete with tests and documentation. Pull requests should be
focused: trying to do more than one thing in a single request will make it more
difficult to process.
If you have a bug or feature request you can try `logging an issue`_.
There's no harm in creating an issue and then submitting a pull request to
resolve it. This can be a good way to start a conversation and can serve as an
anchor point.
.. _`logging an issue`: https://github.com/django-auth-ldap/django-auth-ldap/issues
|
