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
Which lights up:
- 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. Both halves: 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. The Delegation of Control wizard does this properly in about a minute, and it is the difference between a credential that can reset a student’s password and one that can reset 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, which is the correct behaviour.
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”Admin, Connectors, LDAP / Active Directory, Configure.
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 |
userAttr catches people out. The default uid 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(<userAttr>=<username>). - If found, bind as that user’s DN with the password they gave.
- Success means the credentials are valid.
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. Fastest, and 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 |
| 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.