LDAP lets Buttons authenticate against your existing directory (Active Directory or a standard LDAP server) instead of maintaining separate local passwords, while still mapping directory groups to Buttons roles.
Before you begin#
- An Enterprise license with the LDAP feature enabled.
- Your directory's host and port, a service account for searching (bind DN and password), and the base DN under which your users live.
- Knowledge of your directory's actual username attribute and group-membership convention (Active Directory's
memberOf, or a separate group-search base).
- Open Settings → SSO, create a new connection, and set Provider to LDAP / Active Directory.
- Enter a Display name.
- Under Server, set Host and Port, and choose your transport: TLS (LDAPS) or STARTTLS (turning one on turns the other off, and the port updates to match: 636 for LDAPS, 389 for STARTTLS). Leave TLS Certificate Verification on unless you have a specific reason to disable it: doing so shows an explicit warning that it's insecure and for testing only.
- Under Service Account, enter the Bind DN and Bind Password used to search the directory. The password is stored through the same encrypted Secrets vault used for connection credentials elsewhere in Buttons, not inline with the rest of this configuration.
- Under User Search, set the Base DN and User Filter: the filter needs a
{{username}} placeholder, for example (sAMAccountName={{username}}) for Active Directory or (uid={{username}}) for a typical OpenLDAP setup. - Under Attribute Mapping, set Username Attribute, Email Attribute, and Display Name Attribute to match your directory's actual field names.
- Under Group Mapping, set Group Filter and Group Attribute if your directory resolves groups by search, or leave Group Base DN empty to read groups directly from each user's
memberOf attribute instead, which is the Active Directory default.
Note
Plain, unencrypted LDAP (both TLS and STARTTLS left off) is allowed and isn't flagged with a warning on the form itself: only disabling certificate verification gets an explicit warning. If your directory traffic crosses any network you don't fully control, use LDAPS or STARTTLS regardless.
About the search filter#
The User Filter and Group Filter are templates you write yourself: Buttons validates that they're structurally sound (balanced parentheses, and the {{username}}/{{dn}} placeholder actually sitting inside a value comparison rather than loose in the filter's logic) before saving. Separately, whatever a real person actually types as their username at login is escaped before being substituted into your filter, so a username containing LDAP special characters can't be used to manipulate the search: you don't need to build that escaping into the filter yourself.
Map groups to roles#
Buttons resolves each user's groups (either via your Group Mapping search, or from
memberOf) and exposes them as a
groups claim, mapped to Buttons roles the same way as any other SSO provider: add a mapping with Claim name
groups, a Claim value matching a real group name from your directory, and the Local role it should grant. See
Map identity claims to roles for exactly how this behaves at sign-in time.
Test the connection#
Select Test connection on the connection's row. This binds using your service account and runs a wildcard search with your configured User Filter, reporting how many users it finds. A successful result confirms your service account credentials, network reachability, Base DN, and filter syntax are all correct, but it doesn't verify a real end user's password, attribute mapping, or group resolution, so still sign in as a real test user afterward to confirm those separately.
Recover from a misconfiguration#
Local username/password sign-in stays fully available on the same login page regardless of this connection's state: enabling or misconfiguring LDAP does not remove or hide it. Keep at least one local administrator account's credentials on hand before relying on LDAP day to day, as a matter of good practice rather than because Buttons would otherwise lock you out.
If you get stuck#
What you see | What to try |
|---|
Test connection fails to bind. | Check the Bind DN and Bind Password: a bind failure is reported separately from a search failure, so the message tells you which step failed. |
Test connection binds but finds zero users. | Check the Base DN and User Filter: a working bind with no results usually means the search scope or filter doesn't match your directory's actual structure. |
A real user can't sign in even though Test connection succeeds. | That test only checks the service account and search: verify the user's own credentials, and confirm the Username/Email/Display Name attributes actually match your directory's field names. |
A signed-in user doesn't get the role you expected. | Confirm whether your directory exposes groups via memberOf or a separate search, and check that your Group Mapping settings match; then verify your claim mapping's Claim value matches the exact group name. |
You're worried about being locked out while testing. | You won't be: local sign-in remains available on the same login page throughout, regardless of this connection's state. |
Where to go next#
