进阶 docs.cloudreve.org 2026-10-17 18:46:57 · 21 阅读

第27章配置OIDC认证实现单点登录

OIDC 认证 Pro本节内容仅适用于 Pro 版。

Cloudreve 支持对接符合 OpenID Connect（OIDC）规范的认证服务，实现单点登录。本文将以 Microsoft Entra ID（Azure AD）和 Google 为例，说明如何完成对接。

Logto

Cloudreve 原生支持 Logto。在管理面板的设置 -> 用户会话 -> 第三方登录中，即可直接配置 Logto 认证服务。

腾讯 QQ

Cloudreve 原生支持 QQ Connect。在管理面板的设置 -> 用户会话 -> 第三方登录中，即可直接配置腾讯 QQ 认证服务。

Microsoft Entra ID (Azure AD)

创建应用注册

在名称字段中填写应用名称（例如 Cloudreve），并根据需要选择受支持的账户类型。进入 Cloudreve 管理面板的设置 -> 用户会话 -> 第三方登录，勾选 OpenID Connect (OIDC)，从提示中获取重定向 URL，将其填入重定向 URI 字段，并将类型选择为 Web。

配置客户端密钥

应用创建完成后，在左侧导航栏选择证书和密码，点击新建客户端密码，输入描述后点击添加，然后将生成的密钥值填入 Cloudreve 的 Client Secret 字段。

请注意：客户端密钥过期后，需要重新生成并在 Cloudreve 中更新。

配置客户端 ID 和发现文档

回到应用的概述页面，将应用程序(客户端) ID 复制到 Cloudreve 的 Client ID 字段。点击终结点，复制 OpenID Connect 元数据文档 URL，留待后续使用。

在 Cloudreve 的 OIDC Wellknown Config 区域，点击 Import from URL，粘贴上一步复制的 OpenID Connect 元数据文档 URL 并提交。

保存设置后，即可使用 Microsoft Entra ID (Azure AD) 进行认证。

Google

创建应用注册

应用类型选择 Web 应用，在名称字段填写应用名称（例如 Cloudreve）。进入 Cloudreve 管理面板的设置 -> 用户会话 -> 第三方登录，勾选 OpenID Connect (OIDC)，从提示中获取重定向 URL，填入授权重定向 URI。在授权的 JavaScript 来源中填写你的站点地址，例如 https://cloudreve.org。

配置客户端 ID 和密钥

应用创建完成后，会弹出一个对话框，显示 Client ID 和客户端密钥。将它们分别填入 Cloudreve 的 Client ID 和 Client Secret 字段。

配置发现文档

在 Cloudreve 的 OIDC Wellknown Config 区域，点击 Import from URL，输入 https://accounts.google.com/.well-known/openid-configuration 并提交。

保存设置后，即可使用 Google 进行认证。

OIDC 兼容性

对接 Cloudreve 的 OIDC 服务需满足以下基本要求：

必须满足：
- 支持使用 client_secret_post 方式换取 access_token；
- 支持 response_type 为 code；
- 支持的 scope 包含 openid、email、profile；
- 提供 userinfo_endpoint 用于获取用户信息；
- 能够传递 state 参数。
非必需，但建议提供：
- 在 userinfo_endpoint 返回 Email 和头像 URL；
- 提供 end_session_endpoint，以便将用户重定向到认证服务器执行登出。

用户信息字段映射

Cloudreve 通过 UserInfo 获取用户资料信息，默认期望的响应格式为：

{
  "sub": "1234567890",
  "name": "John Doe",
  "email": "[email protected]",
  "picture": "https://example.com/avatar.jpg"
}

如果 OIDC 提供方返回的 UserInfo 格式不符合标准，可以通过 User info fields mapping 进行配置。例如对于以下响应：

{
  "attributes": {
    "uid": "5900055",
    "securityEmail": "[email protected]",
    "cn": "Aaron Liu",
    "status": "Active"
  },
  "id": "5900055"
}

可以配置如下映射关系：