agentic_huge_data_base / wiki
页面 Onyx · 9.1 认证方法·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 9.1

9.1 · 认证方法（Authentication Methods）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节9.1 状态全文译文 模块接口与服务契约、界面与交互、认证、权限与安全、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Authentication Methods 上一章9 下一章9.2
源码线索
  • backend/onyx/auth/captcha.py
  • backend/onyx/auth/email_utils.py
  • backend/onyx/auth/jwt.py
  • backend/onyx/auth/signup_rate_limit.py
  • backend/onyx/configs/saml_config/template.settings.json
  • backend/onyx/db/saml.py
  • backend/onyx/server/auth/captcha_api.py
  • backend/onyx/utils/client_ip.py
  • backend/tests/integration/tests/users/test_seat_limit.py
  • backend/tests/unit/ee/onyx/utils/test_telemetry_client_ip.py
模块标签
  • 接口与服务契约
  • 界面与交互
  • 认证、权限与安全
  • 测试、发布与运维
  • 配置治理

章节正文

认证方法

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/9.1-authentication-methods

认证方法

相关源文件

本章引用的主要源码文件：

  • backend/onyx/auth/captcha.py
  • backend/onyx/auth/email_utils.py
  • backend/onyx/auth/jwt.py
  • backend/onyx/auth/signup_rate_limit.py
  • backend/onyx/configs/saml_config/template.settings.json
  • backend/onyx/db/saml.py
  • backend/onyx/server/auth/captcha_api.py
  • backend/onyx/utils/client_ip.py
  • backend/tests/integration/tests/users/test_seat_limit.py
  • backend/tests/unit/ee/onyx/utils/test_telemetry_client_ip.py
  • backend/tests/unit/onyx/auth/test_captcha_enterprise.py
  • backend/tests/unit/onyx/auth/test_captcha_replay.py
  • backend/tests/unit/onyx/auth/test_jwt_provisioning.py
  • backend/tests/unit/onyx/auth/test_signup_rate_limit.py
  • backend/tests/unit/onyx/auth/test_user_registration.py
  • backend/tests/unit/onyx/auth/test_verify_email_domain.py
  • backend/tests/unit/onyx/auth/test_verify_email_invite.py
  • backend/tests/unit/onyx/server/auth/test_login_captcha_middleware.py
  • backend/tests/unit/onyx/utils/test_client_ip.py
  • web/src/app/admin/users/page.tsx
  • web/src/app/auth/error/AuthErrorContent.tsx
  • web/src/app/auth/error/layout.tsx
  • web/src/app/auth/error/page.tsx
  • web/src/app/auth/join/page.tsx
  • web/src/app/auth/libSS.ts
  • web/src/app/auth/login/EmailPasswordForm.tsx
  • web/src/app/auth/login/LoginPage.tsx
  • web/src/app/auth/login/SignInButton.tsx
  • web/src/app/auth/login/page.tsx
  • web/src/app/auth/oauth/callback/route.ts
  • web/src/app/auth/oidc/callback/route.ts
  • web/src/app/auth/signup/page.tsx
  • web/src/app/auth/verify-email/Verify.tsx
  • web/src/app/auth/waiting-on-verification/page.tsx
  • web/src/app/layout.tsx
  • web/src/app/page.tsx
  • web/src/components/OnyxInitializingLoader.tsx
  • web/src/components/auth/AuthFlowContainer.tsx
  • web/src/components/settings/lib.ts
  • web/src/hooks/useCurrentUser.ts
  • web/src/lib/constants.ts
  • web/src/lib/user.ts
  • web/src/lib/userSS.ts
  • web/tests/e2e/auth/email_verification.spec.ts

本文档描述了 Onyx 支持的认证机制，包括配置选项、会话管理以及不同提供商的认证流程。它详细介绍了 OAuth 回调、基于 SMTP 的验证以及验证码集成和域名过滤等安全限制的具体实现。

概述

Onyx 支持多种认证方法，以适应不同的部署场景和身份提供商集成。认证系统基于 fastapi-users 库构建，并进行了自定义扩展以支持多租户、OAuth 提供商和企业功能。

认证类型由 AUTH_TYPE 环境变量控制，该变量映射到 AuthType 枚举：

  • basic：邮箱/密码认证，可选邮箱验证 web/src/lib/constants.ts:4-4。
  • google_oauth：Google OAuth 2.0 web/src/lib/constants.ts:5-5。
  • oidc：OpenID Connect（通用 OIDC 提供商）web/src/lib/constants.ts:6-6。
  • saml：SAML 2.0 单点登录 web/src/lib/constants.ts:7-7。
  • cloud：云特定认证（企业版多租户）web/src/lib/constants.ts:8-8。

来源： web/src/lib/constants.ts:3-9 web/src/lib/userSS.ts:7-15

认证配置

服务端元数据与重定向

前端通过 getAuthTypeMetadataSS 从后端获取元数据来确定认证状态 web/src/lib/userSS.ts:17-18。该元数据包括系统是否已有用户、是否需要验证以及最小密码长度 web/src/lib/userSS.ts:7-15。

