From 1d344a0c0812d6bb842839b4f10a4879260b849c Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Sun, 15 Nov 2026 20:28:09 -0500 Subject: [PATCH] docs(ldap): rewrite the NAM AD cutover plan; one-group-one-role canonical mapping - New plan docs/plans/2026-11-15-nam-ldap-cutover.md (supersedes the 2026-08-13 plan, now a pointer): current state per app/tier, Phase A OtOpcUa fix (ToLibraryOptions drops FallbackServers/BindMode/ UserBindTemplate/AcceptDomainQualifiedNames; reflection completeness test), decisions D1-D7 (dedicated service account scadaproj#58 = QA prerequisite), winrm deploy-scope runbook, idempotent ScadaBridge LdapGroupMappings SQL, corrections table. - ldap_mapping.md rewritten as the canonical matrix under the rule 'one AD group grants exactly one role per app'; ScadaBridge Deployer moves to a new UG_WW_APP_DEPLOY_ group (was a two-row insert the unique index rejects). Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8 --- .../plans/2026-08-13-vd03-nam-ldap-cutover.md | 268 +-------- docs/plans/2026-11-15-nam-ldap-cutover.md | 558 ++++++++++++++++++ ldap_mapping.md | 361 ++++------- 3 files changed, 677 insertions(+), 510 deletions(-) create mode 100644 docs/plans/2026-11-15-nam-ldap-cutover.md diff --git a/docs/plans/2026-08-13-vd03-nam-ldap-cutover.md b/docs/plans/2026-08-13-vd03-nam-ldap-cutover.md index d43ea08..ebc3d11 100644 --- a/docs/plans/2026-08-13-vd03-nam-ldap-cutover.md +++ b/docs/plans/2026-08-13-vd03-nam-ldap-cutover.md @@ -1,266 +1,4 @@ -# VD03 NAM AD LDAP cutover — plan (NOT executed) +# VD03 NAM AD LDAP cutover: superseded -> **Status lives in Gitea.** Open items from this file are tracked as issues on -> [gitea.dohertylan.com/dohertj2/scadaproj](https://gitea.dohertylan.com/dohertj2/scadaproj/issues) -> (label `migrated`, 2026-11-06). This file is a historical/design record — do not track status -> here; file new work as an issue. - -**Written 2026-08-13. Status: PLAN ONLY.** Execution (VD03, then QA) → #6; consider the Auth `0.4.1` bump first → #5. Swap every auth-bearing service on -`wonder-app-vd03` from its current login posture (mostly login-disabled) to the real -Zimmer NAM Active Directory, with the service-account password held as a -`${secret:}` reference in each app's encrypted Secrets store — never in config. - -Grounded in: [`ldap_setup.md`](../../ldap_setup.md) (directory facts + the 2026-08-13 -end-to-end verification via the HistorianGateway docker container), -[`ldap_mapping.md`](../../ldap_mapping.md) (the `UG_WW_*` → role mapping, §4), -and the wonder deploy records (memory: `wonder-upgrade-program`). - -## Scope - -| Service on VD03 | In scope | LDAP config surface | Login state today | -|---|---|---|---| -| OtOpcUa AdminUI | ✅ | `Security:Ldap` (+ `GroupToRole` subkey, merged with a DB overlay) | LDAP enabled; target = TBD in preflight (data plane is API-key, **not** LDAP — untouched) | -| ScadaBridge (central UI) | ✅ | `ScadaBridge:Security:Ldap` in `appsettings.Central.json`; roles in the **`LdapGroupMapping` DB table**, not config | **Login DISABLED** (`DisableLogin=true` + `AllowOutsideDevelopment=true` — the two-key set) | -| MxAccessGateway dashboard | ✅ | `MxGateway:Ldap` + `MxGateway:Dashboard:GroupToRole` (gRPC stays API-key, untouched) | LDAP enabled per 08-12 notes; target = TBD in preflight | -| HistorianGateway dashboard | ✅ | `Ldap` (root section) + `Dashboard:GroupToRole` (gRPC stays API-key, untouched) | **Login DISABLED** (`Dashboard:DisableLogin=true`, deliberately open) | -| Overview | ❌ exempt | — | No login **by design** (holds no credentials; references no Auth package) | - -Out of scope: windev's OtOpcUa/mxgw instances, the QA pair (VQ03/VQ04 — do it as a -follow-on once VD03 has soaked, → #6; QA is where the 2-node/failover behaviour actually gets -exercised), and OtOpcUa's OPC UA data plane (API-key auth since Gitea #520). - -> ⚠️ **ignitionoee (router): LDAP setup ON HOLD** — explicit decision 2026-08-13. Its role -> vocabulary is not the canonical set (its admin role is literally `"Admin"`, not -> `"Administrator"`), so no existing `UG_WW_*` group maps onto it — a NAM cutover there -> would first require **minting new AD groups**. Do not wire its LDAP as part of this plan -> or its follow-ons; it keeps its current auth until the groups exist and are decided. - -## The target LDAP block (identical shape in all four apps) - -```jsonc -{ - "Enabled": true, - "Server": "uswap-vdc-nam1.nam.zimmer.com", - "Port": 636, - "Transport": "Ldaps", - "AllowInsecure": false, // see TLS decision below - "FallbackServers": [ "uswap-vdc-nam2.nam.zimmer.com:636" ], - "SearchBase": "DC=nam,DC=zimmer,DC=com", - "ServiceAccountDn": "svc_igntadmin@nam.zimmer.com", - "ServiceAccountPassword": "${secret:nam-ldap-svc-password}", - "UserNameAttribute": "sAMAccountName", - "DisplayNameAttribute": "name", - "GroupAttribute": "memberOf" -} -``` - -Facts already proven live (2026-08-13, HG docker → real NAM AD): the UPN bind as -`svc_igntadmin` works (**not** `svc_igntnapp` — that is Ignition's account), the -domain-root SearchBase works **on Auth 0.2.1 only**, `memberOf` DNs collapse to bare -CNs so `GroupToRole` keys are plain `UG_WW_*` names, and `FallbackServers` walks both -DCs on system-side failures. Users log in with the **bare sAMAccountName**. - -## Hard prerequisite: every deployed build must carry Auth 0.2.1 - -**None of the four deployed builds has it** (pins landed 2026-08-13, after the last -deploy round): OtOpcUa runs `c51c5998`, ScadaBridge `20f2ae05`, mxgw the 08-12 build -(Auth 0.2.0), HG `e9c31da` (Auth **0.1.5**). On anything below 0.2.1 a domain-root -SearchBase fails **every** login as `ServiceAccountBindFailed` (AD continuation -referrals), and on 0.1.5 there is no `FallbackServers` at all. Narrowing SearchBase -below the root is NOT an acceptable workaround — user objects span multiple OUs. - -So **Phase 1 is a redeploy of all four apps at their current default-branch tips** -(each already pins 0.2.1 and is pushed: OtOpcUa `08e33fc7`, ScadaBridge `d28824d9`, -mxgw `1cb14d2`, HG `e42ff31`). This folds into the standing wonder-upgrade practice — -HG is behind `main` anyway. Run the standard per-app preflight (migration-delta check, -appsettings SHA capture, env backup) from the `wonder-upgrade-program` memory. - -## Decisions to confirm before executing - -1. **Service account.** Use `svc_igntadmin` (proven), or request a dedicated - `svc_zbmomww` via ServiceNow first (the `UG_WW_*` groups are ticket-provisioned, so - the process exists). Reusing the Ignition admin account couples our uptime to their - rotations. **Recommended: start with `svc_igntadmin`, file the dedicated-account - ticket in parallel, swap later by rotating one secret per store.** -2. **Enabling login on services that are deliberately open.** ScadaBridge and HG run - login-disabled on this box today, on purpose. This cutover flips both to - authenticated. Confirm that is wanted on the DEV box (it is the point of the - exercise, but it changes who can reach those dashboards). -3. **Who gets in: VD03 = DEV tier ⇒ map only `_DEV` groups** (ldap_mapping §3 — a - deployment maps only its own tier; mapping PROD groups here would make every DEV - grant a cross-tier grant). Verify the intended users are actually members: - `UG_WW_APP_ADMIN_DEV` (7), `UG_WW_HIST_ADMIN_DEV` (7), `UG_WW_APP_IDE_DEV` (6), - `UG_WW_APP_IDE_RO_DEV` (2). If someone who needs access is in none, that is a - ServiceNow group-membership request **before** cutover, not a mapping widen. - (`BTMGR_RO` has no DEV group — omit.) Check with - `ldapprobe --insecure --svc svc_igntadmin@nam.zimmer.com --self-bind `. -4. **TLS.** Try `AllowInsecure: false` first — the box is on the corporate network and - Windows machine stores on managed boxes usually carry `zimmer-rootca` (installing it - is sufficient; the only chain error observed is `UntrustedRoot`, and the RSA-1024 - hazard is OpenSSL-container-specific, not Windows). If the preflight cert check - fails: install `zimmer-rootca` into LocalMachine\Root (preferred) or fall back to - `AllowInsecure: true` (DEV-acceptable; transport still encrypted). -5. **ScadaBridge plant-floor/operator rows** (`*_OPERATOR`, `SITE_ADMIN_*`, - `SUPERVISOR`/`ENGINEER`): ldap_mapping flags these ⚠ DECIDE and they are not - env-scoped. **Recommended: leave them out of this cutover** — seed only the - platform rows (below) and add operator rows when a real site use-case lands. - -## Phase 0 — preflight (read-only, no changes) - -From the box (servecli :2222; note servecli never survives a reboot — restart it first -if dead): - -- **Network:** `Test-NetConnection uswap-vdc-nam1.nam.zimmer.com -Port 636` (and nam2). -- **TLS trust:** from PowerShell, open an `SslStream` to nam1:636 (or - `certutil -verify` the exported chain) to learn whether `zimmer-rootca` is trusted → - settles decision 4. -- **Service-account credential, once, without lockout risk** (bad binds count on both - DCs per app attempt; policy is 5/15 min): a single bind test from the Mac — - `LDAPTLS_REQCERT=never ldapsearch -H ldaps://uswap-vdc-nam1.nam.zimmer.com:636 -x -D - svc_igntadmin@nam.zimmer.com -W -b "DC=nam,DC=zimmer,DC=com" -s base dn`. -- **Capture current state per app:** SHA the live appsettings files; record the NSSM - registry env (`Parameters\AppEnvironmentExtra` for mxgw/HG; the OtOpcUa/ScadaBridge - service envs) — **check no `Ldap__*` keys lurk in service env, which would silently - override the JSON edits**; record current `DisableLogin` posture. -- **Secrets plumbing:** confirm the four stores + file-based KEKs are healthy (they - were authored + round-trip-verified 2026-08-12; KEK backups at - `E:\ApiInstall\_kek-backup-20260812T070057`). Stores live outside content roots - (OtOpcUa `E:\ApiInstall\OtOpcUa-data\`, mxgw + HG under their `data\`, - ScadaBridge per its overlays). - -## Phase 1 — redeploy all four apps at Auth-0.2.1 tips - -Standard wonder deploy recipe per app (memory: `wonder-app-vd03-mxgateway-deploy` + -per-app records). Self-contained win-x64 publishes (box has no .NET 10 runtime). -Expected deltas are small (each app's tip is its 08-12 deployed SHA + the 0.2.1 pin -± UI-sweep commits for HG); still run the migration-delta check — HG's jump -(`e9c31da → e42ff31`) carries the Theme 0.4.1/Health 0.3.0/Secrets 0.6.2 sweep, so -give it the full preflight (its Secrets 0.6.2 store-path guard will validate the -box's paths — they were fixed 08-12, so this should pass, but it is the guard that -bit OtOpcUa last round). - -**Gate:** all services healthy on their current (pre-LDAP-swap) config before touching -auth. Do not combine the redeploy and the auth swap in one restart — two variables. - -## Phase 2 — seed the secret into each app's store - -Secret name: **`nam-ldap-svc-password`** (same name in every store, so the config -reference is identical everywhere and rotation is a mechanical sweep). - -Use the on-box CLI `E:\ApiInstall\_tools\secret` (0.6.2, self-contained). **Trap -(proven 08-12): bare CLI verbs read the CLI's own env, NOT the target app's config** — -target each store per-invocation: - -```powershell -$env:Secrets__SqlitePath = "" -$env:Secrets__MasterKey__Source = "File" -$env:Secrets__MasterKey__FilePath = "" -E:\ApiInstall\_tools\secret\secret.exe set nam-ldap-svc-password # prompts; never a literal arg -``` - -Stores to seed (verify paths from the live NSSM/registry env captured in Phase 0): - -| Store | Needed by | -|---|---| -| OtOpcUa (`E:\ApiInstall\OtOpcUa-data\...`) | AdminUI LDAP login | -| ScadaBridge **central** | central UI LDAP login (the `${secret:}` ref lives in `appsettings.Central.json`) | -| ScadaBridge **site** | not strictly needed (site does no LDAP) — seed anyway for symmetry; the two stores share one KEK but are separate stores | -| MxGateway | dashboard LDAP login | -| HistorianGateway | dashboard LDAP login | - -Verify each with `secret.exe get nam-ldap-svc-password` (value round-trip) under the -same per-invocation targeting. **Rotation note for the runbook:** one password now -lives in 4–5 stores; a rotation is N `set` operations plus zero config changes. - -## Phase 3 — config edits (one app at a time, restart, verify, then next) - -Order: **HG → mxgw → OtOpcUa → ScadaBridge** (proven-pattern first, DB-mapping app -last). Back up every file edited; edits go in the box's live overlay files, and the -next deploy must re-apply them (add to the deploy-notes convention — the deploy -process restores box appsettings, so once these edits ARE the box appsettings they -survive; the risk is a fresh-install overwrite, same as every other box-local key). - -### 3a. HistorianGateway -- `Ldap` section ← the target block above. -- `Dashboard:DisableLogin` → `false`; `Dashboard:GroupToRole` ← - `UG_WW_HIST_ADMIN_DEV: Administrator`, `UG_WW_APP_ADMIN_DEV: Administrator`, - `UG_WW_APP_IDE_RO_DEV: Viewer`. -- Restart `ZbHistorianGateway`; run the Phase 4 checks. - -### 3b. MxAccessGateway -- `MxGateway:Ldap` ← target block. -- `MxGateway:Dashboard:GroupToRole` ← `UG_WW_APP_ADMIN_DEV: Administrator`, - `UG_WW_APP_IDE_DEV: Viewer`, `UG_WW_APP_IDE_RO_DEV: Viewer` (only two roles exist; - Designer collapses to Viewer per ldap_mapping §4). -- Restart; verify. (gRPC/API-key surface untouched — do NOT disturb the restored - API-key store in `data\`.) - -### 3c. OtOpcUa (AdminUI only) -- `Security:Ldap` ← target block (keep any existing `GroupToRole` DB-overlay rows in - mind — config merges with the DB overlay; check the RoleGrants page after). -- `Security:Ldap:GroupToRole` ← `UG_WW_APP_ADMIN_DEV: Administrator`, - `UG_WW_APP_IDE_DEV: Designer`, `UG_WW_APP_IDE_RO_DEV: Viewer`, - `UG_WW_HIST_ADMIN_DEV: Viewer` (historization targets are authored here — see - ldap_mapping §4 rationale). -- Restart the AdminUI/central service. Driver-only nodes are unaffected (no LDAP). -- The OPC UA data plane keeps its `otua_` API keys — no consumer impact. - -### 3d. ScadaBridge (central) -- `appsettings.Central.json`: `ScadaBridge:Security:Ldap` ← target block; **remove the - two disable-login keys** (`DisableLogin` + `AllowOutsideDevelopment`) — note the trap: - removing only `AllowOutsideDevelopment` while leaving `DisableLogin=true` - **crash-loops** (`DisableLoginGuard`); remove both. -- Role rows in the central DB (`LdapGroupMapping` — the only app whose mapping is data, - and the only one that can grant two roles per group): - ```sql - INSERT INTO LdapGroupMapping (LdapGroupName, Role) VALUES - ('UG_WW_APP_ADMIN_DEV', 'Administrator'), - ('UG_WW_APP_IDE_DEV', 'Designer'), - ('UG_WW_APP_IDE_DEV', 'Deployer'), -- two rows on purpose (§2.1) - ('UG_WW_APP_IDE_RO_DEV', 'Viewer'); - ``` - (Operator/site rows deliberately deferred — decision 5.) -- Restart central; site service untouched. - -## Phase 4 — verification (per app, immediately after its restart) - -The log **failure stage** is the diagnostic (proven live, recorded in ldap_setup.md): - -1. **Negative control first** (bogus user + bogus password): expect a clean - "invalid/not authorized" with **zero** `WRN ... failed system-side` lines. A - `service-bind`-stage WRN = wrong secret value; a `search`-stage WRN = empty - password (the `${secret:}` ref did not resolve — check the store/KEK targeting); - connect-stage = network/TLS. -2. **Real login** with an account in a mapped `_DEV` group → correct role visible in - the UI. And one with **no** mapped group → denied (fail-closed zero-group rule). -3. **`${secret:}` positive control:** the value must come from the store, not residue — - e.g. confirm no `Ldap__ServiceAccountPassword` in service env, and that - `secret.exe get` matches what auth uses (a wrong-value canary set+revert is the - strong form). -4. **Failover spot-check (once, on HG):** block/blackhole nam1:636 briefly → - login still works, WRN for nam1 + `sticky preference moved` to nam2; restore. - Do not drill on every app — it is the same library and it doubles bad-bind - exposure against lockout policy if anything is misconfigured. -5. Mind the lockout arithmetic throughout: every failed app attempt = a failed bind - on **both** DCs (endpoint walk). Stop and diagnose after 2 failures, don't retry. - -## Rollback - -Per app, in reverse: restore the backed-up appsettings (which restores the previous -login posture, including ScadaBridge's two-key disable and HG's `DisableLogin=true`), -restart. The seeded secrets are inert once nothing references them — leave them. -ScadaBridge: `DELETE FROM LdapGroupMapping WHERE LdapGroupName LIKE 'UG_WW_%'` only if -a clean slate is wanted; unreferenced rows grant nothing while login is disabled. -Phase 1's redeploys are independent and should NOT be rolled back for an auth problem. - -## Follow-ups this creates - -- QA pair (VQ03/VQ04) cutover with `_QA` groups — the same plan, plus real - failover/pair semantics; QA is where `FallbackServers` + sticky actually matter. -- Dedicated service account (decision 1) → rotate `nam-ldap-svc-password` in N stores. -- Revert the Mac's HG docker container from its temporary NAM flip back to the - glauth-redundant pair (uncommitted working-tree change, independent of this plan). -- ldap_mapping.md is still untracked in scadaproj — commit it when its DECIDE items - settle; this plan depends on its §4 tables. -- ignitionoee LDAP: **held** (see the Scope flag) until new `UG_WW_*` groups matching its - role vocabulary are minted and mapped — a group-creation request, not a config task. +**Superseded 2026-11-15 by [`2026-11-15-nam-ldap-cutover.md`](2026-11-15-nam-ldap-cutover.md).** Its §10 lists everything this +plan got wrong. The original text is in git history (`git show fd180e5:docs/plans/2026-08-13-vd03-nam-ldap-cutover.md`). diff --git a/docs/plans/2026-11-15-nam-ldap-cutover.md b/docs/plans/2026-11-15-nam-ldap-cutover.md new file mode 100644 index 0000000..cea458f --- /dev/null +++ b/docs/plans/2026-11-15-nam-ldap-cutover.md @@ -0,0 +1,558 @@ +# 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). + +**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). + +**In scope:** HistorianGateway (dashboard), MxAccessGateway (dashboard), ScadaBridge (Central UI + CLI) +and 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. + +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. + +--- + +## 1. Current state (2026-11-15) + +### 1.1 Builds and the Auth library: the prerequisite is met + +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: + +| 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 | + +- **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. + +### 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. | + +### 1.3 Directory facts (carried forward, still valid) + +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.** + +--- + +## 2. Phase A — OtOpcUa code fix (prerequisite; must ship before the OtOpcUa cutover) + +### 2.1 The defect [V] + +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`. + +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. + +### 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. + +### 2.3 Issue to file in `lmxopcua` (text only; not filed by this plan) + +> **Title:** `Security:Ldap` drops `FallbackServers`, `BindMode`, `UserBindTemplate`, `AcceptDomainQualifiedNames` +> (no AD DC failover for the AdminUI) +> +> **Labels:** `type:bug`, `priority:p2`, `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. +> +> 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. + +### 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. + +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. + +--- + +## 3. The group-mapping standard (DECIDED 2026-11-15) + +### 3.1 The rule + +**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). + +### 3.2 Why + +1. **It is what every app's schema already supports, with no code change:** + + | 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. + +--- + +## 4. The tier mappings, generated from the matrix + +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. + +| 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_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 | + +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`). + +```jsonc +"Ldap": { /* §6 block */ }, +"Dashboard": { + "DisableLogin": false, + "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. + +``` +Dashboard__GroupToRole__UG_WW_APP_ADMIN_QA=Administrator +Dashboard__GroupToRole__UG_WW_HIST_ADMIN_QA=Administrator +Dashboard__GroupToRole__UG_WW_APP_IDE_RO_QA=Viewer +Dashboard__GroupToRole__UG_WW_BTMGR_RO_QA=Viewer +``` + +### 4.2 MxAccessGateway + +DEV goes in the live appsettings file; Phase 0 records which one. QA goes in the same file it uses +today. + +```jsonc +"MxGateway": { + "Ldap": { /* §6 block */ }, + "Dashboard": { + "DisableLogin": false, + "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]. + +### 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__*`. + +``` +Security__Ldap__GroupToRole__UG_WW_APP_ADMIN_=Administrator +Security__Ldap__GroupToRole__UG_WW_APP_IDE_=Designer +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. + +### 4.4 ScadaBridge + +**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: + +```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'); +-- 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; + +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); +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. + +--- + +## 5. Decisions (owner or IT): settle before the cutover (§7) + +| # | 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_*'`. | + +--- + +## 6. The LDAP block (same in all four apps, under each app's section) + +The sections are: HG `Ldap`, mxgw `MxGateway:Ldap`, ScadaBridge `ScadaBridge:Security:Ldap` +(`Security/ServiceCollectionExtensions.cs:24`), OtOpcUa `Security:Ldap`. + +```jsonc +{ + "Enabled": true, + "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 + "SearchBase": "DC=nam,DC=zimmer,DC=com", + "ServiceAccountDn": "", // D1; DEV interim: svc_igntadmin@nam.zimmer.com (Ignition team agreement) + "ServiceAccountPassword": "${secret:nam-ldap-svc-password}", + "UserNameAttribute": "sAMAccountName", + "DisplayNameAttribute": "name", + "GroupAttribute": "memberOf", + "BindMode": "ServiceAccount" +} +``` + +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}`. + +--- + +## 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. + +**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. + +**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. + +### 7.0 Phase 0 — preflight (read-only; deploy scope) + +Run per box: vd03, vq03, vq04. + +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; + - 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. + +### 7.1 Seed the secret (once per store, 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): + ```powershell + $env:Secrets__SqlitePath = ""; $env:Secrets__MasterKey__Source = "File"; $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. + +### 7.2 HistorianGateway (DEV: file; QA: NSSM env) + +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. + +### 7.3 MxAccessGateway (DEV and QA: file) + +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. + +### 7.4 ScadaBridge (Central only; the Site is untouched) + +**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). + +1. Back up `appsettings.Central.json` (and the env). +2. Run the §4.4 SQL. +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. + +### 7.5 OtOpcUa AdminUI (env, both tiers; 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. + +### 7.6 Verify (each app, right after its restart; stop after 2 failures, because of lockout) + +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.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. + +--- + +## 8. Acceptance + +- **A1:** the §2 OtOpcUa failover test passes on the redundant GLAuth pair, and the reflection guard's + mutation check fails as expected. +- **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`. + +## 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) +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. + +## 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. | diff --git a/ldap_mapping.md b/ldap_mapping.md index 1865a07..7051739 100644 --- a/ldap_mapping.md +++ b/ldap_mapping.md @@ -1,286 +1,157 @@ -# `UG_WW_*` → app role mapping (proposal) +# `UG_WW_*` → app role mapping (canonical matrix) -Maps the Zimmer NAM `UG_WW_*` Active Directory groups onto the roles each ZB.MOM.WW app -actually implements. Inputs: the 39-group inventory in [`ldap_setup.md`](ldap_setup.md) -(enumerated live 2026-08-12) and the standardized -[`CANONICAL-ROLES.md`](components/auth/spec/CANONICAL-ROLES.md). +This is the **single source of truth** for which Zimmer NAM `UG_WW_*` Active Directory group grants which +role in each ZB.MOM.WW app. +- **Inputs:** the 39-group inventory in [`ldap_setup.md`](ldap_setup.md) (enumerated 2026-08-12) and + [`CANONICAL-ROLES.md`](components/auth/spec/CANONICAL-ROLES.md). +- **Consumer:** the cutover runbook [`docs/plans/2026-11-15-nam-ldap-cutover.md`](docs/plans/2026-11-15-nam-ldap-cutover.md) + generates each app's config from §4. -> **Status: PROPOSAL.** The mechanical parts (`_RO_`, `_OPERATOR`, `APP_IDE`, `APP_ADMIN`) -> are safe to adopt. Four items marked **⚠ DECIDE** need a human answer before anyone -> writes them into a production config — they are listed in -> [§6](#6-open-questions--decide-before-adopting) and none of them can be resolved from the -> directory alone. Ignition's role set is deliberately out of scope. +> **Rule (DECIDED 2026-11-15): 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.** Where a +> user needs two roles, they need two groups. §2 explains why. > -> ⚠️ **ignitionoee (router): ON HOLD** (decision 2026-08-13) — do **not** set up its LDAP. -> Its role vocabulary is outside the canonical set (admin role is literally `"Admin"`), -> so no existing `UG_WW_*` group maps to it; wiring it to NAM AD requires minting **new** -> AD groups first. Revisit only once those groups exist and their mapping is decided. +> ⚠️ **ignitionoee (router): ON HOLD** (decision 2026-08-13). Its role vocabulary is outside the canonical set +> (its admin role is literally `"Admin"`), so no `UG_WW_*` group maps to it. Wiring it to NAM AD first needs new +> AD groups. It is out of scope here. -## 1. The app role vocabularies (verified in source 2026-08-12) +## 1. The app role vocabularies (verified in source 2026-11-15) -Each app implements only a **subset** of the canonical six. This is the constraint that -shapes everything below — there is no point mapping a group to a role an app does not have. +| App | Roles it actually implements | Where the mapping lives | Shape | +|---|---|---|---| +| **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`) | -| App | Roles it actually implements | Where the mapping lives | -|---|---|---| -| **OtOpcUa** (AdminUI) | `Viewer`, `Designer`, `Administrator` | `Security:Ldap:GroupToRole` (appsettings, merged with a DB overlay) | -| **ScadaBridge** | `Viewer`, `Operator`, `Verifier`, `Designer`, `Deployer`, `Administrator` | `LdapGroupMapping` table (database, not config) | -| **MxAccessGateway** | `Viewer`, `Administrator` | `MxGateway:Dashboard:GroupToRole` | -| **HistorianGateway** | `Viewer`, `Administrator` | `Dashboard:GroupToRole` | +Things that are easy to get wrong: -Three things follow that are easy to get wrong: - -- **OtOpcUa's LDAP mapping governs the AdminUI only.** Since Gitea #520 (2026-08-01) the - OPC UA data plane does not use LDAP at all — a client presents an `otua_` API key as an - OPC UA UserName token. So a plant operator who only reads tags needs **no AD group here**; - granting one gives them the configuration UI, which is not what anyone means by - "operator access". The `CANONICAL-ROLES.md` row showing OtOpcUa data-plane bundles - predates that change and no longer applies to LDAP. +- **OtOpcUa's LDAP mapping governs the AdminUI only.** The OPC UA data plane uses `otua_` API keys + (Gitea #520), so a plant operator who only reads tags needs **no** AD group. Mapping one would hand them + the configuration UI. - **`Administrator` is the literal string in all four apps.** MxGateway's constant is named - `DashboardRoles.Admin` but its value is `"Administrator"`, and its validator rejects - anything that is not `Administrator` or `Viewer`. -- **Every app fails closed on zero matched groups.** A user whose groups match no entry is - denied. So an unmapped group grants nothing — the mapping does not have to be exhaustive, - and leaving a group out is a safe default rather than an omission. + `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. -## 2. Group family → canonical role +## 2. Why one role per group -| `UG_WW_*` family | Canonical | Confidence | -|---|---|---| -| `APP_IDE_RO_`, `BTMGR_RO_` | **Viewer** | firm — `RO` is unambiguous | -| `__OPERATOR` | **Operator** | firm | -| `BTMGR__` | **Operator** | firm — batch execution is operate-level | -| `__ENGINEER` | **Engineer** | firm canonically, **but no app implements Engineer** — see §6.1 | -| `APP_IDE_` | **Designer + Deployer** | **DECIDED** — see §2.1 | -| `APP_ADMIN_` | **Administrator** | firm | -| `HIST_ADMIN_` | **Administrator**, historian-scoped | firm for HistorianGateway; see §4 for the others | -| `SITE_ADMIN_` | **Administrator** (scoped) — *not* Deployer | ⚠ DECIDE — §6.2 | -| `__SUPERVISOR` | **Verifier**? | ⚠ DECIDE — §6.3 | -| `_SMS_TESTER` | — | ⚠ DECIDE — §6.4 | -| `CITRIX_` | **none — deliberately unmapped** | firm — see below | +1. **It is what every schema supports today, with no code change.** + - Three apps key a dictionary by group, so two roles are structurally impossible there. + - ScadaBridge has a **unique index** on `LdapGroupName`. + - OtOpcUa's DB overlay would technically accept two system-wide rows for one group (its unique index + is `(LdapGroup, ClusterId)` with a filter), so **the rule forbids it there explicitly**. +2. **Grants stay readable in AD.** Who holds a role is the membership of named groups, and IT owns those. +3. **It removes a silent failure.** The previous version of this file said ScadaBridge could grant two + roles from one group. The unique index makes the second row fail. -**`CITRIX_*` is not a role and must not be mapped.** It grants desktop/session access to a -Citrix farm, not authority within an application. Mapping it would hand app privileges to -everyone who merely has a published desktop — 12 people in QA alone — which is a -privilege-escalation path disguised as a convenience. +**Rejected:** several roles per group. It would need a ScadaBridge migration plus matching changes in the +other apps. It is recorded as a future option, not current policy. -### 2.1 `APP_IDE` carries both `Designer` and `Deployer` — DECIDED +## 3. The environment axis is per deployment -The ArchestrA IDE is both the authoring surface *and* the deployment surface: templates are -created there and pushed to runtime from the same tool, by the same person, in the same -session. So `APP_IDE_` maps to **both** canonical roles, and `APP_IDE_RO_` maps to -**Viewer** — read the Galaxy, change nothing, deploy nothing. +`DEV`/`QA`/`PROD` is orthogonal to role. **Each deployment maps only its own suffix:** +- the DEV instance lists `UG_WW_APP_ADMIN_DEV` and never `_PROD`; +- QA lists `_QA`; +- PROD lists `_PROD`. -This closes §6.5: the `AUTHOR`/`DEPLOY` separation the canonical set describes **does not -exist in this estate**, and rather than inventing one, the mapping reflects how the tooling -actually works. It is a deliberate collapse, not an oversight. +A config listing all three would make every DEV administrator a PROD administrator, silently. In §4, +`` stands for the deployment's tier suffix. -**Only ScadaBridge can express it.** Its `LdapGroupMapping` is a row per *(group, role)* -pair and its `RoleMapper` accumulates matches into a `HashSet`, so two rows against -the same group grant both roles. The other three apps bind `GroupToRole` as a -`Dictionary` — **one role per group, structurally; a duplicate key is a -config error, not a second grant.** That is not a limitation in practice: none of those -three implements `Deployer` at all, so there is nothing to lose. +## 4. The matrix -**Consequence for `SITE_ADMIN_*`:** §6.2 previously recommended mapping it to a site-scoped -`Deployer`. With `Deployer` now sourced from `APP_IDE`, that would mean two unrelated groups -granting the same authority by different routes, and would leave "site admin" meaning -nothing beyond what an IDE user already has. `Administrator` is the remaining reading — see -the revised §6.2, which raises rather than settles the blast-radius question. +`—` = deliberately unmapped (fails closed). ⚠ = needs a decision (§6), and is not mapped until it's +made. One role per cell. -## 3. The environment axis is per-deployment, not per-role +### 4.1 Platform groups (environment-scoped; mapped in the NAM cutover) -`DEV`/`QA`/`PROD` is **orthogonal to role** and has no representation in `CanonicalRole`. -Do not encode it into role names; that triples the role set and buys nothing. +| Group | OtOpcUa | ScadaBridge | MxAccessGateway | HistorianGateway | Note | +|---|---|---|---|---|---| +| `UG_WW_APP_ADMIN_` | Administrator | Administrator | Administrator | Administrator | | +| `UG_WW_APP_IDE_` | Designer | Designer | Viewer | — | **Was "Designer + Deployer" in ScadaBridge.** Resolved: Designer here; `Deployer` comes from the new group below. mxgw has no Designer, so Viewer. | +| `UG_WW_APP_DEPLOY_` | — | Deployer | — | — | **NEW group: owner/IT decision, request by ServiceNow ticket** (cutover plan D6). Until it exists, no NAM user can deploy in ScadaBridge, so the ScadaBridge cutover waits for it. | +| `UG_WW_APP_IDE_RO_` | Viewer | Viewer | Viewer | Viewer | | +| `UG_WW_HIST_ADMIN_` | Viewer | — | — | Administrator | OtOpcUa Viewer, because historization targets are authored in the AdminUI and visible to a historian admin, but not editable. | +| `UG_WW_BTMGR_RO_` (QA/PROD only) | — | Viewer | — | Viewer | `BTMGR_RO_QA` is **empty** (08-12). | +| `UG_WW_CITRIX_` | — | — | — | — | **Never map.** It is desktop/session access, not app authority. | -Instead, **each deployment maps only its own environment's groups.** The mapping already -lives in per-instance config, so this is free: +### 4.2 Plant-floor, site and batch groups (NOT in the NAM cutover; mapped later, ScadaBridge only) -- the PROD instance's config lists `UG_WW_APP_ADMIN_PROD` and never mentions `_DEV` -- the DEV instance's config lists `UG_WW_APP_ADMIN_DEV` +| Group | OtOpcUa | ScadaBridge | MxAccessGateway | HistorianGateway | Note | +|---|---|---|---|---|---| +| `UG_WW___OPERATOR` (B19 SMS/VitE, PON PRESS, WN ARCOM/ARCOMXL/SOLAR/STERIS) | — | Operator (site-scoped) | — | — | OtOpcUa runtime access is by API key. | +| `UG_WW_BTMGR_{BE,MC}_` | — | Operator (site-scoped) | — | — | | +| `UG_WW___ENGINEER` | — | ⚠ §6.1 | — | — | | +| `UG_WW_WN_STERIS_SUPERVISOR` | — | ⚠ §6.3 (`Verifier`?) | — | — | Never the same group as `Operator`. | +| `UG_WW_B19_SMS_TESTER` | — | ⚠ §6.4 | — | — | | +| `UG_WW_SITE_ADMIN_` | ⚠ §6.2 | ⚠ §6.2 | ⚠ §6.2 | ⚠ §6.2 | No longer a candidate for `Deployer` (that is `APP_DEPLOY`). | -This is load-bearing, not cosmetic. A single config listing all three environments would -make every DEV administrator a **PROD** administrator, silently, with no error anywhere. +### 4.3 Per-app config generated from §4.1 -The blocks in §4 are written for **PROD**. For DEV/QA, substitute the suffix. Note -`CITRIX` has no `PROD` group at all, which is further reason not to treat it as a role. - -## 4. Per-app configuration - -### OtOpcUa — `Security:Ldap:GroupToRole` +These are DEV examples; substitute the `` suffix for other tiers. The cutover plan §4 has the env +forms and the idempotent ScadaBridge SQL. +**OtOpcUa:** `Security:Ldap:GroupToRole`. The DB overlay must not contradict it. ```json -"GroupToRole": { - "UG_WW_APP_ADMIN_PROD": "Administrator", - "UG_WW_SITE_ADMIN_WW19": "Administrator", - "UG_WW_APP_IDE_PROD": "Designer", - "UG_WW_APP_IDE_RO_PROD": "Viewer", - "UG_WW_HIST_ADMIN_PROD": "Viewer" -} +{ "UG_WW_APP_ADMIN_DEV": "Administrator", "UG_WW_APP_IDE_DEV": "Designer", + "UG_WW_APP_IDE_RO_DEV": "Viewer", "UG_WW_HIST_ADMIN_DEV": "Viewer" } ``` -`HIST_ADMIN` gets `Viewer` because historization *targets* are authored in the OtOpcUa -AdminUI: a historian admin needs to see how tags are historized without being able to -change the address space. Plant-floor operator and engineer groups are **deliberately -absent** — the AdminUI is a configuration surface, and their runtime access is API-key -based (§1). - -Replace `WW19` with the site that owns the instance; see §6.2 before listing all eight. - -### ScadaBridge — `LdapGroupMapping` table - -The only app with a role set rich enough to use most of the directory, and the only one -where site scoping is real. - -| Group | Role | Scope | -|---|---|---| -| `UG_WW_APP_ADMIN_PROD` | `Administrator` | — | -| `UG_WW_APP_IDE_PROD` | `Designer` **and** `Deployer` — two rows (§2.1) | — | -| `UG_WW_APP_IDE_RO_PROD` | `Viewer` | — | -| `UG_WW_BTMGR_RO_PROD` | `Viewer` | — | -| `UG_WW_SITE_ADMIN_` | `Administrator` | that site ⚠ §6.2 | -| `UG_WW_B19_SMS_OPERATOR` | `Operator` | B19 | -| `UG_WW_B19_VitE_OPERATOR` | `Operator` | B19 | -| `UG_WW_PON_PRESS_OPERATOR` | `Operator` | PON | -| `UG_WW_WN_ARCOM_OPERATOR` | `Operator` | WN | -| `UG_WW_WN_ARCOMXL_OPERATOR` | `Operator` | WN | -| `UG_WW_WN_SOLAR_OPERATOR` | `Operator` | WN | -| `UG_WW_WN_STERIS_OPERATOR` | `Operator` | WN | -| `UG_WW_BTMGR_BE_PROD` | `Operator` | BE | -| `UG_WW_BTMGR_MC_PROD` | `Operator` | MC | -| `UG_WW_WN_STERIS_SUPERVISOR` | `Verifier`? | WN ⚠ §6.3 | -| `UG_WW_B19_VitE_ENGINEER` | ⚠ §6.1 | B19 | -| `UG_WW_PON_PRESS_ENGINEER` | ⚠ §6.1 | PON | - -The IDE grant is **two rows against one group** — this is the only place in the four apps -where that is possible, and it is the row pair most likely to be entered as one: - -```sql -INSERT INTO LdapGroupMapping (LdapGroupName, Role) VALUES - ('UG_WW_APP_IDE_PROD', 'Designer'), - ('UG_WW_APP_IDE_PROD', 'Deployer'); -``` - -`RoleMapper` unions every matched row into a `HashSet`, so the user comes out -holding both. A single row grants only what it names — there is no implicit widening, and -nothing will report the missing half. - -### MxAccessGateway — `MxGateway:Dashboard:GroupToRole` +**ScadaBridge:** `dbo.LdapGroupMappings (LdapGroupName, Role)`, one row per group: +`UG_WW_APP_ADMIN_DEV`→`Administrator`, `UG_WW_APP_IDE_DEV`→`Designer`, `UG_WW_APP_DEPLOY_DEV`→`Deployer` +(once the group exists), `UG_WW_APP_IDE_RO_DEV`→`Viewer`. +**MxAccessGateway:** `MxGateway:Dashboard:GroupToRole` ```json -"GroupToRole": { - "UG_WW_APP_ADMIN_PROD": "Administrator", - "UG_WW_APP_IDE_PROD": "Viewer", - "UG_WW_APP_IDE_RO_PROD": "Viewer" -} +{ "UG_WW_APP_ADMIN_DEV": "Administrator", "UG_WW_APP_IDE_DEV": "Viewer", "UG_WW_APP_IDE_RO_DEV": "Viewer" } ``` -Only two roles exist, so `Designer` collapses to `Viewer`: an IDE author has a legitimate -reason to browse Galaxy through the gateway dashboard, but no reason to administer API -keys. The gRPC surface is API-key authenticated and is **not** governed by this mapping. - -### HistorianGateway — `Dashboard:GroupToRole` - +**HistorianGateway:** `Dashboard:GroupToRole` ```json -"GroupToRole": { - "UG_WW_HIST_ADMIN_PROD": "Administrator", - "UG_WW_APP_ADMIN_PROD": "Administrator", - "UG_WW_APP_IDE_RO_PROD": "Viewer", - "UG_WW_BTMGR_RO_PROD": "Viewer" -} +{ "UG_WW_APP_ADMIN_DEV": "Administrator", "UG_WW_HIST_ADMIN_DEV": "Administrator", "UG_WW_APP_IDE_RO_DEV": "Viewer" } ``` -`HIST_ADMIN` is the exact-fit group for this app — it is the one place in the directory -whose name already means what the app's `Administrator` grants. +## 5. Group inventory: unverified since 2026-08-12 -## 5. Blast radius +The group list, member counts and the empty `BTMGR_RO_QA` all date from **2026-08-12** +(`ldap_setup.md`). Re-verify before relying on them. The account comes from scadaproj#58; on DEV it can be +the interim `svc_igntadmin@nam.zimmer.com`, with the Ignition team's agreement. -Worth doing the arithmetic before adopting, because these groups are larger than they look: +```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 +``` -| Grant | People | -|---|--:| -| `APP_ADMIN_PROD` → Administrator | 5 | -| `SITE_ADMIN_*` → Administrator, **all 8 sites** | **~48** | -| `APP_IDE_PROD` → Designer | 4 | -| all `_OPERATOR` groups → Operator | ~87 | +**Blast radius** (08-12 counts): +- `APP_ADMIN_PROD`: 5. +- All eight `SITE_ADMIN_*` together: about 48. That is why §6.2 is unresolved. +- All `_OPERATOR` groups: about 87. -Mapping all eight `SITE_ADMIN_*` groups to `Administrator` on all four apps grants roughly -**48 people full administrative control of every app**, including the ones whose site has -nothing to do with the deployment. That is the single largest risk in this document, and -it is why §6.2 exists. +## 6. Open questions: DECIDE before mapping the §4.2 rows -## 6. Open questions — DECIDE before adopting - -### 6.1 `Engineer` has no home ⚠ - -`_ENGINEER` maps cleanly to canonical **Engineer** (`OBSERVE` + `OPERATE` + `TUNE`), and -**no app implements it.** OtOpcUa has `Viewer`/`Designer`/`Administrator`; ScadaBridge has -`Operator`/`Verifier` but no Engineer; the two gateways have `Viewer`/`Administrator`. - -Options: (a) map `_ENGINEER` → `Operator` and accept that engineers lose `TUNE`; -(b) add an `Engineer` role to ScadaBridge; (c) leave unmapped, so the 18 people in the two -`_ENGINEER` groups get nothing. **Recommendation: (a) for now** — it is the honest subset, -grants no authority the group name does not imply, and can be widened later. Do not -silently map Engineer to Administrator to "cover" `TUNE`. - -### 6.2 `SITE_ADMIN_*` — how much authority, and how many sites? ⚠ - -**Narrowed by §2.1, not settled.** `Deployer` now comes from `APP_IDE`, so site-scoped -`Deployer` is no longer available as the gentle reading of "site admin". What remains is -`Administrator` (scoped to the site), `Viewer`, or leaving it unmapped — and those are very -far apart. - -This matters more than it did. There are **eight** of these groups at 6 members each, so -`Administrator` is the maximum grant in the vocabulary being handed to as many as ~48 -people (§5). If a "site admin" is really a local IT contact rather than an application -owner, `Administrator` is badly wrong. - -Second question, unchanged: **which sites should a given deployment list?** Every group has -exactly 6 members and they look like the same handful of people, but that is inference from -counts, not fact. **Recommendation: list only the owning site**, and confirm what the role -means before granting `Administrator` to any of them. - -### 6.3 `_SUPERVISOR` → `Verifier`? ⚠ - -`UG_WW_WN_STERIS_SUPERVISOR` (6 members) is the only `_SUPERVISOR` group. ScadaBridge's -`Verifier` **approves** a two-person Secured Write that an `Operator` initiates, so a -supervisor approving an operator's action is a plausible reading — but "supervisor" could -equally mean a shift lead with no approval authority at all. Confirm with the group owner. - -**Whatever is decided, never map one group to both `Operator` and `Verifier`.** The control -requires two *distinct* principals; a person holding both could initiate and approve their -own write, which removes the entire point of the mechanism while leaving it looking wired. - -### 6.4 `_TESTER` ⚠ - -`UG_WW_B19_SMS_TESTER` (13 members) has no canonical equivalent and appears only in a QA -context. Leave unmapped until someone states what it is for — 13 people is too many to -guess at. - -### 6.5 `Deployer` vs `AUTHOR` separation — RESOLVED - -Closed by §2.1: `APP_IDE` grants both `Designer` and `Deployer`, because the ArchestrA IDE -authors and deploys from the same tool and the same session. The canonical `AUTHOR`/`DEPLOY` -split has no counterpart in this estate, and the mapping now records that as a decision -rather than leaving it to be discovered later. Same class of accepted SoD collapse already -noted in `CANONICAL-ROLES.md`. +1. **§6.1 `Engineer` has no home.** No app implements it. + - (a) Map `_ENGINEER` → `Operator` (the honest subset). + - (b) Add an `Engineer` role to ScadaBridge. + - (c) Leave it unmapped. + - **Recommendation: (a)**, when the plant-floor rows are mapped. +2. **§6.2 `SITE_ADMIN_*`:** `Administrator` for up to about 48 people, or `Viewer`, or unmapped? + - Which sites does a deployment list? + - **Recommendation:** only the owning site, and only after confirming what "site admin" means. +3. **§6.3 `_SUPERVISOR` → `Verifier`?** Verifier approves an Operator's two-person Secured Write. That is + plausible, but confirm with the group owner. + - **Under the rule it can never also be `Operator`**, which also keeps the two-person control real. +4. **§6.4 `_TESTER`:** no canonical equivalent. Leave unmapped until someone says what it is for. +5. **§6.5 `Deployer`: RESOLVED by the rule.** It comes from the new `UG_WW_APP_DEPLOY_` group, not + from `APP_IDE`. + - This replaces the 2026-08-13 "APP_IDE = Designer + Deployer" decision. ScadaBridge's schema can't + express that, and the one-group-one-role rule forbids it. + - Designer and Deployer can still be the same people: put them in both groups. ## 7. Prerequisites -1. **Auth `0.2.1` adopted — DONE 2026-08-13.** All four apps pin `0.2.1` (OtOpcUa - `master @ 08e33fc7`, ScadaBridge `main @ d28824d9`, MxAccessGateway `main @ 1cb14d2`, - HistorianGateway `e42ff31`, merged to `main`; all pushed to origin). - The continuation-referral defect ([`ldap_setup.md`](ldap_setup.md)) is closed at the - app level, so this mapping is exercisable once configs are authored. -2. **`UG_WW_BTMGR_RO_QA` is empty.** It appears in the QA variant of the ScadaBridge and - HistorianGateway tables; mapping it grants nobody anything today. Harmless, but do not - read a working config as evidence that the grant works. -3. **Verify with a real account before rollout.** Every group in §4 was observed on one - long-tenured architect account, which holds every admin-flavoured group and **no** - operator group. The operator mappings are therefore untested against a real operator. - `ldapprobe --self-bind ` settles it in one run — and specifically - whether such an account has any `memberOf` at all, since the library refuses a - zero-group login (`GroupLookupFailed`) regardless of a correct password. -4. **New groups are provisioned by ServiceNow ticket** (the group descriptions are - `TASK…` ids). If §6 concludes that a group is missing — a `Verifier` counterpart, or an - `Engineer` tier — that is a ticket, not a config change. +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). +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 + account that holds no operator groups.