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_<T> group (was a two-row insert
  the unique index rejects).

Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
This commit is contained in:
Joseph Doherty
2026-11-15 20:28:09 -05:00
parent 2ed9bb4892
commit 1d344a0c08
3 changed files with 677 additions and 510 deletions
+3 -265
View File
@@ -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 <sAMAccountName>`.
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 = "<that app's store path>"
$env:Secrets__MasterKey__Source = "File"
$env:Secrets__MasterKey__FilePath = "<that app's KEK file>"
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`).
+558
View File
@@ -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<string>`, `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<string> 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<string>`.
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<string,string> 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<string,string> GroupToRole` (`Server/Configuration/DashboardOptions.cs:69`) | Yes. The validator also allows only `Administrator`/`Viewer` (`GatewayOptionsValidator.cs:506-517`). |
| HistorianGateway | `IReadOnlyDictionary<string,string> 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 (`<T>` = `DEV` or `QA`) | OtOpcUa | ScadaBridge | MxAccessGateway | HistorianGateway |
|---|---|---|---|---|
| `UG_WW_APP_ADMIN_<T>` | Administrator | Administrator | Administrator | Administrator |
| `UG_WW_APP_IDE_<T>` | Designer | Designer | Viewer | — |
| `UG_WW_APP_DEPLOY_<T>` *(new, D6)* | — | Deployer | — | — |
| `UG_WW_APP_IDE_RO_<T>` | Viewer | Viewer | Viewer | Viewer |
| `UG_WW_HIST_ADMIN_<T>` | 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_<T>=Administrator
Security__Ldap__GroupToRole__UG_WW_APP_IDE_<T>=Designer
Security__Ldap__GroupToRole__UG_WW_APP_IDE_RO_<T>=Viewer
Security__Ldap__GroupToRole__UG_WW_HIST_ADMIN_<T>=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 '<svc account UPN from scadaproj#58>' --self-bind <sAMAccountName>` 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": "<svc account UPN from scadaproj#58>", // 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 '<svc account UPN from scadaproj#58>' -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 = "<store>"; $env:Secrets__MasterKey__Source = "File"; $env:Secrets__MasterKey__FilePath = "<kek>"
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_<T>` 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. |
+116 -245
View File
@@ -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<string,string>` (`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<string,string>` (`Configuration/DashboardOptions.cs:69`) |
| **HistorianGateway** | `Viewer`, `Administrator` (`Dashboard/DashboardRoles.cs`) | `Dashboard:GroupToRole` | `IReadOnlyDictionary<string,string>` (`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_<env>`, `BTMGR_RO_<env>` | **Viewer** | firm — `RO` is unambiguous |
| `<SITE>_<AREA>_OPERATOR` | **Operator** | firm |
| `BTMGR_<PLANT>_<env>` | **Operator** | firm — batch execution is operate-level |
| `<SITE>_<AREA>_ENGINEER` | **Engineer** | firm canonically, **but no app implements Engineer** — see §6.1 |
| `APP_IDE_<env>` | **Designer + Deployer** | **DECIDED** — see §2.1 |
| `APP_ADMIN_<env>` | **Administrator** | firm |
| `HIST_ADMIN_<env>` | **Administrator**, historian-scoped | firm for HistorianGateway; see §4 for the others |
| `SITE_ADMIN_<SITE>` | **Administrator** (scoped) — *not* Deployer | ⚠ DECIDE — §6.2 |
| `<SITE>_<AREA>_SUPERVISOR` | **Verifier**? | ⚠ DECIDE — §6.3 |
| `<SITE>_SMS_TESTER` | — | ⚠ DECIDE — §6.4 |
| `CITRIX_<env>` | **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_<env>` maps to **both** canonical roles, and `APP_IDE_RO_<env>` 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,
`<T>` 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<string>`, so two rows against
the same group grant both roles. The other three apps bind `GroupToRole` as a
`Dictionary<string, string>` — **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_<T>` | Administrator | Administrator | Administrator | Administrator | |
| `UG_WW_APP_IDE_<T>` | 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_<T>` | — | 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_<T>` | Viewer | Viewer | Viewer | Viewer | |
| `UG_WW_HIST_ADMIN_<T>` | 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_<T>` (QA/PROD only) | — | Viewer | — | Viewer | `BTMGR_RO_QA` is **empty** (08-12). |
| `UG_WW_CITRIX_<T>` | — | — | — | — | **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_<SITE>_<AREA>_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}_<T>` | — | Operator (site-scoped) | — | — | |
| `UG_WW_<SITE>_<AREA>_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_<SITE>` | ⚠ §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 `<T>` 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_<SITE>` | `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<string>`, 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 '<svc account UPN>' -g 'UG_WW_*' # families + counts
dotnet run --project tools/LdapProbe -- --insecure --svc '<svc account UPN>' --self-bind <sAMAccountName> # 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_<T>` 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 <operator-account>` 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.