Files
scadaproj/ldap_mapping.md
T

12 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), case-sensitive once bound (plan §2B)

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".
  • No role, no login: the family standard (DECIDED 2026-11-15). Every app refuses sign-in, cookie and token, when the user's groups map to no role, including when the role lookup fails.
    • Today only mxgw (DashboardAuthenticator.cs:66-70) and HG (:56-64) do this.
    • OtOpcUa (Security/Endpoints/AuthEndpoints.cs:124-158, even when the mapper throws) and ScadaBridge (CentralUI/Auth/AuthEndpoints.cs:59-115) sign such a user in with no roles. Their read-only pages (AuthenticatedRead / bare [Authorize]) would then be open to any AD user.
    • The cutover plan's Phase A (OtOpcUa) and A2 (ScadaBridge) fix this before either app is pointed at NAM.
    • Once fixed, an unmapped group grants nothing, so leaving a group out is the safe default.
  • Viewer in OtOpcUa means "holds a role, so may sign in". No OtOpcUa policy checks Viewer; its read pages only require an authenticated user. Under the standard above, being signed in requires some mapped role, so the Viewer cells (§4) are what grant AdminUI read access.
  • HistorianGateway matches group names case-sensitively in practice. The binder replaces its OrdinalIgnoreCase default with a plain Dictionary (cutover plan §2B). Copy group names exactly as LdapProbe prints them in every app.

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. DEV interim (2026-11-19, plan §0.2): ScadaBridge DEV maps UG_WW_HIST_ADMIN_DEV → Deployer (same 7 members as APP_ADMIN_DEV) until this group exists.
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>' -u <sAMAccountName>          # one person's groups (service-account path)
dotnet run --project tools/LdapProbe -- --insecure --self-bind -u <sAMAccountName>                         # the same, binding as that person (--svc ignored)

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 and refuse zero-role logins before its cutover (cutover plan §2). ScadaBridge must refuse zero-role logins before its cutover (§2A).
  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.