# `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. - **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. > **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` (`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` (`Configuration/DashboardOptions.cs:69`) | | **HistorianGateway** | `Viewer`, `Administrator` (`Dashboard/DashboardRoles.cs`) | `Dashboard:GroupToRole` | `IReadOnlyDictionary` (`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, `` 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_` | Administrator | Administrator | Administrator | Administrator | | | `UG_WW_APP_IDE_` | 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_` | — | 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_` | Viewer | Viewer | Viewer | Viewer | | | `UG_WW_HIST_ADMIN_` | 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_` (QA/PROD only) | — | Viewer | — | Viewer | `BTMGR_RO_QA` is **empty** (08-12). | | `UG_WW_CITRIX_` | — | — | — | — | **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___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}_` | — | Operator (site-scoped) | — | — | | | `UG_WW___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_` | ⚠ §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 `` 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 { "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` ```json { "UG_WW_APP_ADMIN_DEV": "Administrator", "UG_WW_APP_IDE_DEV": "Viewer", "UG_WW_APP_IDE_RO_DEV": "Viewer" } ``` **HistorianGateway:** `Dashboard:GroupToRole` ```json { "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. ```bash dotnet run --project tools/LdapProbe -- --insecure --svc '' -g 'UG_WW_*' # families + counts dotnet run --project tools/LdapProbe -- --insecure --svc '' --self-bind # 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_` 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.