34694adba2
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.
118 lines
6.4 KiB
Markdown
118 lines
6.4 KiB
Markdown
# 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.
|