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