Use LDAP to sign in through an existing directory, such as Active Directory or OpenLDAP, and assign Buttons roles from directory groups.
Before you begin#
- An Enterprise license and permission to manage SSO settings.
- Your directory's host, port, and TLS requirements.
- A service account that can search for users and groups, with its bind distinguished name (DN) and password.
- The search base DNs, user attributes, and group membership filter for your directory.
- A tested local administrator account. See Get started with SSO for shared setup and recovery guidance.
- Open Settings → SSO and select Add provider.
- Set Provider to LDAP / Active Directory.
- Enter a Display name.
- Under Server, enter the Host and select TLS (LDAPS) or STARTTLS. To use STARTTLS, turn off LDAPS first.
- Check the Port against your directory configuration. The usual ports are 636 for LDAPS and 389 for STARTTLS. The form adjusts these standard ports when you change transport settings, but preserves custom ports.
- Keep TLS Certificate Verification enabled. If your directory uses a private certificate authority, enter its CA bundle under Trusted CA certificates (PEM). This bundle replaces the default trusted CAs for this connection.
- Under Service Account, enter the Bind DN and Bind Password.
- Under User Search, enter the Base DN and User Filter. The filter must contain
{{username}}, for example (sAMAccountName={{username}}) for Active Directory or (uid={{username}}) for OpenLDAP. - Under Attribute Mapping, set Username Attribute, Email Attribute, and Display Name Attribute to match your directory's fields.
- Under Group Mapping, enter the Group Base DN and a Group Filter containing
{{dn}}, for example (member={{dn}}). Use the membership filter appropriate for your directory. - Set Group Attribute to
distinguishedName for full group DN mappings, or to another attribute such as cn for unique group-name mappings. - Save.
Use LDAPS or STARTTLS to protect directory credentials in transit. Disabling certificate verification is insecure and should be limited to testing.
The filter placeholders represent the login username and the user's DN. Buttons escapes these values before inserting them into the filters. You do not need to add escaping yourself.
Map groups to roles#
Buttons searches the directory for the user's groups and exposes the results as a groups claim.
- With Group Attribute set to
distinguishedName, use the group's full DN as the mapping's Claim value. - With another attribute, use its value. Buttons includes that value only when it uniquely identifies one of the user's groups within the Group Base DN.
For example, a full DN might be CN=Operators,OU=Groups,DC=example,DC=com. A unique cn value might be Operators.
Use
groups as the
Claim name and select the
Local role to grant. Follow
Map identity claims to roles for mapping setup and synchronization behavior.
Test the connection and sign-in#
- Select Test connection from the connection's row menu.
- Check the result. The test binds with the service account and searches using your User Filter, with
{{username}} replaced by a wildcard. It requests at most 100 entries, so the reported count is not necessarily the total number of directory users. - Enable the connection and the master SSO login toggle. Follow Enable and test SSO, keeping local login as the default while testing.
- In a separate browser session, sign in as a directory test user.
- Verify the user's profile, assigned roles, and access.
A successful connection test means the bind and search completed. It can still return zero users. It does not verify a user's password, attribute mapping, or group resolution.
If you get stuck#
What you see | What to try |
|---|
Test connection fails to bind. | Check the Bind DN, Bind Password, server address, and TLS settings. For a certificate trust error, check the CA bundle while keeping verification enabled. |
The bind succeeds, but the search fails or finds zero users. | Check the Base DN and User Filter against your directory structure. |
A user cannot sign in even though Test connection succeeds. | Check the user's credentials and that the User Filter matches exactly one user. Check that the connection and SSO login are enabled. |
A user's profile has unexpected values. | Check the Username, Email, and Display Name attribute mappings. |
A user does not get the expected role. | Check the Group Base DN and Group Filter. Match the claim value to the configured Group Attribute. If you use a group name, check that it is unique within the search base, or use distinguishedName instead. |
If directory sign-in fails, select sign in with password and use your local administrator credentials to correct the settings.
Where to go next#
