ScadaBridge/docs/requirements/Component-Security.md

Component: Security & Auth

Purpose

The Security & Auth component handles user authentication via LDAP/Active Directory and enforces role-based authorization across the system. It maps LDAP group memberships to system roles and applies permission checks to all operations.

Location

Central cluster. Sites do not have user-facing interfaces and do not perform independent authentication.

Responsibilities

• Authenticate users against LDAP/Active Directory using a direct LDAP/AD bind (username/password).
• Map LDAP group memberships to system roles.
• Enforce role-based access control on all API and UI operations.
• Support site-scoped permissions for the Deployment role.

Authentication

• Mechanism: The Central UI presents a username/password login form. The app validates credentials by binding to the LDAP/AD server with the provided credentials, then queries the user's group memberships.
• Transport security: LDAP connections must use LDAPS (port 636) or StartTLS to encrypt credentials in transit. Unencrypted LDAP (port 389) is not permitted.
• No local user store: All identity and group information comes from AD. No credentials are cached locally.
• No Windows Integrated Authentication: The app authenticates directly against LDAP/AD, not via Kerberos/NTLM.

Session Management

Cookie + JWT Hybrid

• On successful authentication, the app issues a JWT signed with a shared symmetric key (HMAC-SHA256). Both central cluster nodes use the same signing key from configuration, so either node can issue and validate tokens.
• The JWT is embedded in an authentication cookie rather than being passed as a bearer token. This is the correct transport for Blazor Server, where persistent SignalR circuits do not carry Authorization headers — the browser automatically sends the cookie with every SignalR connection and HTTP request.
• The cookie is HttpOnly and Secure (requires HTTPS).
• On each request, the server extracts and validates the JWT from the cookie. All authorization decisions are made from the JWT claims without hitting the database.
• JWT claims: User display name, username, list of roles (Admin, Design, Deployment), and for site-scoped Deployment, the list of permitted site IDs.

Token Lifecycle

