LDAP

LDAP configuration is done by django ldap module

Take a note that changing configuration/ldap_config.py is strongly discouraged. NetBox container reports barely any python errors.

See also Custom CA on how to configure LDAPS with a custom CA.

Override example

Among others you can use docker-compose.override.yml to inject necessary variables.

NOTE: Images with tag -ldap are not maintained anymore (They were used for versions < 2.0).
Don't forget that the netbox-worker and netbox-housekeeping services should use the same image. See this issue.

Example override file for Active Directory

version: "3.4"
services:
  netbox:
    environment:
      REMOTE_AUTH_ENABLED: "True"
      REMOTE_AUTH_BACKEND: "netbox.authentication.LDAPBackend"
      AUTH_LDAP_SERVER_URI: "ldaps://domain.com"
      AUTH_LDAP_BIND_DN: "CN=Netbox,OU=EmbeddedDevices,OU=MyCompany,DC=domain,dc=com"
      AUTH_LDAP_BIND_PASSWORD: "TopSecretPassword"
      AUTH_LDAP_USER_SEARCH_BASEDN: "OU=MyCompany,DC=domain,dc=com"
      AUTH_LDAP_GROUP_SEARCH_BASEDN: "OU=SubGroups,OU=MyCompany,DC=domain,dc=com"
      AUTH_LDAP_REQUIRE_GROUP_DN: "CN=Netbox-User,OU=SoftwareGroups,OU=SubGroups,OU=MyCompany,DC=domain,dc=com"
      AUTH_LDAP_GROUP_TYPE: "NestedGroupOfNamesType"
      AUTH_LDAP_IS_ADMIN_DN: "CN=Network Configuration Operators,CN=Builtin,DC=domain,dc=com"
      AUTH_LDAP_IS_SUPERUSER_DN: "CN=Domain Admins,CN=Users,DC=domain,dc=com"
      LDAP_IGNORE_CERT_ERRORS: "false"

Example override file for OpenLDAP

Remember to change AUTH_LDAP_GROUP_TYPE to proper value.

version: "3.4"
services:
  netbox:
    environment:
      REMOTE_AUTH_ENABLED: "True"
      REMOTE_AUTH_BACKEND: "netbox.authentication.LDAPBackend"
      AUTH_LDAP_SERVER_URI: "ldaps://domain.com"
      AUTH_LDAP_BIND_DN: "cn=netbox,ou=services,dc=domain,dc=com"
      AUTH_LDAP_BIND_PASSWORD: "TopSecretPassword"
      AUTH_LDAP_USER_SEARCH_BASEDN: "ou=people,dc=domain,dc=com"
      AUTH_LDAP_GROUP_SEARCH_BASEDN: "ou=groups,dc=domain,dc=com"
      AUTH_LDAP_REQUIRE_GROUP_DN: "cn=netbox" # or "cn=netbox,ou=groups,dc=domain,dc=com"
      AUTH_LDAP_IS_ADMIN_DN: "cn=netbox-admins,ou=groups,dc=domain,dc=com"
      AUTH_LDAP_IS_SUPERUSER_DN: "cn=netbox-superusers,ou=groups,dc=domain,dc=com"
      AUTH_LDAP_USER_SEARCH_ATTR: "uid"
      AUTH_LDAP_GROUP_SEARCH_CLASS: "groupOfUniqueNames"
      AUTH_LDAP_GROUP_TYPE: "GroupOfUniqueNamesType"
      AUTH_LDAP_ATTR_LASTNAME: "sn"
      AUTH_LDAP_ATTR_FIRSTNAME: "givenName"
      LDAP_IGNORE_CERT_ERRORS: "false"

Example override file for Active Directory.

It is important to understand that the LDAP configuration in netbox-docker does not work in the same way as it does in normal installation of Netbox. For example, when configuring LDAP Group Types, the normal Netbox installation says that the environment variable should be:

AUTH_LDAP_GROUP_TYPE = GroupOfNamesType()

But in netbox-docker it should be:

AUTH_LDAP_GROUP_TYPE = GroupOfNamesType

All config is handled / controlled in the file netbox/configuration/ldap/*.py. The file ldap_config.py does 99% and extra.py includes group handling functions.

For group handling (such as become admin based on AD group) you MUST use extra.py.

You can choose from adding your LDAP config to either "environment:" in docker-compose.yml or you can add it to the file env/netbox.env.

When creating the below config, it is out most important that you check the base-dn of every object that you address, because it is very easy to make a mistake. For example, the base DN of the AD group "Domain Users" is "CN=Domain Users,CN=Users,OU=Groups,DC=domain,DC=local". Where the double CN attributes is the confusing part.

The below config will enable to login using "[email protected]", but you can change that by replacing userPrincipalName to samAccountName for example, or any other AD attribute really.

This was tested against Cisco Duo Proxy LDAPS, but it's proxying towards Active Directory so it should work just fine with Active Directory directly.

Last tips is that if you look at the Netbox LDAP Configuration, then try to find the value in netbox/config/ldap/ldap_config.py to understand how netbox-docker interprets it.

#ENVIRNOMENT VARIABLES TO CONFIGURE:

BANNER_LOGIN="Please authenticate using Active Directory"
REMOTE_AUTH_ENABLED=True
REMOTE_AUTH_BACKEND="netbox.authentication.LDAPBackend"
AUTH_LDAP_SERVER_URI="ldaps://<ip-address of dc>:636"
AUTH_LDAP_BIND_AS_AUTHENTICATING_USER=False

LDAP_CA_CERT_DIR = "/etc/ssl/certs"
LDAP_CA_CERT_FILE = "/etc/ssl/certs/my-root.pem"
LDAP_IGNORE_CERT_ERRORS=False

AUTH_LDAP_BIND_DN="CN=LDAP Bind,OU=<OU folder name>,DC=domain,DC=local"
AUTH_LDAP_BIND_PASSWORD="<ldap bind account password>"
AUTH_LDAP_USER_SEARCH=LDAPSearch("DC=domain,DC=local",ldap.SCOPE_SUBTREE,"((userPrincipalName=%(user)s))")
AUTH_LDAP_USER_SEARCH_BASEDN: "OU=<OU folder name>,DC=domain,DC=local"
AUTH_LDAP_GROUP_SEARCH_BASEDN: "OU=<OU folder name>,DC=domain,dc=local"

AUTH_LDAP_USER_SEARCH_ATTR: "userPrincipalName"
AUTH_LDAP_GROUP_SEARCH=LDAPSearch("CN=<Netbox AD group>,OU=<OU folder name>,dc=domain,dc=local",ldap.SCOPE_SUBTREE, "(objectClass=groupOfNames)")
AUTH_LDAP_GROUP_TYPE = GroupOfNamesType

AUTH_LDAP_CACHE_TIMEOUT = 300
AUTH_LDAP_MIRROR_GROUPS = True

In order to make group to permission mapping, you must configure netbox/configuration/ldap/extra.py. This is an example of how to make all users with the AD-group "NetboxSuperUsers" superusers in Netbox automatically. Another example is already inside the extra.py file.

#CONFIGURATION OF NETBOX/CONFIGURATION/LDAP/EXTRA.PY:

from django_auth_ldap.config import LDAPGroupQuery

AUTH_LDAP_REQUIRE_GROUP = (
     LDAPGroupQuery(CN=NetboxSuperUsers,OU=<OU folder name>,DC=domain,DC=local")
 )

AUTH_LDAP_USER_FLAGS_BY_GROUP = {
    "is_superuser": "CN=NetboxSuperUsers,OU=<OU folder name>,DC=domain,DC=local",
}