From b8cecf309dc5c3f50fe314e53b221b4be4dda971 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Sun, 15 Nov 2026 20:44:09 -0500 Subject: [PATCH] docs(ldap): apply the 2026-11-15 independent review to the NAM cutover plan Blockers: no-role-no-login family standard (OtOpcUa Phase A refuses empty and mapper-throws logins, reversing Login_when_role_mapper_throws_signs_in_with_no_role_claims; new ScadaBridge Phase A2); OtOpcUa validates only the FallbackServers + BindMode/UserBindTemplate rules (the library validator would block boot on DEV's empty ServiceAccountDn). Majors: inject the library logger; shared-account lockout model, no-lockout ask, value verification, canary, stop rule; DEV automation identity; rolling standby-first restarts for config-only; HG case-sensitive GroupToRole (optional Phase A3); mxgw config-bound cert pin. Minors and nits applied; review disposition table in section 11. Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8 --- docs/plans/2026-11-15-nam-ldap-cutover.md | 911 +++++++++++++--------- ldap_mapping.md | 24 +- 2 files changed, 561 insertions(+), 374 deletions(-) diff --git a/docs/plans/2026-11-15-nam-ldap-cutover.md b/docs/plans/2026-11-15-nam-ldap-cutover.md index cea458f..f247165 100644 --- a/docs/plans/2026-11-15-nam-ldap-cutover.md +++ b/docs/plans/2026-11-15-nam-ldap-cutover.md @@ -1,262 +1,354 @@ # NAM AD LDAP cutover — DEV vd03, then QA vq03/vq04 (plan, NOT executed) > **Status lives in Gitea.** Execution is tracked by -> [scadaproj#6](https://gitea.dohertylan.com/dohertj2/scadaproj/issues/6). The dedicated shared LDAP-lookup service account is -> [scadaproj#58](https://gitea.dohertylan.com/dohertj2/scadaproj/issues/58), a QA prerequisite (§5, D1). This file is the design and -> runbook. It **supersedes** [`2026-08-13-vd03-nam-ldap-cutover.md`](2026-08-13-vd03-nam-ldap-cutover.md) -> (§10 lists what changed and why). +> [scadaproj#6](https://gitea.dohertylan.com/dohertj2/scadaproj/issues/6). The dedicated, shared LDAP-lookup service +> account is [scadaproj#58](https://gitea.dohertylan.com/dohertj2/scadaproj/issues/58), a QA prerequisite (§5, D1). This +> file is the design and runbook. It **supersedes** [`2026-08-13-vd03-nam-ldap-cutover.md`](2026-08-13-vd03-nam-ldap-cutover.md) +> (§10 lists what changed). The independent review of 2026-11-15 is applied (§11). **Written 2026-11-15. Status: PLAN ONLY. Nothing here has been executed.** -**Goal:** move the login of the four auth-bearing apps off their current setup (disabled login, or a -GLAuth test directory) and onto the Zimmer NAM Active Directory. That means DEV first, a soak, then the -QA pair. -- The service-account password lives as a `${secret:}` reference in each app's encrypted Secrets - store, never in config. -- Every app maps AD groups to its roles from one canonical matrix, - [`ldap_mapping.md`](../../ldap_mapping.md), under one rule: **one AD group grants exactly one role per - app** (§3). +**Goal:** move the login of the four auth-bearing apps off their current setup (disabled login, or a GLAuth +test directory) and onto the Zimmer NAM Active Directory: DEV first, a soak, then the QA pair. +- The service-account password lives as a `${secret:}` reference in each app's encrypted Secrets store, never + in config. +- Every app maps AD groups to its roles from one canonical matrix, [`ldap_mapping.md`](../../ldap_mapping.md), + under two family rules (§3): + - **one AD group grants exactly one role per app;** + - **a user whose groups map to no role cannot sign in** (cookie or token). -**In scope:** HistorianGateway (dashboard), MxAccessGateway (dashboard), ScadaBridge (Central UI + CLI) -and OtOpcUa (AdminUI). +**In scope:** HistorianGateway (dashboard), MxAccessGateway (dashboard), ScadaBridge (Central UI + CLI), +OtOpcUa (AdminUI). **Out of scope:** - **Overview:** no login by design. -- **The apps' machine-to-machine surfaces stay API-key based and untouched:** OtOpcUa's OPC UA data plane, - the mxgw and HG gRPC APIs, and ScadaBridge's inbound API. -- **ignitionoee:** on hold, because its role vocabulary has no `UG_WW_*` groups. See `ldap_mapping.md` §6. +- **The machine-to-machine surfaces stay API-key based:** OtOpcUa's OPC UA data plane, the mxgw and HG gRPC + APIs, and ScadaBridge's inbound API. They can still be *disrupted* by the restarts here (§7.0). +- **ignitionoee:** on hold (`ldap_mapping.md` §6). -Grounded in: [`ldap_setup.md`](../../ldap_setup.md) (directory facts, TLS probes, the 2026-08-13 live -login), [`ldap_mapping.md`](../../ldap_mapping.md) (the matrix), and the 2026-11-15 readiness review -(source at each deployed SHA, live config pulled over SMB). - -**Evidence key:** **[V]** = verified in source or a file, with the citation; **[I]** = inferred, to be -confirmed in Phase 0. +**Evidence key:** **[V]** = verified in source or a file, with the citation; **[I]** = inferred, to be confirmed +in Phase 0. Source paths are relative to each repo. --- ## 1. Current state (2026-11-15) -### 1.1 Builds and the Auth library: the prerequisite is met +### 1.1 Builds and the Auth library -The 2026-08-13 plan's Phase 1, "redeploy everything to Auth 0.2.1", is **obsolete**. Every deployed build -already carries a newer Auth library: +The 2026-08-13 plan's "redeploy to Auth 0.2.1" phase is **obsolete**: -| App | Deployed on DEV and QA | Auth pin [V] | Since | -|---|---|---|---| -| OtOpcUa | `76e73e7d` (master tip is `6dd2985b8`) | `ZB.MOM.WW.Auth.*` **0.4.1** (`Directory.Packages.props:238-240`) | deployed 2026-11-13 | -| ScadaBridge | `061432c8` | **0.5.0** (ScadaBridge#46) | deployed 2026-11-15 | -| MxAccessGateway | `76a71bc8` | **0.4.1** | deployed 2026-11-12 | -| HistorianGateway | `6365f34` | **0.4.1** | deployed 2026-11-13 | +| App | Deployed on DEV and QA | Auth pin [V] | +|---|---|---| +| OtOpcUa | `76e73e7d` | **0.4.1** (`Directory.Packages.props:238-240`) | +| ScadaBridge | `061432c8` | **0.5.0** (ScadaBridge#46) | +| MxAccessGateway | `76a71bc8` | **0.4.1** | +| HistorianGateway | `6365f34` | **0.4.1** | -- **Domain-root `SearchBase`** needs ≥ 0.2.1. Met. -- **`FallbackServers`** needs ≥ 0.2.0. It is met in the library, but **OtOpcUa drops it** (§2). -- **`BindMode`, the empty-password guard and a canonical `Username`** need ≥ 0.4.1. Met. +Domain-root `SearchBase` (≥ 0.2.1), `FallbackServers` (≥ 0.2.0 in the library, but **dropped by OtOpcUa**, +§2) and `BindMode` with the empty-password guard (≥ 0.4.1) are all available. + +**Before the cutover:** +- **OtOpcUa (§2)** and **ScadaBridge (§2A)** need code changes and a deploy. +- **HistorianGateway (§2B)** gets an optional hardening change. ### 1.2 Login state per app and tier | App | DEV vd03 | QA vq03/vq04 | |---|---|---| -| **HistorianGateway** | **Login OFF**: `Dashboard:DisableLogin=true` in `appsettings.Production.json`. LDAP points at the shared GLAuth `10.100.0.35:3893`, plain [V, file]. | **Login ON** against the box-local GLAuth. Config is in the **NSSM env** (`Ldap__*`; GroupToRole `SCADA-Admins`/`SCADA-Designers`) [I: inferred from env lengths]. A KEK is present at `C:\ProgramData\ZB\kek\historiangw.kek` [V, 11-13 evidence]. | -| **MxAccessGateway** | **Login OFF**: `MxGateway:Dashboard:DisableLogin=true` [V, file]. LDAP points at `127.0.0.1:3893`, `dc=scadalink,dc=local`. The 08-13 plan said login was on; it is not. | **Login ON**: `localhost:3893`, `dc=zb,dc=local`, password `${secret:ldap/mxgateway/bind}` [V, file], so the Secrets plumbing works. ⚠ `deployment.md` says the box-local GLAuth is `dc=scadabridge,dc=local`, so QA mxgw login may already be broken [I]. Phase 0 checks this. | -| **ScadaBridge** | **Login OFF**: the two-key set `ScadaBridge:Security:Auth:DisableLogin=true` + `AllowOutsideDevelopment=true`. LDAP points at `localhost:3893` [V, file]. | **Login ON** against the box-local GLAuth `127.0.0.1:3893` [V, files]. **Every CLI call and deploy script logs in as the GLAuth `multi-role` user** (`apply.sh`, today's #116 drills, #143). | -| **OtOpcUa** (AdminUI) | `Security:Ldap` comes from code defaults plus files holding only `Transport=Ldaps` and `DevStubMode=false`. The DEV env has no `Security__Ldap__*` [V, 11-13 record], so it runs on the code defaults `localhost:3893`, `dc=zb,dc=local`. `Security__Auth__DisableLogin` is in the env, **value unknown**. | Unknown: the env can't be read without remote execution. Phase 0 reads it. | +| **HistorianGateway** | **Login OFF**: `Dashboard:DisableLogin=true` in `appsettings.Production.json`. LDAP points at the shared GLAuth `10.100.0.35:3893`, plain [V, file]. | **Login ON** against the box-local GLAuth. Config is in the **NSSM env** (`Ldap__*`, GroupToRole `SCADA-Admins`/`SCADA-Designers`) [I]. KEK at `C:\ProgramData\ZB\kek\historiangw.kek` [V, 11-13 evidence]. | +| **MxAccessGateway** | **Login OFF**: `MxGateway:Dashboard:DisableLogin=true` [V, file]. LDAP `127.0.0.1:3893`, `dc=scadalink,dc=local`. The deployed build **refuses** `DisableLogin=true` under `Production` (`GatewayOptionsValidator.cs:484-488`), so vd03 mxgw is **not** running as Production [V by inference from it booting]; Phase 0 records the environment name. | **Login ON**: `localhost:3893`, `dc=zb,dc=local`, `${secret:ldap/mxgateway/bind}` [V, file]. ⚠ `deployment.md` says the box-local GLAuth is `dc=scadabridge,dc=local` [I]. | +| **ScadaBridge** | **Login OFF**: `ScadaBridge:Security:Auth:DisableLogin=true` + `AllowOutsideDevelopment=true` [V, file]. With login off, the management/CLI path authenticates every caller as the all-roles dev user (`ManagementService/ManagementAuthenticator.cs:63-71`: `"multi-role"`, `Roles.All`) [V]. LDAP `localhost:3893`. | **Login ON**, box-local GLAuth `127.0.0.1:3893` [V]. Every CLI, deploy and drill script logs in as GLAuth `multi-role`. | +| **OtOpcUa** (AdminUI) | Code defaults (`Enabled=true`, `Server=localhost`, `Port=3893`, `SearchBase=dc=zb,dc=local`, `ServiceAccountDn=""`), plus files holding `Transport=Ldaps` and `DevStubMode=false`; no `Security__Ldap__*` in the env [V, 11-13 record]. `Security__Auth__DisableLogin` is in the env, **value unknown**. | Unknown; Phase 0 reads it. | -### 1.3 Directory facts (carried forward, still valid) +### 1.3 Directory facts -These come from `ldap_setup.md`: -- **Domain controllers:** `uswap-vdc-nam1.nam.zimmer.com` (`10.201.216.2`) and `uswap-vdc-nam2.nam.zimmer.com` - (`10.201.138.78`). -- **Transports:** LDAPS 636, StartTLS 389 and plain 389 all work on both. -- **TLS:** the DC certs are RSA-1024, chain `leaf ← zimmer-issueca1 ← zimmer-rootca`. - - The only error seen is `UntrustedRoot`, so **installing `zimmer-rootca` is sufficient**. - - Windows accepts the 1024-bit key. -- **Directory shape:** `SearchBase` `DC=nam,DC=zimmer,DC=com` (the domain root); login attribute - `sAMAccountName`; `memberOf` collapses to bare CNs. -- **Lockout:** 5 failed attempts per 15 min. A failed app login is a failed bind on **both** DCs, - because the library walks both endpoints. -- **Reachability:** 2026-11-15, from the Mac, nam1/nam2 on 389 and 636 are open. **Not proven from the - boxes.** +**Still valid, from `ldap_setup.md`:** +- **DCs:** `uswap-vdc-nam1.nam.zimmer.com` (`10.201.216.2`) and `uswap-vdc-nam2.nam.zimmer.com` (`10.201.138.78`). +- **Transports:** LDAPS 636, StartTLS and plain 389 all work. +- **TLS:** the certs are RSA-1024, chain `leaf ← zimmer-issueca1 ← zimmer-rootca`. The only chain error is + `UntrustedRoot`, so installing the root is sufficient. Windows accepts the 1024-bit key. +- **Directory shape:** `SearchBase` `DC=nam,DC=zimmer,DC=com`; login attribute `sAMAccountName`; `memberOf` + collapses to bare CNs. +- **Reachability:** from the Mac, nam1/nam2 on 389 and 636 are open (2026-11-15). Not proven from the boxes. + +**Login names.** In `BindMode=ServiceAccount` (this plan), `AcceptDomainQualifiedNames` has **no effect**: it +applies only in User mode (`ZB.MOM.WW.Auth.Ldap/LdapAuthService.cs:156-161`) [V]. So `NAM\jdoe` and +`jdoe@nam.zimmer.com` return *user not found*. **Users must type their bare sAMAccountName.** Put that on the +login-page notice. + +**Lockout (AD policy: 5 failed binds per 15 min, per account) [V, `LdapAuthService.cs`]:** + +| Failure | Bad binds | Effect | +|---|---|---| +| **Wrong *user* password** | **1**, on one DC (`:164-168`, `:428-436`) | Final (`BadCredentials`); no walk to the next DC. Locks only that user, after 5 tries. | +| **Wrong *service-account* password** | **2 per login attempt**: system-side, so it walks to the next DC (`:173-174`, `:408-415`) | Locks the **shared** account. | + +The shared account is one account for all four apps and both tiers (D1). A mistyped secret in any of the ~7 +stores can therefore lock out login everywhere within a few attempts. + +ScadaBridge's background group refresh also binds as this account. Its throttle is 5 per 5 min +(`ScadaBridge Security/SecurityOptions.cs:132-145`) [V], looser than AD's 5 per 15 min. **Mitigations:** +- D1 asks IT for a no-lockout (or very high threshold) policy on the account. +- §7.1 verifies every store's value before that app restarts. +- §7 does one canary app first. +- §7.6 has a stop rule. --- -## 2. Phase A — OtOpcUa code fix (prerequisite; must ship before the OtOpcUa cutover) +## 2. Phase A — OtOpcUa code fix (prerequisite for the OtOpcUa cutover) -### 2.1 The defect [V] +One OtOpcUa change, one issue, one deploy. It fixes five things. -OtOpcUa has its own `LdapOptions` (`src/Server/ZB.MOM.WW.OtOpcUa.Security/Ldap/LdapOptions.cs`, section -`Security:Ldap`, bound at `ServiceCollectionExtensions.cs:52` and validated at `Host/Program.cs:195`). -`ToLibraryOptions()` (`LdapOptions.cs:111`) copies **12** fields into the shared library's -`ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions` (`ZB.MOM.WW.Auth/src/ZB.MOM.WW.Auth.Abstractions/Ldap/LdapContracts.cs:21`). -Those 12 are `Enabled`, `Server`, `Port`, `Transport`, `AllowInsecure`, `SearchBase`, `ServiceAccountDn`, -`ServiceAccountPassword`, `UserNameAttribute`, `DisplayNameAttribute`, `GroupAttribute` and -`ConnectionTimeoutMs`. +### 2.1 Defects [V] -The library has **five more**, and OtOpcUa has no property for any of them, so a config key is ignored -without error: - -| Library field | Since | Effect of the drop | -|---|---|---| -| `FallbackServers` (`IReadOnlyList`, `host:port`) | 0.2.0 | **No DC failover.** If nam1 goes down, the AdminUI login is down. The 08-13 target block would have bound with no warning. | -| `BindMode` (`ServiceAccount` / `User`) | 0.4.0 | Always `ServiceAccount`. Harmless for this plan, which uses ServiceAccount (§5, D1), but the option is invisible. | -| `UserBindTemplate` | 0.4.0 | Only used by `BindMode=User`. | -| `AcceptDomainQualifiedNames` | 0.4.0 | Stays at the library default `true`. Can't be turned off. | -| `ServerCertificateValidationCallback` | 0.1.x | **Code-only by design** (not config-bound). Excluded from the fix. Pinning a CA is a separate decision (§5, D4). | - -`GroupToRole` and `DevStubMode` are OtOpcUa's own properties and aren't library fields. That is -correct. +1. **Options dropped.** `LdapOptions.ToLibraryOptions()` (`src/Server/ZB.MOM.WW.OtOpcUa.Security/Ldap/LdapOptions.cs:111`) + copies 12 fields into the library's `LdapOptions` (`ZB.MOM.WW.Auth.Abstractions/Ldap/LdapContracts.cs:21`). + - **Dropped:** `FallbackServers` (0.2.0), `BindMode`, `UserBindTemplate` and `AcceptDomainQualifiedNames` + (0.4.0). The config keys are ignored without error, so the AdminUI has **no DC failover**. + - **Not config-bound, by design:** `ServerCertificateValidationCallback`, which is code-only. +2. **Zero-role sign-in (review B1).** `Security/Endpoints/AuthEndpoints.cs:124-158` signs in with an **empty** + role set when the mapper returns no roles, **and** when the mapper throws: it catches the exception, logs a + warning and continues with the baseline roles, which are empty on the real path. + - The fallback policy and `AdminUiPolicies.AuthenticatedRead` (`Security/ServiceCollectionExtensions.cs:192,217`) + only require an authenticated user, and 18 AdminUI pages use `AuthenticatedRead`. + - No policy requires `Viewer`; it is only a default in `RoleGrants.razor:126`. + - With a domain-root `SearchBase`, **any NAM user with any group would get AdminUI read access**, and + `/auth/token` would mint them a token. +3. **No library logger (review M1).** `OtOpcUaLdapAuthService.cs:48` builds `LibLdapAuthService` with no + logger, and the library logs only via `_logger?.`. So the failover log line + (`sticky preference moved`) and the stage diagnostics (`failed system-side at …`) **never appear** in + OtOpcUa, and §7.6's checks can't be done. +4. **No validation of the new options (review B2).** OtOpcUa **never runs the library's + `LdapOptionsValidator`**: it constructs the library service directly (`OtOpcUaLdapAuthService.cs:48`). That + answers the old open question. + - Calling the library validator would **stop OtOpcUa booting on DEV and QA**. It requires + `ServiceAccountDn` in ServiceAccount mode (`ZB.MOM.WW.Auth.Ldap/LdapOptionsValidator.cs:81-87`), DEV runs on + code defaults (`Enabled=true`, `ServiceAccountDn=""`), and OtOpcUa validates LDAP on every node + (`Host/Program.cs:190-195`). +5. **Stale docs.** The OtOpcUa validator comment (`Host/Configuration/LdapOptionsValidator.cs:12-14`) describes a + "direct-bind path" that doesn't exist. The `LdapOptions` doc says the default server is `10.100.0.35`; the + code says `localhost`. ### 2.2 The fix -1. **Add the properties** to OtOpcUa's `LdapOptions`, with the library's defaults: - - `public List FallbackServers { get; set; } = [];` - - `public LdapBindMode BindMode { get; set; } = LdapBindMode.ServiceAccount;` - - `public string UserBindTemplate { get; set; } = "";` - - `public bool AcceptDomainQualifiedNames { get; set; } = true;` - - XML docs pointing at the library's documentation. -2. **Pass them through** in `ToLibraryOptions()`. `FallbackServers` maps to an `IReadOnlyList`. -3. **Validation:** the library's own `LdapOptionsValidator` already checks `FallbackServers` (host:port - form) and the BindMode/UserBindTemplate combination at boot (Auth 0.2.0/0.4.0). - - Check whether OtOpcUa runs that validator on the *mapped* options. If it doesn't, call it (or - mirror its rules) in `Host/Configuration/LdapOptionsValidator.cs`, so a bad fallback entry fails at - boot the way it does in the other three apps. -4. **Completeness guard test (the important part).** Add a unit test that walks the library - `LdapOptions`' public settable properties by reflection, builds an OtOpcUa `LdapOptions` with a - non-default value for each, calls `ToLibraryOptions()`, and asserts every value arrived. - - Keep an explicit allow-list of library fields that are deliberately not mapped: - `ServerCertificateValidationCallback`. - - Effect: a future library field fails the build until someone maps it or allow-lists it. - - Mutation check: remove one assignment from `ToLibraryOptions()` and the test must fail. -5. **Config binding test:** bind `Security:Ldap:FallbackServers:0` (JSON and env form, - `Security__Ldap__FallbackServers__0`) and assert it reaches the library options. -6. **Docs:** add the new keys to the `Security:Ldap` section of OtOpcUa `docs/Configuration.md`, with a - NAM example (two DCs). -7. **Behaviour test (acceptance A1):** run the AdminUI login against the redundant GLAuth pair. - - The pair is the dev Mac's `zb-ldap-primary` `:3893` and `zb-ldap-backup` `:3894`; see - `infra/glauth-redundant/README.md`. - - Set `Server` to the primary and `FallbackServers: ["…:3894"]`. Stop the primary. - - Expect: login still succeeds, the log shows the primary's failure, then - `LDAP sticky preference moved to …:3894`. - - Restore the primary. - - The same drill passed for HistorianGateway on 2026-08-13. +1. **Add the four properties** with the library's defaults and pass them through `ToLibraryOptions()`: + - `List FallbackServers = []` → `IReadOnlyList` + - `LdapBindMode BindMode = ServiceAccount` + - `string UserBindTemplate = ""` + - `bool AcceptDomainQualifiedNames = true` +2. **Refuse a zero-role login (the family standard, §3.2).** In `/auth/login` **and** `/auth/token`: + - if the mapped role set is empty, refuse exactly like bad credentials (HTTP 401 / the login page's + "invalid or not authorized"), with no cookie and no token; + - if the mapper **throws**, also **refuse** (fail closed), log the exception, and do not sign in. + - **This reverses the current code comment's intent and the test + `Login_when_role_mapper_throws_signs_in_with_no_role_claims`** + (`tests/Server/ZB.MOM.WW.OtOpcUa.Security.Tests/AuthEndpointsIntegrationTests.cs:402`). Rewrite that test to + assert refusal. + - Add tests: empty mapping refused (cookie + token); mapper throws refused (cookie + token); one mapped role + signs in. + - **DevStub is unaffected:** it grants `Administrator`. +3. **Inject the logger:** pass `ILogger` from DI into the + `LibLdapAuthService` constructor at `OtOpcUaLdapAuthService.cs:48`. Add a test that a failover writes the + library's `sticky preference moved` line. +4. **Validation, OtOpcUa's own validator only.** In `Host/Configuration/LdapOptionsValidator.cs`, port **only**: + - the library's `FallbackServers` rule (each entry parses as `host[:port]`); + - the `BindMode=User` → `UserBindTemplate` contains `{0}` exactly once rule. -### 2.3 Issue to file in `lmxopcua` (text only; not filed by this plan) + **Do not** port the `ServiceAccountDn`-required rule. -> **Title:** `Security:Ldap` drops `FallbackServers`, `BindMode`, `UserBindTemplate`, `AcceptDomainQualifiedNames` -> (no AD DC failover for the AdminUI) + **Add a test that boots the validator with today's DEV-shaped config** (`Enabled=true`, `Server=localhost`, + `ServiceAccountDn=""`, `Transport=Ldaps`) and asserts it **passes**. +5. **Completeness guard.** Add a unit test that reflects over the library `LdapOptions`' public settable + properties. + - For each one, set a non-default value on OtOpcUa's options, call `ToLibraryOptions()`, and assert the value + arrived. Compare `IReadOnlyList` values **by content**. + - Check **both directions:** every library property is mapped or allow-listed, and no allow-list entry is + stale. + - Allow-list: `ServerCertificateValidationCallback`. + - Mutation check: delete one assignment and the test must fail. +6. **Binding test:** `Security:Ldap:FallbackServers:0` reaches the library options, in JSON and as the env var + `Security__Ldap__FallbackServers__0`. +7. **Docs:** + - `docs/Configuration.md` `Security:Ldap`: the new keys, a NAM two-DC example, the zero-role refusal, and + "type the bare sAMAccountName". + - Fix the two stale comments from §2.1 item 5. +8. **Acceptance A1 (offline):** an AdminUI login against the redundant GLAuth pair (`infra/glauth-redundant/`, + `:3893` + `FallbackServers ["…:3894"]`). + - Stop the primary: login still succeeds and the log shows `sticky preference moved to …:3894`. + - A GLAuth user in no mapped group is refused. + +### 2.3 Issue text for `lmxopcua` (not filed by this plan) + +> **Title:** AdminUI LDAP: drops `FallbackServers`/`BindMode`/…, signs in users with no mapped role, and the library logs nothing > -> **Labels:** `type:bug`, `priority:p2`, `area:auth`, `cross-repo` +> **Labels:** `type:bug`, `priority:p1`, `area:auth`, `cross-repo` > -> **Body:** `LdapOptions.ToLibraryOptions()` (`src/Server/ZB.MOM.WW.OtOpcUa.Security/Ldap/LdapOptions.cs:111`) -> copies 12 fields into `ZB.MOM.WW.Auth` `LdapOptions`. The library's `FallbackServers` (0.2.0), `BindMode`, -> `UserBindTemplate` and `AcceptDomainQualifiedNames` (0.4.0) have no OtOpcUa property, so those config keys -> are ignored without error. The scadaproj#6 NAM cutover needs `FallbackServers` for the two NAM DCs. +> **Body:** +> 1. `LdapOptions.ToLibraryOptions()` (`Security/Ldap/LdapOptions.cs:111`) drops `FallbackServers`, `BindMode`, +> `UserBindTemplate` and `AcceptDomainQualifiedNames`, so there is no AD DC failover. +> 2. `AuthEndpoints.cs:124-158` signs in with an empty role set, including when the mapper throws, and +> `AuthenticatedRead` admits any authenticated user. Once the search base is a whole AD domain, any directory +> user gets AdminUI read access and a token. The fix refuses empty roles at `/auth/login` and `/auth/token`, +> and refuses when the mapper throws. This reverses `Login_when_role_mapper_throws_signs_in_with_no_role_claims`. +> 3. `OtOpcUaLdapAuthService.cs:48` passes no logger to the library, so failover and stage logs are missing. +> Inject `ILogger`. +> 4. Validate the new options in OtOpcUa's own validator: the fallback parse rule and the BindMode/UserBindTemplate +> rules only. **Not** `ServiceAccountDn`, because DEV boots on code defaults with an empty DN. +> 5. A two-way reflection completeness test, a binding test, docs, and fixes to the stale comments. > -> Fix: add the properties and pass them through. Add a reflection test that fails when any library -> option is neither mapped nor on an explicit allow-list (only `ServerCertificateValidationCallback`, -> which is code-only). Add a binding test (JSON + env) and a `docs/Configuration.md` entry. -> -> Acceptance: an AdminUI login fails over on the redundant GLAuth pair (`:3893` → `:3894`, sticky -> preference log line). Plan: `scadaproj/docs/plans/2026-11-15-nam-ldap-cutover.md` §2. +> **Acceptance:** failover on the redundant GLAuth pair, a zero-role user refused (cookie + token), and a +> DEV-shaped config boots. Plan: `scadaproj/docs/plans/2026-11-15-nam-ldap-cutover.md` §2. ### 2.4 Ship it -Merge to OtOpcUa `master`, then deploy using OtOpcUa's own procedure (the `docs/deploy/` records, -most recently `2026-11-13-vd03-qa-to-76e73e7d.md`): -1. DEV vd03. -2. Then the QA pair, stopping both nodes and starting them together, per the record. +Merge to `master` and deploy with OtOpcUa's own procedure (`docs/deploy/`, most recently +`2026-11-13-vd03-qa-to-76e73e7d.md`): DEV, then QA. -This is a normal master deploy. It doesn't change any LDAP config, because no tier sets the new keys yet, -so it can go out ahead of the cutover. **Gate:** the OtOpcUa cutover (§7.4) does not start until the -deployed build contains the fix. +- **No LDAP config change** goes out with this deploy. +- **The zero-role refusal does change behaviour on QA:** it is live against the box-local GLAuth today, so any + GLAuth user without a mapped group loses AdminUI read access. Phase 0 checks that the `multi-role` user maps. +- **Gate:** §7.5 (the OtOpcUa cutover) does not start until the deployed build contains this fix. --- -## 3. The group-mapping standard (DECIDED 2026-11-15) +## 2A. Phase A2 — ScadaBridge zero-role refusal (prerequisite for the ScadaBridge cutover) -### 3.1 The rule +**Defect [V, review B1]:** +- `CentralUI/Auth/AuthEndpoints.cs:59-115` signs in (cookie) and issues a bearer at `/auth/token` (`:125`) even + when `RoleMapper` returns no roles. +- `Dashboard.razor:2` and `Monitoring/Health.razor:2` are bare `[Authorize]`, so any directory user could read + them. -**One AD group grants exactly one role in a given app. A user's roles in an app are the union of the -roles of every mapped group they belong to. No app maps one group to two roles.** The `_DEV`/`_QA`/`_PROD` -suffix is chosen per deployment: a tier maps only its own suffix (`ldap_mapping.md` §3). +**Fix:** +1. In `/auth/login` and `/auth/token`, an empty mapped role set returns the bad-credentials response, with no + cookie and no token. +2. Apply the same rule to the mid-session group refresh (`DirectoryGroupRefresher`). A session whose roles drop + to zero is already ended by that refresh (`:141-142`); keep that behaviour and test it. +3. **Tests:** zero roles refused (login + token); one role signs in; a refresh to zero ends the session. +4. **Docs:** the `Component-Security` / CentralUI auth section. +5. **Leave the bare `[Authorize]` pages** as they are; they are safe once a login requires a role. Add a + static test that every page is either policy-gated or relies on that rule. -### 3.2 Why +**Issue text for `ScadaBridge` (not filed):** -1. **It is what every app's schema already supports, with no code change:** +> **Title:** Central UI / `/auth/token` sign in users whose AD groups map to no role +> +> **Labels:** `type:bug`, `priority:p1`, `area:auth`, `cross-repo` +> +> **Body:** `CentralUI/Auth/AuthEndpoints.cs:59-115` signs in and mints a bearer with an empty role set. With a +> domain-wide NAM search base, any AD user reaches `Dashboard` and `Monitoring/Health` (bare `[Authorize]`). The +> family standard (scadaproj NAM cutover plan §3.2) refuses login when no role is mapped. Fix login and token, +> keep the refresh's end-on-zero, and add tests. +> +> **Acceptance:** a zero-role user is refused at both endpoints. Plan: `docs/plans/2026-11-15-nam-ldap-cutover.md` §2A. - | App | Mapping shape | One role per group? | - |---|---|---| - | OtOpcUa | `Dictionary GroupToRole` (`Security/Ldap/LdapOptions.cs:84`), unioned with DB rows (`OtOpcUaGroupRoleMapper.cs`) | **Config:** yes, by structure (a dictionary key). **DB overlay** `LdapGroupRoleMapping`: index on `LdapGroup` is not unique; only `(LdapGroup, ClusterId)` is unique, with a filter (model snapshot). Several system-wide rows per group are possible, so **the rule forbids them**, and Phase 0 checks there are none. | - | ScadaBridge | table **`LdapGroupMappings`** (`LdapGroupName`, `Role`) (`Commons/Entities/Security/LdapGroupMapping.cs`) | **Yes, enforced:** `HasIndex(m => m.LdapGroupName).IsUnique()` (`ConfigurationDatabase/Configurations/SecurityConfiguration.cs:26`). `RoleMapper` unions roles across *different* groups (`Security/RoleMapper.cs:48-60`). | - | MxAccessGateway | `Dictionary GroupToRole` (`Server/Configuration/DashboardOptions.cs:69`) | Yes. The validator also allows only `Administrator`/`Viewer` (`GatewayOptionsValidator.cs:506-517`). | - | HistorianGateway | `IReadOnlyDictionary GroupToRole` (`Server/Dashboard/DashboardOptions.cs:44`) | Yes. | - -2. **Grants stay auditable where IT manages them.** "Who can deploy" reads directly off one AD group's - membership, not off a combination of rows in four apps. -3. **It removes a silent failure mode.** The 08-13 plan's two-row ScadaBridge insert breaks on the unique - index, and `ldap_mapping.md` §2.1 claimed a capability ScadaBridge does not have. - -### 3.3 Rejected alternative: several roles per group - -This would need a ScadaBridge migration (drop the unique index, add a `(LdapGroupName, Role)` key) and -possibly the Auth library's mapper, plus matching changes in the other three apps. It is recorded as a -future option. **It is not part of this plan.** - -### 3.4 The consequence that matters: ScadaBridge `Deployer` - -`ldap_mapping.md` §2.1 had `APP_IDE` grant both `Designer` and `Deployer` in ScadaBridge. Under the rule, -`APP_IDE` maps to **`Designer`** only. - -In ScadaBridge, `Administrator` does **not** imply `Deployer`: each policy requires its own role claim -(`Security/AuthorizationPolicies.cs:190-202`, `RequireDeployment` → `Roles.Deployer`). No existing -`UG_WW_*` group means "deploy". So: - -- **Needs a new AD group: `UG_WW_APP_DEPLOY_{DEV,QA}`**, by ServiceNow ticket, mapped to ScadaBridge - `Deployer`. This is decision **D6**. -- **Until it exists, the ScadaBridge cutover must not run on that tier.** If it did, no NAM user would - hold `Deployer`, and nobody could deploy through the UI or CLI. -- The other three apps have no `Deployer` role (OtOpcUa's deploy sits under `ConfigEditor` = - Administrator/Designer, `AdminUiPolicies.cs:18`), so they don't need the new group. +**Ship:** a ScadaBridge build containing the fix, deployed DEV then QA before §7.4. This is a binary deploy, so +it follows the QA pair rules: stop both centrals and start them together. --- -## 4. The tier mappings, generated from the matrix +## 2B. Phase A3 — HistorianGateway case-insensitive group match (optional hardening) -The full matrix (every `UG_WW_*` family × the four apps) is in [`ldap_mapping.md`](../../ldap_mapping.md) §4. -These are the **DEV** and **QA** slices for this cutover: -- platform groups only; -- plant-floor operator, site-admin, engineer, supervisor and tester groups are **not** mapped - (`ldap_mapping.md` §6; decision D5); -- `CITRIX_*` is never mapped. +**Defect [review M5]:** `Dashboard/DashboardOptions.cs:44-45` declares `IReadOnlyDictionary` +with an `OrdinalIgnoreCase` default. The configuration binder **replaces** it with a new case-**sensitive** +`Dictionary`. The reviewer proved this with an offline binder test; the XML doc says "compared +case-insensitively", which is wrong once it's bound. AD group names are mixed case, so a key whose case differs +from the `memberOf` CN never matches. + +**Fix:** declare `Dictionary` with `StringComparer.OrdinalIgnoreCase`, so the binder fills the +existing instance, as mxgw and OtOpcUa do. Add a binder test with a mixed-case key. + +**Until it ships (and in any case),** §4 copies each group name **exactly** as LdapProbe prints it. + +**Issue text for `historiangw` (not filed):** + +> **Title:** `Dashboard:GroupToRole` is case-sensitive after binding (docs say case-insensitive) +> +> **Labels:** `type:bug`, `priority:p3`, `area:auth` +> +> **Body:** the `IReadOnlyDictionary` default with `OrdinalIgnoreCase` is replaced by the binder's default +> `Dictionary`. Make the property a `Dictionary` with `OrdinalIgnoreCase` and add a binder test with a mixed-case +> key. Found by the NAM cutover review (scadaproj plan §2B). + +--- + +## 3. The family standards (DECIDED 2026-11-15) + +### 3.1 One AD group grants exactly one role per app + +A user's roles in an app are the union of the roles of every mapped group they belong to. No app maps one group +to two roles. Each deployment maps only its own `_DEV`/`_QA`/`_PROD` suffix. + +**Why:** +1. Every schema already enforces or implies it, so no code change is needed: + + | App | Mapping shape [V] | + |---|---| + | OtOpcUa | `Dictionary GroupToRole` (`Security/Ldap/LdapOptions.cs:84`), unioned with the DB overlay `LdapGroupRoleMapping` (`OtOpcUaGroupRoleMapper.cs`). The overlay's only unique index is `(LdapGroup, ClusterId)`, filtered, so two system-wide rows per group are possible; **the rule forbids them** and Phase 0 checks. | + | ScadaBridge | table **`LdapGroupMappings`**, with `HasIndex(LdapGroupName).IsUnique()` (`ConfigurationDatabase/Configurations/SecurityConfiguration.cs:26`). `RoleMapper` unions roles across different groups (`Security/RoleMapper.cs:48-60`). | + | MxAccessGateway | `Dictionary` (`Configuration/DashboardOptions.cs:69`). The validator allows only `Administrator`/`Viewer` (`GatewayOptionsValidator.cs:506-517`). | + | HistorianGateway | `IReadOnlyDictionary` (`Dashboard/DashboardOptions.cs:44`). Case-sensitive in practice (§2B). | + +2. Grants stay readable in AD, where IT owns membership. +3. It removes a silent failure: the old two-row ScadaBridge insert hits the unique index. + +**Rejected:** several roles per group. It would need a ScadaBridge migration and matching changes in the other +apps. It stays a future option. + +### 3.2 No role, no login (added by review B1) + +**Every app refuses sign-in, both cookie and token, when the user's groups map to no role.** That includes the +case where the role lookup fails. + +| App | Today [V] | Change | +|---|---|---| +| MxAccessGateway | refuses (`Dashboard/DashboardAuthenticator.cs:66-70`) | none | +| HistorianGateway | refuses (`Dashboard/DashboardAuthenticator.cs:56-64`) | none | +| OtOpcUa | signs in with no roles, even when the mapper throws | **§2 (Phase A)** | +| ScadaBridge | signs in with no roles | **§2A (Phase A2)** | + +**Consequence for the matrix:** read access now **requires** a mapped group. In OtOpcUa, `Viewer` is not checked +by any policy (pages use `AuthenticatedRead`), so a **Viewer cell means "holds a role, so may sign in and read"**. +That is why `APP_IDE_RO_` → `Viewer` stays, and why `HIST_ADMIN_` → `Viewer` in OtOpcUa is meaningful. + +### 3.3 Consequence for ScadaBridge `Deployer` + +`APP_IDE` → `Designer` only. In ScadaBridge, `Administrator` does not imply `Deployer`: each policy requires its +own role (`Security/AuthorizationPolicies.cs:190-202`). No existing group means "deploy", so: +- a **new AD group `UG_WW_APP_DEPLOY_{DEV,QA}`** (D6) maps to `Deployer`; +- until it exists on a tier, **the ScadaBridge cutover does not run there**, because nobody could deploy. + +The other apps have no `Deployer` role; OtOpcUa deploy is `ConfigEditor` = Administrator/Designer, +`AdminUiPolicies.cs:18`. + +--- + +## 4. The tier mappings (generated from `ldap_mapping.md` §4.1) + +These are platform groups only. Plant-floor, site and batch groups are not in this cutover (D5), and `CITRIX_*` +is never mapped. **Copy each group name exactly as LdapProbe prints it** (§2B; D7). The names below are as +observed on 2026-08-12. | Group (`` = `DEV` or `QA`) | OtOpcUa | ScadaBridge | MxAccessGateway | HistorianGateway | |---|---|---|---|---| | `UG_WW_APP_ADMIN_` | Administrator | Administrator | Administrator | Administrator | | `UG_WW_APP_IDE_` | Designer | Designer | Viewer | — | -| `UG_WW_APP_DEPLOY_` *(new, D6)* | — | Deployer | — | — | +| `UG_WW_APP_DEPLOY_` *(new, D6; only once it exists)* | — | Deployer | — | — | | `UG_WW_APP_IDE_RO_` | Viewer | Viewer | Viewer | Viewer | | `UG_WW_HIST_ADMIN_` | Viewer | — | — | Administrator | -| `UG_WW_BTMGR_RO_QA` *(QA only; **empty** as of 08-12)* | — | Viewer | — | Viewer | +| `UG_WW_BTMGR_RO_QA` *(QA only; empty as of 08-12)* | — | Viewer | — | Viewer | -Every cell holds one role, so no group appears twice in any app. - -### 4.1 HistorianGateway - -DEV goes in `appsettings.Production.json`. QA goes in the NSSM env (`AppEnvironmentExtra`). +### 4.1 HistorianGateway (DEV: `appsettings.Production.json`; QA: NSSM env) ```jsonc -"Ldap": { /* §6 block */ }, +"Ldap": { /* §6 */ }, "Dashboard": { "DisableLogin": false, - "GroupToRole": { - "UG_WW_APP_ADMIN_DEV": "Administrator", - "UG_WW_HIST_ADMIN_DEV": "Administrator", - "UG_WW_APP_IDE_RO_DEV": "Viewer" - } + "GroupToRole": { "UG_WW_APP_ADMIN_DEV": "Administrator", "UG_WW_HIST_ADMIN_DEV": "Administrator", "UG_WW_APP_IDE_RO_DEV": "Viewer" } } ``` -QA env form. Remove the old `Dashboard__GroupToRole__SCADA-*` entries. +On QA, remove every `Dashboard__GroupToRole__SCADA-*` entry first, then set: ``` Dashboard__GroupToRole__UG_WW_APP_ADMIN_QA=Administrator @@ -265,32 +357,30 @@ Dashboard__GroupToRole__UG_WW_APP_IDE_RO_QA=Viewer Dashboard__GroupToRole__UG_WW_BTMGR_RO_QA=Viewer ``` -### 4.2 MxAccessGateway +### 4.2 MxAccessGateway (the overlay file for the box's environment name; Phase 0 records it) -DEV goes in the live appsettings file; Phase 0 records which one. QA goes in the same file it uses -today. +The **base `appsettings.json` ships `GwAdmin`/`GwReader` mappings** (`:86-89`) [V], and dictionaries **merge** +across overlays. So the overlay alone can't remove them, and they can't be neutralised either, because the +validator accepts only `Administrator`/`Viewer` as a value. **Delete the two entries from the box's base +`appsettings.json`** (backed up). A redeploy restores the base file, so the mxgw deploy notes must carry the +deletion forward. + +Then set: ```jsonc "MxGateway": { - "Ldap": { /* §6 block */ }, + "Ldap": { /* §6 */ }, "Dashboard": { "DisableLogin": false, - "GroupToRole": { - "UG_WW_APP_ADMIN_DEV": "Administrator", - "UG_WW_APP_IDE_DEV": "Viewer", - "UG_WW_APP_IDE_RO_DEV": "Viewer" - } + "GroupToRole": { "UG_WW_APP_ADMIN_DEV": "Administrator", "UG_WW_APP_IDE_DEV": "Viewer", "UG_WW_APP_IDE_RO_DEV": "Viewer" } } } ``` -For QA, use the `_QA` suffix and replace `GwAdmin`/`GwReader`. The validator rejects any value other -than `Administrator`/`Viewer` [V]. +On QA, use the `_QA` suffix and delete `GwAdmin`/`GwReader` the same way. **Acceptance A4 reads the *effective* +config** (§8), not just the edited file. -### 4.3 OtOpcUa (AdminUI) - -This goes in the service env on both tiers. That matches how the tiers already set other OtOpcUa -options, for example `OpcUa__Redundancy__*`. +### 4.3 OtOpcUa (service env, both tiers) ``` Security__Ldap__GroupToRole__UG_WW_APP_ADMIN_=Administrator @@ -299,33 +389,39 @@ Security__Ldap__GroupToRole__UG_WW_APP_IDE_RO_=Viewer Security__Ldap__GroupToRole__UG_WW_HIST_ADMIN_=Viewer ``` -- **DB overlay:** the AdminUI RoleGrants page (`LdapGroupRoleMapping`) must have **no** rows for these - groups, or exactly the same role. Phase 0 lists the rows. -- **Operator role:** OtOpcUa's `DriverOperator` policy also accepts the role `Operator` - (`ServiceCollectionExtensions.cs:201-202`). No platform group maps to it in this cutover; plant-floor - access to the data plane is by API key. +- **DB overlay:** the RoleGrants page / `LdapGroupRoleMapping` must hold **no** rows for these groups, or only the + same role. +- `DriverOperator` also honours the role `Operator` (`ServiceCollectionExtensions.cs:201-202`); nothing maps to + it here. -### 4.4 ScadaBridge +### 4.4 ScadaBridge (central database) -**Roles live in the central database. Run this once per tier**, against the tier's `ScadaBridge` database, -from the Mac with `sqlcmd -b`. The script is idempotent and fails loudly on a conflicting existing row -rather than changing it: +**Preferred: the management surface**, so the change is audited by the ManagementActor and the 30 s +cross-central role-mapping cache is invalidated. +- Use the CLI `security` role-mapping commands: `scadabridge security --help` lists them. Run them on the target + tier with an explicit `--url`, **while DEV login is still off** (the dev user holds every role). +- On QA, run them as the current GLAuth admin before the cutover. +- The Central UI's role-mapping page is equivalent. + +Add one mapping per group: +- `UG_WW_APP_ADMIN_` → `Administrator` +- `UG_WW_APP_IDE_` → `Designer` +- `UG_WW_APP_IDE_RO_` → `Viewer` +- `UG_WW_APP_DEPLOY_` → `Deployer`, **only if that group exists (D6)** +- QA only: `UG_WW_BTMGR_RO_QA` → `Viewer` + +**Fallback: direct SQL** (idempotent; refuses to change a conflicting row). It bypasses the audit and the cache +invalidation, so record it in the deployment record and **wait 30 s (or restart Central) before testing**. ```sql SET XACT_ABORT ON; BEGIN TRAN; DECLARE @t TABLE (LdapGroupName nvarchar(500) NOT NULL, Role nvarchar(100) NOT NULL); -INSERT @t VALUES - (N'UG_WW_APP_ADMIN_DEV', N'Administrator'), - (N'UG_WW_APP_IDE_DEV', N'Designer'), - (N'UG_WW_APP_DEPLOY_DEV', N'Deployer'), -- only once the group exists (D6) - (N'UG_WW_APP_IDE_RO_DEV', N'Viewer'); +INSERT @t VALUES (N'UG_WW_APP_ADMIN_DEV', N'Administrator'), (N'UG_WW_APP_IDE_DEV', N'Designer'), (N'UG_WW_APP_IDE_RO_DEV', N'Viewer'); +-- Only if D6's group exists: INSERT @t VALUES (N'UG_WW_APP_DEPLOY_DEV', N'Deployer'); -- QA: _QA suffix, plus (N'UG_WW_BTMGR_RO_QA', N'Viewer'). - -IF EXISTS (SELECT 1 FROM dbo.LdapGroupMappings m JOIN @t t ON t.LdapGroupName = m.LdapGroupName - WHERE m.Role <> t.Role) - THROW 50001, 'LdapGroupMappings already maps one of these groups to a different role; resolve by hand.', 1; - +IF EXISTS (SELECT 1 FROM dbo.LdapGroupMappings m JOIN @t t ON t.LdapGroupName = m.LdapGroupName WHERE m.Role <> t.Role) + THROW 50001, 'LdapGroupMappings maps one of these groups to a different role; resolve by hand.', 1; INSERT dbo.LdapGroupMappings (LdapGroupName, Role) SELECT t.LdapGroupName, t.Role FROM @t t WHERE NOT EXISTS (SELECT 1 FROM dbo.LdapGroupMappings m WHERE m.LdapGroupName = t.LdapGroupName); @@ -333,13 +429,12 @@ COMMIT; SELECT Id, LdapGroupName, Role FROM dbo.LdapGroupMappings ORDER BY Id; ``` -- **Names [V]:** table `LdapGroupMappings` (model snapshot `ToTable("LdapGroupMappings")`); columns - `LdapGroupName` `nvarchar(500)` and `Role` `nvarchar(100)` (`SecurityConfiguration.cs:16-24`). Role - values are the `Roles` constants (`Security/Roles.cs:45-56`). -- **The `SCADA-*` seed rows** (Ids 1–5, `HasData`) map GLAuth group names that don't exist in NAM, so they - grant nothing after the cutover. Leave them; deleting seed rows fights the migrations. -- **Site scoping** (`SiteScopeRules`) is unused for the platform groups. -- **Order: insert the rows before login is turned on.** While login is disabled they grant nothing. +**Names [V]:** +- Table `LdapGroupMappings`. +- Columns `LdapGroupName` `nvarchar(500)` and `Role` `nvarchar(100)` (`SecurityConfiguration.cs:16-24`). +- Role values are the `Security/Roles.cs:45-56` constants. + +The `SCADA-*` seed rows (Ids 1–5) name GLAuth groups that don't exist in NAM, so they grant nothing; leave them. --- @@ -347,17 +442,17 @@ SELECT Id, LdapGroupName, Role FROM dbo.LdapGroupMappings ORDER BY Id; | # | Decision | Options | Recommendation | |---|---|---|---| -| D1 | **Service account** (owner request: one dedicated LDAP-lookup account shared by the four services, **[scadaproj#58](https://gitea.dohertylan.com/dohertj2/scadaproj/issues/58)**) | **Target:** the dedicated account from scadaproj#58, shared across all four apps. One account for DEV and QA, unless IT prefers one per tier. **Interim (DEV only):** `svc_igntadmin@nam.zimmer.com`, proven 2026-08-13, **only with the Ignition team's agreement**, because it is their admin account and their password changes would break our logins. | **Target from scadaproj#58. scadaproj#58 is a prerequisite for the QA cutover.** DEV may start on the interim account once Ignition agrees. Switching to the dedicated account later means re-seeding the `nam-ldap-svc-password` secret and changing `ServiceAccountDn` in each app. A service account is **required** either way: OtOpcUa has no User bind until §2 ships, and ScadaBridge#46's mid-session group refresh returns `NotSupported` under `BindMode=User`. So **`BindMode=ServiceAccount` everywhere.** | -| D2 | **Turn login on where DEV is deliberately open** (HG, mxgw = mxaccessgw#231 item 3, ScadaBridge) | (a) Turn it on, which is the point of the exercise. (b) Leave DEV open and cut over QA only. | **(a).** DEV is where to find problems before QA. Overview stays open. | -| D3 | **QA automation identity** (ScadaBridge CLI, deploy and drill scripts, which today use GLAuth `multi-role`) | (a) A NAM *user-type* identity that can sign in. The scadaproj#58 account is for LDAP lookups and should not double as a login, unless IT agrees. in `APP_ADMIN_QA` + `APP_IDE_QA` + `APP_DEPLOY_QA`, password in the Mac Keychain. (b) Keep ScadaBridge QA on GLAuth until (a) exists. | **(a).** Union across groups gives it Administrator + Designer + Deployer under the rule. **Blocks the QA ScadaBridge step.** | -| D4 | **TLS trust** | (a) Install `zimmer-rootca` in `LocalMachine\Root` on each box; `AllowInsecure=false`. (b) `AllowInsecure=true`, still encrypted but no chain validation. (c) Pin the CA through `ServerCertificateValidationCallback`; this is code, not config. | **(a)** if the Phase 0 check fails. **(b) is DEV only**, as a stopgap. | -| D5 | **Plant-floor / site groups** (`*_OPERATOR`, `SITE_ADMIN_*`, `*_ENGINEER`, `*_SUPERVISOR`, `*_TESTER`) | Map now / later. | **Later.** They are not in this cutover; see `ldap_mapping.md` §6. | -| D6 | **New group `UG_WW_APP_DEPLOY_{DEV,QA}`** (ScadaBridge `Deployer`) | (a) Ticket it now. (b) Multi-role code change (rejected, §3.3). | **(a). Blocks the ScadaBridge step on each tier.** | -| D7 | **Group membership** | Confirm the intended people are in `APP_ADMIN`, `APP_IDE`, `APP_IDE_RO`, `HIST_ADMIN` (`_DEV`/`_QA`). Anyone missing gets a ServiceNow membership request, not a wider mapping. | Run `dotnet run --project tools/LdapProbe -- --insecure --svc '' --self-bind ` per person. Re-enumerate the families with `ldapprobe -g 'UG_WW_*'`. | +| D1 | **Service account** (owner request: one dedicated LDAP-lookup account shared by the four services, **scadaproj#58**) | **Target:** the dedicated account from scadaproj#58, shared across all four apps; one account for DEV and QA unless IT prefers one per tier. **Interim (DEV only):** `svc_igntadmin@nam.zimmer.com`, **only with the Ignition team's agreement**. It is their admin account, and their rotations or lockouts would hit us. | **Target from scadaproj#58, a QA prerequisite.** **Add to the scadaproj#58 ask: a no-lockout policy (or a very high threshold) on the account**, because it is shared by four apps and two tiers and a wrong secret costs 2 bad binds per login (§1.3). `BindMode=ServiceAccount` everywhere. Rotation = re-seed `nam-ldap-svc-password` in every store **and restart each app**, since values resolve only at startup (§7.1). | +| D2 | **Turn login on where DEV is deliberately open** (HG; mxgw = mxaccessgw#231 item 3; ScadaBridge) | Turn it on / leave DEV open | **Turn it on.** DEV is where problems should surface. | +| D3 | **Automation identity** (CLI, deploy and drill scripts). **QA:** today GLAuth `multi-role`. **DEV:** today the login-off dev user (`ManagementAuthenticator.cs:63-71`), which stops working the moment DEV ScadaBridge login turns on. The same applies to OtOpcUa scripts if DEV `Security__Auth__DisableLogin=true` (Phase 0). | (a) A NAM *user-type* identity per tier in `APP_ADMIN_` + `APP_IDE_` + `APP_DEPLOY_`, password in the Mac Keychain. The scadaproj#58 account is lookup-only and should not double as a login unless IT agrees. (b) An interim DEV identity (a named admin's account) for DEV only. | **(a). A precondition of the DEV ScadaBridge step** (or (b) as a DEV interim) **and of the QA ScadaBridge step.** Also of the OtOpcUa step if Phase 0 finds DEV OtOpcUa login off. | +| D4 | **TLS trust** | (a) Install `zimmer-rootca` in `LocalMachine\Root`, `AllowInsecure=false`. (b) `AllowInsecure=true`: **accepts any certificate** (`ZB.MOM.WW.Auth.Ldap/Internal/NovellLdapConnection.cs:41-46`), so an active man-in-the-middle can read the service-account **and every user's** password. (c) Pin: in OtOpcUa, HG and ScadaBridge this is code-only (`ServerCertificateValidationCallback`), but **mxgw has a config-bound strict pin**, `MxGateway:Ldap:ServerCertificateThumbprintSha256` (`LdapServerCertificatePin.cs:9-21`). | **(a).** (b) is DEV only and short-lived, if at all. For mxgw: **remove any GLAuth pin** left in config (§7.3), and optionally pin the NAM DC leaf thumbprints. The certs expire 2027-03, so a pin must be renewed. | +| D5 | **Plant-floor and site groups** | now / later | **Later** (`ldap_mapping.md` §6). | +| D6 | **New group `UG_WW_APP_DEPLOY_{DEV,QA}`** (ScadaBridge `Deployer`) | ticket it / the rejected multi-role code (§3.1) | **Ticket it. Blocks the ScadaBridge step on each tier.** | +| D7 | **Group membership and exact names** | — | **Per person:** `dotnet run --project tools/LdapProbe -- --insecure --svc '' -u ` (service-account path; prompts for the service password). Or, as the person, `--insecure --self-bind -u ` (binds as them; `--svc` is ignored). **Families:** `-g 'UG_WW_*'`. Missing people get a ServiceNow membership request, not a wider mapping. Copy group names exactly (§2B). | --- -## 6. The LDAP block (same in all four apps, under each app's section) +## 6. The LDAP block (each app's section) The sections are: HG `Ldap`, mxgw `MxGateway:Ldap`, ScadaBridge `ScadaBridge:Security:Ldap` (`Security/ServiceCollectionExtensions.cs:24`), OtOpcUa `Security:Ldap`. @@ -368,10 +463,10 @@ The sections are: HG `Ldap`, mxgw `MxGateway:Ldap`, ScadaBridge `ScadaBridge:Sec "Server": "uswap-vdc-nam1.nam.zimmer.com", "Port": 636, "Transport": "Ldaps", - "AllowInsecure": false, // D4 - "FallbackServers": [ "uswap-vdc-nam2.nam.zimmer.com:636" ], // OtOpcUa: only after §2 ships + "AllowInsecure": false, // D4 + "FallbackServers": [ "uswap-vdc-nam2.nam.zimmer.com:636" ], // OtOpcUa: only with the §2 build "SearchBase": "DC=nam,DC=zimmer,DC=com", - "ServiceAccountDn": "", // D1; DEV interim: svc_igntadmin@nam.zimmer.com (Ignition team agreement) + "ServiceAccountDn": "", // D1; DEV interim: svc_igntadmin@nam.zimmer.com (Ignition agreement) "ServiceAccountPassword": "${secret:nam-ldap-svc-password}", "UserNameAttribute": "sAMAccountName", "DisplayNameAttribute": "name", @@ -380,179 +475,257 @@ The sections are: HG `Ldap`, mxgw `MxGateway:Ldap`, ScadaBridge `ScadaBridge:Sec } ``` -The env form follows the usual pattern, for example `Ldap__FallbackServers__0=uswap-vdc-nam2.nam.zimmer.com:636` -or `Security__Ldap__ServiceAccountPassword=${secret:nam-ldap-svc-password}`. +mxgw only: no `ServerCertificateThumbprintSha256` unless D4 chooses to pin the NAM DCs. + +The env form follows the usual pattern, e.g. `Ldap__FallbackServers__0=uswap-vdc-nam2.nam.zimmer.com:636`. --- ## 7. Runbook -**Order:** DEV HistorianGateway → MxAccessGateway → ScadaBridge → OtOpcUa (only after §2), then a soak of -at least a few working days with real logins, then QA in the same order. +**Order:** +1. **DEV:** HistorianGateway (**the canary**, §7.6 rule 6) → MxAccessGateway → ScadaBridge (after §2A, D3, D6) + → OtOpcUa (after §2). +2. A soak of a few working days with real logins. +3. **QA in the same order.** QA also needs **scadaproj#58** (QA never runs on `svc_igntadmin`). If DEV used the + interim account, switch DEV to the scadaproj#58 account during the soak, so that QA repeats a configuration + already proven on DEV. -**QA prerequisite:** the dedicated service account from **scadaproj#58** exists, and its password is -seeded as `nam-ldap-svc-password`. QA never runs on `svc_igntadmin`. If DEV used the interim account, -switch DEV to the scadaproj#58 account before or during the soak, so that QA repeats a configuration -already proven on DEV. **One app at a time:** edit, -restart, verify, then move on. +**One app at a time:** edit, restart, verify, then the next. -**Remote execution is limited to the `winrm` deploy scope** (`~/.local/bin/winrm`; the skill's *Scope* -section): preflight, backup, edit, restart, verify, rollback. Files are copied over SMB and SQL runs -directly from the Mac. servecli is retired. +**Remote execution only within the `winrm` deploy scope:** preflight, backup, edit, restart, verify, rollback. +Files go over SMB and SQL runs from the Mac. servecli is retired. -### 7.0 Phase 0 — preflight (read-only; deploy scope) +**Restart rules (review M4).** This is a **config-only** change: the same binary, no migration, no wire change. +So restarts are **rolling, standby first**: -Run per box: vd03, vq03, vq04. +| Pair | How | Why | +|---|---|---| +| **OtOpcUa QA pair** | Restart the standby (ServiceLevel 240/90), confirm it is healthy and back at its level, then the primary. The primary's restart is a failover; ScadaBridge's OPC UA client follows ServiceLevel, as WarmCanary showed. | The stop-both/start-both rule in OtOpcUa's records is for binary/schema upgrades. Config-only allows rolling [I: confirm against OtOpcUa's deploy notes in Phase 0]. **A bad LDAP key stops a node booting**, which is why the standby goes first. | +| **ScadaBridge QA centrals** | Standby central first, confirm it rejoins (one active, `/health/active`), then the active one, which gives a takeover of about 8–11 s. **Sites are not restarted.** | Central LDAP config only. The LocalDb stop-together rule applies to the *site* pairs' sync, which this change doesn't touch. The stop-together rule for binaries (§2A) does not apply. | +| **Single nodes** (DEV; HG/mxgw on each QA box) | One restart each. | — | -1. **DC reachability:** `Test-NetConnection uswap-vdc-nam1.nam.zimmer.com -Port 636`, then `-Port 389`, and - the same for nam2. -2. **TLS chain:** open an `SslStream` to nam1:636, or export the chain and `certutil -verify` it. This - settles D4. Also check whether `zimmer-rootca` is in `LocalMachine\Root`. -3. **Service-account bind, once,** from the Mac, without risking lockout: - `LDAPTLS_REQCERT=never ldapsearch -H ldaps://uswap-vdc-nam1.nam.zimmer.com:636 -x -D '' -W -b "DC=nam,DC=zimmer,DC=com" -s base dn`. On DEV with the interim account, use `svc_igntadmin@nam.zimmer.com`. -4. **Capture the current config for each app** (needed for rollback): - - hash the live appsettings; +A pair restarted together **is** an outage of its data plane (OPC UA or the site data path). Don't do it for this +change. + +### 7.0 Phase 0 — preflight (read-only; deploy scope; per box vd03, vq03, vq04) + +1. **DC reachability:** `Test-NetConnection` to nam1 and nam2 on 636 and 389. +2. **TLS:** check the chain to nam1:636 (`SslStream`, or `certutil -verify`) and whether `zimmer-rootca` is in + `LocalMachine\Root`. This settles D4. +3. **Service-account bind, once** from the Mac: + `LDAPTLS_REQCERT=never ldapsearch -H ldaps://uswap-vdc-nam1.nam.zimmer.com:636 -x -D '' -W -b "DC=nam,DC=zimmer,DC=com" -s base dn` +4. **Current config per app, kept for rollback:** + - hash the appsettings; - export the NSSM/service env; - - list **every** `Ldap__*`, `*__Ldap__*`, `*__DisableLogin`, `*__GroupToRole__*` entry, because env - overrides JSON; - - **record OtOpcUa's `Security__Auth__DisableLogin` value on all three boxes.** -5. **QA mxgw `dc=zb` vs box-local GLAuth `dc=scadabridge`:** with a test login against the current - config, record whether QA mxgw login works today. Either way the cutover replaces this config, but - the rollback target must be known. -6. **Secrets/KEK health per app store.** HG on vd03 is unconfirmed (historiangw#134 says "check vd03"). - - **ScadaBridge central:** record `Secrets:Store:Provider`. QA uses the shared SQL Server store (per - the 2026-11-13 QA pack §1, "shared `zbauth`/`zbsecrets`"). DEV is [I] `Sqlite`, the default. -7. **OtOpcUa DB overlay:** list the `LdapGroupRoleMapping` rows. There must be none, or none that - conflicts with §4.3. -8. **Deployed OtOpcUa build contains the §2 fix:** check that ProductVersion is ≥ the fix's merge. - Required only before §7.4. + - list every `Ldap__*`, `*__Ldap__*`, `*DisableLogin*`, `*__GroupToRole__*` entry; + - record **OtOpcUa's `Security__Auth__DisableLogin`** on all three boxes; + - record **mxgw's environment name** (it decides the overlay file; vd03 can't be Production while + `DisableLogin=true`); + - record **mxgw's `ServerCertificateThumbprintSha256`** (a leftover GLAuth pin blocks NAM); + - record **mxgw's base `GwAdmin`/`GwReader` entries**. +5. **QA mxgw `dc=zb` vs `dc=scadabridge`:** does a test login work today? This decides the rollback target. +6. **Secrets per app:** + - the store path, master-key source and KEK location for the §7.1 fallback. The family default is + `MasterKey:Source=Environment` / `ZB_SECRETS_MASTER_KEY`; file-based KEKs exist on some boxes. Record which + each app uses; don't assume. + - **ScadaBridge Central `Secrets:Store:Provider`.** QA is the shared SQL store (2026-11-13 QA pack §1); DEV is + [I] `Sqlite`. + - **OtOpcUa `Secrets:Replication:Enabled`** (`Host/Configuration/SecretsRegistration.cs:21`). If it's on, the + QA pair shares the secret through Akka replication, and "one store per box" becomes "seed once". + - HG KEK health on vd03 (historiangw#134). +7. **OtOpcUa DB overlay:** the `LdapGroupRoleMapping` rows (§4.3). +8. **Builds:** + - the deployed OtOpcUa build contains §2 (required before **§7.5**); + - the deployed ScadaBridge build contains §2A (before §7.4); + - on QA, the GLAuth `multi-role` user still maps to a role after §2/§2A (§2.4). -### 7.1 Seed the secret (once per store, before any config change) +### 7.1 Seed and verify the secret (before any config change) -- **Name:** `nam-ldap-svc-password`. It is the same name in every store, so a password rotation is N - `set`s with zero config edits. -- **Preferred way:** each app's **`/admin/secrets` page**. All four apps host the Secrets UI, admin-gated. - - On DEV, HG/mxgw/ScadaBridge are still login-off at this point, so the page is reachable. - - On QA, log in with the current GLAuth admin. - - This writes through the app's **own** store provider, which is correct for ScadaBridge's shared SQL - store too. -- **Fallback:** the on-box `secret` CLI, with per-invocation targeting (the CLI reads its own env, not - the app's): +- **Name:** `nam-ldap-svc-password`, the same in every store. + - Values resolve **only at startup**, so a rotation is re-seed every store plus restart every app (§7 restart + rules). + - An **unresolved** `${secret:}` throws `SecretNotFoundException` at boot (`SecretReferenceExpander.cs:74-77`), + so the app won't start. +- **Preferred:** each app's `/admin/secrets` page. It writes through the app's own provider, which is correct for + ScadaBridge's shared SQL store and for a replicated OtOpcUa store. + - DEV HG, mxgw and ScadaBridge are still login-off at this point. On QA, use the current GLAuth admin. +- **Fallback:** the `secret` CLI, with the store and master-key settings **from Phase 0 step 6**, per app: ```powershell - $env:Secrets__SqlitePath = ""; $env:Secrets__MasterKey__Source = "File"; $env:Secrets__MasterKey__FilePath = "" + $env:Secrets__SqlitePath = "" + $env:Secrets__MasterKey__Source = "" # family default: Environment (ZB_SECRETS_MASTER_KEY) + $env:Secrets__MasterKey__FilePath = "" secret.exe set nam-ldap-svc-password # prompts; never pass the value as an argument ``` - **Stores:** - - OtOpcUa: per box. - - mxgw: per box. - - HG: per box. - - ScadaBridge: **once per tier through Central.** The QA pair shares one SQL store. The ScadaBridge - site does no LDAP, so it needs nothing. -- **Verify** with a `get` round-trip through the same path. + - HG and mxgw: per box. + - OtOpcUa: per box, or once if replication is on. + - ScadaBridge: **once per tier through Central**. The site does no LDAP. +- **Verify the VALUE before the app's restart (review M2):** read it back (`get`) and bind with it once using + LdapProbe (`--svc ''`, pasting the read-back value). One good bind proves the stored secret. + A wrong secret found here costs 1–2 bad binds, instead of 2 per user login after the restart. -### 7.2 HistorianGateway (DEV: file; QA: NSSM env) +### 7.2 HistorianGateway (DEV: file; QA: NSSM env). The canary. -1. Back up `appsettings.Production.json` (DEV) or export the service env (QA). -2. Write the §6 block and the §4.1 mapping. Set `Dashboard:DisableLogin` to `false` on DEV, or remove - the key. QA: replace the `Ldap__*` and `Dashboard__GroupToRole__*` entries. -3. Restart `ZbHistorianGateway`. Then run §7.6. +1. Back up the file or env. +2. Write §6 and §4.1. On DEV, set `DisableLogin` to `false`. On QA, replace the `Ldap__*` entries and remove the + `SCADA-*` `GroupToRole` entries. +3. Restart `ZbHistorianGateway`. Run §7.6 **fully, including the failover check**, before touching any other app. -### 7.3 MxAccessGateway (DEV and QA: file) +### 7.3 MxAccessGateway (the file for its environment name) -1. Back up. Write `MxGateway:Ldap` (§6) and `MxGateway:Dashboard:GroupToRole` (§4.2). On DEV, set - `DisableLogin` to `false`; this is D2, mxaccessgw#231 item 3. -2. Leave the API-key store under `data\` and the `MxGateway__ApiKeys__Pepper` env alone. -3. Restart. Run §7.6. +1. Back up the base and overlay files. +2. Write `MxGateway:Ldap` (§6) and `GroupToRole` (§4.2), and delete the base `GwAdmin`/`GwReader`. +3. **Remove the `ServerCertificateThumbprintSha256` pin**, or replace it with the NAM DC leaf thumbprints (D4). +4. On DEV, set `DisableLogin` to `false` (D2, mxaccessgw#231 item 3). If that makes the box eligible to run as + Production, record the environment name. Don't change it in this step. +5. Leave the API-key store under `data\` and the pepper env alone. +6. Restart, then run §7.6. -### 7.4 ScadaBridge (Central only; the Site is untouched) +### 7.4 ScadaBridge (Central only) -**Preconditions:** D6 (the `UG_WW_APP_DEPLOY_` group exists and has members) and, on QA, D3 (a NAM -automation identity, stored in the Mac Keychain). +**Preconditions:** +- §2A deployed; +- D6: `UG_WW_APP_DEPLOY_` exists, has members, and is mapped; +- D3: the automation identity works. On DEV it is needed **before** login turns on, because the dev-user path + ends then. -1. Back up `appsettings.Central.json` (and the env). -2. Run the §4.4 SQL. +1. Back up `appsettings.Central.json` and the env. +2. Add the role mappings (§4.4, CLI preferred). 3. Write `ScadaBridge:Security:Ldap` (§6). -4. **Remove BOTH** `ScadaBridge:Security:Auth:DisableLogin` and `AllowOutsideDevelopment` on DEV. - Removing only `AllowOutsideDevelopment` while `DisableLogin=true` stays makes `DisableLoginGuard` - crash-loop the service. -5. QA: replace the GLAuth `Ldap` values. Stop both centrals and start them together. -6. Re-point every script that logs in as `multi-role` (`apply.sh`, the drill and deploy packs) at the D3 - identity. -7. Check that the CLI's `/auth/token` login works with it. +4. On DEV, **remove BOTH** `ScadaBridge:Security:Auth:DisableLogin` and `AllowOutsideDevelopment`. Removing only + the second while `DisableLogin=true` makes `DisableLoginGuard` crash-loop the service. +5. On QA, replace the GLAuth values. +6. Restart: DEV, the single central. QA, rolling, standby central first (§7 restart rules). +7. Re-point every script that used `multi-role` (or relied on login-off) at the D3 identity: `apply.sh`, the + drill and deploy packs. Confirm `/auth/token` works with it. -### 7.5 OtOpcUa AdminUI (env, both tiers; only after §2 is deployed) +### 7.5 OtOpcUa AdminUI (service env; only after §2 is deployed) -1. Back up the service env. -2. Add the §6 block as `Security__Ldap__*` and the §4.3 `GroupToRole` keys. Keep the files' - `Transport`/`DevStubMode`. -3. If `Security__Auth__DisableLogin=true`, set it to `false`. -4. Restart: on DEV the one node; on QA, stop the pair and start it together per OtOpcUa's procedure. -5. The OPC UA data plane (`otua_` keys) is unaffected. +1. Back up the env. +2. Add §6 as `Security__Ldap__*` and the §4.3 `GroupToRole`. Keep the files' `Transport`/`DevStubMode`. +3. If `Security__Auth__DisableLogin=true`, set it to `false`, and if scripts relied on it, have D3 in place first. +4. Restart: DEV, the single node. QA, **rolling, standby first** (§7 restart rules). Watch ServiceLevel and the + ScadaBridge `WarmCanary` connection across the primary's restart. +5. **Existing sessions:** AdminUI cookies and bearer tokens issued under GLAuth stay valid after the switch until + they expire. Either: + - invalidate them (restart both nodes, if the cookie and data-protection keys are per process [I], or rotate + the signing or data-protection key); or + - record their remaining lifetime and accept it. -### 7.6 Verify (each app, right after its restart; stop after 2 failures, because of lockout) + ScadaBridge needs no such step: its group refresh ends sessions whose roles change + (`DirectoryGroupRefresher.cs:141-142`). -1. **Negative control first:** a bogus user and password. Expect a clean "invalid / not authorized" - with **no** `failed system-side` WRN. - - A `service-bind`-stage WRN means the secret value is wrong. - - A `search`-stage WRN means the secret didn't resolve (the password is empty). - - A `connect`-stage WRN means network or TLS. -2. **One real login per mapped role** (Administrator, Designer, Viewer, and Deployer for ScadaBridge). - The UI must show exactly that role. -3. **A user in no mapped group is denied.** Every app fails closed when no group matches. -4. **`${secret:}` proof:** confirm no `*ServiceAccountPassword` sits in env, and the store `get` - matches. -5. **Failover, once per tier, on HG:** block nam1:636 briefly. Login must still work, with the - `sticky preference moved` line. Then restore. - - **OtOpcUa** gets its own nam1→nam2 check (acceptance A2), because it is the app with the new code - path. +### 7.6 Verify (each app, right after its restart) + +1. **Negative control first:** a bogus user and password. Expect a clean "invalid / not authorized" and **no** + `failed system-side` warning. + - A `service-bind`-stage warning means the stored service secret is wrong. **Stop: every further attempt costs + the shared account 2 bad binds.** + - A `connect`-stage warning means network or TLS. + - (An unresolved `${secret:}` never gets this far; the app fails at boot with `SecretNotFoundException`.) + - (OtOpcUa logs these lines only with the §2 logger fix.) +2. **One real login per mapped role:** Administrator, Designer, Viewer, and Deployer for ScadaBridge. The UI shows + exactly that role, and the user typed a **bare sAMAccountName** (§1.3). +3. **A user whose groups map to no role is refused**, on the login page **and** at the token endpoint where one + exists (OtOpcUa and ScadaBridge `/auth/token`). This is the §3.2 standard: in OtOpcUa and ScadaBridge it holds + only with the §2/§2A builds; mxgw and HG already refuse. +4. **`${secret:}` proof:** no `*ServiceAccountPassword` sits in env, and the stored value was bind-verified + (§7.1). +5. **Failover:** + - On HG (the canary), once per tier: block nam1:636 briefly. Login still works and the log shows `sticky + preference moved`; then restore. + - **OtOpcUa** gets its own nam1→nam2 check (acceptance A2). +6. **Stop rule (review M2):** stop the cutover on **2 failed logins attributable to the service account, across + all apps, within 15 minutes.** Count `service-bind` warnings, not user typos. Diagnose before any retry; ask IT + to check the account's lockout state. ### 7.7 Rollback (per app) -- Restore the backed-up file or env and restart. That brings back the previous login setup, including - ScadaBridge's two-key disable and HG's `DisableLogin=true`. -- The seeded secrets are inert once nothing references them. -- ScadaBridge `LdapGroupMappings` `UG_WW_*` rows grant nothing while login is off or pointed at GLAuth. - Delete them only for a clean slate. -- The §2 OtOpcUa build is independent. Don't roll it back over an auth problem. +- Restore the backed-up files or env and restart. On QA, use the same rolling order: standby first. + - mxgw: also restore its base `appsettings.json` (the `GwAdmin`/`GwReader` entries) and any pin. +- **Point the scripts back at `multi-role`** (QA), or back at login-off (DEV ScadaBridge). +- If the shared account got locked, **IT clears the lockout.** Until then, every NAM-backed app is down for login; + roll those apps back to GLAuth or login-off first. +- The seeded secrets are inert once nothing references them. The ScadaBridge `UG_WW_*` mapping rows grant nothing + while login is off or on GLAuth. +- **Keep** the §2/§2A/§2B builds. The zero-role refusal is the family standard and stands on its own. --- ## 8. Acceptance -- **A1:** the §2 OtOpcUa failover test passes on the redundant GLAuth pair, and the reflection guard's - mutation check fails as expected. +- **A1:** the §2 offline tests pass: + - failover on the redundant GLAuth pair with the library's log line; + - zero-role refusal (cookie + token, including the mapper-throws case); + - a DEV-shaped config boots; + - the reflection guard fails under its mutation. + - The §2A tests pass too. - **A2:** on each tier, the OtOpcUa AdminUI login survives nam1 being blocked, through nam2. -- **A3:** on each tier and app, every §7.6 check passes. -- **A4:** no app maps any group to two roles. Check by reading each tier's config and the ScadaBridge - table. -- **A5:** QA automation (CLI, deploy and drill scripts) runs on the D3 identity, and nothing logs in as - `multi-role`. -- **A6:** every app on QA (and on DEV after the soak) binds as the scadaproj#58 account, and none uses - `svc_igntadmin`. +- **A3:** every §7.6 check passes for each tier and app. +- **A4:** no app maps any group to two roles, and no stale GLAuth mapping remains. Check the **effective** + config: env plus all overlays plus base, including mxgw's `GwAdmin`/`GwReader`, and the ScadaBridge table. +- **A5:** automation runs on the D3 identity. Nothing uses `multi-role`, or relies on login-off, on a cut-over + app. +- **A6:** QA (and DEV after the soak) binds as the scadaproj#58 account and never as `svc_igntadmin`. ## 9. Open questions -1. Does OtOpcUa run the library's `LdapOptionsValidator` on the mapped options? (§2.2 step 3) -2. Does QA mxgw login work today, given the `dc=zb` vs `dc=scadabridge` mismatch? (Phase 0 step 5) +1. ~~Does OtOpcUa run the library's validator?~~ **Answered: no** (§2.1 item 4). The validation is ported + selectively (§2.2 item 4). +2. Does QA mxgw login work today (`dc=zb` vs `dc=scadabridge`)? Phase 0 step 5. 3. What is the HG KEK state on vd03? (historiangw#134) -4. Should the ScadaBridge QA central pair's shared SQL secret store also serve the D3 identity's - password? No: that lives in the Mac Keychain, not on the boxes. -5. Do `UG_WW_*` memberships still match the 2026-08-12 inventory? It is **unverified now**; D7 - re-enumerates. -6. Is ignitionoee still on hold, and does it get new groups? Out of scope here. +4. Is OtOpcUa's AdminUI cookie or data-protection key per process or shared? That decides the §7.5 step 5 method + [I]. +5. Does OtOpcUa's deploy procedure allow a rolling restart for config-only changes? Confirm against its records + (§7 restart rules). +6. Do the `UG_WW_*` memberships and exact names still match 2026-08-12? D7 re-enumerates. +7. ignitionoee: still on hold. ## 10. Corrections from the 2026-08-13 plan | 08-13 plan said | Fact (2026-11-15) | |---|---| -| Phase 1: redeploy all four apps to Auth 0.2.1 | Every deployed build already runs 0.4.1 (ScadaBridge 0.5.0). **Phase deleted.** | -| Preflight over servecli `:2222` | servecli is retired. The `winrm` deploy scope plus SMB plus direct SQL replace it. | -| mxgw on vd03 has LDAP login enabled | `MxGateway:Dashboard:DisableLogin=true` on vd03. | -| The same target block works in all four apps | **OtOpcUa drops `FallbackServers`** (and `BindMode`, `UserBindTemplate`, `AcceptDomainQualifiedNames`). A code fix (§2) is now a prerequisite. | -| ScadaBridge `INSERT INTO LdapGroupMapping …` with two rows for `UG_WW_APP_IDE_DEV` | The table is **`LdapGroupMappings`** with a **unique** `LdapGroupName`, so the second row fails. Replaced by the one-group-one-role rule (§3) and an idempotent script (§4.4). `Deployer` now comes from the new group D6. | -| `ldap_mapping.md`: "only ScadaBridge can express two roles per group" | It can't. Rewritten as the canonical matrix. | -| Seed ScadaBridge **central and site** stores with the CLI | Seed **once through ScadaBridge Central's `/admin/secrets`**. QA Central uses the shared SQL store, and the site does no LDAP. | -| OtOpcUa order: before ScadaBridge | OtOpcUa goes **last**, after its fix ships. | -| Service account `svc_igntadmin` everywhere, a dedicated account "later" | The target is the dedicated shared account from **scadaproj#58**, and it is a **QA prerequisite**. `svc_igntadmin` is a DEV-only interim, with the Ignition team's agreement. | -| No plan for QA automation | The CLI and scripts depend on GLAuth `multi-role`, so D3 is required before QA ScadaBridge. | -| `ldap_mapping.md` §1: OtOpcUa roles are Viewer/Designer/Administrator | The DB overlay enum is those three (`AdminRole.cs`), and the AdminUI's `DriverOperator` policy also honours `Operator` (`ServiceCollectionExtensions.cs:201-202`). That is still unmapped here. | +| Phase 1: redeploy to Auth 0.2.1 | Every build already runs 0.4.1 (ScadaBridge 0.5.0). Phase deleted. | +| Preflight over servecli `:2222` | servecli is retired; the winrm deploy scope plus SMB plus SQL replace it. | +| mxgw on vd03 has LDAP login on | `DisableLogin=true` (and so it isn't running as Production). | +| One target block for all four apps | OtOpcUa drops `FallbackServers` and three more options, and logs nothing. Fixed in §2. | +| A zero-group user is denied in every app | **Only mxgw and HG refuse.** OtOpcUa and ScadaBridge sign in with no roles. Fixed in §2/§2A; the standard is §3.2. | +| ScadaBridge `INSERT INTO LdapGroupMapping`, two rows for `APP_IDE` | The table is `LdapGroupMappings`, unique `LdapGroupName`. One-group-one-role plus the new D6 group; CLI preferred over SQL. | +| `ldap_mapping.md`: ScadaBridge can grant two roles per group | It can't. Rewritten as the canonical matrix. | +| Seed the ScadaBridge central and site stores with the CLI | Seed once through Central `/admin/secrets`; the site does no LDAP. | +| Stop after 2 failures; every failed login costs both DCs | A wrong *user* password costs 1 bind. A wrong *service* secret costs 2 per login and locks the shared account. New stop rule, a no-lockout ask and value verification. | +| Service account `svc_igntadmin` now, dedicated "later" | Target: scadaproj#58, a QA prerequisite; `svc_igntadmin` is a DEV interim only, with Ignition's agreement. | +| OtOpcUa before ScadaBridge | OtOpcUa last, after its fix. | +| (silent) automation | DEV and QA automation lose their identity on cutover. D3 is a precondition. | +| (silent) restarts | Rolling, standby first, for config-only changes. Restarting a pair together is a data-plane outage. | + +## 11. Review 2026-11-15: findings and disposition + +| # | Finding | Disposition | +|---|---|---| +| B1 | OtOpcUa and ScadaBridge sign in users with zero mapped roles (OtOpcUa even when the mapper throws); `AuthenticatedRead`/bare `[Authorize]` then grant read access to any AD user | **Applied.** New standard §3.2; OtOpcUa fix §2.2 item 2 (refuses on throw too, reversing `Login_when_role_mapper_throws_signs_in_with_no_role_claims`); ScadaBridge Phase A2 §2A with issue text and a deploy; Viewer semantics §3.2; §7.6 step 3 and `ldap_mapping.md` §1 rewritten. | +| B2 | Calling the library validator would stop OtOpcUa booting on DEV/QA (`ServiceAccountDn` required) | **Applied.** §2.2 item 4 ports only the `FallbackServers` and BindMode/UserBindTemplate rules, with a DEV-shaped boot test. Open question 1 answered (§2.1 item 4). | +| M1 | No logger passed to the library service | **Applied.** §2.2 item 3. | +| M2 | Lockout on the shared account; §1.3 had it backwards | **Applied.** §1.3 table; D1 no-lockout ask; §7.1 value verification; HG as canary; §7.6 rule 6 stop rule. | +| M3 | DEV automation breaks when DEV login turns on | **Applied.** D3 covers DEV (dev-user path, `ManagementAuthenticator.cs:63-71`); a precondition in §7.4/§7.5. | +| M4 | "Data plane unaffected" was misleading; pairs restarted together are an outage | **Applied.** §7 restart rules: rolling, standby first, for config-only changes. The OtOpcUa rolling allowance is [I] pending Phase 0 / open question 5. | +| M5 | HG group match is case-sensitive after binding | **Applied.** §2B (optional Phase A3) with issue text; exact names from LdapProbe in §4 and D7. | +| M6 | mxgw config-bound certificate pin | **Applied.** Phase 0 step 4; §7.3 step 3; D4 corrected. | +| m | §2.4 / §7.0 cross-references | **Applied** (→ §7.5). | +| m | Unresolved `${secret:}` fails at boot | **Applied** (§7.1, §7.6). | +| m | Rotation needs restarts | **Applied** (D1, §7.1). | +| m | `AcceptDomainQualifiedNames` only applies in User mode | **Applied** (§1.3; users type the bare sAMAccountName). | +| m | D7 command was wrong | **Applied** (`-u` with `--svc`, or `--self-bind -u`). | +| m | Secrets CLI hardcoded `File` | **Applied** (Phase 0 step 6 supplies the values; default noted). | +| m | OtOpcUa secret replication | **Applied** (Phase 0 step 6; §7.1 stores). | +| m | mxgw vd03 can't be Production with `DisableLogin` | **Applied** (§1.2; Phase 0 step 4; §7.3 step 4). | +| m | mxgw base `GwAdmin`/`GwReader` merge | **Applied** (§4.2 delete from base; A4 checks the effective config). | +| m | Existing OtOpcUa sessions survive cutover | **Applied** (§7.5 step 5; ScadaBridge self-ends via refresh). | +| m | Rollback gaps | **Applied** (§7.7: scripts, AD lockout, rolling on QA). | +| m | `AllowInsecure` accepts any certificate | **Applied** (D4(b)). | +| m | Stale OtOpcUa validator comment | **Applied** (§2.1 item 5, §2.2 item 7). | +| m | ScadaBridge SQL bypasses audit and cache | **Applied** (§4.4: CLI/UI preferred; SQL fallback with a 30 s wait). | +| n | `LdapOptions` doc default `10.100.0.35` vs code `localhost` | **Applied** (§2.1 item 5). | +| n | Reflection test: compare lists by content, both directions | **Applied** (§2.2 item 5). | +| n | §4.4 DEPLOY row conditional | **Applied.** | diff --git a/ldap_mapping.md b/ldap_mapping.md index 7051739..c5aa883 100644 --- a/ldap_mapping.md +++ b/ldap_mapping.md @@ -22,7 +22,7 @@ role in each ZB.MOM.WW app. | **OtOpcUa** (AdminUI) | `Viewer`, `Designer`, `Administrator`. The DB-overlay enum is `AdminRole.cs`. The `DriverOperator` policy also honours `Operator` (`Security/ServiceCollectionExtensions.cs:201-202`), but only through config `GroupToRole`, not the DB overlay. | `Security:Ldap:GroupToRole`, unioned with the `LdapGroupRoleMapping` DB overlay (`OtOpcUaGroupRoleMapper.cs`) | `Dictionary` (`Security/Ldap/LdapOptions.cs:84`) | | **ScadaBridge** | `Administrator`, `Designer`, `Deployer`, `Viewer`, `Operator`, `Verifier` (`Security/Roles.cs:45-56`). **Each policy requires its own role:** `Administrator` does not imply `Deployer` (`Security/AuthorizationPolicies.cs:190-202`). | the **`LdapGroupMappings`** table (database), plus `SiteScopeRules` for site scoping | **unique** `LdapGroupName` (`ConfigurationDatabase/Configurations/SecurityConfiguration.cs:26`), one `Role` per row | | **MxAccessGateway** | `Viewer`, `Administrator`. The validator rejects anything else (`GatewayOptionsValidator.cs:506-517`). | `MxGateway:Dashboard:GroupToRole` | `Dictionary` (`Configuration/DashboardOptions.cs:69`) | -| **HistorianGateway** | `Viewer`, `Administrator` (`Dashboard/DashboardRoles.cs`) | `Dashboard:GroupToRole` | `IReadOnlyDictionary` (`Dashboard/DashboardOptions.cs:44`) | +| **HistorianGateway** | `Viewer`, `Administrator` (`Dashboard/DashboardRoles.cs`) | `Dashboard:GroupToRole` | `IReadOnlyDictionary` (`Dashboard/DashboardOptions.cs:44`), **case-sensitive once bound** (plan §2B) | Things that are easy to get wrong: @@ -31,8 +31,20 @@ Things that are easy to get wrong: the configuration UI. - **`Administrator` is the literal string in all four apps.** MxGateway's constant is named `DashboardRoles.Admin`, but its value is `"Administrator"`. -- **Every app fails closed when no group matches.** An unmapped group grants nothing, so leaving a group - out is the safe default. +- **No role, no login: the family standard (DECIDED 2026-11-15).** Every app refuses sign-in, cookie **and** + token, when the user's groups map to no role, including when the role lookup fails. + - **Today only mxgw** (`DashboardAuthenticator.cs:66-70`) **and HG** (`:56-64`) **do this.** + - **OtOpcUa** (`Security/Endpoints/AuthEndpoints.cs:124-158`, even when the mapper throws) **and ScadaBridge** + (`CentralUI/Auth/AuthEndpoints.cs:59-115`) sign such a user in with no roles. Their read-only pages + (`AuthenticatedRead` / bare `[Authorize]`) would then be open to any AD user. + - The cutover plan's Phase A (OtOpcUa) and A2 (ScadaBridge) fix this **before** either app is pointed at NAM. + - Once fixed, an unmapped group grants nothing, so leaving a group out is the safe default. +- **`Viewer` in OtOpcUa means "holds a role, so may sign in".** No OtOpcUa policy checks `Viewer`; its read pages + only require an authenticated user. Under the standard above, being signed in requires *some* mapped role, so + the `Viewer` cells (§4) are what grant AdminUI read access. +- **HistorianGateway matches group names case-sensitively** in practice. The binder replaces its + `OrdinalIgnoreCase` default with a plain `Dictionary` (cutover plan §2B). **Copy group names exactly as + LdapProbe prints them** in every app. ## 2. Why one role per group @@ -119,7 +131,8 @@ the interim `svc_igntadmin@nam.zimmer.com`, with the Ignition team's agreement. ```bash dotnet run --project tools/LdapProbe -- --insecure --svc '' -g 'UG_WW_*' # families + counts -dotnet run --project tools/LdapProbe -- --insecure --svc '' --self-bind # one person's groups +dotnet run --project tools/LdapProbe -- --insecure --svc '' -u # one person's groups (service-account path) +dotnet run --project tools/LdapProbe -- --insecure --self-bind -u # the same, binding as that person (--svc ignored) ``` **Blast radius** (08-12 counts): @@ -150,7 +163,8 @@ dotnet run --project tools/LdapProbe -- --insecure --svc '' --s ## 7. Prerequisites 1. **Auth library on every deployed build: met.** 0.4.1, and 0.5.0 for ScadaBridge (cutover plan §1.1). -2. **OtOpcUa must pass `FallbackServers` through** before its cutover (cutover plan §2). +2. **OtOpcUa must pass `FallbackServers` through and refuse zero-role logins** before its cutover (cutover plan §2). + ScadaBridge must refuse zero-role logins before its cutover (§2A). 3. **New AD groups and memberships come by ServiceNow ticket.** `UG_WW_APP_DEPLOY_{DEV,QA}` is the first (D6), and the dedicated service account is scadaproj#58. 4. **Verify with real accounts** (§5) before rollout. The 08-12 inventory came from one architect