> 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).

# 授权源 - 概览

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

{% 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)

## 创建授权源 - 一般说明

1. 获取 **客户端 ID** 和 **客户端密钥** 来自第三方系统；这些凭据必须创建 **基于 VergeOS 系统的 URL**。后续步骤将需要这些值。
2. 单击 **系统** 在顶部菜单中。
3. 选择 **认证源**.
4. 单击 **新建** 左侧菜单中的。
5. **名称：** 用于标识此授权源的名称；该名称将显示在 VergeOS 登录页面的登录按钮上。
6. **驱动程序：**
   * *Azure AD*
   * *GitLab*
   * *Google*
   * *Okta*
   * *Open ID*\*\*\*
   * *Open ID（Well-Known 配置）*
   * *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.