> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/run-the-platform/zh/shen-fen-yan-zheng/auth-sources-general.md).

# 授权源 - 概览

在 VergeOS 中配置 Okta、GitLab、Azure AD 和 Google 等第三方 OAuth2 身份提供商用于用户身份验证的通用说明。

授权源允许在 VergeOS 中利用第三方 OAuth2 身份管理系统（如：Okta、GitLab、Azure AD、Google）进行用户身份验证。

{% hint style="info" %}
**尽管 OAuth2 是一项标准规范，不同实现会有所差异。本页提供了配置第三方 OAuth 源以用于 VergeOS 身份验证的通用说明。具体字段和设置会因所选驱动程序（Google、Azure、OpenID、GitLab 等）而异。有关特定选项的信息，请参阅相应 OAuth 源文档。**
{% endhint %}

以下链接提供特定来源的说明：

* [Google](/run-the-platform/zh/shen-fen-yan-zheng/google-auth.md)
* [Azure](/run-the-platform/zh/shen-fen-yan-zheng/azure-auth.md)
* [VergeOS OIDC](/run-the-platform/zh/shen-fen-yan-zheng/oidc-apps-overview.md)

## UI 登录身份验证 vs. NAS 域加入

VergeOS 有两个各自独立且都涉及 Active Directory 的功能，二者经常被混淆：

| 功能             | 用途                                            | 配置位置                                                                     |
| -------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
| **认证源（UI 登录）** | 允许 VergeOS UI 用户和租户用户使用外部身份提供方凭据登录            | **系统 > 认证源**                                                             |
| **NAS 域加入**    | 将 VergeOS NAS 服务加入 AD 域，以实现 CIFS/SMB 文件共享访问控制 | NAS 服务设置——参见 [将 NAS 加入域](/run-the-platform/zh/nas/nas-join-ad-domain.md) |

这些功能是独立的。将 NAS 加入域并不会 **不会** 启用基于 AD 的 UI 登录，而配置 UI 认证源也不会 **不会** 影响 NAS 文件共享权限。

### 通过 Windows Active Directory 进行 UI 登录身份验证

VergeOS UI 和租户登录认证源基于 OAuth2/OIDC，而不是原生 LDAP 认证源驱动程序——UI 登录没有直接的 LDAP/AD 绑定选项。

要让 Windows 域用户使用其 AD 凭据登录 VergeOS UI，请通过以下方式将本地 AD 联合到 **Microsoft Entra ID** （Azure AD）或其他兼容 OIDC 的身份提供方，并在 VergeOS 中配置相应的认证源。身份提供方中的组成员关系可以映射到 VergeOS 组，以便权限随目录同步。

## 创建认证源 - 通用说明

1. 获取 **客户端 ID** 和 **客户端密钥** 来自第三方系统；这些凭据必须创建 **基于 VergeOS 系统的 URL**。这些值将在后续步骤中用到。
2. 点击 **系统** 顶部菜单中的。
3. 选择 **认证源**.
4. 点击 **新建** 左侧菜单中的。
5. **名称：** 用于标识此认证源的名称；该名称将显示在 VergeOS 登录页面的登录按钮上。
6. **驱动程序：**
   * *Azure AD*
   * *GitLab*
   * *Google*
   * *Okta*
   * *Open ID*\*\*\*
   * *Open ID（已知配置）*
   * *Verge.io* （这可用于为支持人员提供简化访问；请联系 VergeOS 支持团队以配置此类认证源。）

{% hint style="success" %}
**OpenID 设置提供了一个通用选项，适用于任何 OpenID 源；而 Google、GitLab、Okta 和 Azure AD 等特定选项则提供带有配置表单的封装，更适合各自特定的实现。**
{% endhint %}

