diff --git a/docs/security.md b/docs/security.md
index 8c899ec6..e04d4127 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -160,7 +160,7 @@ LDAP is configured under the `Security:Ldap` section (bound to `LdapOptions`, `s
 }
 ```
 
-`GroupToRole` maps LDAP group names → Admin roles (case-insensitive); a user gets every role whose source group is in their membership. The values are the canonical control-plane role strings (`Viewer` / `Designer` / `Administrator`, plus the appsettings-only `Operator` for the `DriverOperator` policy). `UserNameAttribute: "sAMAccountName"` is the critical AD override — the GLAuth dev default is `cn`, which is not how AD users are looked up; use `userPrincipalName` instead if operators log in with `user@corp.example.com` form. `LdapOptionsValidator` (`src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LdapOptionsValidator.cs`) fails startup when `Transport = None` and `AllowInsecure = false` on a real-LDAP (non-DevStub) config.
+`GroupToRole` maps LDAP group names → roles (case-insensitive); a user gets every role whose source group is in their membership. The values are the canonical control-plane role strings (`Viewer` / `Designer` / `Administrator`, plus the appsettings-only `Operator` for the `DriverOperator` policy); the same map also supplies data-plane role strings (`ReadOnly`, `WriteOperate`, `WriteTune`, `WriteConfigure`, `AlarmAcknowledge`) — see [Role grant source (data-plane)](#role-grant-source-data-plane) below. `UserNameAttribute: "sAMAccountName"` is the critical AD override — the GLAuth dev default is `cn`, which is not how AD users are looked up; use `userPrincipalName` instead if operators log in with `user@corp.example.com` form. `LdapOptionsValidator` (`src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LdapOptionsValidator.cs`) fails startup when `Transport = None` and `AllowInsecure = false` on a real-LDAP (non-DevStub) config.
 
 ---
 
@@ -242,6 +242,29 @@ Key properties:
 
 See [`docs/v2/acl-design.md`](v2/acl-design.md) for the complete design: trie invalidation, flag semantics, per-path override rules, and the reasoning behind additive-only (no Deny).
 
+### Role grant source (data-plane)
+
+Data-plane roles come from `Security:Ldap:GroupToRole` (appsettings), **not** from the Config-DB
+`LdapGroupRoleMapping` table. That table's `Role` column is the `AdminRole` enum
+(`Administrator`/`Designer`/`Viewer`) and supplies **control-plane** roles only — it cannot emit the
+data-plane role strings the OPC UA gates read (`ReadOnly`, `WriteOperate`, `WriteTune`,
+`WriteConfigure`, `AlarmAcknowledge`). A deployment therefore **must** map its data-plane LDAP groups
+to those role strings via `GroupToRole`, e.g.:
+
+```json
+"GroupToRole": {
+  "ot-operators":  "WriteOperate",
+  "ot-tuners":     "WriteTune",
+  "ot-engineers":  "WriteConfigure",
+  "ot-alarm-ack":  "AlarmAcknowledge",
+  "ot-readonly":   "ReadOnly"
+}
+```
+
+If this mapping is absent the data-plane evaluator is strictly default-deny: inbound operator writes
+and OPC UA Part-9 alarm acknowledgement all return `BadUserAccessDenied` even for users who
+authenticate successfully. (The same requirement gates the pre-existing scripted-alarm ack path.)
+
 ---
 
 ## Control-Plane Authorization