agentic_huge_data_base / wiki
页面 Onyx · 3.3 凭证管理·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 3.3

3.3 · 凭证管理（Credential Management）

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

项目Onyx 章节3.3 状态全文译文 模块界面与交互、认证、权限与安全、文档对象与元数据、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Credential Management 上一章3.2 下一章3.4
源码线索
  • backend/ee/onyx/external_permissions/sharepoint/doc_sync.py
  • backend/ee/onyx/external_permissions/sharepoint/group_sync.py
  • backend/ee/onyx/external_permissions/sharepoint/permission_utils.py
  • backend/onyx/connectors/sharepoint/connector.py
  • backend/onyx/connectors/sharepoint/connector_utils.py
  • backend/tests/daily/connectors/sharepoint/test_sharepoint_connector.py
  • backend/tests/integration/connector_job_tests/sharepoint/conftest.py
  • backend/tests/unit/ee/onyx/external_permissions/sharepoint/test_permission_utils.py
  • backend/tests/unit/onyx/connectors/sharepoint/test_delta_checkpointing.py
  • backend/tests/unit/onyx/connectors/sharepoint/test_drive_matching.py
模块标签
  • 界面与交互
  • 认证、权限与安全
  • 文档对象与元数据
  • 接口与服务契约
  • 图谱与关系

章节正文

凭证管理

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/3.3-credential-management

凭证管理

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

  • backend/ee/onyx/external_permissions/sharepoint/doc_sync.py
  • backend/ee/onyx/external_permissions/sharepoint/group_sync.py
  • backend/ee/onyx/external_permissions/sharepoint/permission_utils.py
  • backend/onyx/connectors/sharepoint/connector.py
  • backend/onyx/connectors/sharepoint/connector_utils.py
  • backend/tests/daily/connectors/sharepoint/test_sharepoint_connector.py
  • backend/tests/integration/connector_job_tests/sharepoint/conftest.py
  • backend/tests/unit/ee/onyx/external_permissions/sharepoint/test_permission_utils.py
  • backend/tests/unit/onyx/connectors/sharepoint/test_delta_checkpointing.py
  • backend/tests/unit/onyx/connectors/sharepoint/test_drive_matching.py
  • backend/tests/unit/onyx/connectors/sharepoint/test_fetch_site_pages.py
  • backend/tests/unit/onyx/connectors/sharepoint/test_hierarchy_helpers.py
  • backend/tests/unit/onyx/connectors/sharepoint/test_rest_client_context_caching.py
  • web/src/app/admin/documents/sets/DocumentSetCreationForm.tsx
  • web/src/app/auth/forgot-password/page.tsx
  • web/src/app/auth/forgot-password/utils.ts
  • web/src/app/auth/reset-password/page.tsx
  • web/src/components/ConnectorMultiSelect.tsx
  • web/src/components/FederatedConnectorSelector.tsx
  • web/src/components/IsPublicGroupSelector.tsx
  • web/src/components/NonSelectableConnectors.tsx
  • web/src/components/admin/connectors/CredentialForm.tsx
  • web/src/components/chat/MCPApiKeyModal.tsx
  • web/src/components/credentials/CredentialSection.tsx
  • web/src/components/credentials/actions/CreateCredential.tsx
  • web/src/components/credentials/actions/CredentialFieldsRenderer.tsx
  • web/src/components/credentials/actions/EditCredential.tsx
  • web/src/components/credentials/actions/ModifyCredential.tsx
  • web/src/components/credentials/lib.ts
  • web/src/lib/credential.ts

本文档说明了 Onyx 如何管理用于连接外部数据源的凭证。凭证是访问 Slack、GitHub、Google Drive 和 SharePoint 等服务所需的认证令牌、API 密钥或其他机密信息。该系统提供安全存储，支持每个数据源使用多种认证方式（例如客户端密钥与证书），并管理连接器-凭证对（CCPair）的生命周期。

凭证概述

Onyx 中的凭证是特定于数据源的认证对象，使连接器能够访问外部 API。每个凭证：

  • 限定在单个 ValidSources 类型范围内（例如 github、sharepoint、slack）[web/src/lib/connectors/credentials.ts:284-339]
  • 包含一个带有认证字段的 JSON 对象（credential_json）[web/src/lib/connectors/credentials.ts:27-34]
  • 可以通过 admin_public 在用户间共享，或在企业版中分配给特定的 UserGroups[web/src/components/IsPublicGroupSelector.tsx:89-126]
  • 通过连接器-凭证对（CCPair）对象与连接器关联[web/src/lib/types.ts:216-223]

凭证系统抽象了认证的复杂性，使后端连接器逻辑能够专注于使用提供的令牌或证书进行数据检索。

来源： web/src/lib/connectors/credentials.ts:1-46、web/src/components/IsPublicGroupSelector.tsx:17-31、web/src/lib/types.ts:1-5

凭证数据模型

前端凭证接口

前端使用 Credential<T> 接口定义凭证，其中 T 表示特定于数据源的 JSON 结构：

export interface Credential<T> extends CredentialBase<T> {
  id: number;
  user_id: string | null;
  user_email: string | null;
  time_created: string;
  time_updated: string;
}

[web/src/lib/connectors/credentials.ts:40-46]

