Halaman utama Jelajahi Bantuan
Masuk
liuq
/
Unified_Authentication_Platform
1
0
Fork 0
Berkas Masalah 0 Permintaan Tarik 0 Wiki
Pohon: 05316e78bb
Ranting Tag
Unified_Auth...
/
需求功能概述.md

需求功能概述.md 12 KB
Riwayat Mentahan

项目概览：统一认证平台 (Unified Authentication Platform - UAP)

核心价值：

  • 手机号为主入口：以手机号作为核心用户标识，支持密码登录，敏感操作（改密）时使用短信验证码。
  • 账号映射：支持将统一认证平台的手机号映射到第三方系统（如老OA）的旧有账号（邮箱、用户名等），解决老系统字段不匹配问题。
  • 标准协议支持：通过集成 Ory Hydra，全面支持 OIDC/OAuth2 协议，使得新应用和开源系统（如 GitLab, Jenkins, Grafana）可以标准、安全地接入。
  • 双模接口：同时提供OIDC 标准接口（给新系统）和简易 API（给老旧系统），满足混合系统集成需求。
  • 安全加固：集成原生图形验证码（captcha库），并在敏感操作（如发短信、改密）前强制校验。
  • 账号生命周期管理：通过Webhook 通知（FastAPI BackgroundTasks）和查询接口，实现用户的新增、变更、停用同步到下游业务系统。
  • 应用间信任与跳转：支持通过“简易 Ticket”机制，实现老旧系统间的无缝跳转。

一、 技术选型与架构

  • 后端:

    • 框架: FastAPI (Python 3.10+) - 高性能、异步、自动 API 文档。
    • 数据库: MySQL 8.0+ (配合 SQLAlchemy ORM) - 关系型数据存储。
    • 缓存/Session: Redis - 用于存储验证码、Session Cookie、Webhook 任务状态、缓存。
    • AI/CV: captcha 库 (依赖 Pillow) - 生成原生图形验证码。
    • 服务器: Uvicorn (WSGI/ASGI server)。
    • OIDC/OAuth2 核心: Ory Hydra (部署为独立服务，FastAPI 作为 Login/Consent Provider)。
    • Webhook 推送: FastAPI BackgroundTasks (替代 APScheduler)。

  • 前端:

    • 框架: Vue 3 + TypeScript - 现代、高效的 UI 开发。
    • 构建工具: Vite - 极快的冷启动和热更新速度。
    • UI 组件库: Element Plus - 提供一套完整的后台管理和认证页面组件。

  • 部署:

    • API 服务: FastAPI 应用 (Uvicorn + Gunicorn, Docker)。
    • OIDC 服务: Ory Hydra (Docker)。
    • 前端: Vue 应用 (Nginx 静态文件服务)。
    • 反向代理/负载均衡: Nginx。

二、 核心模块详解

1. 用户管理 (Users Table)

  • 主键: id (Integer, PK)
  • 核心标识: mobile (String(20), Unique, Index, Not Null)
  • 安全: password_hash (String(128), Not Null), salt (Optional, if not using modern hashes that include salt)
  • 状态: status (Enum: ACTIVE, DISABLED, Not Null, Default ACTIVE)
  • 审计: created_at, updated_at

2. 应用管理 (Applications Table)

  • 主键: id (Integer, PK)
  • 标识: app_id (String(32), Unique, Index, Not Null) - 分配给第三方系统
  • 密钥: app_secret_hash (String(128), Not Null) - 用于接口签名
  • 访问令牌: access_token (String(64), Unique) - 永久有效的应用访问令牌，用于 M2M 接口鉴权。
  • 信息: app_name, icon_url
  • 协议类型: protocol_type (Enum: OIDC, SIMPLE_API)
  • OIDC 配置 (Hydra 对应): redirect_uris (Text, Not Null - JSON/Array), grant_types, response_types (Store in Hydra DB, but link via app_id)
  • Webhook: notification_url (String, Optional)
  • 审计: created_at, updated_at

