Skip to content
plugboard.appRequest a demo

Connectors

LDAP and Active Directory

Directory authentication, lookup and password reset. Works against Active Directory or any LDAP server.

CategoryIdentity
AuthenticationBind account
ReachesYour directory server, on your network
Needs an agentYes, on managed hosting
Demo modeNo

identity.authenticate, identity.lookupUser, identity.resetPassword

These provide:

  • Password resets from the kiosk, both self-verified by card and staff-verified at the desk.
  • Directory lookups.
  • Authentication against the directory where you want it.

Active Directory and other LDAP servers are internal by definition.

Self-hosted on that network: reaches it directly.

Managed hosting: needs a connector agent inside your network, and the connector’s Runs on set to that agent’s site. An installed agent that no connector points at does nothing.

The connector uses a service account to search, then binds as the user to verify their credentials. So the service account only needs to read, except for password reset, which needs the right to change other users’ passwords.

Create a dedicated account. Do not use a domain administrator.

For Active Directory, the minimum is:

RightFor
Read on the user OUSearch and lookup
Reset password on the user OUOnly if you want kiosk password resets

Delegate the reset right on the specific OU containing students, not at the domain root, using the Delegation of Control wizard. That way the credential can reset a student’s password but not the principal’s.

Password reset over plain LDAP sends the new password unencrypted. Active Directory refuses password changes over an unencrypted connection anyway.

Use ldaps:// on port 636. If your domain controller’s certificate is from your internal CA, the server running Plugboard or the agent needs to trust that CA.

Settings, Connectors, then LDAP / Active Directory under Add a service, and Continue to setup.

FieldDefaultValue
urlThe LDAP URL, for example ldaps://dc.school.edu:636
baseDNSearch base, for example ou=Users,dc=school,dc=edu
userAttruidThe login attribute. Use sAMAccountName for Active Directory
bindDNThe service account DN used to search

The default uid for userAttr is right for OpenLDAP and wrong for Active Directory, where you almost always want sAMAccountName, or userPrincipalName if your users sign in with their email address.

FieldValue
bindPasswordThe service account password

On managed hosting the bind password does not go here. With Runs on set to a connector agent, the field is not offered and is refused if sent: the agent binds to your directory, so the agent holds the password. Put it in the agent’s own secrets file, the AGENT_SECRETS path in its agent.env, under that connector’s instance ID:

JSON
{ "<ldap-instance-id>": { "bindPassword": "..." } }

Use the connector instance ID for each LDAP connection in 0.14.0. The legacy ldap key remains compatible only with the original default instance. See agent credential keys.

A self-hosted install on the same network as the domain controller binds directly and takes the password here as normal.

Save and test. Success reports “LDAP bind OK” with a latency.

  1. Bind as the service account.
  2. Search under baseDN for the person’s entry.
  3. If exactly one is found, bind as that user’s DN with the password they gave.
  4. Success means the credentials are valid.

How the entry is found depends on who is signing in:

WhoSearched for
Staff, signing in to the deskTheir whole Plugboard email address, matched against mail or userPrincipalName: (|(mail=<email>)(userPrincipalName=<email>))
Students and parents, at the kiosk or portalTheir username, in the login attribute: (<userAttr>=<username>)

From 0.55.0, staff are never matched on the part of the address before the @. Otherwise a different directory account whose login happened to be the same, such as a vendor’s support account or a student, could sign in as the staff member. A staff member whose Plugboard email is neither the mail nor the userPrincipalName of their directory entry is refused, so check those match before turning directory sign-in on for staff.

When the search finds more than one entry, the directory is treated as not answering rather than picking one.

Directory sign-in is turned on per audience in single sign-on, under Directory sign-in. While the directory cannot be reached, staff fall back to their Plugboard password.

Plugboard never sees a hash and never stores the password. The directory does the verifying.

Two paths, both landing here.

Self-verified. The person taps their own card, the card resolves to them, and they are taken straight to a “set a new password” screen. It needs no staff time.

Staff-verified. The person requests a reset, an ICT staff member confirms who they are at the desk and approves it, and then the person sets a new password.

Either way the actual change happens through this connector, against your directory, subject to your password policy. A password your directory rejects as too weak is rejected here too, with the directory’s own message.

See the service desk kiosk.

SymptomCause
Bind failed on testWrong bind DN or password. The DN is a full distinguished name, not a username. On managed hosting the password is the one in the agent’s secrets file, not in Plugboard
Connection refused or a timeoutWrong port, firewall, or a managed deployment with no agent
Certificate errors on ldaps://The host does not trust your internal CA. Install the CA certificate on that machine
Test passes, users not foundbaseDN is too specific, or userAttr is wrong. Try sAMAccountName for AD
Authentication always failsuserAttr mismatch, so the search finds nobody to bind as
One staff member cannot sign in with their directory passwordTheir Plugboard email is not the mail or userPrincipalName on their directory entry. Correct one of them
Password reset fails with insufficient rightsThe bind account lacks the reset-password delegation
Password reset fails over ldap://Active Directory refuses password changes on an unencrypted connection. Use ldaps://
Reset rejected as too weakYour directory’s password policy said no. That message is passed through

For managing licences, locking accounts and delegating mailboxes, see directory management, which is a separate connector serving a different purpose.