lmxopcua/.claude/rules/data-plane-auth.md

paths

paths
src/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/** src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/** src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/** src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/**/*Acl* docs/security.md

Data-plane authentication (API keys), node ACL enforcement, anonymous principal, AdminUI LDAP

Moved verbatim from the root CLAUDE.md (2026-10-13) so it loads only when working in this area. Root CLAUDE.md § "Subsystem guides" indexes it. Edit it here, not in the root file.

Authentication: API keys on the data plane, LDAP on AdminUI (#520)

⚠️ Changed 2026-07-31. The OPC UA data plane no longer uses LDAP at all. It is machine-to-machine, so a client presents an OPC UA UserName token with the fixed username apikey and an otua_<keyId>_<secret> credential as the password. ApiKeyOpcUaUserAuthenticator (src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/) implements IOpcUaUserAuthenticator: one indexed lookup on keyId plus one peppered HMAC-SHA256, FixedTimeEquals, no network I/O. The key resolves to a principal; NodeAcl.Principal rows grant it permissions. LdapOpcUaUserAuthenticator is deleted, along with four Security:Ldap keys that existed only for it (AuthTimeoutMs, MaxConcurrentAuthentications, OutageFailureThreshold, OutageCooldownSeconds) — they bounded an LDAP bind running inline in the SDK's synchronous, SessionManager-lock-holding impersonation callback, and nothing on the remaining LDAP path has that property.

LDAP remains, for AdminUI login only (Security:Ldap, OtOpcUaLdapAuthService → ILdapAuthService, group→role mapping via GroupToRole + LdapGroupRoleMapping). Do not "restore" the data-plane authenticator when you see LDAP wiring in Program.cs — it is there for the AdminUI.

Two things to know before relying on any of this:

• ⚠️ Node ACLs are enforced only behind Security:Acl:Enabled (default false). With the flag off, a key's grants collapse into the two server-wide role gates (WriteOperate on Value writes, AlarmAck on Part 9 methods), only Cluster-scoped grants count — ApiKeyInterimRoleMapper deliberately under-grants, because honouring a narrower grant's flags while unable to honour its scope would turn "WriteOperate on Equipment X" into server-wide write authority — and read, browse, subscribe and HistoryRead are ungated for any admitted session including Anonymous. With the flag on (DataPlaneAuthorizer), scoped grants decide every data-plane operation: write and alarm commands and HistoryRead (stage 5), read and browse and subscription creation (stage 6).
  • The two role gates re-check the session's KEY on every call, flag off or on (Gitea #563). Roles are resolved once at activation, so an expired / deployment-disabled key used to keep WriteOperate / AlarmAck on its open session until the client disconnected. DataPlaneAuthorizer.AuthorizeKeyUsable runs the same FindUsableKey probe against the same snapshot + clock as the ACL path (one dictionary lookup, no I/O) and denies BadUserAccessDenied before the role check. Only those two gates — reads/subscriptions stay ungated with the flag off, by design. Anonymous carries no key and is unaffected. No flag: a dead key keeping write authority is a defect, not a rollout choice. ⚠️ On a fused node a key minted after the last deploy authenticates (ConfigDb) but cannot write/ack until a deployment carries it — the flag-on path always behaved this way.
  • ⚠️ The ACL decision REPLACES the role check — the two are never chained. Chained, a grant would have to confer the server-wide role as well as pass the scope check, and only Cluster-scoped grants confer a role, so every narrow grant would stay inert and the flag would appear to do nothing. The load-bearing test is therefore an allow — a session carrying no roles writing successfully on the strength of its grant. A deny-only test passes against a build where the ACL is never consulted, because the role gate denies too.
  • The trie is built inside DataPlaneAuthorityState.Apply, not by a second wiring at the publish actor, and the state owns its PermissionTrieCache rather than being handed one. An uninstalled trie denies everything, which is indistinguishable from working enforcement until someone checks that an ALLOW is possible at all.
  • A deploy reaches sessions that are already open, in both directions: each decision stamps the current generation rather than the one the session activated under, and re-checks the authenticating key — so revoking a key or a grant stops an open session immediately instead of at the client's next reconnect. On a driver-only node the artifact is the only revocation channel.
  • UserAuthorizationState is built per decision walk, not per session — and since the hot-path change it is allocated only on a cache miss, so a cache hit never constructs one. Its LDAP-shaped freshness/staleness predicates are switched off EXPLICITLY (AuthCacheMaxStaleness = MaxValue). ⚠️ Relying on "the stamp is always fresh" was not safe: MembershipResolvedUtc comes from DataPlaneAuthorizer's TimeProvider while IsStale is evaluated against TriePermissionEvaluator's, so any divergence between the two clocks denies every request with a verdict indistinguishable from "no grant matched". Found by a test clock two hours ahead.
  • Stage 6's hot seams (read/browse/subscribe) go through a per-(session, node, operation, realm) decision cache, cleared wholesale when the generation advances. It is sharded per API key (ApiKeyId ?? Principal — despite the type name, sessions sharing one key share one shard and one budget), so a client crawling a large tree past the per-key ceiling evicts only that key's shard and not every other key's decisions. ⚠️ It caches the grant walk only — key revocation and expiry are re-checked before the cache lookup on every call, because expiry moves with the clock rather than with a deployment.
  • Browse needs ancestor visibility, and it must NOT be a synthesized grant on the ancestors. A grant deep in the tree is reached by browsing the nodes above it, and the trie inherits downward only, so PermissionTrieNode.BrowseTransitPrincipals marks the path. Planting a real Browse grant on each ancestor instead would be collected by the additive downward walk and leak Browse onto every sibling subtree beneath that ancestor. ⚠️ The topmost ancestor is the single shared root folder (s=OtOpcUa, raw namespace) that BOTH realm trees hang under — its identifier is a display name, not a path, so DataPlaneAuthorizer.BuildScope maps it onto the trie's zero-segment realm-root scope (V3NodeIds.SharedRootFolderId, realm-qualified: in the UNS namespace that identifier is an ordinary Area), and its Browse considers transit in either realm because it fronts both trees. Before this every narrow Browse grant was unreachable by navigation — the Browse gate denies the whole call when its source node is denied, so clients were stopped at the front door.
  • Revocation reaches live subscriptions (stage 6): every other operation re-asks per request, but a subscription is authorized once and then streams — and streaming is how machine consumers actually read this server. DataPlaneAuthorityState.Changed fires RevalidateMonitoredItems. ⚠️ A denied item is queued BadUserAccessDenied and then detached from its MonitoredNode2 fan-out — NOT set MonitoringMode.Disabled: disabling discards the item's queued notifications, so the client is silenced without ever being told why (caught only by the over-the-wire test). Detaching is also reversible, so restoring the grant resumes the feed with no client action. ⚠️ Changed is no longer the only trigger (arch-review 03/S19): AclRevalidationTimer, armed by OtOpcUaServerHostedService at Security:Acl:RevalidationIntervalSeconds (default 60 s, 0 disables, inert while Security:Acl:Enabled is false), runs the same pass on the clock — because ExpiresUtc passes with the clock, not with a deployment. The pass's verdict memo is pass-local and must stay that way; hoisting it across ticks would serve an expiry that landed between two ticks the earlier tick's allow. Event/alarm items ride both triggers too (Gitea #562) — a second map (_eventItems), fed by the SubscribeToEvents override, holds every direct notifier subscription; a denied one is detached via the SDK's own protected SubscribeToEvents(…, unsubscribe: true) (what a client delete does) and re-attached with unsubscribe: false on restore — again never Disabled. Unlike a data item it is not told (no value slot for a status; the feed goes quiet), and a client delete of a stood-down item is absorbed by the override (the SDK would otherwise remove an item that is not attached). Server-object (i=2253) event subscriptions are filtered per event at delivery (Gitea #586). The SubscribeToAllEvents override attaches them to nothing (just records them in _allEventsItems); each condition's own OnReportEvent (OnConditionReportEvent, fires once per event ⇒ still one Server-object copy) queues the event to each recorded item whose session holds Subscribe on the condition (RawPath) or any notifier folder it reports through — the per-folder path's question. The root-notifier forward to the core Server object (OnReportEvent override) is dropped: it was the ungated path, and it is the only one that served an item created before the alarm was deployed (the SDK's AddRootNotifier subscribes existing all-events items with unsubscribe: true). Revalidation is implicit — every event re-asks the authorizer, so a deploy or expiry lands on the next event with no pass. ConditionRefresh on an i=2253 item is filtered the same way. The dispatcher must keep the SDK's audit guard (AuditEventState only while Server.Auditing over SignAndEncrypt/https), because conditions report their Part 9 method audit events through themselves. ReconcileAllEventsMonitoring must keep AreEventsMonitored raised on every condition while any i=2253 item exists, because ConditionState gates its method audit reports on EventsMonitored() (method-driven state-change events no longer depend on it — #587, below). The protected SubscribeToEvents override that no-ops all-events items is what stops the SDK's AddRootNotifier (unsubscribe: true bug) taking that unit back. Both review findings (review of 75e559f6). ⚠️ The materialise path raises only the new condition's unit (RaiseAllEventsMonitoring); a full reconcile there made a deploy of N alarms O(N²) under Lock with ScadaBridge connected — keep the full reconcile to remove/rebuild/(un)subscribe. Model-change and audit events are gated too (Gitea #588). The manager's own server-wide events (GeneralModelChangeEvent, the rejected-write AuditWriteUpdateEvent) go through ReportToServerObject: flag off ⇒ Server.ReportEvent as before; flag on ⇒ delivered per item to _allEventsItems (same audience), a model change narrowed to the Affected nodes the session may Browse (dropped when none — the builders' Messages name the node, so a narrowed copy gets a neutral one), an audit write only with Read on its source node plus the SDK's audit/encryption guard. Any other event type fails closed. Auditing is off by default (never configured in this repo).
• ns=0 standard nodes stay ungated by design, even with Security:Acl:Enabled (#617) — ServerStatus, NamespaceArray, ServiceLevel etc. are served by the SDK's core node manager outside our authorizer and clients read them to connect and to judge redundancy health; they carry no plant data. Every raw/UNS node, event subscription and HistoryRead is still gated. docs/security.md.
• Equipment-node writes: EvaluateEquipmentWriteStructure is the ONLY type check. OnWriteValue bypasses the SDK's own type check on every writable equipment node, so OtOpcUaNodeManager.EvaluateEquipmentWriteStructure (plus EvaluateEquipmentWriteRange) is the whole gate. Scalars are deliberately lenient (drivers range-check; ScadaBridge sends Double to a Float node). Array writes (#610): a numeric array of another element type is converted, checked, element by element to the node's element type (ScadaBridge writes CLR int[]/double[] lists) — any out-of-range, fractional-to-integer or NaN/∞ element refuses the whole write BadTypeMismatch with nothing sent, so a UInt32 > Int32.MaxValue can never reach a Galaxy Int32 attribute as reinterpreted bits; non-numeric mismatches are refused (Byte[] ≈ ByteString); wrong length ⇒ BadTypeMismatch; an array to a scalar node is refused only on Modbus/S7 (EnsureVariable's refuseArrayOnScalar — pass-through drivers keep their browse-committed scalar-shaped array tags writable; a new sink wrapper must forward that argument, and the reflection guard checks only that the call arrives); IndexRange writes ⇒ BadWriteNotSupported, ValueRank > 1 out of scope. An array node is writable only when the driver can write the array (DriverArrayWriteSupport: Modbus bounded by maxRegistersPerWrite/coil cap, S7 non-Bool/non-wide types, OpcUaClient, Galaxy signed types with a declared arrayLength — an undeclared length stays read-only because a short whole-array write would resize the Galaxy attribute); arrayLength >= 1 is required, and the node's Writable && (!IsArray || ArrayWritable) is projected onto the raw node and every UNS mirror.
• Anonymous is a normal grantable principal, not a bypass. OpcUa:AllowAnonymous (default true, preserving today's behaviour) controls admission; when admitted the session authenticates as the reserved principal anonymous and gets roles from NodeAcl rows naming it, arriving at the gates as the same RoleCarryingUserIdentity a key produces. Set it false to make keys mandatory. A key may not use the anonymous principal, and a failure to read anonymous's grants denies rather than admitting with no roles.
• Keys reach a driver-only node inside the deployment artifact (stage 4). ConfigComposer snapshots the ApiKey rows — the peppered HMAC only, never a secret, and the pepper is node config that is deliberately not in the artifact — and DeploymentArtifact.ParseDataPlaneAuthority decodes them node-side alongside the cluster's NodeAcl rows. OpcUaPublishActor installs both on IDataPlaneAuthoritySource on every apply, before its plan.IsEmpty early-return, so a deployment that only revokes a key still lands. A node with a ConfigDb keeps ConfigDbApiKeyStore (per-activation read, wrapped — see below); a driver-only node gets ArtifactApiKeyStore. ⚠️ The asymmetry is ACTIVATION-scoped, not session-scoped — this line used to say "immediate on a ConfigDb node" and that was wrong. Clearing Enabled in the ConfigDb stops the next session activation on an admin/fused node (bounded by Security:ApiKeys:StoreCacheSeconds, default 5 s) and takes until the next deployment on a driver-only one — but an already-open session re-checks its key against the in-memory artifact snapshot (DataPlaneAuthorizer.Evaluate → snapshot.FindUsableKey), never against IApiKeyStore, so on both node kinds an Enabled revocation reaches an open session only at the next deployment. Expiry is the exception: FindUsableKey compares ExpiresUtc against the authorizer's clock on every call, so it is immediate everywhere — and since arch-review 03/S19 it reaches live subscriptions too, on the host's Security:Acl:RevalidationIntervalSeconds timer (default 60 s; the session is silenced with BadUserAccessDenied, not closed, and recovers on re-activation). Direct event/alarm subscriptions are revalidated on both triggers as well (#562); with the flag off, expiry and revocation reach the two role gates (#563) but not reads or subscriptions.
• ⚠️ The activation lookup is BOUNDED (arch-review 03/S18). The SDK raises impersonation synchronously under a SessionManager-wide lock, so a ConfigDb that is slow rather than refusing stalled every session activation on the server, Anonymous and X.509 included. BoundedApiKeyStore wraps the ConfigDb store — and only it, never ArtifactApiKeyStore, which is two in-memory dictionary probes — with Security:ApiKeys:StoreTimeoutMs (2000; exceeding it denies, via the authenticator's existing catch-all) plus a StoreCacheSeconds (5) read-through cache. Faults and timeouts are never cached, a cached hit whose ExpiresUtc has passed is re-read rather than served, and a timeout logs a distinct Warning + otopcua.opcua.apikey_store.bounded{outcome=timeout}. Both knobs at 0 restore the old behaviour exactly.
• ⚠️ The auth generation is a node-local COUNTER driven by the RevisionHash, not derived from its bits. PermissionTrieCache treats the highest GenerationId as current, so a generation taken from hash bytes would install a lower number about half the time and the cache would go on serving the previous deployment's ACLs with nothing logged. Pinned by DataPlaneAuthorityStateTests.The_generation_only_ever_increases_even_when_the_hash_decreases.
• Note OtOpcUaServerHostedService takes IOpcUaUserAuthenticator and IDataPlaneAuthoritySource as required ctor parameters — the built-in DI container does not fall back to a default value for an unregistered service, so both must be registered explicitly on every node (deny-all / empty on a node with neither role) or it does not boot.

Grants are authored through a scope picker, not free text (stage 7). /clusters/{id}/acls opens AclScopePickerModal over the cluster's raw + UNS trees, and selecting a node supplies ScopeKind and ScopeId together — so RawDevice + a TagId, a cross-cluster scope, a Cluster grant carrying an id, and the retired FolderSegment kind are all unauthorable by construction rather than merely rejected later. ⚠️ A Cluster row must produce a NULL ScopeId — the deploy gate rejects one that carries an id (NodeAclScopeIdUnexpected), so a picker that helpfully filled in the cluster id would author rows that cannot be deployed. IAclScopeService.CheckScopeAsync mirrors DraftValidator.ValidateNodeAclScopes rule for rule and blocks the save when a scope resolves to nothing (re-checked on submit, since a row loaded unchanged is exactly where the operator never touches the picker); the list page marks such rows unresolved. UNS tags are deliberately not offered — a UNS signal is a UnsTagReference, and a Tag grant already covers the raw node and every UNS projection of it. The picker is AclScopeTree, a separate component from RawTree, which already carries two modes.

All eight stages are done (d4389f57 enforcement, stage 7 authoring after it), each live-gated on docker-dev. The rationale for every decision above is in docs/plans/2026-07-31-apikey-acl-enforcement-design.md. See docs/security.md for the full guide.

Dev/test LDAP is the shared GLAuth running on the Linux Docker host at 10.100.0.35:3893 (baseDN dc=zb,dc=local, plaintext/Transport=None). It is managed via scadaproj/infra/glauth/ (source of truth + deploy runbook). Single bind account cn=serviceaccount,dc=zb,dc=local / serviceaccount123; all test users password password. The docker-dev compose binds this shared instance directly — DevStubMode is no longer used. The per-VM NSSM GLAuth at C:\publish\glauth\ and the old base DNs dc=lmxopcua,dc=local / dc=otopcua,dc=local are obsolete. (The integration-test harness under tests/.../Host.IntegrationTests/ runs its own ephemeral GLAuth container on port 3894 — seeded by tests/.../Host.IntegrationTests/glauth/config.toml with dev users alice/bob + the cn=serviceaccount bind account — for the opt-in OTOPCUA_HARNESS_USE_LDAP=1 real-bind mode; distinct from the shared dev GLAuth on 3893. It replaced the retired bitnami/openldap:2.6 in PR #451, 2026-07-15.)