Files

Joseph Doherty 34694adba2 Apply Codex review findings across all 17 components

Template Engine: add composed member addressing (path-qualified canonical names),
override granularity per entity type, semantic validation (call targets, arg types),
graph acyclicity enforcement, revision hashes for flattened configs.

Deployment Manager: add deployment ID + idempotency, per-instance operation lock
covering all mutating commands, state transition matrix, site-side apply atomicity
(all-or-nothing), artifact version compatibility policy.

Site Runtime: add script trust model (forbidden APIs, execution timeout, constrained
compilation), concurrency/serialization rules (Instance Actor serializes mutations),
site-wide stream backpressure (per-subscriber buffering, fire-and-forget publish).

Communication: add application-level correlation IDs for protocol safety beyond
Akka.NET transport guarantees.

External System Gateway: add 408/429 as transient errors, CachedCall idempotency
note, dedicated dispatcher for blocking I/O isolation.

Health Monitoring: add monotonic sequence numbers to prevent stale report overwrites.

Security: require LDAPS/StartTLS for LDAP connections.

Central UI: add failover behavior (SignalR reconnect, JWT survives, shared Data
Protection keys, load balancer readiness).

Cluster Infrastructure: add down-if-alone=on for safe singleton ownership.

Site Event Logging: clarify active-node-only logging (no replication), add 1GB
storage cap with oldest-first purge.

Host: add readiness gating (health check endpoint, no traffic until operational).

Commons: add message contract versioning policy (additive-only evolution).

Configuration Database: add optimistic concurrency on deployment status records.

2026-03-16 09:06:12 -04:00

6.4 KiB

Raw Blame History

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 Windows Integrated Authentication.
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

JWT Tokens

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.
JWT claims: User display name, username, list of roles (Admin, Design, Deployment), and for site-scoped Deployment, the list of permitted site IDs. All authorization decisions are made from token claims without hitting the database.

Token Lifecycle

JWT expiry: 15 minutes. On each request, if the token is near expiry, the app re-queries LDAP for current group memberships and issues a fresh token with updated claims. Roles are never more than 15 minutes stale.
Idle timeout: Configurable, default 30 minutes. If no requests are made within the idle window, the token is not refreshed and the user must re-login. Tracked via a last-activity timestamp in the token.
Sliding refresh: Active users stay logged in indefinitely — the token refreshes every 15 minutes as long as requests are made within the 30-minute idle window.

Load Balancer Compatibility

JWT tokens are self-contained — 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. Central failover is transparent to users with valid tokens.

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 valid (not-yet-expired) JWTs can continue operating with their current roles. The token refresh is skipped until LDAP is available again. This avoids disrupting engineers mid-work during a brief LDAP outage.
Recovery: When LDAP becomes reachable again, the next token refresh cycle re-queries group memberships and issues a fresh token with current roles.

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, notification lists) to all sites.
- View deployment diffs and status.
- Use debug view.
- Manage parked messages.
- 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.

6.4 KiB Raw Blame History