3. 账号映射 (AppUserMappings Table)

  • 主键: id (Integer, PK)
  • 关联: app_id (FK to Applications), user_id (FK to Users)
  • 核心映射: mapped_key (String(100), Not Null) - 目标系统的账号（邮箱、用户名等）
  • 状态: is_active (Boolean, Default True) - 映射关系是否启用。
  • 唯一性约束: UNIQUE(app_id, user_id) 确保一个用户在同一应用下只映射一次。
  • 可选约束: UNIQUE(app_id, mapped_key) (如果目标系统的账号在该应用内必须唯一)。

4. 基础认证 (Auth)

  • 登录:
    • API (/api/v1/auth/login): mobile, password, app_id (Optional for direct login). Returns JWT + refresh token.
    • H5 Page: /page/login (integrated into UAP).
    • OIDC Login: Redirects to /auth/login endpoint, challenge param.
  • Token: JWT for API authentication. Refresh tokens for long-term sessions.
  • 改密:
    • Hosted Page: /page/pwd/reset (Handles SMS, validation, password update).
    • API (/api/v1/open/sms/send, /api/v1/open/pwd/reset): Developers call these to implement their own UI.
      • sms/send: Requires captcha_id, captcha_code.
      • pwd/reset: Requires mobile, sms_code, new_password, sign.

5. 验证码 (Captcha)

  • 技术: captcha Python library + Pillow。
  • 接口 (/api/v1/utils/captcha):
    • GET: Generates captcha_id, image (Base64), stores code in Redis (key CAPTCHA:{uuid}, expiry settings.CAPTCHA_EXPIRE_SECONDS).
    • POST /sms/send (and others) must call CaptchaService.verify_captcha(captcha_id, user_input) before proceeding.
    • verify_captcha deletes the key upon success or first attempt (fail-safe).

6. 账号映射与导入导出 (Mappings & Import/Export)

  • 核心逻辑: mapped_key 字段存储映射值。
  • 导入/导出:
    • Template Download: Generate Excel template (phone, mapped_key, name). Use pandas or openpyxl.
    • Preview API (/api/v1/apps/{app_id}/mapping/preview):
      1. Read Excel with pandas.
      2. Validate mobile is not empty.
      3. Batch query Users table for existence.
      4. Batch query AppUserMappings table for duplicates.
      5. Return JSON with counts (new, duplicate, invalid) and detailed rows with status, reason.
    • Import API (/api/v1/apps/{app_id}/mapping/import):
      • Accepts strategy (SKIP/OVERWRITE).
      • Performs batch INSERT IGNORE or ON DUPLICATE KEY UPDATE using SQLAlchemy.

7. OIDC 集成 (Ory Hydra)

  • FastAPI 作为 Login/Consent Provider:
    • /auth/login endpoint: Receives login_challenge from Hydra. Verifies user credentials (phone+pass) or checks UAP Session Cookie. Calls hydra.accept_login_request(challenge, subject=user_id).
    • /auth/consent endpoint: Receives consent_challenge from Hydra. Fetches user's mappings for the client_id (App ID). Constructs id_token claims (e.g., email, preferred_username) based on mapped_key. Calls hydra.accept_consent_request(challenge, session={"id_token": {...}}).
  • Application Registration: When an App is created/updated in UAP Admin, a corresponding Client is created/updated in Hydra via its Admin API.

8. 账号生命周期同步 (User Provisioning)

  • Webhook (Push):
    • FastAPI BackgroundTasks triggers send_webhook_notification.
    • Payload includes event_type (ADD, UPDATE, DISABLE), app_id, user_data (mobile, name, mapped_key, status).
    • Signature X-UAP-Signature must be verified by the receiving system.
    • Logging: Failed calls are logged to WebhookLogs table. Manual retry option for admins.
  • API (Pull - Detail Query & Sync):
    • POST /api/v1/apps/mapping/sync: 同步映射关系（新增/更新/停用）。支持 Header X-App-Access-Token。
    • GET /api/v1/apps/{app_id}/users/query?mobile={mobile}: Returns user details and mappings. Used by legacy systems during login if local user not found.
    • GET /api/v1/apps/{app_id}/users/changes?since={timestamp}: Returns a list of changes. Less critical if Webhook is primary.

