Skip to main content

Company directory (LDAP)

A company can let its people sign in with their user name and password from its own LDAP directory, such as Active Directory or OpenLDAP. Merge Pilot checks the password against the directory at each sign-in and creates the person's account the first time.

  • Where: Company → Sign-in → Company directory (LDAP).
  • Who: company admins and platform admins, in a signed-in session (API tokens cannot change the directory).
  • Platform switch: Company directories (LDAP) must be on in the platform settings (Platform settings). When it is off, the card shows Turned off on the platform.
  • The settings are saved with the company page's save button. When the company turned on Review control changes, a change waits for a second administrator (Four-eyes review).
  • A change that would leave people without any way to sign in (for example turning the directory off, or narrowing Only these groups) names them and needs confirming; the admin saving it cannot lock themselves out (Changes that would lock people out).

To use several directories in one company, put an identity provider in front of them (for example Keycloak federating each directory) and use it as an identity provider.

Settings​

Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
Sign in with the directoryTurns directory sign-in on for the companyOffOn or offCompany admin, platform adminldap.enabled
ServerThe directory's host name or IP address. With TLS it must match the server's certificate—A host name or IP address; required when the directory is onCompany admin, platform adminldap.server
PortThe directory's port3891 to 65535. Switching to LDAPS changes 389 to 636, and backCompany admin, platform adminldap.port
Connection securityHow the connection is protectedStartTLSSee the options belowCompany admin, platform adminldap.tls_mode
CA certificate (optional)Trusted besides the system CAs, for a directory whose certificate your own CA issued. Hidden when Connection security is NoneEmptyA PEM certificateCompany admin, platform adminldap.ca_certificate
Base DNWhere people are searched, including everything below it—A DN, such as dc=example,dc=com; required when the directory is onCompany admin, platform adminldap.base_dn
Bind userThe service account Merge Pilot binds with to search for people—A DN, such as cn=admin,dc=example,dc=comCompany admin, platform adminldap.bind_user
Bind passwordThe service account's password. Shown as Configured or Not configured; never shown again. Leave empty to keep the saved one—Any textCompany admin, platform adminldap.bind_password
User filterThe search filter that finds a person. {{username}} is replaced by what the person typed (escaped)—, required when the directory is onAn LDAP filter containing {{username}}, such as (uid={{username}}) or (sAMAccountName={{username}})Company admin, platform adminldap.user_filter
Only these groupsOnly members of one of these groups (see Groups) sign in. Empty lets in everyone the filter finds. Checked at every sign-in and when the session renewsEmptyGroup names (CN) or DNs, comma-separated; at most 50, each 1 to 256 characters. Compared without regard to caseCompany admin, platform adminldap.allowed_groups
Email attributeThe attribute the account's email is read frommailAn attribute name, such as userPrincipalNameCompany admin, platform adminldap.email_attribute
Display name attributeThe attribute the display name is read from (else cn)displayNameAn attribute nameCompany admin, platform adminldap.name_attribute
Account name attributeNames the account by this attribute instead of what the person typed, so one person keeps one accountEmpty: what was typedAn attribute name, such as sAMAccountName or uidCompany admin, platform adminldap.username_attribute
Group attributeThe attribute listing the person's groupsmemberOfAn attribute nameCompany admin, platform adminldap.group_attribute
Group search filterFinds the person's groups by a search instead of the group attribute. {{dn}} is the person's DN, {{username}} the user nameEmpty: the group attributeAn LDAP filter in parentheses containing {{dn}} or {{username}}, such as (&(objectClass=groupOfNames)(member={{dn}}))Company admin, platform adminldap.group_filter
Group search base DNWhere groups are searchedEmpty: the Base DNA DNCompany admin, platform adminldap.group_base_dn
Roles from directory groups: Role when no group matches, group rowsGives directory accounts a role from their groups at every sign-in; the highest mapped role winsOff: roles are set in Merge PilotUser, Auditor, Policy manager, Company adminCompany admin, platform adminldap.roles.default_role, ldap.roles.mappings[] (group, role)

