Skip to main content

LDAP / Active Directory

Federate logins against an LDAP v3 directory or Active Directory. Passwords of federated users never land in CertAutoPilot's database — the backend verifies them by binding to the directory. This page deepens the LDAP summary on the Auth & RBAC page.

note

LDAP is available on every tier. When no LDAP config with a non-empty Host is saved, logins simply use local authentication only.

How authentication works​

There is one bind mode: search-then-bind with a service account. Which method checks a password depends on the account, never on the order of attempts:

  • A username that already exists signs in with its own method: an LDAP account through the directory, a local account with its CertAutoPilot password, and an SSO account never with a password.
  • An unknown username is tried against the directory; a successful bind creates the account (see Auto-provisioning).

An LDAP sign-in runs like this:

  • Filters use a %s placeholder — it is replaced with the LDAP-escaped username (user filter) or the user's full DN (group filter). Values are escaped, so filter injection via the login form is not possible.
  • Directory searches carry a 30-second time limit; a fresh connection is opened per login (no pooling).
  • A local account keeps signing in with its own password while LDAP is on — the directory is never asked about it, even when an entry with the same name exists there.
  • LDAP can be switched off without losing its configuration (ldap_enabled in the sign-in settings). While it is off, LDAP accounts cannot sign in. CertAutoPilot refuses the switch when no organization owner could sign in afterwards.

Settings reference​

Settings → Sign-in → LDAP (Configure LDAP). Viewing and saving require the owner org role. LDAP is active once a config with a non-empty Host is saved and LDAP sign-in is on (it is unless switched off — see above). Clearing the host removes the configuration and, like switching LDAP sign-in off, ends the sessions of LDAP accounts at their next refresh (within 15 minutes); it is refused when no organization owner could sign in without LDAP. The configuration is stored in the settings collection under ldap_config. The bind password is stored separately, encrypted under your KEK in ldap_credentials (covered by key rotation); it is never returned to the browser (the form shows a "has password" state and keeps the stored value when you leave the field blank). The stored password is used only for the same host over a connection at least as protected as the saved one: changing the host, turning TLS / StartTLS off, turning certificate checking off or giving another CA certificate needs the password typed again (save and the tests refuse otherwise).

A directory sign-in takes at most 20 seconds in all (connect, service bind, search, user bind, group search) and stops when the browser gives up. Each CertAutoPilot process runs at most 16 directory sign-ins at once; one more waits up to 5 seconds and is then answered 503 with error_type: LDAP_BUSY, the directory is busy; try again in a few seconds and Retry-After: 5 (not "wrong password").

Upgrading from 1.6.4 or earlier

Earlier versions kept the bind password in plaintext inside ldap_config. After the upgrade it is copied into ldap_credentials straight away, and the plaintext copy is removed once every running CertAutoPilot process has been on 1.6.5 or later for 24 hours (checked a minute after start and then hourly; a process restart starts the wait again) — an older process still reads only the plaintext copy, and one that is only restarting sends no heartbeat for a moment.

Downgrading after the upgrade

Once every node runs 1.6.5, the plaintext copy is removed. A node rolled back to an earlier version then binds with an empty password and LDAP sign-in fails there: re-enter the bind password on the LDAP page after a downgrade.

Field (JSON)UI labelNotes
hostHostDirectory hostname / IP. Non-empty = LDAP active.
portPort389 (plain / STARTTLS) or 636 (LDAPS).
use_tlsUse TLSLDAPS — TLS from the first byte. Mutually exclusive with STARTTLS.
use_start_tlsUse StartTLSPlain connect, then upgrade.
skip_verifySkip TLS VerifyDisables certificate verification. Avoid — see TLS.
tls_ca_certTLS CA CertificatePEM, optional — see the warning under TLS.
bind_dnBind DNService account DN, e.g. cn=admin,dc=example,dc=com.
bind_passwordBind PasswordService account password. Write-only. Left empty, the stored one is kept — but only for the same host: changing the host needs the password re-entered, and a connection or filter test against another host never uses the stored one.
base_dnBase DNSearch root for users, e.g. dc=example,dc=com.
user_filterUser FilterMust contain %s, e.g. (&(objectClass=person)(uid=%s)).
group_filterGroup FilterMust contain %s (user DN), e.g. (&(objectClass=groupOfNames)(member=%s)). Empty = skip group lookup.
group_base_dnGroup Base DNSearch root for groups; defaults to Base DN when empty.
username_attributeUsernameAttribute mapped to the CertAutoPilot username, e.g. uid or sAMAccountName. It must be on the user entries: a sign-in whose entry lacks it is refused. When the attribute has several values, the one matching the name typed at sign-in is used; with several values and none matching, the sign-in is refused.
email_attributeEmaile.g. mail. Empty result falls back to <username>@local.ldap.
display_name_attributeDisplay Namee.g. cn or displayName.
group_attributeGroupAttribute read from matched group entries, e.g. cn (compared regardless of case). Its values are the names you link to user groups. dn uses each group entry's full DN instead — pins a link to one entry.
default_roleDefault role for new LDAP usersviewer (default) or none. See Auto-provisioning & roles.

TLS​

  • LDAPS (use_tls, port 636) is preferred. STARTTLS on 389 is supported. Minimum: fix the directory rather than running plain LDAP — but note that plain LDAP is not refused; with both TLS switches off the connection is unencrypted.
  • skip_verify disables certificate verification and logs a MitM warning on every connection. Don't ship it to production.
