│ │ │ │ │ │
│ │ │

Logging

│ │ │

LDAPBackend uses the standard Python │ │ │ -logging module to log debug and warning messages to the logger named │ │ │ +logging module to log debug and warning messages to the logger named │ │ │ 'django_auth_ldap'. If you need debug messages to help with configuration │ │ │ issues, you should add a handler to this logger. Using Django’s │ │ │ -LOGGING setting, you can add an entry to your config.

│ │ │ +LOGGING setting, you can add an entry to your config.

│ │ │ 
LOGGING = {
│ │ │      "version": 1,
│ │ │      "disable_existing_loggers": False,
│ │ │      "handlers": {"console": {"class": "logging.StreamHandler"}},
│ │ │      "loggers": {"django_auth_ldap": {"level": "DEBUG", "handlers": ["console"]}},
│ │ │  }
│ │ │
│ │ ├── ./usr/share/doc/python-django-auth-ldap-doc/html/performance.html │ │ │ @@ -54,15 +54,15 @@ │ │ │

  • Cache groups. If AUTH_LDAP_FIND_GROUP_PERMS is True, the │ │ │ default behavior is to reload a user’s group memberships on every request. │ │ │ This is the safest behavior, as any membership change takes effect │ │ │ immediately, but it is expensive. If possible, set │ │ │ AUTH_LDAP_CACHE_TIMEOUT to remove most of this traffic.

    • │ │ │

  • Don’t access user.ldap_user.*. Except for ldap_user.dn, these │ │ │ properties are only cached on a per-request basis. If you can propagate LDAP │ │ │ -attributes to a User, they will only be │ │ │ +attributes to a User, they will only be │ │ │ updated at login. user.ldap_user.attrs triggers an LDAP connection for │ │ │ every request in which it’s accessed.

    • │ │ │

  • Use simpler group types. Some grouping mechanisms are more expensive than │ │ │ others. This will often be outside your control, but it’s important to note │ │ │ that the extra functionality of more complex group types like │ │ │ NestedGroupOfNamesType is not free and will │ │ │ generally require a greater number and complexity of LDAP queries.

    • │ │ ├── ./usr/share/doc/python-django-auth-ldap-doc/html/permissions.html │ │ │ @@ -83,15 +83,15 @@ │ │ │ session timeouts.

    │ │ │

    If AUTH_LDAP_MIRROR_GROUPS is True, then every time a user logs │ │ │ in, LDAPBackend will update the database with │ │ │ the user’s LDAP groups. Any group that doesn’t exist will be created and the │ │ │ user’s Django group membership will be updated to exactly match their LDAP group │ │ │ membership. If the LDAP server has nested groups, the Django database will end │ │ │ up with a flattened representation. For group mirroring to have any effect, you │ │ │ -of course need ModelBackend installed as │ │ │ +of course need ModelBackend installed as │ │ │ an authentication backend.

    │ │ │

    By default, we assume that LDAP is the sole authority on group membership; if │ │ │ you remove a user from a group in LDAP, they will be removed from the │ │ │ corresponding Django group the next time they log in. It is also possible to │ │ │ have django-auth-ldap ignore some Django groups, presumably because they are │ │ │ managed manually or through some other mechanism. If │ │ │ AUTH_LDAP_MIRROR_GROUPS is a list of group names, we will manage │ │ │ @@ -100,15 +100,15 @@ │ │ │ AUTH_LDAP_MIRROR_GROUPS is ignored in this case.

    │ │ │
    │ │ │
    │ │ │

    Non-LDAP Users

    │ │ │

    LDAPBackend has one more feature pertaining │ │ │ to permissions, which is the ability to handle authorization for users that it │ │ │ did not authenticate. For example, you might be using │ │ │ -RemoteUserBackend │ │ │ +RemoteUserBackend │ │ │ to map externally authenticated users to Django users. By setting │ │ │ AUTH_LDAP_AUTHORIZE_ALL_USERS, │ │ │ LDAPBackend will map these users to LDAP │ │ │ users in the normal way in order to provide authorization information. Note that │ │ │ this does not work with AUTH_LDAP_MIRROR_GROUPS; group mirroring is │ │ │ a feature of authentication, not authorization.

    │ │ │
    │ │ ├── ./usr/share/doc/python-django-auth-ldap-doc/html/reference.html │ │ │ @@ -46,17 +46,17 @@ │ │ │
    │ │ │

    Reference

    │ │ │
    │ │ │

    Settings

    │ │ │
    │ │ │

    AUTH_LDAP_ALWAYS_UPDATE_USER

    │ │ │

    Default: True

    │ │ │ -

    If True, the fields of a User object │ │ │ +

    If True, the fields of a User object │ │ │ will be updated with the latest values from the LDAP directory every time the │ │ │ -user logs in. Otherwise the User object │ │ │ +user logs in. Otherwise the User object │ │ │ will only be populated when it is automatically created.

    │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_AUTHORIZE_ALL_USERS

    │ │ │

    Default: False

    │ │ │

    If True, LDAPBackend will be able furnish │ │ │ permissions for any Django user, regardless of which backend authenticated it.

    │ │ │ @@ -103,16 +103,16 @@ │ │ │ settings.

    │ │ │
    │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_CONNECTION_OPTIONS

    │ │ │

    Default: {}

    │ │ │

    A dictionary of options to pass to each connection to the LDAP server via │ │ │ -LDAPObject.set_option(). Keys are │ │ │ -ldap.OPT_* constants.

    │ │ │ +LDAPObject.set_option(). Keys are │ │ │ +ldap.OPT_* constants.

    │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_DENY_GROUP

    │ │ │

    Default: None

    │ │ │

    The distinguished name of a group; authentication will fail for any user │ │ │ that belongs to this group.

    │ │ │
    │ │ │ @@ -123,16 +123,16 @@ │ │ │ permissions based on the LDAP groups the authenticated user belongs to. │ │ │ AUTH_LDAP_GROUP_SEARCH and AUTH_LDAP_GROUP_TYPE must also be │ │ │ set.

    │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_GLOBAL_OPTIONS

    │ │ │

    Default: {}

    │ │ │ -

    A dictionary of options to pass to ldap.set_option(). Keys are │ │ │ -ldap.OPT_* constants.

    │ │ │ +

    A dictionary of options to pass to ldap.set_option(). Keys are │ │ │ +ldap.OPT_* constants.

    │ │ │
    │ │ │

    Note

    │ │ │

    Due to its global nature, this setting ignores the settings prefix. Regardless of how many backends are installed, this setting │ │ │ is referenced once by its default name at the time we load the ldap module.

    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_START_TLS

    │ │ │

    Default: False

    │ │ │

    If True, each connection to the LDAP server will call │ │ │ -start_tls_s() to enable TLS encryption over the standard │ │ │ +start_tls_s() to enable TLS encryption over the standard │ │ │ LDAP port. There are a number of configuration options that can be given to │ │ │ AUTH_LDAP_GLOBAL_OPTIONS that affect the TLS connection. For example, │ │ │ -ldap.OPT_X_TLS_REQUIRE_CERT can be set to ldap.OPT_X_TLS_NEVER │ │ │ +ldap.OPT_X_TLS_REQUIRE_CERT can be set to ldap.OPT_X_TLS_NEVER │ │ │ to disable certificate verification, perhaps to allow self-signed certificates.

    │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_USER_QUERY_FIELD

    │ │ │

    Default: None

    │ │ │

    The field on the user model used to query the authenticating user in the │ │ │ database. If unset, uses the value of USERNAME_FIELD of the model class. │ │ │ @@ -234,28 +234,28 @@ │ │ │ 

    AUTH_LDAP_USER_ATTRLIST = ["*", "+"]