7. **重定向 URI：** 会自动填入 VergeOS UI 的地址，通常不应更改。 **此地址必须是公共地址，或者远程 OAuth 源能够访问。**
8. **客户端 ID** 和 **客户端密钥：** 在远程 OAuth 源上生成的值，基于 VergeOS 系统的 URL。
9. **远程用户字段：** 定义一个或多个可用于在 OAuth 源中查找用户的字段。该字段会自动填充一组常见字段的默认列表（sub、preferred\_username、email、nickname），这些字段可在多种常见 OAuth 实现中通用

{% hint style="warning" %}
**出于安全原因，不建议基于 OAuth 源中可由终端用户更改的字段来定位远程用户。**
{% endhint %}

10. **进一步配置：**

### 推荐选项（建议启用这些选项。）

* **更新远程用户：** 更新 *远程用户名* 将 VergeOS 用户的字段更新为来自 OAuth 源的唯一 ID。启用此选项可先基于更易读的字段（定义于 *远程用户字段*，见上方）来初步定位用户，然后再将 VergeOS *远程用户名* 字段更改为与源系统中的唯一 ID 匹配。这可确保即使电子邮件地址或易记用户名等附加字段随时间变化，用户记录仍保持不变。
* **更新用户电子邮件地址：** 根据 OAuth 源中的电子邮件地址更新电子邮件地址字段。
* **更新用户显示名称：** 根据 OAuth 源中的显示名称更新用户显示名称。

### 其他可选字段

* **作用域：** 因不同实现而异；如适用，请查阅源 OAuth2 文档了解更多信息。在大多数情况下，默认的“openid profile email”即可。
* **组作用域：** 因不同实现而异；请查阅源 OAuth2 文档了解更多信息。在大多数情况下，组作用域可设置为单词“groups”。组作用域 **在使用 *****更新组成员关系***** 选项时为必需。**.
* **要求已验证的电子邮件地址：** （适用于支持验证用户电子邮件地址的 OAuth2 实现）仅允许源中已验证电子邮件地址标志启用/为 true 的用户进行身份验证。
* **更新组成员关系：** 在每次用户登录时更新用户的组成员关系，使其与 OAuth 源中的组成员关系一致

**调试模式：** （复选框）为此认证源开启详细日志；仅应在故障排查时启用，因为大量身份验证日志可能影响性能。

**在菜单中显示：** （复选框）将显示方式改为下拉菜单而非列表。

***

### 用户创建

* **自动创建用户：** 系统会自动创建与 OAuth 源中用户对应的用户（按需，在首次 VergeOS 登录时）。使用单个星号可应用于所有用户。
* **在组中自动创建用户：** 只有位于指定 OAuth2 源组中的用户才会在首次登录时按需自动创建。可以输入具体组名，或使用正则表达式包含匹配模式的组。

{% hint style="info" %}
**要基于一个或多个组自动创建用户， *****自动创建用户***** 字段应留空。**
{% endhint %}

{% hint style="info" %}
**将使用外部认证源的用户也可选择在 VergeOS 中手动创建；创建新的 VergeOS 用户时：在下拉列表中选择相应的认证源。**
{% endhint %}

* 设置 **远程用户名** 为与以下定义中的某个字段匹配 *远程用户字段* （用于在外部认证源中查找用户的字段）。通常最好使用用户的登录名或唯一用户 ID。

### 登录样式

登录样式定义 VergeOS 登录页面上登录按钮的外观。

* **登录按钮背景颜色：** 登录按钮的背景颜色。
* **登录按钮文字颜色：** 登录按钮的文字颜色。
* **登录按钮 Font Awesome 图标：** 为登录按钮指定备用图标；可用的 Font Awesome 图标列表可在以下位置找到： [此处](https://fontawesome.com/v4.7.0/cheatsheet/).
* **登录按钮 Font Awesome 图标颜色：** 为登录按钮指定备用颜色；请使用标准 HEX 代码，例如 #FF5733。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/run-the-platform/zh/shen-fen-yan-zheng/auth-sources-general.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.