> 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/azure-auth.md).

# 使用 Entra ID（Azure AD）进行身份验证

VergeOS 可以配置为允许用户使用其企业 Azure 凭据进行身份验证。本页将引导您完成配置过程。

## 配置 Entra ID 授权源

1. 在 Azure 服务中：注册一个单租户 Web 应用程序，设置 ***重定向 URI*** 为 VergeOS 系统的 URL，并创建一个新的客户端密钥。 **Azure Active Directory > 应用注册 > 新注册** ![azurereg1.png](/files/fa3965be17ea92afcdc9597aca75c1b6d6c8c63f)

   ![azurereg2.png](/files/b02bfa8e46a32272de4a310bbcd956b6f42d8822)
2. 创建一个新的客户端密钥。 **应用注册 > 客户端凭据 > 添加证书或密钥。点击 + 新客户端密钥。**

   * 输入一个 **描述和到期日期** 用于新的客户端密钥。
   * **从 Azure 获取以下内容** 以用于在 VergeOS 中配置授权源：
     * **租户 ID** - **提示： *****所有服务 > Azure Active Directory > 概览。***** 租户 ID 列在基本信息下。**
     * **客户端 ID** - **提示： *****Azure 应用注册 > 已配置项 > 客户端凭据***
     * **客户端密钥** - **提示： *****Azure 应用注册 > 已配置项 > 客户端凭据***** 使用 “VALUE” 字段。**

   ![azureclientsecretadd.png](/files/c41f849f905fa93c8ec94e3f82633669ac931f8d) ![azureclientsecret2.png](/files/5903c60271e380d685eabe57cf148c9139addc98)
3. 单击 **系统** 在顶部菜单中。
4. 选择 **认证源**.
5. 单击 **新建** 左侧菜单中的。
6. 输入一个 ***名称*** 用于该来源（例如“Azure”）。此名称将显示在 VergeOS 登录页的登录按钮上。 ![azureauthform.png](/files/d8062466888b96b5c835642fcba182ab9ec0947e)
7. 在 ***驱动程序*** 字段（下拉列表），选择 **Azure AD**.
8. 输入 ***租户 ID*** 在上一步中获取。
9. 该 ***重定向 URI*** 应为您的 VergeOS 系统的 URL（例如：https\:/\[]/verge.io.mycompanyabc.com）
10. 输入 ***用于用户注销会话令牌的端点 URL*** (https\:/\[]/login.microsoftonline.com/***TENANTID***/oauth2/v2.0/logout)
11. ***范围*** 通常应保持默认值：“OpenID profile email”。
12. ***组范围*** 如果应根据组成员关系自动创建用户，则需要设置；通常设置为单词“groups”，不带标点。
13. 输入 ***客户端 ID*** 在上一步中获取。
14. 输入 ***客户端密钥*** 在上一步中获取。
15. ***远程用户字段*** 定义用于初始查找 Azure 用户的字段列表；此字段会自动填充为 (sub,preferred\_username,email nickname)，这是一个默认列表，通常可适用于大多数实现。 **注意：出于安全原因，不建议根据远程系统中可被最终用户更改的字段来定位远程用户。**
16. 要将组成员关系从 Azure 传递到 VergeOS，请勾选 ***更新组成员关系*** 复选框。必须按照下面的说明在 VergeOS 中创建组。
17. **用户自动创建功能（可选）**: 用户可在首次登录 VergeOS 时自动创建；这可以针对所有 Entra ID 用户进行选择，或者仅限于指定 Entra ID 组中的用户。
    * ***自动创建用户*** - 如果应自动创建所有用户，请在 `.*` 此处输入。
    * ***自动创建组中的用户*** - 若只自动创建属于指定 Entra ID 组的用户，请以正则表达式（regex）形式输入组对象 ID。

{% hint style="info" %}
**自动创建组中的用户**

