docs(cloud-console): document user authentication
This commit is contained in:
+136
@@ -0,0 +1,136 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Persistent user accounts protect password material
|
||||
The system SHALL persist uniquely identifiable human user accounts with a case-insensitive unique username, display name, fixed role, enabled state, forced-password-change state, and security timestamps, and SHALL store passwords only as salted Argon2id hashes that are never returned or logged.
|
||||
|
||||
#### Scenario: Administrator creates a user
|
||||
- **WHEN** an authorized administrator creates a user with a username, display name, role, and valid initial password
|
||||
- **THEN** the system stores the normalized unique identity and password hash, returns only non-secret account fields, and marks the account to change its initial password
|
||||
|
||||
#### Scenario: Username differs only by case
|
||||
- **WHEN** an administrator attempts to create a username that differs from an existing username only by normalization or letter case
|
||||
- **THEN** the system rejects the duplicate without changing either account
|
||||
|
||||
#### Scenario: Stored password needs stronger parameters
|
||||
- **WHEN** a user successfully signs in and the password hasher reports that the stored Argon2id parameters are outdated
|
||||
- **THEN** the system replaces the stored hash using current parameters without retaining or logging the submitted password
|
||||
|
||||
### Requirement: Fixed roles map to operation scopes
|
||||
The system SHALL map `viewer`, `operator`, and `admin` users to the existing Cloud API scopes so resource handlers authorize user sessions and bearer principals through the same `Principal` scope checks.
|
||||
|
||||
#### Scenario: Viewer accesses read dashboards
|
||||
- **WHEN** a logged-in `viewer` calls task-read, pool-read, or plugin-read operations
|
||||
- **THEN** the request is authorized, while task submission, plugin administration, and user administration remain forbidden
|
||||
|
||||
#### Scenario: Operator submits a task
|
||||
- **WHEN** a logged-in `operator` submits a task
|
||||
- **THEN** the request is authorized in addition to all viewer read operations, while plugin and user administration remain forbidden
|
||||
|
||||
#### Scenario: Administrator manages users
|
||||
- **WHEN** a logged-in `admin` invokes an operation requiring `users:admin` or another Cloud API scope
|
||||
- **THEN** the request is authorized subject to the operation's normal validation
|
||||
|
||||
### Requirement: Password login creates a revocable server-side session
|
||||
The system SHALL authenticate enabled users with username and password, SHALL create an opaque expiring session whose secret is stored only as a digest, and SHALL deliver the session secret in an `HttpOnly`, `SameSite` cookie that is `Secure` in production.
|
||||
|
||||
#### Scenario: Valid credentials create a session
|
||||
- **WHEN** an enabled user submits a correct username and password within throttle limits
|
||||
- **THEN** the system records a revocable session, returns the non-secret current-user representation, and sets the session and CSRF cookies with their required security attributes
|
||||
|
||||
#### Scenario: Credentials are not valid
|
||||
- **WHEN** the username is unknown, disabled, temporarily throttled, or paired with a wrong password
|
||||
- **THEN** the system returns the same generic authentication failure without revealing which condition occurred and without setting a session cookie
|
||||
|
||||
#### Scenario: Session is expired or revoked
|
||||
- **WHEN** a request presents a session whose idle or absolute expiry has passed, whose row is revoked, or whose authentication version no longer matches the user
|
||||
- **THEN** authentication fails and the system clears the browser session cookies
|
||||
|
||||
### Requirement: User session lifecycle is controllable
|
||||
The system SHALL let a logged-in user inspect the current account, sign out, and change their own password, and SHALL revoke sessions when a password, role, enabled state, or authentication version changes.
|
||||
|
||||
#### Scenario: User signs out
|
||||
- **WHEN** a logged-in user signs out with valid CSRF proof
|
||||
- **THEN** the current session is revoked server-side and both browser cookies are cleared
|
||||
|
||||
#### Scenario: User changes password
|
||||
- **WHEN** a logged-in user proves the current password and supplies a valid new password
|
||||
- **THEN** the password hash and authentication version are updated, other sessions are revoked, and the user must continue only with a newly established valid session
|
||||
|
||||
#### Scenario: Temporary password requires replacement
|
||||
- **WHEN** a user signs in while `must_change_password` is set
|
||||
- **THEN** the session may call current-user, password-change, and logout operations but cannot access other Cloud API resources until the password is changed
|
||||
|
||||
### Requirement: Cookie-authenticated writes require CSRF proof
|
||||
The system SHALL require a session-bound CSRF value on unsafe HTTP methods authenticated by a user cookie, while requests authenticated by an explicit bearer header SHALL remain exempt from cookie CSRF validation.
|
||||
|
||||
#### Scenario: Valid cookie session submits a write
|
||||
- **WHEN** a cookie-authenticated request uses an unsafe method and its `X-CSRF-Token` header matches the CSRF cookie and session-bound digest
|
||||
- **THEN** the request proceeds to normal scope and payload validation
|
||||
|
||||
#### Scenario: Cookie request omits CSRF proof
|
||||
- **WHEN** a cookie-authenticated request uses an unsafe method without matching CSRF proof
|
||||
- **THEN** the system rejects it before executing the operation
|
||||
|
||||
#### Scenario: Bearer client submits a write
|
||||
- **WHEN** an authorized client sends an unsafe request with an `Authorization: Bearer` credential and no session cookie is used for authentication
|
||||
- **THEN** the request is evaluated by existing bearer scope checks without requiring a CSRF header
|
||||
|
||||
### Requirement: Failed login attempts are throttled without permanent lockout
|
||||
The system SHALL enforce a bounded failed-login window and temporary block by normalized username and trusted client-address bucket, SHALL use generic client responses, and SHALL clear applicable failure state after successful authentication.
|
||||
|
||||
#### Scenario: Repeated failures exceed the limit
|
||||
- **WHEN** repeated failed logins for the same username and client bucket exceed the configured limit within the failure window
|
||||
- **THEN** further attempts are temporarily blocked, audited, and answered with the generic authentication failure
|
||||
|
||||
#### Scenario: Temporary block expires
|
||||
- **WHEN** the configured block duration passes
|
||||
- **THEN** the account can attempt authentication again without administrator intervention
|
||||
|
||||
#### Scenario: Unknown username is submitted
|
||||
- **WHEN** a login names no stored user
|
||||
- **THEN** the system performs timing-resistant dummy password verification and applies the same throttle and response behavior as a wrong password
|
||||
|
||||
### Requirement: Administrators control user lifecycle
|
||||
The system SHALL expose `users:admin`-protected operations to list and create users, change display name/role/enabled state, reset passwords, and revoke sessions, and SHALL prevent API actions that remove the last enabled administrator.
|
||||
|
||||
#### Scenario: Administrator disables an operator
|
||||
- **WHEN** an administrator disables an enabled operator
|
||||
- **THEN** the account can no longer authenticate and all of its active sessions are revoked
|
||||
|
||||
#### Scenario: Administrator resets a password
|
||||
- **WHEN** an administrator assigns a valid temporary password to another user
|
||||
- **THEN** existing sessions are revoked and the account is required to change that password after its next login
|
||||
|
||||
#### Scenario: Non-admin attempts user management
|
||||
- **WHEN** a viewer, operator, anonymous caller, or Host principal calls a user-administration operation
|
||||
- **THEN** the system rejects the request without exposing password or session state
|
||||
|
||||
#### Scenario: Last administrator would be removed
|
||||
- **WHEN** an API request would disable or demote the only enabled administrator
|
||||
- **THEN** the system rejects the request and preserves an enabled administrator
|
||||
|
||||
### Requirement: Deployment administrators can bootstrap and recover accounts safely
|
||||
The system SHALL provide an administration CLI that checks the current database schema, reads new passwords interactively without echo, and can create, reset, enable, or revoke sessions for user accounts without accepting passwords in command arguments.
|
||||
|
||||
#### Scenario: First administrator is created in Compose
|
||||
- **WHEN** a deployment administrator runs the user-create command inside the Cloud API container and enters a valid password twice at the interactive prompts
|
||||
- **THEN** an enabled administrator account is created without placing the password in process arguments, Compose configuration, or command output
|
||||
|
||||
#### Scenario: Interactive password confirmation differs
|
||||
- **WHEN** the two interactive password entries do not match
|
||||
- **THEN** the CLI exits unsuccessfully without changing the account
|
||||
|
||||
#### Scenario: Database schema is not current
|
||||
- **WHEN** a user administration CLI command runs against a database missing the required migration
|
||||
- **THEN** it fails with a migration diagnostic rather than creating partial schema state
|
||||
|
||||
### Requirement: Authentication security events are auditable without secrets
|
||||
The system SHALL record durable structured audit events for authentication and user-administration outcomes with actor, target, action, timestamp, outcome, and correlation context, and SHALL exclude submitted passwords, hashes, raw cookies, CSRF values, and bearer credentials.
|
||||
|
||||
#### Scenario: Login fails
|
||||
- **WHEN** a login attempt fails or is throttled
|
||||
- **THEN** the system records a safe failure category and correlation context without recording the submitted password or confirming whether the username exists
|
||||
|
||||
#### Scenario: Administrator changes a role
|
||||
- **WHEN** an administrator changes a user's role
|
||||
- **THEN** the system records the actor, target user id, old/new role metadata, outcome, and associated session revocation without any credential material
|
||||
Reference in New Issue
Block a user