LDAP and Active Directory
Directory authentication, lookup and password reset. Works against Active Directory or any LDAP server.
| Category | Identity |
| Authentication | Bind account |
| Reaches | Your directory server, on your network |
| Needs an agent | Yes, on managed hosting |
| Demo mode | No |
Capabilities
Section titled “Capabilities”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.
The private network question
Section titled “The private network question”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 bind account
Section titled “The bind account”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:
| Right | For |
|---|---|
| Read on the user OU | Search and lookup |
| Reset password on the user OU | Only 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.
Use LDAPS
Section titled “Use LDAPS”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.
Configuring it in Plugboard
Section titled “Configuring it in Plugboard”Settings, Connectors, then LDAP / Active Directory under Add a service, and Continue to setup.
Settings
Section titled “Settings”| Field | Default | Value |
|---|---|---|
url | The LDAP URL, for example ldaps://dc.school.edu:636 | |
baseDN | Search base, for example ou=Users,dc=school,dc=edu | |
userAttr | uid | The login attribute. Use sAMAccountName for Active Directory |
bindDN | The 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.
Credentials
Section titled “Credentials”| Field | Value |
|---|---|
bindPassword | The 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:
{ "<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.
How authentication works
Section titled “How authentication works”- Bind as the service account.
- Search under
baseDNfor the person’s entry. - If exactly one is found, bind as that user’s DN with the password they gave.
- Success means the credentials are valid.
How the entry is found depends on who is signing in:
| Who | Searched for |
|---|---|
| Staff, signing in to the desk | Their whole Plugboard email address, matched against mail or userPrincipalName: (|(mail=<email>)(userPrincipalName=<email>)) |
| Students and parents, at the kiosk or portal | Their 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.
Password reset from the kiosk
Section titled “Password reset from the kiosk”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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause |
|---|---|
| Bind failed on test | Wrong 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 timeout | Wrong 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 found | baseDN is too specific, or userAttr is wrong. Try sAMAccountName for AD |
| Authentication always fails | userAttr mismatch, so the search finds nobody to bind as |
| One staff member cannot sign in with their directory password | Their Plugboard email is not the mail or userPrincipalName on their directory entry. Correct one of them |
| Password reset fails with insufficient rights | The 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 weak | Your directory’s password policy said no. That message is passed through |
Related
Section titled “Related”For managing licences, locking accounts and delegating mailboxes, see directory management, which is a separate connector serving a different purpose.