{"id":14972908,"url":"https://github.com/sjkingo/django_auth_ldap3","last_synced_at":"2025-06-28T17:08:20.584Z","repository":{"id":25745997,"uuid":"29183792","full_name":"sjkingo/django_auth_ldap3","owner":"sjkingo","description":"A library for connecting Django's authentication system to an LDAP directory","archived":false,"fork":false,"pushed_at":"2016-12-14T14:56:53.000Z","size":49,"stargazers_count":23,"open_issues_count":6,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-01T15:18:22.755Z","etag":null,"topics":["active-directory","authentication-backend","django","django-application","ldap","python","python-2","python-3"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sjkingo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-13T09:59:29.000Z","updated_at":"2022-08-31T03:38:39.000Z","dependencies_parsed_at":"2022-08-24T14:13:25.864Z","dependency_job_id":null,"html_url":"https://github.com/sjkingo/django_auth_ldap3","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/sjkingo/django_auth_ldap3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fdjango_auth_ldap3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fdjango_auth_ldap3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fdjango_auth_ldap3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fdjango_auth_ldap3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sjkingo","download_url":"https://codeload.github.com/sjkingo/django_auth_ldap3/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjkingo%2Fdjango_auth_ldap3/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262465788,"owners_count":23315641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["active-directory","authentication-backend","django","django-application","ldap","python","python-2","python-3"],"created_at":"2024-09-24T13:47:43.748Z","updated_at":"2025-06-28T17:08:20.563Z","avatar_url":"https://github.com/sjkingo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# django_auth_ldap3\n\nThis is a small library for connecting Django's authentication system to an\nLDAP directory.  Unlike other similar libraries, it and its dependencies are\npure-Python and do not require any special system headers to run, making it\nperfect for running in a hosted virtualenv.\n\nIt has a sane default configuration that requires minimal customization, and\nhas been tested against OpenLDAP and Microsoft's Active Directory.\n\nIt is licensed under the [BSD license](https://github.com/sjkingo/django_auth_ldap3/blob/master/LICENSE).\n\nIt is known to work with:\n\n* Python 2.7, 3.3-3.5\n* Django 1.6.10, 1.7-1.9\n\nNote at some point in the future, support for Python 2.7/3.3 and Django 1.6/1.7 will be dropped (see [issue #15](https://github.com/sjkingo/django_auth_ldap3/issues/15)).\n\n[![Latest Version](http://img.shields.io/pypi/v/django_auth_ldap3.svg)](https://pypi.python.org/pypi/django_auth_ldap3/)\n[![License](https://img.shields.io/badge/license-BSD-blue.svg)](https://github.com/sjkingo/django_auth_ldap3/blob/master/LICENSE)\n\n## Installation\n\nThe easiest way is to install from [PyPi](https://pypi.python.org/pypi/django_auth_ldap3) using pip:\n\n```\n$ pip install django_auth_ldap3\n```\n\nAlternatively you may install from the latest commit on the `master` branch:\n\n```\n$ pip install -e git+https://github.com/sjkingo/django_auth_ldap3.git#egg=django_auth_ldap3\n```\n\n## Base configuration\n\nA full configuration reference of all settings [is available](https://github.com/sjkingo/django_auth_ldap3#configuration-reference).\n\n1. First, add the LDAP backend to Django's `AUTHENTICATION_BACKENDS` tuple in `settings.py`:\n\n   ```\n   AUTHENTICATION_BACKENDS = (\n       'django_auth_ldap3.backends.LDAPBackend',\n       'django.contrib.auth.backends.ModelBackend',\n   )\n   ```\n\n   We specify `ModelBackend` here as a fallback in case any superusers are defined locally in the database.\n\n2. Point the configuration to the directory server with only two required settings:\n\n   ```\n   AUTH_LDAP_URI = 'ldap://localhost:389'\n   AUTH_LDAP_BASE_DN = 'dc=example,dc=com'\n   ```\n\n   * Any valid [LDAP\n   URI](https://www.centos.org/docs/5/html/CDS/ag/8.0/LDAP_URLs-Examples_of_LDAP_URLs.html)\n   is allowed for the `AUTH_LDAP_URI` setting (the port is optional and will\n   default to 389 if not specified).\n\n   * TLS has been supported since [v0.9.5](https://github.com/sjkingo/django_auth_ldap3/releases/tag/v0.9.5) with `AUTH_LDAP_TLS`.\n\n   * `AUTH_LDAP_BASE_DN` must be set to the base container to perform any subtree\n   searches from.\n\n## Configuration for authenticating\n\nThere are two methods of authenticating against an LDAP directory.\n\n### Method 1: Direct binding\n\nThis is by far the easiest method to use, and requires minimal configuration.\nIn this method, the username and password provided during authentication are\nused to bind directly to the directory. If the bind fails, the\nusername/password combination (or `AUTH_LDAP_BIND_TEMPLATE` [1]) is incorrect.\n\n[1] When direct binding, there is no way to distinguish between an incorrect\nusername/password and the bind template being incorrect, since both result in\nan invalid bind.\n\nOnly one extra setting is required for direct binding to an OpenLDAP directory:\n\n* `AUTH_LDAP_BIND_TEMPLATE`: the template to use when constructing the user to bind. For example: `uid={username},ou=People`. It must contain `{username}` somewhere which will be substituted for the username that is being authenticated.\n\nAlternatively you may wish to change the attribute that matches the Django username - by default it is `uid`:\n\n* `AUTH_LDAP_UID_ATTRIB`: the attribute used for a unique username (e.g. `uid` or `sAMAccountName`)\n\nThe key requirement for direct binding is that a distinguished name is able to\nbe constructed from a given username, for instance:\n\n* username `'jsmith'` is known with a distinguished name of `'uid=jsmith,ou=People,dc=example,dc=com'` in the directory\n\nA point to note here is that if you are using Active Directory, you may tell\nthe backend to bind with a full user principal instead, such as `DOMAIN\\user`\nor `user@domain`.  This can be accomplished by setting one of the following\nsettings:\n\n* `AUTH_LDAP_USERNAME_PREFIX`: e.g. `DOMAIN\\`\n* `AUTH_LDAP_USERNAME_SUFFIX`: e.g. `@domain.com`\n\nIf using either of these settings, set `AUTH_LDAP_BIND_TEMPLATE` to `None`. You\nwill almost certainly want to change the `AUTH_LDAP_UID_ATTRIB` to\n`sAMAccountName`.\n\n### Method 2: Search and bind\n\nThe second method is more flexible but requires more directory-specific\nconfiguration: it allows you to filter users by any valid LDAP filter, across a\ndirectory tree.\n\nIt is yet to be implemented in this library. See [issue #2](https://github.com/sjkingo/django_auth_ldap3/issues/2).\n\n## Group membership\n\nSometimes it is desirable to restrict authentication to users that are members\nof a specific LDAP group. This may be accomplished by setting the\n`AUTH_LDAP_LOGIN_GROUP` setting. By default it is set to `'*'`; any valid user\nmay authenticate. If you wish to restrict this, change the setting to the\ndistinguished name of a group, for example:\n\n```\nAUTH_LDAP_LOGIN_GROUP = 'cn=Web Users,ou=Groups,dc=example,dc=com'\n```\n\nYou may also allow a subset of users to authenticate to the Django admin\ninterface by setting the `AUTH_LDAP_ADMIN_GROUP` setting. By default this is\nset to `None`, indicating no user may have access to the admin. If you wish to\nallow access, change the setting to the distinguished name of a group, for\nexample:\n\n```\nAUTH_LDAP_ADMIN_GROUP = 'cn=Admin Users,ou=Groups,dc=example,dc=com'\n```\n\nShould you wish to map LDAP groups to Django groups, you can use the `AUTH_LDAP_GROUP_MAP`\nsetting.  By default it is set to `None`, indicating that no mapping will occur.  The mapping is\ndone in the form of a dict where the keys are LDAP group DNs and the values are sequences of Django groups,\nfor example:\n\n```\nAUTH_LDAP_GROUP_MAP = {\n    'cn=Admin Users,ou=Groups,dc=example,dc=com': ('site_admins', 'editors'),\n    'cn=Authors,ou=Groups,dc=example,dc=com': ('editors',)\n}\n```\n\nNote that any Django groups you list will be controlled by this mapping, and can't be manually managed,\nbecause users will be added or removed from the groups according to their LDAP group memberships at login.\nAny Django groups not included in the mappings will be unaffected.\n\n## Example configuration for OpenLDAP\n\n```\nAUTH_LDAP_URI = 'ldap://localhost:389'\nAUTH_LDAP_BASE_DN = 'ou=People,dc=example,dc=com'\nAUTH_LDAP_BIND_TEMPLATE = 'uid={username},{base_dn}'\n```\n\nThe last line is only required if the bind template differs from the default.\n\n## Example configuration for Active Directory\n\n```\nAUTH_LDAP_URI = 'ldap://DC1.example.com:389'\nAUTH_LDAP_BASE_DN = 'dc=example,dc=com'\nAUTH_LDAP_BIND_TEMPLATE = None\nAUTH_LDAP_USERNAME_PREFIX = 'DOMAIN\\\\'\nAUTH_LDAP_UID_ATTRIB = 'sAMAccountName'\n```\n\n## Configuration reference\n\n#### `AUTH_LDAP_BASE_DN`\n\nDefault: `'dc=example,dc=com'`\n\n**Required.** The base container to perform any subtree searches from.\n\n#### `AUTH_LDAP_BIND_TEMPLATE`\n\nDefault: `'uid={username},{base_dn}'`\n\n**Required.** Template used to construct the distinguished name of the user to authenticate.\n\nValid substitution specifiers are:\n\n* `{username}` (required): the username being authenticated\n* `{base_dn}`: will be substituted for `AUTH_LDAP_BASE_DN`\n\n#### `AUTH_LDAP_URI`\n\nDefault: `'ldap://localhost'`\n\n**Required.** A valid LDAP URI that specifies a connection to a directory server.\n\nTLS has been supported since [v0.9.5](https://github.com/sjkingo/django_auth_ldap3/releases/tag/v0.9.5) with `AUTH_LDAP_TLS`.\n\n#### `AUTH_LDAP_ADMIN_GROUP`\n\nDefault: `None`\n\n*Optional.* Distinguished name of the group of users allowed to access the admin area, or `None`\nto deny all.\n\n#### `AUTH_LDAP_GROUP_MAP`\n\nDefault: `None`\n\n*Optional.* Dictionary of LDAP groups to Django groups to perform mapping on.\nSee *Group membership*, above, for more details.\n\n*Added in version 0.9.4*\n\n#### `AUTH_LDAP_LOGIN_GROUP`\n\nDefault: `'*'`\n\n*Optional.* Restrict authentication to users that are a member of this group\n(distinguished name). `'*'` indicates any user may authenticate.\n\n#### `AUTH_LDAP_UID_ATTRIB`\n\nDefault: `'uid'`\n\n*Optional.* The unique attribute in the directory that stores the username. For\nActive Directory this will be `sAMAccountName`.\n\n#### `AUTH_LDAP_USERNAME_PREFIX`\n\nDefault: `None`\n\n*Optional.* String to prefix the username before binding. This is used for `DOMAIN\\user` principals.\n\nYou must set `AUTH_LDAP_BIND_TEMPLATE` to `None` when using this option.\n\n#### `AUTH_LDAP_USERNAME_SUFFIX`\n\nDefault: `None`\n\n*Optional.* String to suffix the username before binding. This is used for `user@domain` principals.\n\nYou must set `AUTH_LDAP_BIND_TEMPLATE` to `None` when using this option.\n\n*Added in version 0.9.5*\n\n#### `AUTH_LDAP_TLS`\n\n*Optional.* Flag to enable LDAP over TLS. Further options can be configured through `AUTH_LDAP_TLS_CA_CERTS`,\n`AUTH_LDAP_TLS_VALIDATE`, `AUTH_LDAP_TLS_PRIVATE_KEY`, and `AUTH_LDAP_TLS_LOCAL_CERT`.\n\nDefault: `False`\n\n#### `AUTH_LDAP_TLS_CA_CERTS`\n*Optional.* String to the location of the file containing the certificates of the certification authorities.\n\nIt's checked only if `AUTH_LDAP_TLS_VALIDATE` is set to `True`.\n\nDefault: It will use the system wide certificate store.\n\n#### `AUTH_LDAP_TLS_VALIDATE`\n*Optional.* Specifies if the server certificate must be validated.\n\nDefault: `True`\n\n#### `AUTH_LDAP_TLS_PRIVATE_KEY`\n*Optional.* Specifies the location for the file with the private key of the client.\n\n#### `AUTH_LDAP_TLS_LOCAL_CERT`\n*Optional.* Specifies the location for the file with the certificate of the server.\n\n## Caveats\n\nWhen using this library, it is strongly recommended to not manually\nmodify the usernames in the Django user table (either through the admin or modifying a \n`User.username` field). See issues [#7](https://github.com/sjkingo/django_auth_ldap3/issues/7) and [#9](https://github.com/sjkingo/django_auth_ldap3/issues/9) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjkingo%2Fdjango_auth_ldap3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsjkingo%2Fdjango_auth_ldap3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjkingo%2Fdjango_auth_ldap3/lists"}