Microsoft Entra ID 群组名称同步

注意

本教程为社区贡献，Open WebUI 团队不提供官方支持。它仅作为如何针对您的特定使用场景自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。

默认情况下，当您使用 Open WebUI 配置 Microsoft Entra ID OAuth 和自动群组创建时，安全群组是使用其 Group ID (GUID) 而不是人类可读的群组名称进行同步的。这是 Microsoft 的一项限制，即在默认情况下，ID token 中不包含群组显示名称。

本教程将介绍如何配置 Microsoft Entra ID 以返回群组名称而不是 ID，从而在 Open WebUI 中使用群组时提供更好的用户体验。

前提条件

一个配置了 Microsoft OAuth 的 Open WebUI 实例
一个拥有修改应用注册 (App Registrations) 权限的 Azure 账户
访问 Microsoft Entra 管理中心
对 Microsoft Entra ID 应用程序配置有基本了解

概述

要在 Open WebUI 中获取人类可读的群组名称，您需要：

配置您的应用注册 (App Registration) 以在 token 中包含群组
修改应用清单 (Application Manifest) 以使用 cloud_displayname
将 groupMembershipClaims 仅设置为 ApplicationGroup
将安全群组分配给企业应用程序 (Enterprise Application)
为 OAuth 群组管理配置 Open WebUI 环境变量

关键要求

清单 (manifest) 中的 cloud_displayname 属性仅在 groupMembershipClaims 设置为 ApplicationGroup 时有效。如果您包含其他选项（如 SecurityGroup 或 All），token 将恢复使用 Group ID 而不是名称。

步骤 1：在 App 注册中配置 Token 声明

导航到 Microsoft Entra 管理中心 > 应用注册 (App registrations)
选择您的 Open WebUI 应用程序
前往左侧菜单中的 Token configuration
点击 Add groups claim
选择 Security groups（或适合您需求的其他群组类型）
在 Customize token properties by type 下，确保为以下项添加了群组：
- ID token
- Access token
点击 Add

步骤 2：修改 Application Manifest

这是启用群组名称而不是 ID 的关键步骤。

在您的应用注册 (App Registration) 中，前往左侧菜单的 Manifest
找到 optionalClaims 部分
为每种 token 类型在 additionalProperties 数组中添加 cloud_displayname

您的清单 (manifest) 应该类似于以下内容：