│ │ │
    │ │ │
    │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_USER_ATTR_MAP

    │ │ │

    Default: {}

    │ │ │ -

    A mapping from User field names to LDAP │ │ │ -attribute names. A users’s User object will │ │ │ +

    A mapping from User field names to LDAP │ │ │ +attribute names. A users’s User object will │ │ │ be populated from his LDAP attributes at login.

    │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_USER_DN_TEMPLATE

    │ │ │

    Default: None

    │ │ │

    A string template that describes any user’s distinguished name based on the │ │ │ username. This must contain the placeholder %(user)s.

    │ │ │
    │ │ │
    │ │ │

    AUTH_LDAP_USER_FLAGS_BY_GROUP

    │ │ │

    Default: {}

    │ │ │ -

    A mapping from boolean User field names to │ │ │ +

    A mapping from boolean User field names to │ │ │ distinguished names of LDAP groups. The corresponding field is set to True │ │ │ or False according to whether the user is a member of the group.

    │ │ │

    Values may be strings for simple group membership tests or │ │ │ LDAPGroupQuery instances for more complex │ │ │ cases.

    │ │ │
    │ │ │ │ │ │
    │ │ │

    Backend

    │ │ │
    │ │ │
    │ │ │ django_auth_ldap.backend.populate_user
    │ │ │

    This is a Django signal that is sent when clients should perform additional │ │ │ -customization of a User object. It is │ │ │ +customization of a User object. It is │ │ │ sent after a user has been authenticated and the backend has finished │ │ │ populating it, and just before it is saved. The client may take this │ │ │ opportunity to populate additional model fields, perhaps based on │ │ │ ldap_user.attrs. This signal has two keyword arguments: user is the │ │ │ -User object and ldap_user is the │ │ │ +User object and ldap_user is the │ │ │ same as user.ldap_user. The sender is the │ │ │ LDAPBackend class.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ django_auth_ldap.backend.ldap_error
    │ │ │

    This is a Django signal that is sent when we receive an │ │ │ -ldap.LDAPError exception. The signal has three keyword arguments:

    │ │ │ +ldap.LDAPError exception. The signal has three keyword arguments:

    │ │ │
      │ │ │

    • context: one of 'authenticate', 'get_group_permissions', or │ │ │ 'populate_user', indicating which API was being called when the │ │ │ exception was caught.

      • │ │ │

    • user: the Django user being processed (if available).

      • │ │ │ -

    • exception: the LDAPError object itself.

      • │ │ │ +

    • exception: the LDAPError object itself.

      • │ │ │
    │ │ │

    The sender is the LDAPBackend class (or │ │ │ subclass).

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ @@ -590,15 +590,15 @@ │ │ │
    │ │ │
    │ │ │ get_user_model(self)
    │ │ │

    Returns the user model that │ │ │ get_or_build_user() will │ │ │ instantiate. By default, custom user models will be respected. │ │ │ Subclasses would most likely override this in order to substitute a │ │ │ -proxy model.

    │ │ │ +proxy model.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ authenticate_ldap_user(self, ldap_user, password)
    │ │ │

    Given an LDAP user object and password, authenticates the user and │ │ │ returns a Django user object. See Customizing Authentication.

    │ │ ├── ./usr/share/doc/python-django-auth-ldap-doc/html/users.html │ │ │ @@ -51,47 +51,47 @@ │ │ │ case-insensitive, the default implementation also searches for existing Django │ │ │ users with an iexact query and new users are created with lowercase usernames. │ │ │ See get_or_build_user() if you’d │ │ │ like to override this behavior. See │ │ │ get_user_model() if you’d like to │ │ │ substitute a proxy model.

    │ │ │

    By default, lookups on existing users are done using the user model’s │ │ │ -USERNAME_FIELD. To lookup by a │ │ │ +USERNAME_FIELD. To lookup by a │ │ │ different field, use AUTH_LDAP_USER_QUERY_FIELD. When set, the │ │ │ username field is ignored.

    │ │ │

    When using the default for lookups, the only required field for a user is the │ │ │ -username. The default User model can be │ │ │ +username. The default User model can be │ │ │ picky about the characters allowed in usernames, so │ │ │ LDAPBackend includes a pair of hooks, │ │ │ ldap_to_django_username() and │ │ │ django_to_ldap_username(), to │ │ │ translate between LDAP usernames and Django usernames. You may need this, for │ │ │ example, if your LDAP names have periods in them. You can subclass │ │ │ LDAPBackend to implement these hooks; by │ │ │ -default the username is not modified. User │ │ │ +default the username is not modified. User │ │ │ objects that are authenticated by │ │ │ LDAPBackend will have an ldap_username │ │ │ attribute with the original (LDAP) username. │ │ │ -username (or │ │ │ -get_username()) will, of │ │ │ +username (or │ │ │ +get_username()) will, of │ │ │ course, be the Django username.

    │ │ │
    │ │ │

    Note

    │ │ │

    Users created by LDAPBackend will have an │ │ │ unusable password set. This will only happen when the user is created, so if │ │ │ you set a valid password in Django, the user will be able to log in through │ │ │ -ModelBackend (if configured) even if │ │ │ +ModelBackend (if configured) even if │ │ │ they are rejected by LDAP. This is not generally recommended, but could be │ │ │ useful as a fail-safe for selected users in case the LDAP server is │ │ │ unavailable.

    │ │ │
    │ │ │
    │ │ │

    Populating Users

    │ │ │

    You can perform arbitrary population of your user models by adding listeners to │ │ │ -the Django signal: │ │ │ +the Django signal: │ │ │ django_auth_ldap.backend.populate_user. This signal is sent after the │ │ │ user object has been constructed (but not necessarily saved) and any configured │ │ │ attribute mapping has been applied (see below). You can use this to propagate │ │ │ information from the LDAP directory to the user object any way you like. If you │ │ │ need the user object to exist in the database at this point, you can save it in │ │ │ your signal handler or override │ │ │ get_or_build_user(). In either case, │ │ │ @@ -133,15 +133,15 @@ │ │ │ To disable this, set AUTH_LDAP_ALWAYS_UPDATE_USER to False. If │ │ │ you need to populate a user outside of the authentication process—for example, │ │ │ to create associated model objects before the user logs in for the first │ │ │ time—you can call django_auth_ldap.backend.LDAPBackend.populate_user(). │ │ │ You’ll need an instance of LDAPBackend, which │ │ │ you should feel free to create yourself. │ │ │ populate_user() returns the │ │ │ -User or None if the user could not be │ │ │ +User or None if the user could not be │ │ │ found in LDAP.

    │ │ │ 
    from django_auth_ldap.backend import LDAPBackend
│ │ │  
│ │ │  user = LDAPBackend().populate_user("alice")
│ │ │  if user is None:
│ │ │      raise Exception("No user named alice")
│ │ │