{"id":5763,"library":"django-auth-ldap","title":"Django LDAP Authentication Backend","description":"django-auth-ldap is a Django authentication backend that integrates with LDAP (Lightweight Directory Access Protocol) services, allowing Django applications to authenticate users against an LDAP server. It provides rich configuration options for managing users, groups, and permissions. Currently at version 5.3.0, the library is actively maintained with frequent releases to support the latest Django and Python versions.","status":"active","version":"5.3.0","language":"en","source_language":"en","source_url":"https://github.com/django-auth-ldap/django-auth-ldap","tags":["django","ldap","authentication","auth","directory","active directory"],"install":[{"cmd":"pip install django-auth-ldap","lang":"bash","label":"Install with pip"},{"cmd":"sudo apt-get install libldap2-dev libsasl2-dev","lang":"bash","label":"Install system dependencies (Debian/Ubuntu for python-ldap)"}],"dependencies":[{"reason":"Required for LDAP communication. It also needs system-level OpenLDAP libraries and headers to compile.","package":"python-ldap"},{"reason":"Peer dependency, compatible with Django 4.2, 5.2, 6.0 as of v5.3.0.","package":"Django"}],"imports":[{"symbol":"LDAPBackend","correct":"from django_auth_ldap.backend import LDAPBackend"},{"note":"Configuration objects like LDAPSearch should be imported from `django_auth_ldap.config` as `backend.py` might have app loading side-effects in settings.py.","wrong":"from django_auth_ldap.backend import LDAPSearch","symbol":"LDAPSearch","correct":"from django_auth_ldap.config import LDAPSearch"}],"quickstart":{"code":"import os\nimport ldap\nfrom django_auth_ldap.config import LDAPSearch, LDAPGroupQuery\n\nAUTHENTICATION_BACKENDS = [\n    'django_auth_ldap.backend.LDAPBackend',\n    'django.contrib.auth.backends.ModelBackend',\n]\n\nAUTH_LDAP_SERVER_URI = os.environ.get('AUTH_LDAP_SERVER_URI', 'ldap://localhost:389')\nAUTH_LDAP_BIND_DN = os.environ.get('AUTH_LDAP_BIND_DN', '')\nAUTH_LDAP_BIND_PASSWORD = os.environ.get('AUTH_LDAP_BIND_PASSWORD', '')\n\nAUTH_LDAP_USER_SEARCH = LDAPSearch(\n    os.environ.get('AUTH_LDAP_USER_SEARCH_BASE', 'ou=users,dc=example,dc=com'),\n    ldap.SCOPE_SUBTREE,\n    \"uid=%(user)s\"\n)\n\nAUTH_LDAP_USER_ATTR_MAP = {\n    'first_name': 'givenName',\n    'last_name': 'sn',\n    'email': 'mail'\n}\n\nAUTH_LDAP_MIRROR_GROUPS = True\nAUTH_LDAP_GROUP_SEARCH = LDAPSearch(\n    os.environ.get('AUTH_LDAP_GROUP_SEARCH_BASE', 'ou=groups,dc=example,dc=com'),\n    ldap.SCOPE_SUBTREE,\n    '(objectClass=groupOfNames)'\n)\nAUTH_LDAP_GROUP_TYPE = LDAPGroupQuery()\n\n# Populate Group permissions\nAUTH_LDAP_FIND_GROUP_PERMS = True\nAUTH_LDAP_CACHE_TIMEOUT = 3600 # Cache for 1 hour\n\n# Optional: Require valid TLS certificate from LDAP server\nAUTH_LDAP_START_TLS = True\n# AUTH_LDAP_GLOBAL_OPTIONS = {\n#     ldap.OPT_X_TLS_CACERTFILE: os.environ.get('LDAP_TLS_CACERTFILE', '/path/to/ca.pem'),\n#     ldap.OPT_X_TLS_CERTFILE: os.environ.get('LDAP_TLS_CERTFILE', '/path/to/client.pem'),\n#     ldap.OPT_X_TLS_KEYFILE: os.environ.get('LDAP_TLS_KEYFILE', '/path/to/client.key')\n# }","lang":"python","description":"This quickstart configures `django-auth-ldap` to authenticate users against an LDAP server, synchronize user attributes, and mirror LDAP groups to Django. It assumes basic LDAP setup and uses environment variables for sensitive data. Remember to adjust search bases and attribute mappings to match your LDAP directory structure. Ensure `python-ldap`'s system dependencies are installed for successful installation."},"warnings":[{"fix":"Review existing LDAP group mirroring configurations (`AUTH_LDAP_MIRROR_GROUPS`, `AUTH_LDAP_GROUP_SEARCH`) and ensure your LDAP server is reliably accessible. Implement robust error handling around `AuthenticationFailed` or `ldap_error` signals if custom behavior is needed.","message":"Version 5.0.0 changed the handling of LDAPError during search operations and group mirroring. Previously, an LDAPError might have been silently ignored, leading to incomplete group mirroring. Now, an `LDAPError` during group mirroring can raise `AuthenticationFailed`, aborting the operation and preventing access control issues due to missing group memberships.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always check the release notes for version compatibility before upgrading `django-auth-ldap` or Django/Python. Upgrade your Python and Django versions to supported ones in tandem with `django-auth-ldap` to maintain compatibility.","message":"django-auth-ldap frequently drops support for older Python and Django versions. For instance, v5.3.0 dropped support for Python 3.9 and Django 5.1. Using an unsupported combination can lead to unexpected behavior or security vulnerabilities.","severity":"breaking","affected_versions":"All major versions (e.g., v5.3.0 dropped P3.9/D5.1; v5.2.0 dropped D5.0; v5.1.0 dropped P3.8; v4.7.0 dropped D4.1)."},{"fix":"Install the necessary system packages for `python-ldap` before attempting to install `django-auth-ldap` via pip. Example for Debian/Ubuntu: `sudo apt-get install libldap2-dev libsasl2-dev`.","message":"The underlying `python-ldap` library requires system-level OpenLDAP development libraries and headers (e.g., `libldap2-dev` and `libsasl2-dev` on Debian/Ubuntu) to be installed before `pip install python-ldap` (which is a dependency of `django-auth-ldap`) can succeed. This is a common installation stumbling block.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Evaluate if user data truly needs to be updated on every login. If not, consider setting `AUTH_LDAP_ALWAYS_UPDATE_USER = False`. If updates are necessary, consider strategies to mitigate database load, such as increasing cache timeouts (`AUTH_LDAP_CACHE_TIMEOUT`) or optimizing database performance.","message":"Setting `AUTH_LDAP_ALWAYS_UPDATE_USER = True` causes Django's `auth_user` table to be updated on every successful LDAP login. In high-traffic applications or APIs with frequent login attempts, this can lead to a significant load on the database due to repeated `UPDATE` queries, potentially causing performance bottlenecks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Arrange your `AUTHENTICATION_BACKENDS` tuple in `settings.py` according to your desired authentication flow. To prioritize LDAP authentication, place `django_auth_ldap.backend.LDAPBackend` before `django.contrib.auth.backends.ModelBackend`.","message":"The order of `AUTHENTICATION_BACKENDS` is crucial. If `django.contrib.auth.backends.ModelBackend` is listed before `django_auth_ldap.backend.LDAPBackend`, Django will attempt to authenticate against its local database first. This might be desired for superusers or local accounts, but can cause confusion if all users are expected to authenticate via LDAP first.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}