9. 应用间跳转 (Ticket Exchange)

  • 场景: System A needs to log user into System B without re-authentication.
  • API (POST /api/v1/simple/ticket/exchange):
    • Requires: app_id (source), target_app_id, user_mobile, sign.
    • Logic: Verifies source app_id/sign. Looks up mapping for target_app_id and user_mobile. Generates a short-lived Ticket_B. Returns redirect_url (target_app_url/callback?ticket=TICKET_B).
  • SSO Cookie Enhancement: If user already has UAP AUTH_SESSION_ID cookie, the redirection logic in /page/login (for SIMPLE_API apps) can directly generate Ticket_B without user interaction.

10. API 文档 (Swagger UI)

  • Backend: Use FastAPI's automatic OpenAPI generation.
    • Tag endpoints clearly: tags=["Admin"] vs tags=["OpenAPI"], tags=["SimpleAuth"].
    • Customize /docs/admin (all routes) and /docs/open (filtered routes) using get_openapi and get_swagger_ui_html.
    • Enrich descriptions with Markdown, Pydantic Field descriptions, summary.
  • Frontend: Embed /docs/open into a Vue page using <iframe>. Provide separate guides for Signatures and Quick Start.

三、 核心安全考虑

  1. 密码: Never store plain text. Use strong hashing (Argon2/BCrypt).
  2. Secrets: Use environment variables (.env files, Docker secrets). Never hardcode.
  3. API Signatures: All /api/v1/open/ and /api/v1/simple/ endpoints must use HMAC-SHA256 signed requests with app_secret. Enforce signature validation.
  4. Rate Limiting: Implement limits on login attempts, SMS sending, and API calls per app_id and mobile.
  5. Captcha: Mandatory before sending SMS or initiating password reset via API/Hosted page.
  6. HTTPS: Absolutely required for all communication.
  7. Input Validation: Strict validation using Pydantic for all incoming data.
  8. Session Management: Secure AUTH_SESSION_ID cookie, HTTPOnly, Secure flags. Handle logout by invalidating sessions.
  9. Webhook Security: Verify X-UAP-Signature on incoming webhook calls. Consider IP whitelisting for critical targets.
  10. Least Privilege: Admin roles should be granular. API keys (app_secret) should grant only necessary permissions.

四、 Cursor AI 开发建议

  1. 代码生成:

    • Models: "Generate SQLAlchemy models for Users, Applications, AppUserMappings tables in Python."
    • Schemas: "Create Pydantic schemas for /api/v1/auth/login and /api/v1/open/pwd/reset endpoints."
    • API Endpoints: "Implement a FastAPI endpoint POST /api/v1/open/sms/send with request body validation and Redis captcha check."
    • Services: "Write a Python function using Pillow to generate a random text captcha image and return its base64 representation and a UUID."
    • Import Logic: "Write a Python function using Pandas to read an Excel file, validate 'mobile' column, check against existing DB users, and return preview results."

  2. 调试与重构:

    • "My FastAPI endpoint POST /api/v1/auth/login is returning 500 error, here's the code and traceback, please debug."
    • "Refactor this synchronous code block in my service to use FastAPI BackgroundTasks."
    • "How can I optimize this SQLAlchemy query for checking duplicate mappings?"

  3. 文档:

    • "Generate OpenAPI tags and descriptions for these FastAPI routes based on their functionality."
    • "Write markdown documentation for the signature generation algorithm."

  4. OIDC:

    • "Show me an example of FastAPI's Depends injection for integrating with Ory Hydra SDK client."
    • "How do I structure the session data for accept_consent_request to include mapped email in id_token?"

这份总结包含了你项目的核心架构、技术栈、数据库设计、API 规范、安全策略以及如何利用 Cursor AI 进行高效开发。祝你开发顺利！