CredentialBase 的关键字段：

  • credential_json：机密数据（例如 GithubCredentialJson、SlackCredentialJson）[web/src/lib/connectors/credentials.ts:28]
  • admin_public：如果为 true，所有管理员用户都可以查看/使用此凭证[web/src/lib/connectors/credentials.ts:29]
  • curator_public：如果为 true，已分配组中的管理员可以访问此凭证（仅限企业版）[web/src/lib/connectors/credentials.ts:32]
  • groups：具有访问权限的 UserGroup ID 数组[web/src/lib/connectors/credentials.ts:33]

来源： web/src/lib/connectors/credentials.ts:27-46

凭证基础类型

Onyx 支持两种用于凭证创建的基础类型：

export interface CredentialBase<T> {
  credential_json: T;
  admin_public: boolean;
  source: ValidSources;
  name?: string;
  curator_public?: boolean;
  groups?: number[];
}

export interface CredentialWithPrivateKey<T> extends CredentialBase<T> {
  private_key: TypedFile;
}

CredentialWithPrivateKey 用于需要基于证书认证的数据源，例如使用 .pfx 或 .pem 文件的 SharePoint。[web/src/lib/connectors/credentials.ts:36-38] [web/src/components/credentials/actions/CreateCredential.tsx:113-133]

来源： web/src/lib/connectors/credentials.ts:27-38、web/src/components/credentials/actions/CreateCredential.tsx:111-133

多认证模式

某些数据源支持多种认证方式。这通过 credentialTemplates 中的 AuthMethodOption 实现。

示例：SharePoint 多认证

SharePoint 支持 Graph API 的两种主要方式：

  1. 客户端密钥：使用 sp_client_id、sp_client_secret 和 sp_directory_id。[web/src/lib/connectors/credentials.ts:211-212]
  2. 证书认证：使用 sp_client_id、sp_directory_id、sp_certificate_password 和 private_key 文件。[web/src/lib/connectors/credentials.ts:213-215]

后端 SharepointConnector 使用这些信息来初始化 msal.ConfidentialClientApplication 或 office365.GraphClient。[backend/onyx/connectors/sharepoint/connector.py:140-147]

Onyx · 示例：SharePoint 多认证 · 图 1
Onyx · 示例：SharePoint 多认证 · 图 1

来源： backend/onyx/connectors/sharepoint/connector.py:140-172、web/src/lib/connectors/credentials.ts:210-216

凭证模板与校验

credentialTemplates 定义了每个数据源所需的字段。系统使用这些模板动态生成表单和校验模式。

export const credentialTemplates: Record<ValidSources, any> = {
  github: { github_access_token: "" } as GithubCredentialJson,
  confluence: {
    confluence_username: "",
    confluence_access_token: "",
  } as ConfluenceCredentialJson,
  // ...
};

[web/src/lib/connectors/credentials.ts:284-300]

校验逻辑

createValidationSchema 函数使用 Yup 基于模板构建校验模式。如果模板包含 authMethods，则会应用条件校验：

  • 要求提供 authentication_method。[web/src/components/credentials/lib.ts:17-19]
  • 使用 .when("authentication_method", ...) 确保只要求所选方法相关的字段。[web/src/components/credentials/lib.ts:46-53]

来源： web/src/components/credentials/lib.ts:11-57、web/src/lib/connectors/credentials.ts:284-491

桥接：前端到代码实体空间

下图将凭证管理的 UI 组件映射到其底层代码实体。

Onyx · 桥接：前端到代码实体空间 · 图 2
Onyx · 桥接：前端到代码实体空间 · 图 2

来源： web/src/components/credentials/actions/CreateCredential.tsx:53-170、web/src/components/credentials/lib.ts:11-90、web/src/components/credentials/actions/ModifyCredential.tsx:173-186

凭证提交数据流

从表单输入到后端存储的数据流：

  1. Formik 初始化：CreateCredential 使用模板中的 initialValues 进行初始化。[web/src/components/credentials/actions/CreateCredential.tsx:189-199]
  2. 字段渲染：CredentialFieldsRenderer 将模板键映射到 UI 输入组件。[web/src/components/credentials/actions/CreateCredential.tsx:222-225]
  3. 文件处理：如果存在 TypedFile（例如 SharePoint 证书），则从表单值中提取。[web/src/components/credentials/actions/CreateCredential.tsx:113-122]
  4. API 调用：使用 credential_json 和元数据调用 submitCredential。[web/src/components/credentials/actions/CreateCredential.tsx:125-133]
Onyx · 凭证提交数据流 · 图 3
Onyx · 凭证提交数据流 · 图 3

来源： web/src/components/credentials/actions/CreateCredential.tsx:95-170、web/src/components/admin/connectors/CredentialForm.tsx:6-20

访问控制与可见性

凭证支持细粒度的访问控制，尤其是在企业环境中：

  • 公开与私有：is_public 决定凭证是对所有用户可用还是受限。[web/src/components/IsPublicGroupSelector.tsx:89-109]
  • 组分配：IsPublicGroupSelector 允许管理员将凭证分配给特定的 UserGroups。[web/src/components/IsPublicGroupSelector.tsx:113-125]
  • 管理员权限：管理员可以看到分配给其组的凭证，但可能被限制将其设为"公开"。[web/src/components/IsPublicGroupSelector.tsx:37-57]

来源： web/src/components/IsPublicGroupSelector.tsx:1-126、web/src/components/credentials/actions/CreateCredential.tsx:18-22