docs(security): AdminUI LDAP failover/bind-mode keys, no-role-no-login, validator scope (#913)

Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
This commit is contained in:
Joseph Doherty
2026-11-17 11:18:18 -05:00
parent 46d9a19bc5
commit 19a445bb61
2 changed files with 45 additions and 4 deletions
+23 -1
View File
@@ -116,7 +116,29 @@ Until #678.6 the overlay never loaded on a node carrying a `cluster-*` role (the
> **Flipping `Security:Acl:Enabled` is a config change, not a redeploy** — both paths are wired in both modes (the node builds its permission trie on every deploy regardless), the same dark-switch discipline as [`MeshTransport`](#meshtransport), [`ConfigSource`](#configsource) and [`Telemetry`](#telemetry). It defaults off because the first deployment carrying the code would otherwise start denying every client that has no key, **including ScadaBridge's Data Connection Layer, which consumes this address space from another repo.** Enforcement fails closed on every unresolvable case, so a wiring or config mistake presents as *everything denied* — check the `OpcUaPublish: data-plane authority generation N installed` line for a non-zero grant count before debugging an individual rule. See [`security.md` § Node ACL enforcement](security.md#node-acl-enforcement-securityaclenabled).
**`Security:Ldap` — see [`security.md`](security.md) for the full field-by-field reference and bind-flow.** The checked-in role overlays set only `DevStubMode` and `Transport`; the remaining `LdapOptions` fields (`Enabled`, `Server`, `Port`, `AllowInsecure`, `SearchBase`, `ServiceAccountDn`, `ServiceAccountPassword`, `GroupAttribute`, `DisplayNameAttribute`, `UserNameAttribute`, `GroupToRole`) are covered there.
**`Security:Ldap` — see [`security.md`](security.md) for the full field-by-field reference and bind-flow.** The checked-in role overlays set only `DevStubMode` and `Transport`; the remaining `LdapOptions` fields (`Enabled`, `Server`, `Port`, `AllowInsecure`, `SearchBase`, `ServiceAccountDn`, `ServiceAccountPassword`, `GroupAttribute`, `DisplayNameAttribute`, `UserNameAttribute`, `GroupToRole`, `ConnectionTimeoutMs`, `FallbackServers`, `BindMode`, `UserBindTemplate`, `AcceptDomainQualifiedNames`) are covered there.
<a id="securityldap"></a>
**AD with two domain controllers (lmxopcua#913).** `FallbackServers`, `BindMode`, `UserBindTemplate` and `AcceptDomainQualifiedNames` are passed through to the shared `ZB.MOM.WW.Auth.Ldap` client (before #913 they were silently dropped, so there was no DC failover). A NAM-shaped service-env block (values are illustrative — the real hosts, DN and groups come from the cutover plan):
```text
Security__Ldap__Enabled=true
Security__Ldap__Server=dc1.nam.example.com
Security__Ldap__Port=389
Security__Ldap__Transport=None
Security__Ldap__AllowInsecure=true
Security__Ldap__FallbackServers__0=dc2.nam.example.com
Security__Ldap__SearchBase=DC=nam,DC=example,DC=com
Security__Ldap__ServiceAccountDn=<service account DN or UPN>
Security__Ldap__ServiceAccountPassword=${secret:...}
Security__Ldap__UserNameAttribute=sAMAccountName
Security__Ldap__DisplayNameAttribute=displayName
Security__Ldap__GroupToRole__<AD group>=Viewer
```
- **Type the bare `sAMAccountName`** at the AdminUI login. In the default `BindMode=ServiceAccount`, `AcceptDomainQualifiedNames` has no effect, so `NAM\jdoe` or `jdoe@nam…` does not match the search.
- **No role, no login:** a user whose groups map to no role (through `GroupToRole` or a system-wide DB grant) is refused at `/auth/login` (401 / "not authorized") and gets no `/auth/token`; a role-mapper fault refuses too. See [`security.md`](security.md#ldap-bind-flow-otopcualdapauthservice).
- Startup validation checks each `FallbackServers` entry and, in `BindMode=User`, that `UserBindTemplate` contains `{0}` exactly once. `ServiceAccountDn` is **not** required at startup.
**`Security:Jwt`** key fields (`JwtOptions`):
+22 -3
View File
@@ -418,10 +418,18 @@ LDAP is configured under the `Security:Ldap` section (bound to `LdapOptions`, `s
1. If `Enabled = false`, denies outright — no bind, no DevStub bypass (the master switch wins).
2. If `DevStubMode = true`, accepts any non-empty credentials and grants the `Administrator` role **without any network bind** (dev only — must be `false` in production).
3. Refuses to bind over a plaintext transport (`Transport = None`) unless `AllowInsecure = true` (dev/test only). This is enforced at login, not at startup.
4. Delegates the real path to the shared `ZB.MOM.WW.Auth.Ldap` client: it binds (search-then-bind via `ServiceAccountDn`, or direct-bind `cn={user},{SearchBase}` when no service account is set), verifies the password, and reads the user's group memberships.
4. Delegates the real path to the shared `ZB.MOM.WW.Auth.Ldap` client (built with its own `ILogger<LdapAuthService>` from DI, so its per-endpoint failover Warnings, `LDAP sticky preference moved to …` line and stage diagnostics appear in the OtOpcUa log — lmxopcua#913). In `BindMode = ServiceAccount` (default) it binds as `ServiceAccountDn`, searches `SearchBase` for the user by `UserNameAttribute`, then re-binds as the user's DN; there is **no direct-bind fallback** — an empty `ServiceAccountDn` is an anonymous bind (works against GLAuth, not against AD). In `BindMode = User` it binds as `UserBindTemplate` with the login name substituted and reads the user's own entry; no service account is used. On a system-side failure (connect/TLS, service-account bind, search) it tries each `FallbackServers` entry in order; the endpoint that answers becomes the sticky preference.
5. Returns an `LdapAuthResult` carrying the validated username + the **groups** (never roles). Failure codes are folded into opaque user-facing error strings so a probe cannot distinguish "unknown user" from "wrong password".
**Group → role mapping happens downstream**, not in the auth service: the `/auth/login` handler (`AuthEndpoints`) resolves `IGroupRoleMapper<string>` (`OtOpcUaGroupRoleMapper`) per login — it applies the appsettings `GroupToRole` baseline, merges system-wide DB grants from the user's LDAP groups, and unions any pre-resolved roles (the DevStub grant) — and the resulting roles land in the Admin UI cookie principal. A mapper fault (e.g. a Config DB outage) falls back to the pre-resolved baseline rather than denying an otherwise-authenticated login. **Since #520 nothing on the OPC UA data plane consumes LDAP groups** — data-plane session roles come from the authenticated principal's `NodeAcl` grants (see [Role grant source](#role-grant-source-data-plane)).
**Group → role mapping happens downstream**, not in the auth service: the `/auth/login` handler (`AuthEndpoints`) resolves `IGroupRoleMapper<string>` (`OtOpcUaGroupRoleMapper`) per login — it applies the appsettings `GroupToRole` baseline, merges system-wide DB grants from the user's LDAP groups, and unions any pre-resolved roles (the DevStub grant) — and the resulting roles land in the Admin UI cookie principal.
**No role, no login (lmxopcua#913; family standard).** The fallback policy and `AdminUiPolicies.AuthenticatedRead` only require an authenticated user, so a role-less cookie would give AdminUI read access to any directory user once `SearchBase` is a whole AD domain. So:
- if the mapped role set is **empty**, `/auth/login` refuses exactly like bad credentials — JSON callers get **401**, the form gets a redirect to `/login` with a generic "Invalid username or password, or the account is not authorized." — and **no cookie** is issued; the refusal is logged at Warning with the user's groups;
- if the **mapper throws** (e.g. a Config DB outage), the login is refused (fail closed) — JSON **503**, form redirect with "Sign-in is temporarily unavailable." — and the exception is logged. (Before #913 it signed the user in with zero roles.)
- `/auth/token` refuses (**401**, no token) a cookie session that carries no role claim.
`DevStubMode` is unaffected: it pre-resolves `Administrator`. In OtOpcUa `Viewer` is not checked by any policy, so mapping a group to `Viewer` means "may sign in and read". **Since #520 nothing on the OPC UA data plane consumes LDAP groups** — data-plane session roles come from the authenticated principal's `NodeAcl` grants (see [Role grant source](#role-grant-source-data-plane)).
`Transport` replaces the former `UseTls` bool: `Ldaps` (implicit TLS), `StartTls` (upgrade), or `None` (plaintext, requires `AllowInsecure`). Configuration example (Active Directory production):
@@ -451,7 +459,18 @@ LDAP is configured under the `Security:Ldap` section (bound to `LdapOptions`, `s
}
```
`GroupToRole` maps LDAP group names → roles (case-insensitive); a user gets every role whose source group is in their membership. The values are the canonical control-plane role strings (`Viewer` / `Designer` / `Administrator`, plus the appsettings-only `Operator` for the `DriverOperator` policy); the same map also supplies data-plane role strings (`ReadOnly`, `WriteOperate`, `WriteTune`, `WriteConfigure`, `AlarmAck`) — see [Role grant source (data-plane)](#role-grant-source-data-plane) below. `UserNameAttribute: "sAMAccountName"` is the critical AD override — the GLAuth dev default is `cn`, which is not how AD users are looked up; use `userPrincipalName` instead if operators log in with `user@corp.example.com` form. `LdapOptionsValidator` (`src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LdapOptionsValidator.cs`) fails startup when `Transport = None` and `AllowInsecure = false` on a real-LDAP (non-DevStub) config.
`GroupToRole` maps LDAP group names → roles (case-insensitive); a user gets every role whose source group is in their membership. The values are the canonical control-plane role strings (`Viewer` / `Designer` / `Administrator`, plus the appsettings-only `Operator` for the `DriverOperator` policy); the same map also supplies data-plane role strings (`ReadOnly`, `WriteOperate`, `WriteTune`, `WriteConfigure`, `AlarmAck`) — see [Role grant source (data-plane)](#role-grant-source-data-plane) below. `UserNameAttribute: "sAMAccountName"` is the critical AD override — the GLAuth dev default is `cn`, which is not how AD users are looked up; use `userPrincipalName` instead if operators log in with `user@corp.example.com` form. `LdapOptionsValidator` (`src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LdapOptionsValidator.cs`) runs on every node and, on a real-LDAP (enabled, non-DevStub) config, fails startup when `Transport = None` and `AllowInsecure = false`, when any `FallbackServers` entry is not `host` / `host:port` (port 1–65535, no IPv6 literals), or when `BindMode = User` and `UserBindTemplate` does not contain `{0}` exactly once. It deliberately does **not** require `ServiceAccountDn` (the shared library's own validator does, and is not run by OtOpcUa): DEV boots on the code defaults with an empty DN.
#### Failover and bind mode keys (lmxopcua#913)
| Key | Default | Meaning |
|---|---|---|
| `FallbackServers` | `[]` | Ordered backup endpoints (`"host"` adopts `Port`, or `"host:port"`), tried on a system-side failure; preference is sticky. Env: `Security__Ldap__FallbackServers__0`, `__1`, … |
| `BindMode` | `ServiceAccount` | `ServiceAccount` (search-then-bind) or `User` (bind as the user, no service account). |
| `UserBindTemplate` | `""` | `User` mode only: bind identity with `{0}` exactly once; prefer the down-level `DOMAIN\{0}`. |
| `AcceptDomainQualifiedNames` | `true` | `User` mode only: reduce `DOMAIN\name` / `name@suffix` to `name`. In `ServiceAccount` mode it has no effect — users type the bare `sAMAccountName`. |
Every settable property of the library's `LdapOptions` is either projected by `LdapOptions.ToLibraryOptions()` or allow-listed (`ServerCertificateValidationCallback`, code-only); `LdapOptionsProjectionCompletenessTests` fails on a library property that is neither. NAM AD two-DC example: see [`Configuration.md`](Configuration.md#securityldap).
### API-key identity (OPC UA data plane)