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

158 lines
10 KiB
Markdown

# `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<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.
```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 '<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.