Docs

Platform Sign-On with LDAP

Federate your Active Directory or OpenLDAP directory into the identity provider bundled with NetBox Enterprise, so your users sign in to the platform interface with their directory account

NetBox Enterprise 2.5.0 can federate your Active Directory or OpenLDAP directory into its bundled identity provider, Keycloak. Your users then type their directory username and password into the Keycloak sign-in form, and Keycloak checks them against the directory. Keycloak copies each directory user into its own database, so each user keeps a stable ID (the sub claim). NetBox sign-in does not change. To let people sign in to NetBox itself with their directory account, see LDAP Authentication.

Platform Single Sign-On gives the background and the requirements that every source shares.

Before you start

  • The bundled identity provider is on and provisioned. See Before you start.
  • No other federation source is on. See One source at a time.
  • The directory accepts LDAPS (ldaps://) or StartTLS. NetBox Enterprise refuses plain ldap:// without StartTLS.
  • The Keycloak pod trusts the directory's TLS certificate. For a private CA, add the CA certificate under Additional CA Certificates (under Show Advanced Settings in the Admin Console), or in spec.extraCaCertificates on Helm. No setting ignores certificate errors. See Troubleshooting for a distrusted chain.
  • A bind account can read the users under the users DN. Keycloak never writes to the directory.
  • On OpenLDAP, the memberof overlay covers the group object class that the directory uses, and memberOf has an equality index (olcDbIndex: memberOf eq). Without the overlay, users have no groups.
  • Recommended on OpenLDAP: an equality index on modifyTimestamp (olcDbIndex: modifyTimestamp eq). Keycloak searches on it every minute by default. Without the index, the directory reads every entry under the search base.

Connect your directory

1. Choose the name

The name identifies the directory in Keycloak. Use only letters, digits, _ and -, up to 27 characters.

Do not change the name after you deploy it. A new name is a new directory, and the old directory stays on. See Turn federation off.

2. List the servers

List one to eight server URLs, one for each domain controller or replica. Keycloak tries them in order and uses the first one that answers. Put the closest and most reliable server first: a server that drops packets costs the connection timeout (5 seconds by default) for each connection, and a first sign-in opens more than one.

3. Choose the users DN and the filter

The users DN is one base DN, and Keycloak searches its full subtree. A list of DNs separated by ; does not work.

Without a user filter, every user under the users DN can sign in. The filter is the only control on who can sign in, because Keycloak has no required-group check in this release. For users in more than one OU, set the users DN to a common parent. Active Directory does not match a wildcard in a DN, so filter on a group:

(memberOf=CN=NetBox Users,OU=Groups,DC=corp,DC=example,DC=com)

Filter on an attribute that only your directory administrators can change, such as group membership. Do not filter on an attribute that users or the help desk can edit, such as department: a change to it gives a person access.

The filter must be one LDAP filter in parentheses, up to 4096 characters. Write a parenthesis inside a value as \28 or \29. Unequal counts of ( and ) fail the whole deploy. The Admin Console shows a warning until the counts match.

A search from an Active Directory domain root can return referrals. A Windows Server 2022 domain controller returns three, to the DomainDnsZones, ForestDnsZones and Configuration partitions. Samba AD returns none. With the users DN at the domain root of the Windows Server 2022 domain controller, NetBox Labs tested sign-in, the group filter and the sync: all three work.

4. Enter the configuration

Admin Console

  1. Tick Federate an LDAP directory. This also ticks Enable Bundled Keycloak, unless you saved it off before.
  2. Fill in the fields.
  3. Save the config, then deploy.
FieldRequiredValue
LDAP Directory NameYesThe name from step 1
LDAP Directory TypeYesActive Directory or OpenLDAP
LDAP Server URLsYesOne URL on each line, up to eight. Use only ldaps:// URLs, or only ldap:// URLs, which use StartTLS
LDAP Bind DNYesThe DN of the bind account
LDAP Bind PasswordYesThe password of the bind account
LDAP Users DNYesThe base DN from step 3
LDAP User FilterNoThe filter from step 3. Blank admits every user under the users DN

The console keeps the bind password in the Secret keycloak-ldap-federation-bind, key password. The console does not offer the sync periods, the timeouts, or excludeLockedAccounts, so their defaults apply.

Helm

Type the bind password at a prompt, so that it does not go into your shell history. Run this line on its own. If your terminal sends a paste as typed lines, the prompt reads the pasted lines as the password, and the Secret can get the wrong value. The password that you type can also run as a command, and go into your shell history. If this happens, delete the Secret and remove the password from your shell history.

printf 'Bind password: '; IFS= read -rs BIND_PASSWORD; echo

Then create the Secret. Each command runs only when the one before it succeeds. If the password is empty or the Secret exists, nothing changes: run the prompt again, or delete the old Secret first.

[ -n "$BIND_PASSWORD" ] && \
  kubectl -n <namespace> create secret generic corp-ldap-bind \
    --from-file=password=<(printf '%s' "$BIND_PASSWORD") && \
  kubectl -n <namespace> label secret corp-ldap-bind \
    netboxlabs.com/federation-credential=true \
    app.kubernetes.io/part-of=netbox-enterprise
unset BIND_PASSWORD
  • netboxlabs.com/federation-credential=true lets NetBox Enterprise read the Secret. Keycloak sends the password to the directory host in your configuration, so the owner of the Secret must opt it in.
  • app.kubernetes.io/part-of=netbox-enterprise puts the Secret in the Velero backup. Without it, a restored install has no bind password, and LDAP sign-in fails until you create the Secret again. Do not use app.kubernetes.io/managed-by=netbox-operator: NetBox Enterprise deletes a Secret that has that label and the instance label of your install.

NetBox Enterprise uses the value as it is, so a trailing newline becomes part of the password, and the bind fails.

Then add the entry to your values file. ldapFederation holds one entry:

idp:
  enabled: true
netboxEnterprise:
  enabled: true
  spec:
    idp:
      enabled: true
      ldapFederation:
        - name: corp
          vendor: activeDirectory
          connectionUrls:
            - ldaps://dc1.corp.example.com:636
            - ldaps://dc2.corp.example.com:636
          bindDn: CN=keycloak-bind,OU=Service,DC=corp,DC=example,DC=com
          bindCredential:
            name: corp-ldap-bind
            key: password
          usersDn: DC=corp,DC=example,DC=com
          userSearchFilter: "(memberOf=CN=NetBox Users,OU=Groups,DC=corp,DC=example,DC=com)"
FieldRequiredValue
nameYesThe name from step 1
enabledNoUnset means true. Use false to turn the directory off
vendorYesactiveDirectory or openLdap. See Directory attributes
connectionUrlsYesOne to eight ldap:// or ldaps:// URLs, tried in order
startTlsNoUnset means false. Required with ldap://, refused with ldaps://
bindDnYesThe DN of the bind account
bindCredentialYesThe Secret name and key of the bind password
usersDnYesOne base DN, searched with subtree scope
userSearchFilterNoOne LDAP filter in parentheses
excludeLockedAccountsNoOpenLDAP only. See excludeLockedAccounts on OpenLDAP
changedSyncPeriodNoInterval of the changed-users sync, such as 60, 5m, or 1h. Default 60 seconds, range 1 second to 720 hours
fullSyncPeriodNoInterval of the full sync. Default 24 hours, range 1 second to 720 hours
connectionTimeoutNoTime to open a connection to one server. Default 5 seconds, range 1 second to 5 minutes
readTimeoutNoTime to wait for one LDAP answer. Default 30 seconds, range 1 second to 5 minutes

The custom resource reference gives every field.

Directory attributes

The directory type sets the attributes that Keycloak reads. Users sign in with the username attribute, and Keycloak finds only users with the listed object classes.

SettingActive DirectoryOpenLDAP
UsernamesAMAccountNameuid
RDNcnuid
UUIDobjectGUIDentryUUID
User object classesperson, organizationalPerson, userinetOrgPerson, organizationalPerson

Keycloak copies each user's memberOf values into the federated_groups attribute, as full DNs. memberOf does not include nested groups.

Check that it works

Read the IdentityFederation condition, as The IdentityFederation condition shows. These rows apply to LDAP:

Status and reasonMeaning
True, FederationConsistentThe realm matches your configuration, and Keycloak can bind to the directory
False, LdapConnectionFailedKeycloak cannot bind, so every LDAP sign-in fails. The message gives the error code. See Troubleshooting
False, FederationCredentialRefusedThe bind password Secret does not have the label netboxlabs.com/federation-credential=true, so NetBox Enterprise did not read it. Keycloak keeps the password it already holds, and a directory it does not hold yet is not created. The message gives the command that adds the label
False, FederationNotReconciledNetBox Enterprise cannot read the bind password Secret for another reason, refuses a user filter that is not one filter, or cannot write the directory
Unknown, FederationUnconfirmedThe bind test got no answer, for example from a directory that drops packets, or NetBox Enterprise could not read the realm

On each reconcile, NetBox Enterprise asks Keycloak to test the bind with the stored password, and waits up to one minute. A test with no answer never sets True, and does not clear an earlier LdapConnectionFailed.

The condition tests the bind only. It stays True in these cases:

  • A filter that Keycloak cannot parse, or that matches nobody.
  • A users DN that does not exist.
  • An account collision.

After each change, open https://<netbox-hostname>/sso/realms/netbox/account, and sign in as a user that the filter must admit. On Embedded Cluster, the support bundle reports some of these problems.

Who can sign in

Keycloak admits a user under the users DN who matches all of these clauses:

  1. On Active Directory, always: (!(userAccountControl:1.2.840.113556.1.4.803:=2)), which excludes disabled accounts.
  2. On OpenLDAP, when excludeLockedAccounts is true: (!(pwdAccountLockedTime=*)), which excludes accounts that the password policy locked.
  3. Your user filter, if you set one.

The clauses apply at each sign-in, so an excluded user is refused at the next sign-in, with no wait for a sync. Keycloak keeps that user's record, so the person keeps the same sub if the account comes back. Sessions that are open continue until they end.

excludeLockedAccounts on OpenLDAP

Set this field only when the ppolicy overlay applies to the database that holds the users DN. Without the overlay, every sign-in fails. With the overlay on a different database, the filter excludes nobody, so the setting does nothing. Do these checks first:

  1. The schema has the attribute. This command must print a line:

    ldapsearch -x -H ldaps://<directory-host> -D <bind-dn> -W \
      -b cn=Subschema -s base attributeTypes | grep pwdAccountLockedTime
  2. The overlay is on the users' database. On the directory host, find the olcDatabase whose olcSuffix holds the users DN:

    ldapsearch -Y EXTERNAL -H ldapi:/// -b cn=config '(olcSuffix=*)' dn olcSuffix

    This command must return an olcOverlay entry under that database, for example olcOverlay={0}ppolicy,olcDatabase={1}mdb,cn=config:

    ldapsearch -Y EXTERNAL -H ldapi:/// -b cn=config '(objectClass=olcPPolicyConfig)' dn
  3. The filter admits an unlocked user under the access rules of the bind DN. This command must return the user's entry:

    ldapsearch -x -H ldaps://<directory-host> -D <bind-dn> -W -b <users-dn> \
      '(&(!(pwdAccountLockedTime=*))(uid=<unlocked-user>))' dn
  4. The filter excludes a locked user. Lock a test account, for example with failed binds up to pwdMaxFailure. The command from check 3 with uid=<locked-user> must return no entry.

On OpenLDAP 2.4, the overlay module must be loaded to define pwdAccountLockedTime. On 2.5 and later, the overlay brings its own schema.

Sync and group changes

Keycloak runs two syncs:

  • The changed-users sync, every changedSyncPeriod (60 seconds by default), reads the users whose own entry changed.
  • The full sync, every fullSyncPeriod (24 hours by default), reads every user under the users DN.

A group change usually does not change the user's own entry. On Active Directory, memberOf comes from the group. On the OpenLDAP image that NetBox Labs tested, the memberof overlay did not change modifyTimestamp. So a group change, removals too, reaches federated_groups only at the next full sync, and a sign-in does not refresh it. Nothing in this release reads federated_groups for access. On Helm, a shorter fullSyncPeriod brings changes sooner, but each full sync reads the whole directory.

Rotate the bind password

Change the password in the directory first. Every LDAP sign-in then fails until NetBox Enterprise has the new password. The condition shows LdapConnectionFailed with AuthenticationFailure.

Until then, Keycloak binds with the old password at each sign-in and each sync. A lockout policy that covers the bind account, such as ppolicy with pwdLockout on OpenLDAP or an account lockout threshold on Active Directory, locks the account soon after the change, and the new password then fails too. Exempt the bind account from lockout before you rotate, or unlock it after NetBox Enterprise has the new password.

  • Admin Console: enter the new password in LDAP Bind Password, save, then deploy.

  • Helm: run the prompt on its own, as in step 4:

    printf 'New bind password: '; IFS= read -rs BIND_PASSWORD; echo

    Then update the Secret. A server-side apply keeps its labels, and an empty password changes nothing:

    [ -n "$BIND_PASSWORD" ] && \
      kubectl -n <namespace> create secret generic corp-ldap-bind \
        --from-file=password=<(printf '%s' "$BIND_PASSWORD") --dry-run=client -o yaml \
      | kubectl -n <namespace> apply --server-side --force-conflicts -f -
    unset BIND_PASSWORD

    To apply the change before the next reconcile, see Applying a Secret change.

If NetBox Enterprise cannot read the Secret, Keycloak keeps the old password. If the Secret does not have the netboxlabs.com/federation-credential=true label, the condition shows FederationCredentialRefused, and a FederationCredentialRefused event gives the command that adds the label. If NetBox Enterprise cannot read the Secret for another reason, such as a wrong name or key, the condition shows FederationNotReconciled. In both cases, a KeycloakFederationUnavailable event names the Secret.

What changes for your users

  • NetBox's own LDAP backend stays on, if you use it.
  • Each person signs in two times: to NetBox, and to the platform interface through Keycloak. With the same directory, both use the same username and password, and each sign-in asks for the password.
  • An administrator connects each platform user to their NetBox account by hand. Until then, the platform interface shows that person no NetBox data. See Identity Mapping.

Username collisions

Keycloak keys an imported user to its directory entry by the UUID attribute, and uses the directory username as the Keycloak username. If a Keycloak user from a different directory has the same username, the sync skips the directory user. The condition does not report this. The Keycloak log shows is not updated during sync as he already exists in Keycloak database but is not linked to federation provider.

The usual cause is a renamed or replaced directory. You cannot delete one user of a directory that is off. If you delete the old directory in the Keycloak admin console, Keycloak deletes all of its users. Those people then come back with a new sub.

Turn federation off

  • Admin Console: untick Federate an LDAP directory, save, then deploy. The console keeps your settings and writes the directory as off.
  • Helm: set enabled: false in the entry, and keep the rest of the entry.

Keycloak then refuses sign-ins through the directory, and the imported users keep their sub.

You do not need the bind password Secret to turn the directory off, so you can delete the Secret before or after the change. If you delete the Secret, LDAP stays on. Keycloak keeps the stored password. It also keeps it in the directory that is off, in its database, and in your backups. When you retire LDAP federation, disable the bind account or change its password in the directory.

Do not delete the entry or change the name. On the Admin Console, a cleared required field also deletes the entry. NetBox Enterprise never deletes a directory, because Keycloak deletes the users of a deleted directory. The old directory stays on, and the condition shows UndeclaredFederationSource. To recover, turn the old directory off in the Keycloak admin console, or put the old entry back with enabled: false if no other directory replaces it.

To change to another source, turn LDAP off and the other source on in the same save.

Troubleshooting

ProblemCause and fix
LdapConnectionFailed, code AuthenticationFailureThe bind DN or the password is wrong
LdapConnectionFailed, code SocketResetNo URL accepted the connection, for example because of a wrong port
LdapConnectionFailed, other codeRead the Keycloak log. A TLS error means that Keycloak does not trust the directory's certificate: add the CA certificate. Untrusted certificate means that the chain goes through a certificate that NetBox Enterprise distrusts, such as the eMudhra roots and intermediates, and a CA certificate does not help
"Unexpected error when handling authentication request to identity provider."Keycloak cannot search the directory. LdapConnectionFailed means that the bind fails. With True, the users DN usually does not exist: compare the DN in the Could not query server using DN log line with your users DN
"Invalid username or password." for a user in the directoryCheck, in order: the user is under the users DN; the user matches the filter (not disabled on Active Directory, ppolicy loaded on OpenLDAP with excludeLockedAccounts); no other Keycloak user has the same username
federated_groups is emptyThe user has no memberOf. On OpenLDAP, make sure that the memberof overlay covers the group object class of the directory, such as groupOfUniqueNames

Read the Keycloak log

Keycloak runs up to three pods, and each pod logs only its own sign-ins and syncs. Read every pod:

kubectl -n <namespace> logs -c keycloak --prefix --tail=-1 \
  -l app=keycloak,app.kubernetes.io/managed-by=keycloak-operator \
  | grep org.keycloak.storage.ldap

Keep --tail=-1: with -l, kubectl shows only 10 lines of each pod. For a container that restarted, add --previous --ignore-errors. Without --ignore-errors, kubectl stops at the first pod that did not restart. Each sync logs its counts, and a skipped user logs a warning with its UUID. The bundled realm does not store login events by default, so failed sign-ins show only here. No output does not prove that there is no problem.

Support-bundle checks

On Embedded Cluster, the support bundle reads the Keycloak log with four checks. A Helm install has no support-bundle spec, so read the log there.

CheckResultFix
Keycloak LDAP users DN not foundFailCompare the DN in the log line with your users DN, and correct the users DN
Keycloak LDAP user search filter rejectedFailCompare the filter in the log line with your user filter, and correct the filter
Keycloak LDAP email collisionWarnChange the email address of the directory user or of the Keycloak account
Keycloak LDAP username collisionWarnSee Username collisions

Each check reads the recent lines of the current container of each pod, and gives one result for each pod without its name. A fail means that the line appeared after the container started: compare its timestamp with your last change. A pass means only that the collected lines have no such line. No check finds a filter that matches nobody, or an Active Directory users DN outside the domain that returns a referral.

On this page