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:
@@ -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`).
|
||||
|
||||
@@ -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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user