The CA-certificate field is not applied to the connection

The TLS CA Certificate field is stored with the config, but the current connection logic verifies the server certificate against the host's system trust store only (with SNI set to the configured host). For a private CA, add the CA to the OS trust store of every backend host (or container image) instead of relying on this field.

Auto-provisioning & roles​

The first successful directory login creates the user automatically:

  • auth_source: ldap, username / email / display name from the configured attributes, and the user's directory DN recorded on the account.
  • Own role: set by Default role for new LDAP users — Viewer (an org-wide viewer role; the default) or None (no role of its own; the user has only what its groups give). It is applied once, to the account a first sign-in creates (a failed role write is retried at the next sign-in); a user whose own roles an owner later removed does not get it back.

After provisioning, the user's own roles are managed locally in Settings → Users, exactly like local users; a sign-in never changes them. What the directory does change is group membership:

  • When a Group Filter is set, every LDAP sign-in reads the user's LDAP groups and makes its LDAP memberships of user groups match them — joining the groups linked to those LDAP groups and leaving the others it had joined through LDAP. The roles and grants of those groups then apply. Members added by hand are never touched. Details and corner cases: User groups → Linking LDAP groups.
  • Without a Group Filter, no group is read and memberships stay as they are.

Disabling an LDAP user locally sticks. A user disabled in Settings → Users stays disabled: a later directory login with a valid password is refused and does not re-enable the account, and disabling also ends the user's current sessions. Disabling in the directory works as well (the user bind fails) — do whichever fits your offboarding; you no longer need both.

A directory identity never takes over a local account

If the directory has an entry whose username equals a local (or SSO) CertAutoPilot account — admin from setup, or any password-based user — that identity is never attached to it: a sign-in with that name is checked against the account's own method (the local password), the directory is not asked, and the account's password and roles are untouched. A name that differs only in letter case is refused at login, and the server logs a warning naming the username and DN. Whoever can create or rename directory entries therefore cannot borrow a local account's roles. To federate that person, move the account to LDAP (Settings → Users → Change the sign-in method).

Test tools​

Use these before and after saving — both accept the form's current (unsaved) values and fall back to the stored bind password when the field is blank:

  • Test Connection (POST /settings/ldap/test) — verifies the service-account bind only. Returns success or the directory's bind error.
  • Filter test (search icon next to User Filter and Group Filter, POST /settings/ldap/test-filter) — runs the filter with a test value you supply and lists matching entries. Results expose a safe attribute allowlist only: dn, cn, uid, sAMAccountName, mail, memberOf, objectClass, plus your configured attribute names. For the Group Filter (test value: a user's DN) the result also lists the group names a sign-in would read — the configured Group attribute of each entry, the values you link on Settings → Groups — and warns when the entries do not carry that attribute (typically memberOf, which is an attribute of user entries; use cn).

Active Directory notes​

  • User filter: (&(objectClass=user)(sAMAccountName=%s)), with Username = sAMAccountName. To let users log in with their UPN instead, filter on (userPrincipalName=%s).
  • Group filter: (member=%s) (the placeholder is the user's full DN). memberOf shows up in filter-test results, which helps sanity-check membership.
  • Attribute mapping: Email = mail, Display Name = displayName or cn.

Interaction with TOTP and lockout​

  • TOTP applies to LDAP users the same as local users — the directory never sees the OTP code. With the org policy set to Required, LDAP users are forced through enrollment on their next login.
  • The account-lockout check runs for LDAP users too, but failed directory binds do not increment the local failure counter — brute-force protection for federated accounts belongs in the directory's own lockout policy.

Troubleshooting​

Service bind fails ("Test Connection" errors)​

Wrong Bind DN / password, or the service account is disabled or password-expired in the directory. AD frequently wants the DN form (cn=svc-cap,ou=service,dc=corp,dc=example,dc=com); test exactly what you saved.

Test or login fails with a timeout​

CertAutoPilot gives the directory 10 seconds to accept the connection and 30 seconds to answer each request (bind, search, StartTLS). A timeout means the host or port is unreachable or firewalled (connection), or the server accepted the connection but never answered — typically a non-LDAP service on that port, or LDAPS vs. plain LDAP mismatched with Use TLS. A login is refused rather than left waiting.

"filter must contain %s"​

Both filters are templates — the user filter substitutes the username, the group filter the user DN. {{ .username }}-style placeholders are not supported. Saving the LDAP page refuses a filter without %s too: a group filter without it would match every group, and every sign-in would join every linked user group.

"LDAP entry has no … attribute"​

The user entry has no value for the Username attribute — usually an Active Directory filter on sAMAccountName with Username left at uid. Set Username to the attribute the filter matches.

User can authenticate but lands as viewer​

Expected with the default Default role for new LDAP users = Viewer. Grant the real role under Settings → Users, or link the user's LDAP group to a user group that holds it (and set the default role to None if new users should get nothing else).

A user signs in but sees no project​

Default role for new LDAP users is None and none of the user's LDAP groups is linked to a user group with a role. Link one, or give the user a role in Settings → Users.

TLS handshake fails against a private CA​

The connection verifies against the host system trust store, not the form's CA field. Install the CA on the backend host, or (temporarily, never in production) set Skip TLS Verify to confirm that trust is the only problem.

See also​