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
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
django-ldapdb
=============
.. image:: https://secure.travis-ci.org/django-ldapdb/django-ldapdb.png?branch=master
:target: http://travis-ci.org/django-ldapdb/django-ldapdb/
.. image:: https://img.shields.io/pypi/v/django-ldapdb.svg
:target: https://pypi.python.org/pypi/django-ldapdb/
:alt: Latest Version
.. image:: https://img.shields.io/pypi/pyversions/django-ldapdb.svg
:target: https://pypi.python.org/pypi/django-ldapdb/
:alt: Supported Python versions
.. image:: https://img.shields.io/pypi/wheel/django-ldapdb.svg
:target: https://pypi.python.org/pypi/django-ldapdb/
:alt: Wheel status
.. image:: https://img.shields.io/pypi/l/django-ldapdb.svg
:target: https://pypi.python.org/pypi/django-ldapdb/
:alt: License
``django-ldapdb`` is an LDAP database backend for Django, allowing to manipulate
LDAP entries through Django models.
It supports most of the same APIs as a Django model:
* ``MyModel.objects.create()``
* ``MyModel.objects.filter(x=1, y__contains=2)``
* Full admin support and browsing
``django-ldapdb`` supports every upstream-supported Django version, based on
the `Django support policy <https://www.djangoproject.com/download/#supported-versions>`_.
For the current version, the following versions are supported:
- Django 2.2 (LTS), under Python 3.6 - 3.8 (Python 3.5 has reached its end of life);
- Django 3.0, under Python 3.6 - 3.8;
- Django 3.1, under Python 3.6 - 3.8.
Installing django-ldapdb
------------------------
Linux
~~~~~
Use pip: ``pip install django-ldapdb``
You might also need the usual ``LDAP`` packages from your distribution, usually named ``openldap`` or ``ldap-utils``.
Windows
~~~~~~~
``django-ldapdb`` depends on the `python-ldap <https://pypi.python.org/pypi/python-ldap>` project.
Either follow `its Windows installation guide <https://www.python-ldap.org/en/latest/installing.html>`_,
or install a pre-built version from https://www.lfd.uci.edu/~gohlke/pythonlibs/#python-ldap
(choose the ``.whl`` file matching your Python/Windows combination, and install it with ``pip install python-ldap-3...whl``).
You may then install ``django-ldapdb`` with
``pip install django-ldapdb``
Using django-ldapdb
-------------------
Add the following to your ``settings.py``:
.. code-block:: python
DATABASES = {
'ldap': {
'ENGINE': 'ldapdb.backends.ldap',
'NAME': 'ldap://ldap.nodomain.org/',
'USER': 'cn=admin,dc=nodomain,dc=org',
'PASSWORD': 'some_secret_password',
},
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
},
}
DATABASE_ROUTERS = ['ldapdb.router.Router']
If you want to access posixGroup entries in your application, you can add
something like this to your ``models.py``:
.. code-block:: python
from ldapdb.models.fields import CharField, IntegerField, ListField
import ldapdb.models
class LdapGroup(ldapdb.models.Model):
"""
Class for representing an LDAP group entry.
"""
# LDAP meta-data
base_dn = "ou=groups,dc=nodomain,dc=org"
object_classes = ['posixGroup']
# posixGroup attributes
gid = IntegerField(db_column='gidNumber', unique=True)
name = CharField(db_column='cn', max_length=200, primary_key=True)
members = ListField(db_column='memberUid')
def __str__(self):
return self.name
def __unicode__(self):
return self.name
and add this to your ``admin.py``:
.. code-block:: python
from django.contrib import admin
from . import models
class LDAPGroupAdmin(admin.ModelAdmin):
exclude = ['dn', 'objectClass']
list_display = ['gid', 'name']
admin.site.register(models.LDAPGroup, LDAPGroupAdmin)
**Important note:**
You **must** declare an attribute to be used as the primary key.
This attribute will play a special role, as it will be used to build
the Relative Distinguished Name of the entry.
For instance in the example above, a group whose cn is ``foo``
will have the DN ``cn=foo,ou=groups,dc=nodomain,dc=org``.
Supported fields
----------------
djanglo-ldapdb provides the following fields, all imported from ``ldapdb.models.fields``:
Similar to Django:
* ``IntegerField``
* ``FloatField``
* ``BooleanField``
* ``CharField``
* ``ImageField``
* ``DateTimeField``
Specific to a LDAP server:
* ``ListField`` (holds a list of text values)
* ``TimestampField`` (Stores a datetime as a posix timestamp, typically for posixAccount)
Legacy:
* ``DateField`` (Stores a date in an arbitrary format. A LDAP server has no notion of ``Date``).
Tuning django-ldapdb
--------------------
It is possible to adjust django-ldapdb's behavior by defining a few parameters in the ``DATABASE`` section:
``PAGE_SIZE`` (default: ``1000``)
Define the maximum size of a results page to be returned by the server
``QUERY_TIMEOUT`` (default: no limit)
Define the maximum time in seconds we'll wait to get a reply from the server (on a per-query basis).
.. note:: This setting applies on individual requests; if a high-level operation requires many
queries (for instance a paginated search yielding thousands of entries),
the timeout will be used on each individual request;
the overall processing time might be much higher.
Developing with a LDAP server
-----------------------------
When developing against a LDAP server, having access to a development LDAP server often proves
useful.
django-ldapdb uses the `volatildap project <https://pypi.org/project/volatildap>`_ for this purpose:
- A LDAP server is instantiated for each TestClass;
- Its content is reset at the start of each test function;
- It can be customized to embark any schemas required by the application;
- Starting with volatildap 1.4.0, the volatildap server can be controlled remotely, avoiding the need
to install a LDAP server on the host.
Applications using django-ldapdb may use the following code snippet when setting up their tests:
.. code-block:: python
# This snippet is released in the Public Domain
from django.conf import settings
from django.test import TestCase
import volatildap
class LdapEnabledTestCase(TestCase):
@classmethod
def setUpClass(cls):
super().setUpClass()
cls.ldap = volatildap.LdapServer(
# Load some initial data
initial={'ou=people': {
'ou': ['people'],
'objectClass': ['organizationalUnit'],
}},
# Enable more LDAP schemas
schemas=['core.schema', 'cosine.schema', 'inetorgperson.schema', 'nis.schema'],
)
# The volatildap server uses specific defaults, and listens on an arbitrary port.
# Copy the server-side values to Django settings
settings.DATABASES['ldap']['USER'] = cls.ldap.rootdn
settings.DATABASES['ldap']['PASSWORD'] = cls.ldap.rootpw
settings.DATABASES['ldap']['NAME'] = cls.ldap.uri
def setUp(self):
super().setUp()
# Starting an already-started volatildap server performs a data reset
self.ldap.start()
@classmethod
def tearDownClass(cls):
# Free up resources on teardown.
cls.ldap.stop()
super().tearDownClass()
|
