Rolter can check a sign-in against your LDAP or Active Directory server. A directory user types the login and password they use everywhere else into the ordinary Rolter sign-in form, and gets the same session a local account gets.
LDAP is compiled into Rolter behind the ldap cargo feature. A build without it refuses to store a directory, with an error that says so. Build with --features postgres,ldap (for the container image, --build-arg CARGO_FEATURES=postgres,ldap).
Everything below is done on Governance › LDAP in the dashboard, or through the control-plane API, which the curl examples use. Both need the admin role on the org (see RBAC); the API also accepts the deployment admin token. The dashboard screen registers, edits, takes in and out of service and deletes the org’s directory, rotates or removes its bind password, and maps its groups to roles. A grant an LDAP sign-in wrote is marked from LDAP on the Users screen.
How a sign-in works#
The local account is tried first. If its password does not verify and the org’s directory is enabled, Rolter asks the directory: it binds as a read-only service account to find the user, then binds again as that user with the password they typed. The second bind is the authentication; Rolter never reads or stores a password from the directory.
From there everything is the same as for a local account: an org’s second-factor policy applies, failed attempts are throttled, and the sign-in is audited.
- A wrong password, an unknown login and a login outside the search base all get the same
invalid email or passwordanswer, so the form cannot be used to find out who is in your directory. - If the directory is unreachable, the sign-in is answered the same way and the reason goes to the control plane’s log. Local accounts keep working.
- A directory entry whose mail matches a superadmin never signs in as that account. Superadmins sign in locally, so the break-glass account stays reachable when the directory is down.
- A directory entry whose mail matches an account that holds a deployment role (operator or security auditor) never signs in as that account, even if it has no organization roles. Those accounts sign in locally.
- A directory entry whose mail matches an existing account that holds a role in another organization never signs in as that account. Your directory’s entries are chosen by your organization’s admins, so it may only sign in as accounts whose roles are all inside your organization.
- While your organization has password login turned off (to send members through its identity provider), the directory does not sign anyone in either: a directory sign-in is a password typed into Rolter’s form. Turning password login back on restores it.
- A deactivated account stays out.
- The account is keyed on the entry’s email attribute. If the directory supplies none and the login typed is not an email address, the sign-in is refused.
Register a directory#
An org has one directory.
| Field | Meaning |
|---|---|
url | ldaps:// or ldap:// address of the directory |
bind_dn | the read-only service account that finds users |
bind_password | its password. Sealed with ROLTER_KEK before it is stored and never returned; the response says has_bind_password instead |
base_dn | the subtree searched for users |
user_filter | the search filter; {login} is replaced with what the user typed, escaped. Default (uid={login}) |
email_attr | attribute holding the email. Default mail |
display_name_attr | attribute holding the display name. Default cn |
group_attr | attribute on the user entry listing their groups. Default memberOf |
require_tls | refuse a plain ldap:// URL so the bind password is never sent in cleartext. Default true |
default_role | admin, member or viewer for a user in no mapped group. Leave it out to refuse those users |
enabled | take the directory out of service without deleting it. Default true |
Rolter refuses a directory it could not use safely: an unknown URL scheme, require_tls with a plain ldap:// URL, a filter without {login}, an empty base, or an address your egress policy denies. Update a directory with PUT /api/v1/ldap-directories/{id}; leave bind_password out to keep the stored one, send an empty string to clear it, or send a value to rotate it.
Map groups to roles#
Group mapping works exactly as it does for single sign-on and SCIM: a directory group is worth a role at the org, a team or a project.
Add team_id or project_id to grant at a narrower scope. A mapping can only grant inside the directory’s own org. Group names are matched ignoring case and surrounding spaces.
- A user in several mapped groups gets all of their roles.
- A user in no mapped group gets
default_role, or is refused when there is none. - Roles are reconciled on every sign-in. Removing a user from a group in the directory takes the role away the next time they sign in, with one exception: an org’s last active admin grant is kept and audited rather than failing the sign-in. A role an administrator granted by hand is never touched.
- A first sign-in gives an account that has no display name the one in the directory; the user can still change it.
What is not supported#
- Groups are read from the user entry (
memberOf). Nested groups are not expanded, so map the groups users are directly in. - StartTLS on a plain
ldap://connection is not implemented; useldaps://. - Referrals are not followed.