Set up LDAP/AD sign-in (Company Login)

With Company Login, users sign in with their Active Directory account (username + password) — alongside the one-time passcode (OTP) sign-in. Both run at the same time: the sign-in page then shows two tabs, “Code login” and “Company login”. The tab and the first sign-in from the user’s point of view are explained in Company login (first sign-in).

LDAP is a Pro/Site feature (available in Pro and Site, not Free → License & edition model) and is served exclusively by the central Web API server. Single-workstation and peer installations (standalone desktop, desktop-as-server) offer no LDAP — see Topology.

Prerequisites

• Service account in AD: a dedicated account with read access to the user subtree — least privilege, not a domain admin. Its password should ideally not expire, otherwise every sign-in breaks until it is re-entered.
• LDAPS / TLS: a domain controller with a valid LDAPS certificate on port 636; the CA certificate must be trustable by the server.
• Network: port 636 (LDAPS) or 389 (StartTLS) open from the API server to the DC.
• Base DN: e.g. DC=corp,DC=example,DC=com. Optionally a narrower search subtree.
• At least one AD group whose members are allowed to sign in.

Setting it up

The settings live under Admin → “LDAP / AD” tab (visible only in web/paired mode).

1. Fill in Connection: Host (DC hostname/IP), Port 636, Security Ldaps, Base DN (DC=corp,DC=example,DC=com), optionally a narrower UserSearchBase.
2. Fill in Service account: ServiceAccountDn (bind DN or UPN) and password. The password is stored encrypted and never shown in clear text; on a later save leave it empty to keep the stored secret.
3. Leave Attributes on the AD defaults in most cases. For UPN login (jane.doe@corp.example.com) set LoginAttribute to userPrincipalName.
4. Click “Test connection” — it probes the entered config (a successful service-account bind) without saving.
5. Create group mappings (see below): at least one login group with a role.
6. Set Enabled to true and save. Changes apply live (hot reload) — no restart needed.
7. Verify: sign out → “Company login” tab → test with a real AD account, and cross-check an admin account via the admin group.

Groups → roles

Each mapping maps an AD group to a permission. The gate decides per sign-in “allowed in?” and “which role?”:

• Login vs. deny groups. Only a group marked as a login group (IsAllowedLoginGroup = true) grants access and a role. Deny/observe groups can never accidentally elevate a user.
• Highest role wins. With multiple memberships, the strongest matched login group counts (Admin > Employee). An overly broad admin group grants admin rights unintentionally.
• AllowAllAuthenticated is a wide gate: true lets any successfully bound AD user in with the DefaultRole — convenient for “all employees”, but without a group gate. For graded permissions, prefer login groups.
• Safe default of “nobody”. As long as the login list is empty and AllowAllAuthenticated = false, nobody gets in — an admin must open the gate deliberately.

Account linking

On the first successful company login, no second account is created if an account with the same email already exists: the existing OTP user is linked, not duplicated. The anchor is the stable AD identifier objectGUID — a later change of email or username does not break the link.

After that, a linked account is one row. Both tabs keep working — a linked user can also sign in via OTP without creating a second account.

Protection rules: if an email already belongs to a different AD account, the login is refused (no hijack); an anonymized (GDPR-deleted) account is never revived.

Role ownership

Manual role changes are overwritten

From linking onward, AD “owns” the role: on every company login, role, knowledge roles and clearance are re-applied from the AD groups. If you manually change an AD-linked user’s role in the admin UI, it lasts only until the next company login. Manage AD-linked accounts’ roles in AD (via groups), not in the admin UI.

Revoking access = deactivate the account, not just remove the AD group

If you remove a user from all login groups, their company login fails at the gate — but their OTP login still works (email-based) with the last stored role. To fully revoke access, deactivate the local account (or GDPR-anonymize it), not just change the AD group.

Where Company Login runs (topology)

The client never talks to the directory directly: it only posts username/password to its server; the server binds against AD — the same pattern as OTP, where the server sends the code.

• Browser (web mode) and paired desktop (server mode) → company login via the central Web API server. ✅
• Desktop as its own server (peer for other desktops) → serves OTP only, no company login. ❌
• Standalone desktop (single installation) → no directory reachable, no company login tab. ❌

The “Company login” tab appears only when the paired server reports LDAP as enabled and configured. Servers without that report show only the OTP tab.

Troubleshooting

Failure reason	Cause / fix
ServerUnreachable	Host unreachable, TLS handshake failed (CA not trusted), port closed or timeout. Check the CA, the port, and the Security+Port pairing.
InvalidCredentials	Wrong user password or wrong service-account password. Check the service-account bind in isolation with “Test connection”.
UserNotFound	Service-account bind ok, but the search finds no user. Check Base DN/UserSearchBase, LoginAttribute and filter.
”Nobody can sign in”, despite correct bind data	Login list empty and AllowAllAuthenticated = false = the safe default of “nobody”. Create login group(s) or set AllowAllAuthenticated deliberately.

Related

• Company login (first sign-in) — the user’s view
• Set up OTP sign-in
• RBAC & confidentiality levels
• User management