LabelingSystem/.kiro/specs/sso-token-unification/requirements.md

Requirements Document

Introduction

将标注平台的用户认证体系从"本地 JWT 签发"迁移为"SSO 中心统一签发 token"。当前系统在 OAuth 回调后自行生成 JWT token 用于后续 API 认证，改造后将直接使用 SSO 中心签发的 access_token 和 refresh_token，实现统一认证体系。本地用户名/密码登录和注册功能将被移除，所有认证统一走 SSO。

Glossary

• SSO_Center: 外部 SSO 认证中心，负责用户身份认证和 token 签发，地址由 oauth.base_url 配置
• Platform: 本标注平台后端服务（FastAPI 应用）
• Frontend: 本标注平台前端应用（React/TypeScript）
• SSO_Token: SSO 认证中心签发的 access_token，用于 API 请求认证
• SSO_Refresh_Token: SSO 认证中心签发的 refresh_token，用于刷新 SSO_Token
• Auth_Middleware: 后端认证中间件，负责验证每个请求的 token 有效性
• Token_Introspection: 向 SSO_Center 验证 token 有效性的过程
• User_Sync: 从 SSO 用户信息同步到本地数据库的过程

Requirements

Requirement 1: 移除本地认证

User Story: As a platform administrator, I want to remove local username/password authentication, so that all users authenticate through the unified SSO system.

Acceptance Criteria

1. WHEN the Platform starts, THE Platform SHALL only support SSO-based authentication (local login and registration endpoints removed)
2. WHEN a request is made to the removed /api/auth/login endpoint, THE Platform SHALL return HTTP 404
3. WHEN a request is made to the removed /api/auth/register endpoint, THE Platform SHALL return HTTP 404
4. THE Frontend SHALL remove the local login form and registration form, displaying only the SSO login button

Requirement 2: SSO Token 透传

User Story: As a developer, I want the platform to use SSO-issued tokens directly, so that the authentication system is unified with the SSO center.

Acceptance Criteria

1. WHEN the OAuth callback is completed successfully, THE Platform SHALL return the SSO_Token and SSO_Refresh_Token directly to the Frontend (instead of generating local JWT tokens)
2. WHEN the Frontend makes API requests, THE Frontend SHALL attach the SSO_Token in the Authorization header as a Bearer token
3. THE Platform SHALL NOT generate or sign any JWT tokens locally for user authentication purposes

Requirement 3: SSO Token 验证

User Story: As a platform administrator, I want every API request to be validated against the SSO center, so that revoked or expired tokens are rejected immediately.

Acceptance Criteria

1. WHEN a protected API request is received, THE Auth_Middleware SHALL first check the local token cache for a valid cached session
2. WHEN the token is found in the local cache, THE Auth_Middleware SHALL use the cached user information and attach it to the request state
3. WHEN the token is not found in the local cache, THE Auth_Middleware SHALL validate the SSO_Token by calling the SSO_Center's /oauth/userinfo endpoint
4. WHEN the SSO_Center returns a response with code=0 and user data in the data field, THE Auth_Middleware SHALL cache the token-to-user mapping and attach user information to the request state
5. WHEN the SSO_Center returns an error or the token is invalid, THE Auth_Middleware SHALL return HTTP 401 with an appropriate error message
6. WHEN the SSO_Center is unreachable, THE Auth_Middleware SHALL return HTTP 503 with a service unavailable error message
7. THE Auth_Middleware SHALL support a configurable cache TTL (default 5 minutes) to balance between performance and token revocation responsiveness

Requirement 4: Token 刷新

User Story: As a user, I want my session to be refreshed automatically when my token expires, so that I don't have to re-login frequently.

Acceptance Criteria

1. WHEN the Frontend receives a 401 response indicating token expiration, THE Frontend SHALL attempt to refresh the token using the SSO_Refresh_Token
2. WHEN refreshing the token, THE Platform SHALL forward the refresh request to the SSO_Center's token endpoint with grant_type=refresh_token
3. WHEN the SSO_Center returns new tokens, THE Platform SHALL return the new SSO_Token and SSO_Refresh_Token to the Frontend
4. WHEN the refresh request fails, THE Frontend SHALL clear stored tokens and redirect the user to the SSO login flow

Requirement 5: 用户信息同步

User Story: As a platform administrator, I want user information to be synchronized from SSO on each login, so that user data stays up-to-date.

Acceptance Criteria

1. WHEN a user completes SSO login via the OAuth callback, THE Platform SHALL fetch user information from the SSO_Center and sync it to the local database
2. WHEN the SSO user does not exist in the local database, THE Platform SHALL create a new user record with the SSO-provided information
3. WHEN the SSO user already exists in the local database, THE Platform SHALL update the username and email if they have changed
4. THE Platform SHALL store the oauth_provider as "sso" and the oauth_id from the SSO_Center for each synced user

Requirement 6: 前端认证流程改造

User Story: As a user, I want a seamless SSO login experience, so that I can access the platform through the unified authentication system.

Acceptance Criteria

1. WHEN a user visits the login page, THE Frontend SHALL automatically initiate the SSO login flow (redirect to SSO_Center)
2. WHEN the OAuth callback returns tokens, THE Frontend SHALL store the SSO_Token and SSO_Refresh_Token in localStorage
3. WHEN the user clicks logout, THE Frontend SHALL clear stored tokens and redirect to the SSO_Center's logout endpoint (if available)
4. WHEN the Frontend detects an invalid or expired token and refresh fails, THE Frontend SHALL redirect the user to the SSO login flow

Requirement 7: 配置简化

User Story: As a developer, I want the configuration to reflect the new SSO-only authentication model, so that the system is easy to understand and maintain.

Acceptance Criteria

1. THE Platform SHALL remove the local JWT secret_key configuration since tokens are no longer signed locally
2. THE Platform SHALL retain the oauth configuration section for SSO_Center connection settings
3. WHEN the oauth.enabled configuration is set to false, THE Platform SHALL return HTTP 503 for all authentication-related requests with a message indicating SSO is not configured