Skip to content

sync #1040

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Classic298 merged 6 commits into from
Jan 29, 2026
+217 −15
Merged

sync #1040

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bb26891
docs: add entra group name sync tutorial
fstau Jan 14, 2026
ca7a90a
Merge pull request #1005 from berlin-bytes/main
Classic298 Jan 25, 2026
e9b84bd
Pin Google PSE Disclaimer (#1036)
webgtx Jan 27, 2026
d707007
Update development.mdx
Classic298 Jan 27, 2026
ef86b58
docs(searxng): make the style of uwsgi.ini consistent (#1038)
MaxDevNix Jan 28, 2026
08ced90
Update env-configuration.mdx
Classic298 Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/features/plugin/tools/development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1605,7 +1605,6 @@ When embedding external content, several security options can be configured thro

- `iframeSandboxAllowForms`: Allow form submissions within embedded content
- `iframeSandboxAllowSameOrigin`: Allow same-origin requests (use with caution)
- `iframeSandboxAllowPopups`: Allow popup windows from embedded content

#### Use Cases

Expand Down
6 changes: 6 additions & 0 deletions docs/features/web-search/google-pse.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ title: "Google PSE"

:::warning

**New Google PSE projects are no longer supported.** Google has restricted the legacy JSON API to existing customers only. New users attempting to use Google PSE will receive a `403 Forbidden` error.

:::

:::warning

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.

:::
Expand Down
2 changes: 1 addition & 1 deletion docs/features/web-search/searxng.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,7 @@ docker compose up -d

:::note

On the first run, you must remove `cap_drop: - ALL` from the `docker-compose.yaml` file for the `searxng` service to successfully create `/etc/searxng/uwsgi`.ini. This is necessary because the `cap_drop: - ALL` directive removes all capabilities, including those required for the creation of the `uwsgi.ini` file. After the first run, you should re-add `cap_drop: - ALL` to the `docker-compose.yaml` file for security reasons.
On the first run, you must remove `cap_drop: - ALL` from the `docker-compose.yaml` file for the `searxng` service to successfully create `/etc/searxng/uwsgi.ini`. This is necessary because the `cap_drop: - ALL` directive removes all capabilities, including those required for the creation of the `uwsgi.ini` file. After the first run, you should re-add `cap_drop: - ALL` to the `docker-compose.yaml` file for security reasons.

:::

Expand Down
14 changes: 1 addition & 13 deletions docs/getting-started/env-configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,23 +270,11 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b
- Default: `True`
- Description: Enables admin users to directly access the chats of other users. When disabled, admins can no longer accesss user's chats in the admin panel. If you disable this, consider disabling `ENABLE_ADMIN_EXPORT` too, if you are using SQLite, as the exports also contain user chats.

#### `ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS`

- Type: `bool`
- Default: `True`
- Description: Enables admin users to access all workspace content (models, knowledge bases, prompts, and tools) regardless of access control settings. When set to `False`, admins will only see workspace items they have been explicitly granted access to.

:::warning **Deprecated**

**This environment variable is deprecated and may be removed in a future release.** Use [`BYPASS_ADMIN_ACCESS_CONTROL`](#bypass_admin_access_control) instead, which provides the same functionality with a clearer name.

:::

#### `BYPASS_ADMIN_ACCESS_CONTROL`

- Type: `bool`
- Default: `True`
- Description: When disabled, admin users are treated like regular users for workspace access (models, knowledge, prompts and tools) and only see items they have **explicit permission to access** through the existing access control system. This also applies to the visibility of models in the model selector - admins will be treated as regular users: base models and custom models they do not have **explicit permission to access**, will be hidden. If set to `True` (Default), admins have access to **all created items** in the workspace area and all models in the model selector, **regardless of access permissions**.
- Description: When disabled, admin users are treated like regular users for workspace access (models, knowledge, prompts and tools) and only see items they have **explicit permission to access** through the existing access control system. This also applies to the visibility of models in the model selector - admins will be treated as regular users: base models and custom models they do not have **explicit permission to access**, will be hidden. If set to `True` (Default), admins have access to **all created items** in the workspace area and all models in the model selector, **regardless of access permissions**. This environment variable deprecates `ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS`. If you are still using `ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS` you should switch to `BYPASS_ADMIN_ACCESS_CONTROL`.

#### `ENABLE_USER_WEBHOOKS`

Expand Down
209 changes: 209 additions & 0 deletions docs/tutorials/integrations/entra-group-name-sync.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
---
sidebar_position: 15
title: "Microsoft Entra ID Group Name Sync"
---

:::warning

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.

:::

# Microsoft Entra ID Group Name Sync

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.

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.

## Prerequisites

- An Open WebUI instance configured with [Microsoft OAuth](/features/auth/sso#microsoft)
- An Azure account with permissions to modify App Registrations
- Access to the Microsoft Entra admin center
- Basic understanding of Microsoft Entra ID application configuration

## Overview

To get human-readable group names in Open WebUI, you need to:

1. Configure your App Registration to include groups in the token
2. Modify the application manifest to use `cloud_displayname`
3. Set `groupMembershipClaims` to `ApplicationGroup` only
4. Assign security groups to the Enterprise Application
5. Configure Open WebUI environment variables for [OAuth Group Management](/features/auth/sso#oauth-group-management)

:::info Key Requirement

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.

:::

## Step 1: Configure Token Claims in App Registration

1. Navigate to the **Microsoft Entra admin center** > **App registrations**
2. Select your Open WebUI application
3. Go to **Token configuration** in the left menu
4. Click **Add groups claim**
5. Select **Security groups** (or the appropriate group type for your needs)
6. Under **Customize token properties by type**, ensure groups are added for:
- ID token
- Access token
7. Click **Add**

## Step 2: Modify the Application Manifest

This is the critical step that enables group names instead of IDs.

1. In your App Registration, go to **Manifest** in the left menu
2. Locate the `optionalClaims` section
3. Add `cloud_displayname` to the `additionalProperties` array for each token type

Your manifest should look like this:

```json
"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"
]
}
]
}
```

4. **Critical**: Set `groupMembershipClaims` to `ApplicationGroup` only:

```json
"groupMembershipClaims": "ApplicationGroup"
```

:::warning

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.

:::

5. Click **Save**

## Step 3: Assign Groups to the Enterprise Application

When using `ApplicationGroup`, only groups explicitly assigned to the Enterprise Application will be included in the token.

1. Navigate to **Microsoft Entra admin center** > **Enterprise applications**
2. Find and select your Open WebUI application
3. Go to **Users and groups** in the left menu
4. Click **Add user/group**
5. Select the security groups you want to sync with Open WebUI
6. Click **Assign**

:::warning Multiple Group Assignment

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.

:::

## Step 4: Configure API Permissions

Ensure your App Registration has the required Microsoft Graph permissions:

1. In your App Registration, go to **API permissions**
2. Click **Add a permission** > **Microsoft Graph** > **Delegated permissions**
3. Add the following permissions from the OpenID section if not already present:
- `openid`
- `email`
- `profile`
4. Click **Grant admin consent for [your organization]**

## Step 5: Configure Open WebUI Environment Variables

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

```bash
# Required: Your public WebUI address
WEBUI_URL=https://your-open-webui-domain

# Microsoft OAuth Configuration (required)
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

# Required for logout to work properly
OPENID_PROVIDER_URL=https://login.microsoftonline.com/your_tenant_id/v2.0/.well-known/openid-configuration

# Enable OAuth signup
ENABLE_OAUTH_SIGNUP=true

# OAuth Group Management
OAUTH_GROUP_CLAIM=groups
ENABLE_OAUTH_GROUP_MANAGEMENT=true
ENABLE_OAUTH_GROUP_CREATION=true

# Recommended: Set a consistent secret key
WEBUI_SECRET_KEY=your_secure_secret_key
```

### Environment Variable Reference

| Variable | Default | Description |
| ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OAUTH_GROUP_CLAIM` | `groups` | The claim in the ID/access token containing the user's group memberships. |
| `ENABLE_OAUTH_GROUP_MANAGEMENT` | `false` | When `true`, user group memberships are synchronized with OAuth claims upon each login. |
| `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. |

:::warning Strict Group Synchronization

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.

- Users will be **added** to Open WebUI groups that match their OAuth claims.
- 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.

:::

## Verification

After completing the configuration:

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.
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.
3. **Check Open WebUI**: Navigate to the Admin Panel and verify that groups appear with readable names.

:::info Admin Users

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.

:::


## Additional Resources

- [SSO (OAuth, OIDC, Trusted Header)](/features/auth/sso) - OAuth configuration overview
- [OAuth Group Management](/features/auth/sso#oauth-group-management) - Group synchronization details
- [Groups](/features/rbac/groups) - Group management in Open WebUI
- [SSO Troubleshooting Guide](/troubleshooting/sso) - Common OAuth issues and solutions
- [Environment Configuration](/getting-started/env-configuration) - All environment variables
- [Microsoft Optional Claims Documentation](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims) - Microsoft's official documentation