Skip to content

Commit ca7a90a

Browse files
Classic298Classic298
authored
Merge pull request #1005 from berlin-bytes/main
2 parents 38890cd + bb26891 commit ca7a90a

File tree

1 file changed

+209
-0
lines changed

1 file changed

+209
-0
lines changed

‎docs/tutorials/integrations/entra-group-name-sync.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
---
2+
sidebar_position: 15
3+
title: "Microsoft Entra ID Group Name Sync"
4+
---
5+
6+
:::warning
7+
8+
This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
9+
10+
:::
11+
12+
# Microsoft Entra ID Group Name Sync
13+
14+
By default, when you configure Microsoft Entra ID OAuth and automatic group creation with Open WebUI, security groups are synced using their **Group IDs (GUIDs)** rather than human-readable group names. This is a Microsoft limitation where the ID token doesn't include group display names by default.
15+
16+
This tutorial explains how to configure Microsoft Entra ID to return group **names** instead of IDs, enabling a much better user experience when working with groups in Open WebUI.
17+
18+
## Prerequisites
19+
20+
- An Open WebUI instance configured with [Microsoft OAuth](/features/auth/sso#microsoft)
21+
- An Azure account with permissions to modify App Registrations
22+
- Access to the Microsoft Entra admin center
23+
- Basic understanding of Microsoft Entra ID application configuration
24+
25+
## Overview
26+
27+
To get human-readable group names in Open WebUI, you need to:
28+
29+
1. Configure your App Registration to include groups in the token
30+
2. Modify the application manifest to use `cloud_displayname`
31+
3. Set `groupMembershipClaims` to `ApplicationGroup` only
32+
4. Assign security groups to the Enterprise Application
33+
5. Configure Open WebUI environment variables for [OAuth Group Management](/features/auth/sso#oauth-group-management)
34+
35+
:::info Key Requirement
36+
37+
The `cloud_displayname` property in the manifest **only works** when `groupMembershipClaims` is set to `ApplicationGroup`. If you include other options (like `SecurityGroup` or `All`), the token will revert to using Group IDs instead of names.
38+
39+
:::
40+
41+
## Step 1: Configure Token Claims in App Registration
42+
43+
1. Navigate to the **Microsoft Entra admin center** > **App registrations**
44+
2. Select your Open WebUI application
45+
3. Go to **Token configuration** in the left menu
46+
4. Click **Add groups claim**
47+
5. Select **Security groups** (or the appropriate group type for your needs)
48+
6. Under **Customize token properties by type**, ensure groups are added for:
49+
- ID token
50+
- Access token
51+
7. Click **Add**
52+
53+
## Step 2: Modify the Application Manifest
54+
55+
This is the critical step that enables group names instead of IDs.
56+
57+
1. In your App Registration, go to **Manifest** in the left menu
58+
2. Locate the `optionalClaims` section
59+
3. Add `cloud_displayname` to the `additionalProperties` array for each token type
60+
61+
Your manifest should look like this:
62+
63+
```json
64+
"optionalClaims": {
65+
"idToken": [
66+
{
67+
"name": "groups",
68+
"source": null,
69+
"essential": false,
70+
"additionalProperties": [
71+
"cloud_displayname"
72+
]
73+
}
74+
],
75+
"accessToken": [
76+
{
77+
"name": "groups",
78+
"source": null,
79+
"essential": false,
80+
"additionalProperties": [
81+
"cloud_displayname"
82+
]
83+
}
84+
],
85+
"saml2Token": [
86+
{
87+
"name": "groups",
88+
"source": null,
89+
"essential": false,
90+
"additionalProperties": [
91+
"cloud_displayname"
92+
]
93+
}
94+
]
95+
}
96+
```
97+
98+
4. **Critical**: Set `groupMembershipClaims` to `ApplicationGroup` only:
99+
100+
```json
101+
"groupMembershipClaims": "ApplicationGroup"
102+
```
103+
104+
:::warning
105+
106+
If `groupMembershipClaims` includes other values like `SecurityGroup` or `All`, the `cloud_displayname` property will be ignored and the token will contain Group IDs instead of names. See [Microsoft's optional claims documentation](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims) for more details.
107+
108+
:::
109+
110+
5. Click **Save**
111+
112+
## Step 3: Assign Groups to the Enterprise Application
113+
114+
When using `ApplicationGroup`, only groups explicitly assigned to the Enterprise Application will be included in the token.
115+
116+
1. Navigate to **Microsoft Entra admin center** > **Enterprise applications**
117+
2. Find and select your Open WebUI application
118+
3. Go to **Users and groups** in the left menu
119+
4. Click **Add user/group**
120+
5. Select the security groups you want to sync with Open WebUI
121+
6. Click **Assign**
122+
123+
:::warning Multiple Group Assignment
124+
125+
When a user belongs to multiple groups, ensure all relevant groups are assigned to the Enterprise Application. Note that only groups explicitly assigned here will appear in the user's token and subsequently sync to Open WebUI.
126+
127+
:::
128+
129+
## Step 4: Configure API Permissions
130+
131+
Ensure your App Registration has the required Microsoft Graph permissions:
132+
133+
1. In your App Registration, go to **API permissions**
134+
2. Click **Add a permission** > **Microsoft Graph** > **Delegated permissions**
135+
3. Add the following permissions from the OpenID section if not already present:
136+
- `openid`
137+
- `email`
138+
- `profile`
139+
4. Click **Grant admin consent for [your organization]**
140+
141+
## Step 5: Configure Open WebUI Environment Variables
142+
143+
Configure the following environment variables for your Open WebUI deployment. For more details on each variable, see the [environment variable documentation](/getting-started/env-configuration).
144+
145+
```bash
146+
# Required: Your public WebUI address
147+
WEBUI_URL=https://your-open-webui-domain
148+
149+
# Microsoft OAuth Configuration (required)
150+
MICROSOFT_CLIENT_ID=your_client_id
151+
MICROSOFT_CLIENT_SECRET=your_client_secret
152+
MICROSOFT_CLIENT_TENANT_ID=your_tenant_id
153+
MICROSOFT_REDIRECT_URI=https://your-open-webui-domain/oauth/microsoft/callback
154+
155+
# Required for logout to work properly
156+
OPENID_PROVIDER_URL=https://login.microsoftonline.com/your_tenant_id/v2.0/.well-known/openid-configuration
157+
158+
# Enable OAuth signup
159+
ENABLE_OAUTH_SIGNUP=true
160+
161+
# OAuth Group Management
162+
OAUTH_GROUP_CLAIM=groups
163+
ENABLE_OAUTH_GROUP_MANAGEMENT=true
164+
ENABLE_OAUTH_GROUP_CREATION=true
165+
166+
# Recommended: Set a consistent secret key
167+
WEBUI_SECRET_KEY=your_secure_secret_key
168+
```
169+
170+
### Environment Variable Reference
171+
172+
| Variable | Default | Description |
173+
| ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
174+
| `OAUTH_GROUP_CLAIM` | `groups` | The claim in the ID/access token containing the user's group memberships. |
175+
| `ENABLE_OAUTH_GROUP_MANAGEMENT` | `false` | When `true`, user group memberships are synchronized with OAuth claims upon each login. |
176+
| `ENABLE_OAUTH_GROUP_CREATION` | `false` | When `true`, enables **Just-in-Time (JIT) group creation** - groups present in OAuth claims but not in Open WebUI will be created automatically. |
177+
178+
:::warning Strict Group Synchronization
179+
180+
When `ENABLE_OAUTH_GROUP_MANAGEMENT` is set to `true`, a user's group memberships in Open WebUI are **strictly synchronized** with the groups received in their OAuth claims upon each login.
181+
182+
- Users will be **added** to Open WebUI groups that match their OAuth claims.
183+
- Users will be **removed** from any Open WebUI groups (including those manually assigned within Open WebUI) if those groups are **not** present in their OAuth claims for that login session.
184+
185+
:::
186+
187+
## Verification
188+
189+
After completing the configuration:
190+
191+
1. **Test the token**: Use [https://jwt.ms](https://jwt.ms) to decode your ID token and verify that the `groups` claim contains display names instead of GUIDs.
192+
2. **Log in as a non-admin user**: Admin users' group memberships are not automatically updated via OAuth group management. Use a standard user account for testing.
193+
3. **Check Open WebUI**: Navigate to the Admin Panel and verify that groups appear with readable names.
194+
195+
:::info Admin Users
196+
197+
Admin users' group memberships are **not** automatically updated via OAuth group management. If you need to test the configuration, use a non-admin user account.
198+
199+
:::
200+
201+
202+
## Additional Resources
203+
204+
- [SSO (OAuth, OIDC, Trusted Header)](/features/auth/sso) - OAuth configuration overview
205+
- [OAuth Group Management](/features/auth/sso#oauth-group-management) - Group synchronization details
206+
- [Groups](/features/rbac/groups) - Group management in Open WebUI
207+
- [SSO Troubleshooting Guide](/troubleshooting/sso) - Common OAuth issues and solutions
208+
- [Environment Configuration](/getting-started/env-configuration) - All environment variables
209+
- [Microsoft Optional Claims Documentation](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims) - Microsoft's official documentation

0 commit comments

Comments
 (0)