ActiveDirectory connection standard #741

Open
opened 2026-09-25 09:02:40 +00:00 by hyrsh · 5 comments
Collaborator

Since our target audience mostly uses Active Directory of Microsoft (local or EntraID), we need to implement a standard for this kind of AD authentication.

The general idea is as follows:

  • the application is provided dedicated user that is allowed to query the AD (e.g. "af_ad_query_user")
  • the application must be able to use the user "af_ad_query_user" to determine if an incoming login request is valid
  • the validity of a login request is based on a AD group membership of the requesting user

Pseudo flow:

  1. set AD group to e.g. "alpinefiles_users"
  2. user login request --> af_ad_query_user looks up the user and checks "alpinefiles_users" membership --> if OK --> login allowed
  3. user login request --> af_ad_query_user looks up the user and checks "alpinefiles_users" membership --> if NOT OK --> access denied

There must be a possibility to set the "Base DN" and "Group DN" to narrow down the lookup location and permissions needed by the "af_ad_query_user".

e.g. "Base DN" --> "dc=company,dc=ch"
e.g. "Group DN" --> "ou=groups,dc=company,dc=ch"

The AD group "alpinefile_users" exists in the OU "groups" and the user "af_ad_query_user" has permissions to list groups in this OU.

Most customers (90%+) that use Active Directory do not enable specific users to be allowed to login but use groups instead (which is considered best practice) since the configuration of valid users then shifts to AD control where an admin can add/remove users to/from the given group and there is no further configuration needed in the target application.

AlpineFiles must therefore provide the following input fields to establish an LDAP/AD connection:

  • AD Query user (this user handles all AD queries)
  • AlpineFiles AD group (members of this group are allowed to login)
  • Base DN (standard AD path)
  • Group DN (group AD path)
Since our target audience mostly uses Active Directory of Microsoft (local or EntraID), we need to implement a standard for this kind of AD authentication. The general idea is as follows: - the application is provided dedicated user that is allowed to query the AD (e.g. "af_ad_query_user") - the application must be able to use the user "af_ad_query_user" to determine if an incoming login request is valid - the validity of a login request is based on a AD group membership of the requesting user Pseudo flow: 1. set AD group to e.g. "alpinefiles_users" 2. user login request --> af_ad_query_user looks up the user and checks "alpinefiles_users" membership --> if OK --> login allowed 3. user login request --> af_ad_query_user looks up the user and checks "alpinefiles_users" membership --> if NOT OK --> access denied There must be a possibility to set the "Base DN" and "Group DN" to narrow down the lookup location and permissions needed by the "af_ad_query_user". e.g. "Base DN" --> `"dc=company,dc=ch"` e.g. "Group DN" --> `"ou=groups,dc=company,dc=ch"` The AD group "alpinefile_users" exists in the OU "groups" and the user "af_ad_query_user" has permissions to list groups in this OU. Most customers (90%+) that use Active Directory do not enable specific users to be allowed to login but use groups instead (which is considered best practice) since the configuration of valid users then shifts to AD control where an admin can add/remove users to/from the given group and there is no further configuration needed in the target application. AlpineFiles must therefore provide the following input fields to establish an LDAP/AD connection: - AD Query user (this user handles all AD queries) - AlpineFiles AD group (members of this group are allowed to login) - Base DN (standard AD path) - Group DN (group AD path)
Owner

Deep research (2026-10-24)

Full write-up: ~/cairn-work/scratch/b7e/backlog/research-741.md.

Verdict: Manuel's design (a query service account, an allowed group, a base DN and a group DN) is what Gitea, GitLab, Nextcloud, Seafile, Mattermost and Grafana all do. Today Cairn can only express it as a raw filter: ldapUserFilter with memberOf:1.2.840.113556.1.4.1941:=<groupDN>, which also matches nested groups.

