docs(cloud-console): document user authentication

2026-07-13 17:55:21 +08:00
parent cdef630e67
commit c72c31de04
10 changed files with 595 additions and 113 deletions
@@ -0,0 +1,58 @@
+## ADDED Requirements
+
+### Requirement: Account login is the primary Console authentication flow
+The Console SHALL use username/password login and a server-managed user session as its primary authentication flow, while retaining the existing tab-scoped bearer-token flow behind an explicit compatibility action.
+
+#### Scenario: Operator opens the Console without authentication
+- **WHEN** `/v1/auth/me` reports no valid user session and no compatibility bearer token is active
+- **THEN** the Console displays the username/password login form as the primary action and offers a secondary “Use API token” action
+
+#### Scenario: Login succeeds
+- **WHEN** an operator submits valid account credentials
+- **THEN** the Console enters session mode, displays the authenticated user's identity, and loads only views allowed by the returned effective scopes
+
+#### Scenario: Login fails
+- **WHEN** the login endpoint rejects credentials or throttles the attempt
+- **THEN** the Console shows the generic authentication failure without revealing whether the username exists or persisting the password
+
+#### Scenario: Operator chooses token compatibility
+- **WHEN** an operator explicitly selects “Use API token” and enters a bearer token
+- **THEN** the Console retains that token only in tab-scoped session storage and uses the existing bearer request behavior
+
+### Requirement: Console manages authenticated session lifecycle
+The Console SHALL send cookies on user-session requests, attach session CSRF proof to unsafe requests, provide logout and password-change controls, and distinguish authentication loss from insufficient authorization.
+
+#### Scenario: User logs out
+- **WHEN** a logged-in user activates logout
+- **THEN** the Console submits CSRF-protected logout, clears local authentication state, and returns to the login screen
+
+#### Scenario: Session expires
+- **WHEN** a session-authenticated request returns `401`
+- **THEN** the Console clears session UI state and returns to login with a session-expired message
+
+#### Scenario: User lacks a required scope
+- **WHEN** an otherwise valid session-authenticated request returns `403`
+- **THEN** the Console preserves the session and shows an authorization error for that operation
+
+#### Scenario: User must change a temporary password
+- **WHEN** the current-user response sets `must_change_password`
+- **THEN** the Console restricts navigation to password change and logout until password change succeeds
+
+### Requirement: Administrators manage users from the Console
+The Console SHALL expose a user-management view only to principals whose effective scopes include `users:admin`, with controls to list/create users, change role or enabled state, reset passwords, and revoke sessions.
+
+#### Scenario: Administrator opens user management
+- **WHEN** an authenticated administrator opens the Users view
+- **THEN** the Console displays non-secret user records and the supported lifecycle controls without exposing password or session credential material
+
+#### Scenario: Administrator creates an account
+- **WHEN** an administrator submits valid user details and an initial password
+- **THEN** the Console creates the account, clears password fields immediately, and shows that the new user must change the initial password
+
+#### Scenario: Non-admin loads the Console
+- **WHEN** the current principal lacks `users:admin`
+- **THEN** the Console does not render the Users navigation or management controls, while backend authorization remains authoritative
+
+#### Scenario: User-management mutation fails
+- **WHEN** a create, update, reset, or revoke request returns validation, conflict, or authorization failure
+- **THEN** the Console preserves non-secret form state as appropriate, clears all password fields, and displays the API error without retrying the mutation automatically