Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LDAPBackend
✓ from django_auth_ldap.backend import LDAPBackend
LDAPSearch
✓ from django_auth_ldap.config import LDAPSearch
✗ from django_auth_ldap.backend import LDAPSearch
Configuration objects like LDAPSearch should be imported from `django_auth_ldap.config` as `backend.py` might have app loading side-effects in settings.py.
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.
import os
import ldap
from django_auth_ldap.config import LDAPSearch, LDAPGroupQuery
AUTHENTICATION_BACKENDS = [
'django_auth_ldap.backend.LDAPBackend',
'django.contrib.auth.backends.ModelBackend',
]
AUTH_LDAP_SERVER_URI = os.environ.get('AUTH_LDAP_SERVER_URI', 'ldap://localhost:389')
AUTH_LDAP_BIND_DN = os.environ.get('AUTH_LDAP_BIND_DN', '')
AUTH_LDAP_BIND_PASSWORD = os.environ.get('AUTH_LDAP_BIND_PASSWORD', '')
AUTH_LDAP_USER_SEARCH = LDAPSearch(
os.environ.get('AUTH_LDAP_USER_SEARCH_BASE', 'ou=users,dc=example,dc=com'),
ldap.SCOPE_SUBTREE,
"uid=%(user)s"
)
AUTH_LDAP_USER_ATTR_MAP = {
'first_name': 'givenName',
'last_name': 'sn',
'email': 'mail'
}
AUTH_LDAP_MIRROR_GROUPS = True
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
os.environ.get('AUTH_LDAP_GROUP_SEARCH_BASE', 'ou=groups,dc=example,dc=com'),
ldap.SCOPE_SUBTREE,
'(objectClass=groupOfNames)'
)
AUTH_LDAP_GROUP_TYPE = LDAPGroupQuery()
# Populate Group permissions
AUTH_LDAP_FIND_GROUP_PERMS = True
AUTH_LDAP_CACHE_TIMEOUT = 3600 # Cache for 1 hour
# Optional: Require valid TLS certificate from LDAP server
AUTH_LDAP_START_TLS = True
# AUTH_LDAP_GLOBAL_OPTIONS = {
# ldap.OPT_X_TLS_CACERTFILE: os.environ.get('LDAP_TLS_CACERTFILE', '/path/to/ca.pem'),
# ldap.OPT_X_TLS_CERTFILE: os.environ.get('LDAP_TLS_CERTFILE', '/path/to/client.pem'),
# ldap.OPT_X_TLS_KEYFILE: os.environ.get('LDAP_TLS_KEYFILE', '/path/to/client.key')
# }
Debug
Known issues
breakingVersion 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.fixReview 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.
affects: >=5.0.0
breakingdjango-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.fixAlways 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.
affects: 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).
gotchaThe 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.fixInstall 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`.
affects: All versions
gotchaSetting `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.fixEvaluate 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.
affects: All versions
gotchaThe 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.fixArrange 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`.
affects: All versions
Errors
Common errors & fixes
Caught LDAPError while authenticating <username>: CONNECT_ERROR
This error typically indicates that the Django application cannot establish a connection to the LDAP server. Common reasons include incorrect `AUTH_LDAP_SERVER_URI`, network issues (firewall, incorrect port), or problems with TLS/SSL certificates.
fixVerify the `AUTH_LDAP_SERVER_URI` is correct and accessible from the Django server. Check network connectivity and firewall rules. If using LDAPS (SSL/TLS), ensure the server's certificate is trusted by the client system or configure `AUTH_LDAP_GLOBAL_OPTIONS = { ldap.OPT_X_TLS_REQUIRE_CERT: ldap.OPT_X_TLS_NEVER }` (for testing only) or `ldap.OPT_REFERRALS: 0` for Active Directory. Caught LDAPError while authenticating <username>: INVALID_CREDENTIALS
This error means the LDAP server rejected the bind (login) attempt due to incorrect credentials. This is usually caused by an incorrect `AUTH_LDAP_BIND_DN` or `AUTH_LDAP_BIND_PASSWORD`, or if the user attempting to authenticate has an incorrect password or is disabled in LDAP.
fixDouble-check the `AUTH_LDAP_BIND_DN` and `AUTH_LDAP_BIND_PASSWORD` in your settings for accuracy. Ensure the account specified by `AUTH_LDAP_BIND_DN` is active and has the correct password on the LDAP server. For user authentication, ensure the user's password is correct and their account is not locked or expired in LDAP. Ensure the correct username attribute is used in `AUTH_LDAP_USER_SEARCH` (e.g., `sAMAccountName` instead of `cn` for Active Directory).
AttributeError: 'module' object has no attribute 'LDAPError'
This error typically occurs when there's an incompatibility or issue with the `python-ldap` library, often related to Python 2 vs. Python 3 environments or an outdated `python-ldap` installation. The `LDAPError` class might not be directly available under the `ldap` module as expected.
fixEnsure you are using a compatible version of `python-ldap` for your Python and Django versions (e.g., `python-ldap >= 3.1` is required for recent `django-auth-ldap` versions). Upgrade `python-ldap` using `pip install --upgrade python-ldap`. Verify that `import ldap` and then `ldap.LDAPError` works in a Python shell outside of Django to isolate the issue.
Login failed (despite correct credentials being entered in the Django login form)
While the user might be entering correct credentials, `django-auth-ldap` fails to locate the user in the LDAP directory or properly process their information. This is frequently caused by an incorrect `AUTH_LDAP_USER_SEARCH` filter or base DN, or `AUTH_LDAP_USER_DN_TEMPLATE` is incorrectly configured for direct binds.
fixReview your `AUTH_LDAP_USER_SEARCH` configuration to ensure the `base_dn`, `scope`, and `filterstr` correctly match your LDAP directory structure and user attributes. For example, ensure you are searching for the correct attribute (e.g., `sAMAccountName=%(user)s` for Active Directory users). If you are using `AUTH_LDAP_USER_DN_TEMPLATE`, confirm it accurately constructs the user's distinguished name.
Please enter the correct username and password for a staff account.
This message appears when a user successfully authenticates via LDAP, but Django's `ModelBackend` (which is typically still enabled for permission management) determines the user lacks the `is_staff` flag necessary to access the Django admin interface.
fixAfter successful authentication, you need to ensure `is_staff` (and possibly `is_superuser`) is set for the LDAP-authenticated user in Django. This can be done by configuring `AUTH_LDAP_USER_FLAGS_BY_GROUP` to map LDAP group membership to Django user flags, or by using the `django_auth_ldap.backend.populate_user` signal to set these flags programmatically when a user logs in.
Upgrade
Version history
5.3.0latest on PyPI · released Dec 26, 2025
Audit
Dependencies
python-ldaprequiredRequired for LDAP communication. It also needs system-level OpenLDAP libraries and headers to compile.
DjangorequiredPeer dependency, compatible with Django 4.2, 5.2, 6.0 as of v5.3.0.