授权源 - 概览

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

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

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

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

• Google
• Azure
• VergeOS OIDC

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

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

功能	用途	配置位置
认证源（UI 登录）	允许 VergeOS UI 用户和租户用户使用外部身份提供方凭据登录	系统 > 认证源
NAS 域加入	将 VergeOS NAS 服务加入 AD 域，以实现 CIFS/SMB 文件共享访问控制	NAS 服务设置——参见 将 NAS 加入域

这些功能是独立的。将 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 支持团队以配置此类认证源。）

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

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

出于安全原因，不建议基于 OAuth 源中可由终端用户更改的字段来定位远程用户。

1. 进一步配置：

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

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

其他可选字段

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

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

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

---

用户创建

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

要基于一个或多个组自动创建用户， 自动创建用户 字段应留空。

将使用外部认证源的用户也可选择在 VergeOS 中手动创建；创建新的 VergeOS 用户时：在下拉列表中选择相应的认证源。

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

登录样式

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

• 登录按钮背景颜色： 登录按钮的背景颜色。
• 登录按钮文字颜色： 登录按钮的文字颜色。
• 登录按钮 Font Awesome 图标： 为登录按钮指定备用图标；可用的 Font Awesome 图标列表可在以下位置找到： 此处.
• 登录按钮 Font Awesome 图标颜色： 为登录按钮指定备用颜色；请使用标准 HEX 代码，例如 #FF5733。