* 该 **组范围** 必须定义。（上面定义的组范围字段）
* **令牌配置** 必须在 Entra ID 中设置好（说明见下文）。
* Entra ID **组** 指定用于自动创建 **必须在 VergeOS 端创建** （说明见下文）。
* 要基于组自动创建， ***自动创建用户*** **字段必须为空**
* 多个特定组 ID 可使用以下格式输入：(ID)|(ID)|(ID)
  {% endhint %}

18. **选项（建议启用）：**

* ***更新远程用户：*** - 一旦在 Entra ID 中定位到用户，即更新 VergeOS 用户 *远程用户名* 字段为相应的 Azure 唯一 ID。

{% hint style="success" %}
**启用“更新远程用户”将允许 VergeOS 系统将 Azure 唯一 ID 存储在 VergeOS 用户记录中（在使用“远程用户字段”中定义的字段最初定位 Entra ID 用户之后），这样随后就可以使用该唯一标识符来查找 Entra ID 用户；通常建议这样做，因为电子邮件地址等字段可能会更改。**
{% endhint %}

* ***更新用户电子邮件地址：*** - 将 VergeOS 用户电子邮件地址更新为与 Entra ID 中的电子邮件地址一致。
* ***更新用户显示名称：*** - 将 VergeOS 用户显示名称更新为与 Entra ID 中的显示名称一致。
* ***更新组成员关系：*** - 更新 VergeOS 用户所属的组。（此功能需要组范围。）

19. **其他可选字段：** 参见 [**授权源（常规）**](https://github.com/verge-io/docs-vergeos/tree/main/run/product-guide/auth/auth-sources-overview.md) 有关其他可选字段的信息。

## 向 VergeOS 添加 Azure 组

与 Azure 组交互需要在 Entra ID 应用注册中有一个令牌，并在 VergeOS 中创建组：

### 在 Entra ID 中设置令牌配置

1. 导航到 **应用注册页面** 用于上面创建的应用。
2. 点击 **令牌配置** 左侧菜单中的 **+ 添加组声明**.
3. 勾选相应的 **组类型**.
4. 设置 **ID、Access 和 SAML 为 sAMAccountName**.

![azure-editgroupsclaim.pn](/files/930b36f66db9c7599ba1a3175b21f45f41538c98)

### 添加 Azure 组的步骤

1. 导航到 **系统 > 组。**
2. 单击 **新建** 左侧菜单中的。
3. 输入组 ***名称*** 以匹配 Entra ID 中的组名。
4. 可选地， ***电子邮件*** 可为该组输入。此电子邮件地址用于发送分配给该组的订阅提醒和/或报告。
5. 复制对应的 **对象 ID** 从 Entra ID 中的 组/所有组 页面复制到 ***标识符*** 字段中。
6. 单击 **提交** （页面底部）以保存新组。

![azure-groupspage.png](/files/7baa923f3222be734764ff864dd26986e75d0065)

![azure-creategroup.png](/files/61e957cdc19fb6bc983b9cda9a5a298703f07a9b)

## 从 Azure 手动添加用户

创建 Azure 身份验证源后，可以在 VergeOS 中手动创建用户以利用该授权源进行登录身份验证。只有在用户未配置为自动创建时，才需要手动创建用户。

### 添加将使用 Entra ID 身份验证的 VergeOS 用户

创建新用户时，请使用以下配置：

* ***授权源：*** 从下拉列表中选择 Entra ID 源
* ***用户名：*** 在 VergeOS 系统中的唯一名称；通常建议使用 Azure 主体名称。
* ***远程用户名：*** 使用定义为以下项之一的字段的值： *远程用户字段* 这些是在 Azure 中搜索的字段（例如：用户名、电子邮件）
* ***显示名称：*** （可选）如果 *更新用户显示名称* 在 Entra ID 身份验证源上启用时，显示名称将自动与 Entra ID 同步。
* ***电子邮件地址：*** （可选）如果 *更新用户电子邮件地址* 在 Entra ID 身份验证源上启用时，电子邮件地址将自动与 Entra ID 同步。

![azure-newuser.png](/files/b4fa2d001dc9e6131a105a1e5ef88ad4ca99959a)


---

# 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/azure-auth.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.