Files
scadaproj/ldap_mapping.md
T
Joseph Doherty 1d344a0c08 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
2026-11-15 20:28:09 -05:00

10 KiB

UG_WW_* → app role mapping (canonical matrix)

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.

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). 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-11-15)

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)

Things that are easy to get wrong:

  • 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".
  • Every app fails closed when no group matches. An unmapped group grants nothing, so leaving a group out is the safe default.

2. Why one role per group

  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.

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.

3. The environment axis is per deployment

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.

A config listing all three would make every DEV administrator a PROD administrator, silently. In §4, <T> stands for the deployment's tier suffix.

4. The matrix

— = deliberately unmapped (fails closed). ⚠ = needs a decision (§6), and is not mapped until it's made. One role per cell.

4.1 Platform groups (environment-scoped; mapped in the NAM cutover)

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.

4.2 Plant-floor, site and batch groups (NOT in the NAM cutover; mapped later, ScadaBridge only)

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).

4.3 Per-app config generated from §4.1

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.

{ "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" }

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

{ "UG_WW_APP_ADMIN_DEV": "Administrator", "UG_WW_APP_IDE_DEV": "Viewer", "UG_WW_APP_IDE_RO_DEV": "Viewer" }

HistorianGateway: Dashboard:GroupToRole

{ "UG_WW_APP_ADMIN_DEV": "Administrator", "UG_WW_HIST_ADMIN_DEV": "Administrator", "UG_WW_APP_IDE_RO_DEV": "Viewer" }

5. Group inventory: unverified since 2026-08-12

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.

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

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.

6. Open questions: DECIDE before mapping the §4.2 rows

  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 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.