Implementation note (M2.19, #15). The interactive Central UI login path signs in with bare cookie claims, not a cookie-embedded JWT. The session lifecycle below is therefore enforced by the cookie middleware (ExpireTimeSpan + SlidingExpiration) plus a CookieAuthenticationEvents.OnValidatePrincipal handler — see Session Validation (OnValidatePrincipal) below. The embedded-JWT model remains the documented design intent and is the mechanism for any non-cookie bearer surface (e.g. /auth/token), but it is not the transport for the cookie principal.

• Idle timeout: Configurable, default 30 minutes. If no requests are made within the idle window, the session is rejected and the user must re-login. Tracked via a LastActivity last-activity timestamp claim. The cookie's ExpireTimeSpan is set to the idle timeout and SlidingExpiration renews it on activity, so the cookie window and the explicit OnValidatePrincipal idle check use the same value and cannot contradict each other.
• Role-mapping refresh (LDAP-free): Configurable, default 15 minutes (SecurityOptions.RoleRefreshThresholdMinutes). At login the session stores the user's raw LDAP groups (one zb:group claim each) plus a zb:lastrolerefresh anchor. Once the anchor is older than the threshold, OnValidatePrincipal re-runs the DB-backed RoleMapper on the stored groups — with no LDAP call — rebuilds the role/scope claims via the shared claim-builder, advances the anchor, and re-issues the cookie. Central role-mapping (DB) changes — including a revoked mapping that drops the user's roles, and changed site-scope rules — take effect within this window. Roles derived from central mappings are never more than ~15 minutes stale.

Session Validation (OnValidatePrincipal)

• The cookie principal is built at login by a single shared claim-builder (SessionClaimBuilder). The OnValidatePrincipal role-refresh path rebuilds the principal through the same builder, so the login and refresh claim shapes cannot drift.
• Failure policy: the refresh is best-effort. Any error during the refresh (e.g. the configuration database is unreachable) keeps the existing principal with its current roles — it never signs the user out and never throws out of the request pipeline. This mirrors the Active sessions stance under LDAP Connection Failure below. Only the explicit idle-timeout path rejects the principal.

Residual limitation — live LDAP group-membership changes (follow-up). The mid-session refresh re-maps the stored groups against the central database; it does not re-query LDAP, so a change to the user's actual group membership in the directory is picked up only at next login. A live group re-query for an active session would require a new passwordless service-account group-search method on the shared ZB.MOM.WW.Auth.Ldap library, which is an external NuGet package and exposes only AuthenticateAsync(username, password, ct) (no standalone group search). Adding that method is tracked as a follow-up. Until then: central role-mapping/scope changes are reflected within ~15 minutes; directory group-membership changes require re-login.

Load Balancer Compatibility

• The authentication cookie carries a self-contained JWT — no server-side session state. A load balancer in front of the central cluster can route requests to either node without sticky sessions or a shared session store.
• Since both central nodes share the same JWT signing key, either node can validate the cookie-embedded JWT. Central failover is transparent to users with valid cookies.

LDAP Connection Failure

• New logins: If the LDAP/AD server is unreachable, login attempts fail. Users cannot be authenticated without LDAP.
• Active sessions: Users with a valid (not-idle-timed-out) session can continue operating with their current roles during an LDAP outage. Interactive cookie sessions never re-query LDAP mid-session (the mid-session role-mapping refresh is DB-only — see Session Validation above), so a brief LDAP outage does not disrupt engineers mid-work; central role-mapping changes still apply within the refresh window regardless of LDAP availability.
• Recovery (group-membership changes): Because the mid-session refresh is LDAP-free, a change to a user's directory group membership is picked up at the user's next login (when LDAP is queried again), not mid-session — see the Residual limitation note above.

Roles

Admin

• Scope: System-wide (always).
• Permissions:
  • Manage site definitions.
  • Manage site-level data connections (define and assign to sites).
  • Manage area definitions per site.
  • Manage LDAP group-to-role mappings.
  • Manage API keys (create, enable/disable, delete).
  • System-level configuration.
  • View audit logs.

Design

• Scope: System-wide (always).
• Permissions:
  • Create, edit, delete templates (including attributes, alarms, scripts).
  • Manage shared scripts.
  • Manage external system definitions.
  • Manage database connection definitions.
  • Manage notification lists and SMTP configuration.
  • Manage inbound API method definitions.
  • Run on-demand validation (template flattening, script compilation).

Deployment

• Scope: System-wide or site-scoped.
• Permissions:
  • Create and manage instances (overrides, connection bindings, area assignment).
  • Disable, enable, and delete instances.
  • Deploy configurations to instances.
  • Deploy system-wide artifacts (shared scripts, external system definitions, DB connections, data connections) to all sites.
  • View deployment diffs and status.
  • Use debug view.
  • Manage parked messages.
  • Monitor and manage the Notification Outbox (retry and discard parked notifications).
  • View site event logs.
• Site scoping: A user with site-scoped Deployment role can only perform these actions for instances at their permitted sites.

Multi-Role Support

• A user can hold multiple roles simultaneously by being a member of multiple LDAP groups.
• Roles are independent — there is no implied hierarchy between roles.
• For example, a user who is a member of both SCADA-Designers and SCADA-Deploy-All holds both the Design and Deployment roles, allowing them to author templates and also deploy configurations.

LDAP Group Mapping

• System administrators configure mappings between LDAP groups and roles.
• Examples:
  • SCADA-Admins → Admin role
  • SCADA-Designers → Design role
  • SCADA-Deploy-All → Deployment role (all sites)
  • SCADA-Deploy-SiteA → Deployment role (Site A only)
  • SCADA-Deploy-SiteB → Deployment role (Site B only)
• A user can be a member of multiple groups, granting multiple independent roles.
• Group mappings are stored in the configuration database and managed via the Central UI (Admin role).

Permission Enforcement

• Every API endpoint and UI action checks the authenticated user's roles before proceeding.
• Site-scoped checks additionally verify the target site is within the user's permitted sites.
• Unauthorized actions return an appropriate error and are not logged as audit events (only successful changes are audited).

Dependencies

• Active Directory / LDAP: Source of user identity and group memberships.
• Configuration Database (MS SQL): Stores LDAP group-to-role mappings and site scoping rules.
• Configuration Database (via IAuditService): Security/admin changes (role mapping updates) are audit logged.

Interactions

• Central UI: All UI requests pass through authentication and authorization.
• Template Engine: Design role enforcement.
• Deployment Manager: Deployment role enforcement with site scoping.
• All central components: Role checks are a cross-cutting concern applied at the API layer.
• Management Service: The ManagementActor enforces role-based authorization on every incoming command using the authenticated user identity carried in the message envelope. The CLI authenticates users via the same LDAP bind mechanism and passes the user's identity (username, roles, permitted sites) in every request message. The ManagementActor applies the same role and site-scoping rules as the Central UI — no separate authentication path exists on the server side.
• Transport (#24): Provides the RequireDesign policy (export) and RequireAdmin policy (import) enforced at both the Razor page layer and inside the ZB.MOM.WW.ScadaBridge.Transport service entrypoints.