Bugs found in the code:

  1. Group removal does not end access. The periodic re-check looks the user up without ldapUserFilter (ldap.go:285-288). Someone removed from the allowed group keeps their sessions (up to 12 h) and their app passwords. GitLab re-checks this every hour.
  2. StartTLS with certificate checking can never work. No server name is set (ldap.go:400), so Go refuses with tls: either ServerName or InsecureSkipVerify must be specified. LDAPS works.
  3. Only the first %s in the filter is replaced (ldap.go:446). A sAMAccountName OR userPrincipalName filter never matches a UPN login.
  4. Group names are reduced to their CN, from any OU. A group named cairn-admins created in any OU grants Cairn admin. This is a privilege-escalation path wherever OU admins can create groups.

Smaller gaps:

  • accountExpires is not honoured for existing sessions.
  • AD bind sub-codes (532 password expired, 533 disabled, 775 locked) all show as "wrong password".
  • Plain ldap:// is accepted with no warning, although Windows Server 2025 refuses unencrypted simple binds by default.
  • There is no CA option, and only one DC can be configured.
  • The handbook's AD example does not work as written: it has no bind DN, and the default filter is (uid=%s).

Entra ID: OIDC is the right path; LDAP only exists through the paid Domain Services. The gate is "Assignment required" on the app, and app roles (oidcGroupsClaim: "roles") avoid the 200-group overage. Kerberos SSO is best left to an IdP in front.

Decisions are being asked now.

## Deep research (2026-10-24) Full write-up: `~/cairn-work/scratch/b7e/backlog/research-741.md`. **Verdict:** Manuel's design (a query service account, an allowed group, a base DN and a group DN) is what Gitea, GitLab, Nextcloud, Seafile, Mattermost and Grafana all do. Today Cairn can only express it as a raw filter: `ldapUserFilter` with `memberOf:1.2.840.113556.1.4.1941:=<groupDN>`, which also matches nested groups. **Bugs found in the code:** 1. **Group removal does not end access.** The periodic re-check looks the user up without `ldapUserFilter` (`ldap.go:285-288`). Someone removed from the allowed group keeps their sessions (up to 12 h) and their app passwords. GitLab re-checks this every hour. 2. **StartTLS with certificate checking can never work.** No server name is set (`ldap.go:400`), so Go refuses with `tls: either ServerName or InsecureSkipVerify must be specified`. LDAPS works. 3. **Only the first `%s` in the filter is replaced** (`ldap.go:446`). A `sAMAccountName` OR `userPrincipalName` filter never matches a UPN login. 4. **Group names are reduced to their CN, from any OU.** A group named `cairn-admins` created in any OU grants Cairn admin. This is a privilege-escalation path wherever OU admins can create groups. **Smaller gaps:** - `accountExpires` is not honoured for existing sessions. - AD bind sub-codes (532 password expired, 533 disabled, 775 locked) all show as "wrong password". - Plain `ldap://` is accepted with no warning, although Windows Server 2025 refuses unencrypted simple binds by default. - There is no CA option, and only one DC can be configured. - The handbook's AD example does not work as written: it has no bind DN, and the default filter is `(uid=%s)`. **Entra ID:** OIDC is the right path; LDAP only exists through the paid Domain Services. The gate is "Assignment required" on the app, and app roles (`oidcGroupsClaim: "roles"`) avoid the 200-group overage. Kerberos SSO is best left to an IdP in front. Decisions are being asked now.
Owner

Decision (Nikola, 2026-10-24): dedicated keys. Every recommendation is accepted.

New settings:

  • ldapDirectoryType (ad preset).
  • ldapAllowedGroups, a list of group names or DNs.
  • ldapGroupBaseDn.
  • ldapNestedGroups, on by default for AD.
  • ldapLoginAttrs, for example sAMAccountName and userPrincipalName.
  • ldapUrl takes several DC URLs (failover).
  • oidcAllowedGroups for Entra ID and other OIDC providers.