"optionalClaims": {
    "idToken": [
        {
            "name": "groups",
            "source": null,
            "essential": false,
            "additionalProperties": [
                "cloud_displayname"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "groups",
            "source": null,
            "essential": false,
            "additionalProperties": [
                "cloud_displayname"
            ]
        }
    ],
    "saml2Token": [
        {
            "name": "groups",
            "source": null,
            "essential": false,
            "additionalProperties": [
                "cloud_displayname"
            ]
        }
    ]
}

关键：将 groupMembershipClaims 仅设置为 ApplicationGroup：

"groupMembershipClaims": "ApplicationGroup"

注意

如果 groupMembershipClaims 包含 SecurityGroup 或 All 等其他值，cloud_displayname 属性将被忽略，并且 token 将包含 Group ID 而不是名称。有关更多详细信息，请参阅 Microsoft 的可选声明文档。

点击 Save

步骤 3：将群组分配给 Enterprise Application

使用 ApplicationGroup 时，只有显式分配给企业应用程序 (Enterprise Application) 的群组才会包含在 token 中。

导航到 Microsoft Entra 管理中心 > 企业应用程序 (Enterprise applications)
找到并选择您的 Open WebUI 应用程序
前往左侧菜单中的 Users and groups
点击 Add user/group
选择您要与 Open WebUI 同步的安全群组
点击 Assign

多个群组分配

当用户属于多个群组时，请确保将所有相关群组都分配给企业应用程序 (Enterprise Application)。请注意，只有在此处显式分配的群组才会出现在用户的 token 中，并随后同步到 Open WebUI。

步骤 4：配置 API 权限

确保您的应用注册 (App Registration) 拥有所需的 Microsoft Graph 权限：

在您的应用注册 (App Registration) 中，前往 API permissions
点击 Add a permission > Microsoft Graph > Delegated permissions
如果尚不存在，从 OpenID 部分添加以下权限：
- openid
- email
- profile
点击 Grant admin consent for [your organization]

步骤 5：配置 Open WebUI 环境变量

为您的 Open WebUI 部署配置以下环境变量。有关每个变量的更多详细信息，请参阅环境变量文档。

# 必填：您的公开 WebUI 地址
WEBUI_URL=https://your-open-webui-domain

# Microsoft OAuth 配置（必填）
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret
MICROSOFT_CLIENT_TENANT_ID=your_tenant_id
MICROSOFT_REDIRECT_URI=https://your-open-webui-domain/oauth/microsoft/callback

# 注销正常工作所必需
OPENID_PROVIDER_URL=https://login.microsoftonline.com/your_tenant_id/v2.0/.well-known/openid-configuration

# 启用 OAuth 注册
ENABLE_OAUTH_SIGNUP=true

# OAuth 群组管理
OAUTH_GROUP_CLAIM=groups
ENABLE_OAUTH_GROUP_MANAGEMENT=true
ENABLE_OAUTH_GROUP_CREATION=true

# 推荐：设置一致的安全密钥
WEBUI_SECRET_KEY=your_secure_secret_key

环境变量参考

变量	默认值	描述
`OAUTH_GROUP_CLAIM`	`groups`	ID/access token 中包含用户群组成员身份的 claim。
`ENABLE_OAUTH_GROUP_MANAGEMENT`	`false`	当为 `true` 时，用户群组成员身份将在每次登录时与 OAuth 声明进行同步。
`ENABLE_OAUTH_GROUP_CREATION`	`false`	当为 `true` 时，启用即时 (Just-in-Time, JIT) 群组创建——OAuth 声明中存在但 Open WebUI 中不存在的群组将被自动创建。

严格群组同步

当 ENABLE_OAUTH_GROUP_MANAGEMENT 设置为 true 时，用户在 Open WebUI 中的群组成员身份将在每次登录时与从其 OAuth 声明中接收到的群组进行严格同步。

用户将被添加到与其 OAuth 声明相匹配的 Open WebUI 群组中。
如果某些 Open WebUI 群组在登录会话期间不存在于用户的 OAuth 声明中，用户将被从这些群组（包括在 Open WebUI 中手动分配的群组）中移除。

验证

完成配置后：

测试 token：使用 https://jwt.ms 解码您的 ID token，并验证 groups claim 是否包含显示名称而不是 GUID。
以非管理员用户登录：管理员用户的群组成员身份不会通过 OAuth 群组管理自动更新。请使用普通用户账户进行测试。
检查 Open WebUI：导航到管理员面板并验证群组是否显示为可读名称。

管理员用户

管理员用户的群组成员身份不会通过 OAuth 群组管理自动更新。如果您需要测试配置，请使用非管理员用户账户。

混合 AD 群组（本地 Active Directory）

上述 cloud_displayname 方法适用于云原生 Entra ID 安全群组。但是，如果您的组织将群组从本地 Active Directory (On-Premises Active Directory) 同步到 Entra ID，那么在执行上述步骤后，这些同步的群组在 Open WebUI 中可能仍然显示为 GUID。

发生这种情况是因为 cloud_displayname 仅解析源自 Entra ID 的群组名称。从本地 AD 同步的群组需要不同的 token 配置。

解决方案：为混合群组使用 sAMAccountName

在 Azure Portal 中，导航到您的 应用注册 (App Registration)
前往 Token configuration
如果您已经有 groups claim，请点击它进行编辑。否则，点击 Add groups claim
在 ID token 类型下，将群组标识符格式设置为 sAMAccountName
点击 Save

这告诉 Entra ID 针对 AD 同步的群组包含本地 sAMAccountName 属性，该属性可解析为人类可读的群组名称。

混合环境

如果您的环境同时包含云原生和本地 AD 同步的群组，使用 sAMAccountName 将正确解析这两种类型的名称。

其他资源

SSO (OAuth, OIDC, Trusted Header) - OAuth 配置概述
OAuth 群组管理 - 群组同步详情
群组 - Open WebUI 中的群组管理
SSO 问题排查指南 - 常见 OAuth 问题与解决方案
环境配置 - 所有环境变量
Microsoft 可选声明文档 - Microsoft 官方文档

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

前提条件​

概述​

步骤 1：在 App 注册中配置 Token 声明​

步骤 2：修改 Application Manifest​

步骤 3：将群组分配给 Enterprise Application​

步骤 4：配置 API 权限​

步骤 5：配置 Open WebUI 环境变量​

环境变量参考​

验证​

混合 AD 群组（本地 Active Directory）​

解决方案：为混合群组使用 sAMAccountName​

其他资源​