django-ldap3-sync 0.1.5

django-ldap3-sync
=================

django-ldap3-sync is a fork of
`django-ldap-sync <https://github.com/jbittel/django-ldap-sync>`__
originally created by Jason Bittel. django-ldap3-sync introduces the
following features:

- Uses the `ldap3 library <https://github.com/cannatag/ldap3>`__ for
ldap communication. ldap3 is pure python and python 3 compatible.
- Can synchronize group membership directly out of the LDAP directory.
- Can manage deletion of groups / users in the directory by suspending
or deleting those objects in Django.
- Will update existing Django users groups if information changes in
the directory.
- Paged LDAP searches
- LDAP Server Pools

django-ldap3-sync provides a Django management command that synchronizes
LDAP users and groups from an authoritative server. It performs a
one-way synchronization that creates and/or updates the local Django
users and groups. It can also optionally delete or suspend users or
groups that are no longer present in the directory.

This synchronization is performed each time the management command is
run and can be fired manually on demand, via an automatic cron script or
as a periodic ``Celery`` task.

Quickstart
----------

1. Install the application::

``pip install django-ldap3-sync``

2. Append it to the installed apps::

``INSTALLED_APPS = ( # ... 'ldap3_sync', )``

3. Configure the required ``settings``.

4. Run the synchronization management command::

``manage.py syncldap``

For more information on configuration see the documentation below.

--------------

Configuration
-------------

**User Synchronization Configuration Items**

| ***LDAP\_SYNC\_USER\_FILTER***
| Default: ``(objectClass=user)``
| The filter used to retrieve users from the directory. Must be in
standard LDAP filter syntax as per
`RFC2254 <http://www.ietf.org/rfc/rfc2254.txt?number=2254>`__

| ***LDAP\_SYNC\_USER\_BASE***
| Default: The value of ``LDAP_SYNC_BASE``
| The distinguished name of the container to base the search for users
in.

| ***LDAP\_SYNC\_USER\_ATTRIBUTES***
| Default: **No Default -- Required Item**
| A dictionary of key value pairs where the keys are the names of ldap
fields and the values are the names of corresponding django model
fields. New users will be created with these fields populated and
existing users will have these fields updated. *This dictionary must
map the Django User model username field to an LDAP object field.*

| ***LDAP\_SYNC\_USER\_EXEMPT\_FROM\_SYNC***
| Default: ``[]``
| A list of usernames corresponding to Django users who should be
excluded from the sync. Useful for Administrative users who do not
have a corresponding user in the directory.

| ***LDAP\_SYNC\_USER\_REMOVAL\_ACTION***
| Default: ``NOTHING``
| The action to take when a user no longer exists in the directory.
Possible values are ``NOTHING``, ``SUSPEND`` and ``DELETE``. Note that
the ``SUSPEND`` option uses the Django user models is\_active field
and sets it to False.

| ***LDAP\_SYNC\_USER\_SET\_UNUSABLE\_PASSWORD***
| Default: ``True``
| If true this uses the django method set\_unusable\_password on all
newly created users. Useful where django authentication will not be
used.

| ***LDAP\_SYNC\_USERS***
| Default: ``True``
| Controls whether users should be synchronized from the directory.

**Group Synchronization Configuration Items**

| ***LDAP\_SYNC\_GROUP\_FILTER***
| Default: ``(objectClass=group)``
| The filter used to retrieve groups from the directory. Must be in
standard LDAP filter syntax as per
`RFC2254 <http://www.ietf.org/rfc/rfc2254.txt?number=2254>`__

| ***LDAP\_SYNC\_GROUP\_BASE***
| Default: The value of ``LDAP_SYNC_BASE``
| The distinguished name of the container to base the search for groups
in.

| ***LDAP\_SYNC\_GROUP\_ATTRIBUTES***
| Default: **No Default -- Required Item**
| A dictionary of key value pairs where the keys are the names of LDAP
fields and the values are the names of corresponding Django model
fields. New groups will be created with these fields populated and
existing users will have these fields updated.

| ***LDAP\_SYNC\_GROUP\_REMOVAL\_ACTION***
| Default: ``NOTHING``
| The action to take when a group no longer exists in the directory.
Possible values are ``NOTHING`` and ``DELETE``.

| ***LDAP\_SYNC\_GROUP\_EXEMPT\_FROM\_REMOVAL***
| Default: ``[]``
| A list of group names of Django groups that should be excluded from
the sync.

| ***LDAP\_SYNC\_GROUPS***
| Default: ``True``
| Controls wether groups should be synchronized.

**Membership Synchronization Configuration Items**

| ***LDAP\_SYNC\_GROUP\_MEMBERSHIP***
| Default: ``True``
| Controls wether groups will be synchronized from the directory.

| ***LDAP\_SYNC\_GROUP\_MEMBERSHIP\_FILTER***
| Default: ``(&(objectClass=group)(member={user_dn}))``
| The filter used to retrieve the groups that a user belongs to.
``{user_dn}`` will be replaced with the distinguished name of the
user.

**LDAP Server Options**

| ***LDAP\_CONFIG***
| Default: **No Default -- Required Item**
| Configuration item used to configure the server pool. ``LDAP_CONFIG``
can contain the following keys:

- **page\_size**
Default: ``500``
The page size for searches using this server pool.
- **bind\_user**
Default: ``None``
The distinguished name of the user to bind to the directory with.
- **bind\_pass**
Default: ``None``
The password of the user to bind to the directory with.
- **pooling\_strategy**
Default: ``ROUND_ROBIN``
The strategy to use when the pool contains multiple servers. See
ldap3 documentation at
https://ldap3.readthedocs.org/en/latest/servers.html#server-pool for
more information. Can be ``FIRST``, ``ROUND_ROBIN`` or ``RANDOM``.
- **servers**
Default: ``None``
A list of dictionaries each one containing configuration information
for a server. Possible server configuration keys are:

- **address**
Default: **No Default -- Required Item**
Either the IP address or FQDN of the directory server.
- **use\_ssl**
Default: ``False``
Use SSL with this conntection.
- **port**
Default: ``389``
The port to use with this server.
- **timeout**
Default: ``30``
Connection timeout with this server.
- **get\_schema**
Default: ``SCHEMA``
Determines which schema information to retrieve from the server.
At a minimum this should be SCHEMA so that values retrieved from
the directory are coerced to proper python types.