The raw ldapUserFilter stays as the expert override. A private CA comes from the global trust directory (#740), not from a separate ldapCaFile.

Behaviour:

  • Someone removed from the allowed group is treated like a disabled account: their sessions and app passwords end at the next re-check. This applies the same rules as for disabled accounts.
  • Group names count only for groups under ldapGroupBaseDn. Without it, Cairn warns at start.
  • Plain ldap:// is refused unless ldapAllowPlain is set.
  • accountExpires is honoured.
  • AD bind sub-codes are logged precisely.

Bugs fixed:

  • the re-check skipped the filter;
  • StartTLS had no server name;
  • only the first %s was replaced;
  • groups were taken from any OU.

Not now:

  • No Kerberos in Cairn; an IdP in front handles it.
  • The Graph re-check for Entra comes later.
  • The UI pieces (LDAP facts in Users & access, the "not allowed" and "password expired" login messages) follow in a mockup round.

This is built in batch 5 (v0.6.352).

**Decision (Nikola, 2026-10-24): dedicated keys. Every recommendation is accepted.** **New settings:** - `ldapDirectoryType` (`ad` preset). - `ldapAllowedGroups`, a list of group names or DNs. - `ldapGroupBaseDn`. - `ldapNestedGroups`, on by default for AD. - `ldapLoginAttrs`, for example `sAMAccountName` and `userPrincipalName`. - `ldapUrl` takes several DC URLs (failover). - `oidcAllowedGroups` for Entra ID and other OIDC providers. The raw `ldapUserFilter` stays as the expert override. A private CA comes from the global trust directory (#740), not from a separate `ldapCaFile`. **Behaviour:** - Someone removed from the allowed group is treated like a disabled account: their sessions and app passwords end at the next re-check. This applies the same rules as for disabled accounts. - Group names count only for groups under `ldapGroupBaseDn`. Without it, Cairn warns at start. - Plain `ldap://` is refused unless `ldapAllowPlain` is set. - `accountExpires` is honoured. - AD bind sub-codes are logged precisely. **Bugs fixed:** - the re-check skipped the filter; - StartTLS had no server name; - only the first `%s` was replaced; - groups were taken from any OU. **Not now:** - No Kerberos in Cairn; an IdP in front handles it. - The Graph re-check for Entra comes later. - The UI pieces (LDAP facts in Users & access, the "not allowed" and "password expired" login messages) follow in a mockup round. This is built in batch 5 (v0.6.352).
Owner

Shipped in v0.6.352 (PR #986). Kept open: a check against a real Active Directory is still to do.

Built:

  • New keys: ldapDirectoryType, ldapAllowedGroups, ldapGroupBaseDn, ldapNestedGroups, ldapLoginAttrs, several ldapUrl DCs, ldapAllowPlain and oidcAllowedGroups.
  • Removal from an allowed group is treated as disabled at the next re-check: sessions end, app passwords are paused, and the mass-miss guard applies.
  • Bugs fixed:
    • the re-check now applies the filter;
    • StartTLS uses the server name;
    • every %s is replaced;
    • groups only count from the group base;
    • group lookups run only after the password bind.
  • Tests: against the in-repo LDAP harness, plus the reviewers' probes.

Live: OIDC sign-in works on both dogfoods. Neither dogfood uses LDAP or oidcAllowedGroups, so the AD path has not been seen live.

Proposed check with Manuel's AD (from docs/handbook/directory-ldap-ad.md):

  1. The four-field config (ldapDirectoryType: "ad", the service account, ldapBaseDn, ldapGroupBaseDn, ldapAllowedGroups) over LDAPS.
  2. Sign in as a member and as a non-member.
  3. Remove a member from the group: the session and app passwords stop at the next re-check.
  4. A nested group.
  5. Login with the UPN.
  6. Confirm the bind sub-codes 532 and 773 for #985.

Docs: directory-ldap-ad.md and directory-entra-id.md.

**Shipped in v0.6.352 (PR #986). Kept open: a check against a real Active Directory is still to do.** **Built:** - **New keys:** `ldapDirectoryType`, `ldapAllowedGroups`, `ldapGroupBaseDn`, `ldapNestedGroups`, `ldapLoginAttrs`, several `ldapUrl` DCs, `ldapAllowPlain` and `oidcAllowedGroups`. - **Removal from an allowed group** is treated as disabled at the next re-check: sessions end, app passwords are paused, and the mass-miss guard applies. - **Bugs fixed:** - the re-check now applies the filter; - StartTLS uses the server name; - every `%s` is replaced; - groups only count from the group base; - group lookups run only after the password bind. - **Tests:** against the in-repo LDAP harness, plus the reviewers' probes. **Live:** OIDC sign-in works on both dogfoods. Neither dogfood uses LDAP or `oidcAllowedGroups`, so the AD path has not been seen live. **Proposed check with Manuel's AD** (from `docs/handbook/directory-ldap-ad.md`): 1. The four-field config (`ldapDirectoryType: "ad"`, the service account, `ldapBaseDn`, `ldapGroupBaseDn`, `ldapAllowedGroups`) over LDAPS. 2. Sign in as a member and as a non-member. 3. Remove a member from the group: the session and app passwords stop at the next re-check. 4. A nested group. 5. Login with the UPN. 6. Confirm the bind sub-codes 532 and 773 for #985. Docs: `directory-ldap-ad.md` and `directory-entra-id.md`.
Owner

#985 research follow-up for the real-AD test with Manuel (research-985-1 §3 has the full script, about 15 minutes plus one day if 532 needs a real expiry):

  • 9 prepared accounts (normal, disabled, expired account, password expired, must change at next logon, logon hours, workstation restriction, locked, Protected Users), one PSO.
  • For each: ldapwhoami simple bind with the right and with a wrong password; record the data sub-code; read badPwdCount/lockoutTime on the same DC and on the PDC emulator.
  • Goal: confirm that 530/531/532/533/701/773 only come after a correct password on Windows Server (Samba's source already confirms it for Samba; 775 and 52f come before the password on both).
  • Also measure timing: 50 sign-ins each, unknown name vs wrong password vs correct-but-not-allowed (#991).

Corrections to earlier statements: "logon type not granted" is 0x569, not 534; Windows Server 2025 requires signing only on new deployments; the Global Catalog lacks domain local and global group memberships (#995). New related issues: #990 (Samba nested-group bug), #992 (AD lockout through Cairn).

#985 research follow-up for the real-AD test with Manuel (research-985-1 §3 has the full script, about 15 minutes plus one day if 532 needs a real expiry): - 9 prepared accounts (normal, disabled, expired account, password expired, must change at next logon, logon hours, workstation restriction, locked, Protected Users), one PSO. - For each: `ldapwhoami` simple bind with the right and with a wrong password; record the `data` sub-code; read `badPwdCount`/`lockoutTime` on the same DC and on the PDC emulator. - Goal: confirm that 530/531/532/533/701/773 only come after a correct password on Windows Server (Samba's source already confirms it for Samba; 775 and 52f come before the password on both). - Also measure timing: 50 sign-ins each, unknown name vs wrong password vs correct-but-not-allowed (#991). Corrections to earlier statements: "logon type not granted" is `0x569`, not 534; Windows Server 2025 requires signing only on new deployments; the Global Catalog lacks domain local **and** global group memberships (#995). New related issues: #990 (Samba nested-group bug), #992 (AD lockout through Cairn).
Owner

All open live tests for the real AD are now gathered in #1005, section A. That covers the sub-codes, the lock attribute (new in v0.6.354), timing (#991), the lockout cache (#992), the four-field config, LDAPS/StartTLS failure classes and Samba 15515. This issue stays open until section A is done.

All open live tests for the real AD are now gathered in #1005, section A. That covers the sub-codes, the lock attribute (new in v0.6.354), timing (#991), the lockout cache (#992), the four-field config, LDAPS/StartTLS failure classes and Samba 15515. This issue stays open until section A is done.
Sign in to join this conversation.
No labels
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#741
No description provided.