scadalink-design/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 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: Windows Integrated Authentication (Kerberos/NTLM) against Active Directory.
• Session: Authenticated user identity is maintained for the duration of the UI session.
• No local user store: All identity and group information comes from AD.

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.