This guide explains how to implement LDAP authentication using an external server. User authentication will fall back to built-in Django users in the event of a failure.


Install openldap-devel

On Ubuntu:

sudo apt-get install -y python-dev libldap2-dev libsasl2-dev libssl-dev

On CentOS:

sudo yum install -y python-devel openldap-devel

Install django-auth-ldap

sudo pip install django-auth-ldap


Create a file in the same directory as (typically netbox/netbox/) named Define all of the parameters required below in Complete documentation of all django-auth-ldap configuration options is included in the project's official documentation.

General Server Configuration


When using Windows Server 2012 you may need to specify a port on AUTH_LDAP_SERVER_URI. Use 3269 for secure, or 3268 for non-secure.

import ldap

# Server URI

# The following may be needed if you are binding to Active Directory.
    ldap.OPT_REFERRALS: 0

# Set the DN and password for the NetBox service account.
AUTH_LDAP_BIND_DN = "CN=NETBOXSA, OU=Service Accounts,DC=example,DC=com"

# Include this setting if you want to ignore certificate errors. This might be needed to accept a self-signed cert.
# Note that this is a NetBox-specific setting which sets:
#     ldap.set_option(ldap.OPT_X_TLS_REQUIRE_CERT, ldap.OPT_X_TLS_NEVER)

STARTTLS can be configured by setting AUTH_LDAP_START_TLS = True and using the ldap:// URI scheme.

User Authentication


When using Windows Server 2012, AUTH_LDAP_USER_DN_TEMPLATE should be set to None.

from django_auth_ldap.config import LDAPSearch

# This search matches users with the sAMAccountName equal to the provided username. This is required if the user's
# username is not in their DN (Active Directory).
AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=Users,dc=example,dc=com",

# If a user's DN is producible from their username, we don't need to search.
AUTH_LDAP_USER_DN_TEMPLATE = "uid=%(user)s,ou=users,dc=example,dc=com"

# You can map user attributes to Django attributes as so.
    "first_name": "givenName",
    "last_name": "sn",
    "email": "mail"


When using Microsoft Active Directory, support for nested groups can be activated by using NestedGroupOfNamesType() instead of GroupOfNamesType() for AUTH_LDAP_GROUP_TYPE. You will also need to modify the import line to use NestedGroupOfNamesType instead of GroupOfNamesType .

from django_auth_ldap.config import LDAPSearch, GroupOfNamesType

# This search ought to return all groups to which the user belongs. django_auth_ldap uses this to determine group
# hierarchy.
AUTH_LDAP_GROUP_SEARCH = LDAPSearch("dc=example,dc=com", ldap.SCOPE_SUBTREE,

# Define a group required to login.

# Define special user types using groups. Exercise great caution when assigning superuser status.
    "is_active": "cn=active,ou=groups,dc=example,dc=com",
    "is_staff": "cn=staff,ou=groups,dc=example,dc=com",
    "is_superuser": "cn=superuser,ou=groups,dc=example,dc=com"

# For more granular permissions, we can map LDAP groups to Django groups.

# Cache groups for one hour to reduce LDAP traffic
  • is_active - All users must be mapped to at least this group to enable authentication. Without this, users cannot log in.
  • is_staff - Users mapped to this group are enabled for access to the administration tools; this is the equivalent of checking the "staff status" box on a manually created user. This doesn't grant any specific permissions.
  • is_superuser - Users mapped to this group will be granted superuser status. Superusers are implicitly granted all permissions.