Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/django-ldapdb/django-ldapdb

django-ldapdb, an LDAP database backend for Django
https://github.com/django-ldapdb/django-ldapdb

Last synced: 10 days ago
JSON representation

django-ldapdb, an LDAP database backend for Django

Awesome Lists containing this project

README 

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



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

Either follow `its Windows installation guide `_,

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 `_ 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()