Connection security options:

  • StartTLS: upgraded to TLS before the bind (port 389) (starttls): connects in plain LDAP and upgrades to TLS before any password is sent.
  • LDAPS: TLS from the start (port 636) (ldaps): TLS from the first byte.
  • None (none): no encryption. The bind password and everyone's password cross the network in the clear. Use this only on a trusted network.

With StartTLS and LDAPS, Merge Pilot uses TLS 1.2 or newer and checks the server's certificate against the system CAs and the CA certificate.

When the API is used and ldap.tls_mode is left out, it is starttls, as in the dialog.

The saved bind password​

The saved bind password is sent only to the same server, port and bind user, with the same connection security and CA certificate. When any of these changes, enter the bind password again; otherwise the save is refused, and Test connection binds without the saved password. This keeps a changed server, or turning TLS off, from receiving the saved password.

Test connection​

Test connection checks the settings as the form shows them, before saving. It connects to the server and binds with the bind user and bind password (the saved password when the field is empty and the connection is unchanged). It reports:

  • the directory answered and accepted the bind user, or
  • the directory could not be reached or refused the bind user, with the reason.

The test does not search for a person or check the user filter. Sign in with a test person to check those.

How a directory sign-in works​

  1. On the sign-in page, the person chooses the company (by their work email's domain or from the company list) and types their directory user name and password. The page says Use your directory (LDAP) user name and password.
  2. If a Merge Pilot account with a password matches the user name and password, that account signs in instead.
  3. Merge Pilot binds with the bind user, searches below the Base DN with the User filter, and takes the first match.
  4. It binds as that person with the typed password. A wrong password is a failed sign-in (see Failed sign-ins).
  5. It reads the person's email, display name (else cn) and groups, from the attributes set (by default mail, displayName and memberOf, or the group search). If Only these groups is set and the person is in none of them, the sign-in is refused with your directory account is not in a group that may sign in to this company: ask an administrator.

Each directory operation times out after 10 seconds.

The account​

  • The first sign-in creates an account with the User role, or the role its groups give when Roles from directory groups is on. While the directory gives roles, the Users list marks the role role from directory and it cannot be changed there (this account's role comes from its directory groups). A role the groups change is recorded as ldap_role_changed and sends the Role changed notification.
  • When the directory is turned off or its role mapping removed, roles return to Merge Pilot: each account keeps its current role, and admins can change it on the Users page again.
  • Its user name is the name the person typed, or the Account name attribute's value, in lower case. Its email and display name come from the directory and are updated at every sign-in; they cannot be edited in Merge Pilot.
  • When the user name or email is already used by another account of the company, the sign-in is refused with a message naming the conflict.
  • The account has no Merge Pilot password and cannot become a platform admin or move to another company.
  • In a company with the directory on, accounts created by GitLab or GitHub sign-in always get a suffix (alice-gitlab), so plain names stay with the directory.

Groups​

Groups are read from the person's group attribute (memberOf by default): direct memberships only. With a Group search filter, they are the groups that search finds instead (for directories such as OpenLDAP whose people carry no group attribute). Each group counts by its full DN and by its CN, so mp-users and cn=mp-users,ou=groups,dc=example,dc=com both match.

Sessions​

At every session renewal Merge Pilot looks the person up again with the bind user. With an Account name attribute set, the person is found by that attribute, so sessions stay signed in whichever name they typed:

  • not found by the user filter any more, or no longer in Only these groups: the session ends with your sign-in was withdrawn: sign in again;
  • the directory cannot be reached: the person is asked to sign in again;
  • directory sign-in turned off for the company or the platform: the session ends.

Audit log​

  • A successful directory sign-in is recorded as login, with source ldap.
  • A sign-in refused because the person is in none of the allowed groups is recorded as ldap_login with status failure and the person's groups.
  • A sign-in the directory could not check is recorded as ldap_login with status failure and the reason: the directory could not be reached (including a failed TLS connection), it refused Merge Pilot's bind user, or its search failed.
  • A change to the directory settings is recorded as update_company; with review on, the request is recorded as config_change_requested.

See Audit log.