External Authentication (LDAP)

This guide explains how to use this role to deploy LDAP authentication for NetBox.

Requirements

All system and Python dependencies are installed automatically when LDAP configuration is present.

Configuration

Configuration is applied to ldap_config.py by specifying raw configuration options to the config sub key within the netbox_auth_ldap dictionary variable. NetBox specific detailed information can be found in the official documentation. Additional LDAP configuration options can be found in the django-auth-ldap documentation

Below is a simple example demonstrating how to apply such options.

Example

# host_vars.yml

# Enable LDAP remote authentication
netbox_remote_auth:
  enabled: True
  backend: 'netbox.authentication.LDAPBackend'

# NetBox LDAP configuration
netbox_auth_ldap:
  config: |
    # Server URI
    AUTH_LDAP_SERVER_URI = "ldaps://ad.example.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)
    LDAP_IGNORE_CERT_ERRORS = True

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

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

    # USER AUTHENTICATION
    AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=Users,dc=example,dc=com",
                                        ldap.SCOPE_SUBTREE,
                                        "(sAMAccountName=%(user)s)")

    # 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"
    # When using Windows Server 2012, AUTH_LDAP_USER_DN_TEMPLATE should be set to None.
    # AUTH_LDAP_USER_DN_TEMPLATE = None

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

    # USER GROUPS FOR PERMISSIONS
    # 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,
                                        "(objectClass=group)")
    AUTH_LDAP_GROUP_TYPE = GroupOfNamesType()

    # Define a group required to login.
    AUTH_LDAP_REQUIRE_GROUP = "CN=NETBOX_USERS,DC=example,DC=com"

    # Mirror LDAP group assignments.
    AUTH_LDAP_MIRROR_GROUPS = True

    # Define special user types using groups. Exercise great caution when assigning superuser status.
    AUTH_LDAP_USER_FLAGS_BY_GROUP = {
      "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.
    AUTH_LDAP_FIND_GROUP_PERMS = True

    # Cache groups for one hour to reduce LDAP traffic
    AUTH_LDAP_CACHE_TIMEOUT = 3600

Suggestions

The example provided in this guide is meant to quickly demonstrate how to inject your own LDAP configuration into this role. One way to avoid this raw configuration directly within a playbook is to define your own template or file and load it using a lookup plugin:

# Load from static configuration file
netbox_auth_ldap:
  config: "{{ lookup('file', 'path/to/ldap_config.py') }}"

# Load from custom template
netbox_auth_ldap:
  config: "{{ lookup('template', './ldap_config.template.py.j2') }}"