ss-tools/specs/016-multi-user-auth/spec.md

Feature Specification: Multi-User Authentication and Authorization

Feature Branch: 016-multi-user-auth Created: 2026-01-26 Status: Draft Input: User description: "Нужна поддержка многопользовательского логина. Нужно, чтобы пользователи могли логинится по связке логин/пароль, поддержка adfs, разделение прав доступа по плагинам"

Clarifications

Session 2026-01-26

• Q: Permission Model Structure? → A: RBAC (Role-Based Access Control) - Permissions assigned to Roles, Users assigned to Roles.
• Q: Initial Admin Provisioning? → A: CLI Command/Script - Explicit script to create the first admin user.
• Q: ADFS User Role Assignment? → A: AD Group Mapping - Login requires valid AD group membership; AD groups map to local Roles (e.g., 'superset_admin' -> 'Admin').
• Q: Token Management? → A: JWT (JSON Web Tokens) - Stateless, scalable, standard for SPAs.
• Q: Persistence Layer? → A: Dedicated SQLite DB (auth.db) - Relational storage for Users, Roles, Permissions.
• Q: Switching Auth Providers? → A: Dual Support - Both Local and ADFS login options are available simultaneously on the login page.

User Scenarios & Testing (mandatory)

User Story 1 - Local User Authentication (Priority: P1)

As a user, I want to log in using a username and password so that I can securely access the application.

Why this priority: Basic authentication is the foundation for multi-user support and is required before implementing more complex auth methods or permissions.

Independent Test: Can be fully tested by creating a local user account and successfully logging in/out without any external dependencies.

Acceptance Scenarios:

1. Given a registered user, When they enter valid credentials on the login page, Then they are redirected to the dashboard and receive a session token.
2. Given a registered user, When they enter invalid credentials, Then they see an error message "Invalid username or password".
3. Given an authenticated user, When they click logout, Then their session is terminated and they are redirected to the login page.

---

User Story 2 - Plugin-Based Access Control (Priority: P1)

As an administrator, I want to assign specific plugin access rights to users so that I can control who can use sensitive tools (e.g., Backup, Migration).

Why this priority: Security is a core requirement. Without granular permissions, all authenticated users would have full administrative access, which defeats the purpose of multi-user support.

Independent Test: Create two users with different permissions (e.g., User A has access to "Backup", User B does not). Verify User A can access the Backup tool while User B receives a 403 Forbidden error.

Acceptance Scenarios:

1. Given a user with "Backup" plugin permission, When they navigate to the Backup tool, Then the page loads successfully.
2. Given a user WITHOUT "Backup" plugin permission, When they navigate to the Backup tool, Then they are denied access (UI hides the link, API returns 403).
3. Given an administrator, When they edit a user's permissions, Then the changes take effect immediately or upon next login.

---

User Story 3 - ADFS Integration (Priority: P2)

As a corporate user, I want to log in using my organization's ADFS credentials so that I don't have to manage a separate password.

Why this priority: Essential for enterprise environments but dependent on the core authentication infrastructure being in place (Story 1).

Independent Test: Configure the application with a test ADFS provider (or mock). Verify a user can initiate the SSO flow and be logged in automatically.

Acceptance Scenarios:

1. Given a configured ADFS provider, When a user clicks "Login with ADFS", Then they are redirected to the identity provider.
2. Given a successful ADFS authentication, When the user returns to the app, Then a local user session is created/matched and they are logged in.
3. Given a new ADFS user, When they log in for the first time, Then a local user record is automatically created (JIT provisioning) with default permissions.

---

Edge Cases

• What happens when an ADFS user's account is disabled in the local system? (Should block login even if ADFS succeeds)
• How does the system handle concurrent sessions? (Allow or restrict?)
• What happens if a plugin is removed but users still have permission for it? (Graceful handling/cleanup)
• What happens if the ADFS server is unreachable? (Fallback to local login if applicable, or clear error message)

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST support local user authentication via username and password.
• FR-002: System MUST support authentication via ADFS (Active Directory Federation Services) using standard federation protocols.
• FR-003: System MUST provide a mechanism to manage users (Create, Read, Update, Delete) - restricted to administrators.
• FR-004: System MUST implement Role-Based Access Control (RBAC) where permissions are assigned to Roles, and Roles are assigned to Users.
• FR-005: System MUST enforce permissions at the server level for all plugin execution requests.
• FR-006: System MUST enforce permissions at the user interface level (hide navigation items/buttons for unauthorized plugins).
• FR-007: System MUST securely store local user credentials.
• FR-008: System MUST support Just-In-Time (JIT) provisioning for ADFS users ONLY if they belong to a mapped AD group.
• FR-009: System MUST provide a CLI utility to create an initial administrator account to prevent lockout during first deployment.
• FR-010: System MUST allow configuring mappings between Active Directory Groups and local System Roles.
• FR-011: System MUST use JWT (JSON Web Tokens) for API session management.
• FR-012: System MUST persist authentication and authorization data in a dedicated SQLite database (auth.db).
• FR-013: System MUST provide a unified login interface supporting both Local (Username/Password) and ADFS (SSO Button) authentication methods simultaneously.

Key Entities

• User: Represents a system user. Attributes: ID, Username, Email, PasswordHash, AuthSource (Local/ADFS), IsActive, Roles (List[RoleID]).
• Role: Named collection of permissions. Attributes: ID, Name, Description, Permissions (List[Permission]).
• Permission: Represents access capability. Attributes: ResourceID (e.g., Plugin ID), Action (Execute, Read).
• ADGroupMapping: Configuration mapping AD Group names to Role IDs.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Administrators can successfully create a new local user and assign specific plugin permissions in under 2 minutes.
• SC-002: Users without permission for a specific plugin are denied access 100% of the time when attempting to use its functions.
• SC-003: ADFS login flow completes successfully for valid credentials and maps to the correct local user identity.
• SC-004: User interface dynamically updates to show only permitted tools for the logged-in user.

Assumptions

• The application currently has a simple or placeholder authentication mechanism.
• "Plugin access" refers to the ability to use the plugin's functionality and view its interface.
• A default administrator account will be available upon initial system setup to prevent lockout.