File: README.rst

package info (click to toggle)
django-ldapdb 1.4.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 284 kB
  • sloc: python: 1,989; makefile: 39
file content (172 lines) | stat: -rw-r--r-- 5,266 bytes parent folder | download
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
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 Django versions 1.11 / 2.1 / 2.2, and Python 2.7 / 3.4 / 3.5 / 3.6 / 3.7,
as far as the Django and Python versions are compatible.


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``).

and then you can also 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.