对于 OIDC 或 SAML 等单点登录（SSO）方法，应用可以配置为自动将未认证用户重定向到身份提供商（IdP）web/src/lib/userSS.ts:43-52。

数据流：认证类型到代码实体

下图将高层级的 AuthType 配置映射到具体的后端和前端组件。

认证类型映射到实现

Onyx · 数据流：认证类型到代码实体 · 图 1
Onyx · 数据流：认证类型到代码实体 · 图 1

来源： web/src/app/auth/login/page.tsx:32-41 web/src/app/auth/login/EmailPasswordForm.tsx:133-138 web/src/app/auth/login/SignInButton.tsx:53-60 web/src/lib/userSS.ts:100-122

OAuth 和 OIDC 流程

Onyx 实现了标准的 OAuth 2.0 和 OIDC 流程。前端使用 getAuthUrlSS 根据配置的 AuthType 生成授权 URL web/src/lib/userSS.ts:100-122。

验证码保护的 OAuth 流程

当 CAPTCHA_ENABLED 启用时，OAuth 流程会被拦截以防止自动创建账户：

  1. 前端拦截：SignInButton 拦截点击事件，为 oauth 操作获取 reCAPTCHA v3 令牌 web/src/app/auth/login/SignInButton.tsx:76。
  2. 预验证：令牌通过 POST 请求发送到 /api/auth/captcha/oauth-verify web/src/app/auth/login/SignInButton.tsx:85。
  3. 签名 Cookie：后端验证令牌并设置一个签名的 onyx_captcha_verified Cookie backend/onyx/auth/captcha.py:41。
  4. 重定向：只有在 Cookie 设置完成后，浏览器才会导航到 IdP 的授权 URL web/src/app/auth/login/SignInButton.tsx:105。
  5. 回调验证：后端中间件在 OAuth 回调期间验证签名的 Cookie。

来源： web/src/app/auth/login/SignInButton.tsx:66-113 backend/onyx/auth/captcha.py:7-15

SMTP 和邮箱验证

Onyx 支持通过 SMTP 或 SendGrid 进行邮箱验证和密码重置。这通过 EMAIL_CONFIGURED 和 REQUIRE_EMAIL_VERIFICATION 设置启用 backend/onyx/auth/email_utils.py:22-29。

验证实现
  • 邮件生成：build_html_email 使用标准 HTML 模板为验证邮件和系统邮件创建一致的品牌风格 backend/onyx/auth/email_utils.py:157-180。
  • 传输方式：如果存在 SENDGRID_API_KEY，则使用 send_email_with_sendgrid backend/onyx/auth/email_utils.py:194-198。否则，回退到 send_email_with_smtplib backend/onyx/auth/email_utils.py:200-202。
  • 流程：在 basic 模式下注册时，如果 shouldVerify 为 true，前端会调用 requestEmailVerification 并将用户重定向到等待页面 web/src/app/auth/login/EmailPasswordForm.tsx:141-146。

来源： backend/onyx/auth/email_utils.py:183-203 web/src/app/auth/login/EmailPasswordForm.tsx:141-146

安全限制

验证码验证

Onyx 使用 Google reCAPTCHA Enterprise 在 signup（注册）、login（登录）和 oauth 操作期间进行风险分析 backend/onyx/auth/captcha.py:64-72。

  • 重放保护：令牌通过 _reserve_token_or_raise 缓存在 Redis 中，以防止重放攻击 backend/onyx/auth/captcha.py:115-131。
  • 硬拒绝：如果评估结果包含 AUTOMATION（自动化）、TOO_MUCH_TRAFFIC（流量过大）或 SUSPECTED_CARDING（疑似盗刷）等理由，则会被拒绝 backend/onyx/auth/captcha.py:47-55。
会话管理

会话通过 Cookie 和 JWT 进行管理。

  • 服务端获取：getCurrentUserSS 函数从请求头中处理 Cookie，以在服务端对用户进行认证 web/src/lib/userSS.ts:152-174。
  • 调试认证：对于本地开发，可以注入 DEBUG_AUTH_COOKIE 来模拟针对远程后端的认证 web/src/lib/userSS.ts:183-193。

认证实体映射

Onyx · 会话管理 · 图 2
Onyx · 会话管理 · 图 2

来源： web/src/lib/types.ts:1-5（用户接口） web/src/lib/userSS.ts:7-15（AuthTypeMetadata 接口） backend/onyx/auth/captcha.py:91-98（RecaptchaAssessmentResponse）

会话管理与登出

登出行为因认证类型而异。对于 SAML，使用特定的登出端点 /auth/saml/logout 来终止与 IdP 的会话 web/src/lib/userSS.ts:131-136。所有其他类型使用标准的 /auth/logout 端点 web/src/lib/userSS.ts:124-129。

来源：

  • web/src/lib/userSS.ts:138-150
  • web/src/lib/user.ts:18-24