OpenWebUI/docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs synced 2025-06-13 10:02:50 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

clarify just in time group creation, distinguish bt group mgmt and creation flags, sync warning

Browse Source
This commit is contained in:
Taylor Wilsdon 2025-04-19 07:36:35 -07:00
parent 1762b338bd
commit d7e1785e68
3 changed files with 43 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/features/sso.md
View File

@ -88,20 +88,30 @@ If changing the role of a logged in user, they will need to log out and log back
### OAuth Group Management
Any OAuth provider that can be configured to return groups in the access token can be used to manage user groups in Open WebUI.
To use this feature set `ENABLE_OAUTH_GROUP_MANAGEMENT` to `true`.
You can configure the following environment variables to match the groups returned by the OAuth provider:
Any OAuth provider that can be configured to return groups in the access token can be used to manage user groups in Open WebUI upon user login.
To enable this synchronization, set `ENABLE_OAUTH_GROUP_MANAGEMENT` to `true`.
1. `OAUTH_GROUP_CLAIM` - The claim that contains the groups. Defaults to `groups`. Can also be nested, for example `user.memberOf`.
1. `ENABLE_OAUTH_GROUP_CREATION` - If `true` (and `ENABLE_OAUTH_GROUP_MANAGEMENT` is also `true`), Open WebUI will automatically create groups during OAuth login if they are present in the user's OAuth claims but do not yet exist in the system. Defaults to `false`.
You can configure the following environment variables:
:::warning
Admin users do not get their groups updated
1. `OAUTH_GROUP_CLAIM` - The claim in the ID/access token containing the user's group memberships. Defaults to `groups`. Can also be nested, for example `user.memberOf`. Required if `ENABLE_OAUTH_GROUP_MANAGEMENT` is true.
1. `ENABLE_OAUTH_GROUP_CREATION` - If `true` (and `ENABLE_OAUTH_GROUP_MANAGEMENT` is also `true`), Open WebUI will perform **Just-in-Time (JIT) group creation**. This means it will automatically create groups during OAuth login if they are present in the user's OAuth claims but do not yet exist in the system. Defaults to `false`. If `false`, only memberships in *existing* Open WebUI groups will be managed.
:::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 created or assigned within Open WebUI) if those groups are **not** present in their OAuth claims for that login session.
Ensure all necessary groups are correctly configured in your OAuth provider and included in the group claim (`OAUTH_GROUP_CLAIM`).
:::
:::info
:::warning Admin Users
Admin users' group memberships are **not** automatically updated via OAuth group management.
:::
If changing the group of a logged in user, they will need to log out and log back in to receive the new group.
:::info Login Required for Updates
If a user's groups change in the OAuth provider, they will need to log out of Open WebUI and log back in for the changes to be reflected.
:::

6
docs/getting-started/env-configuration.md
View File

@ -1723,21 +1723,21 @@ the search query. Example: `http://searxng.local/search?q=<query>`
- Type: `bool`
- Default: `False`
- Description: Enables role management to oauth delegation.
- Description: Enables role management delegation via OAuth claims.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `ENABLE_OAUTH_GROUP_MANAGEMENT`
- Type: `bool`
- Default: `False`
- Description: Enables or disables OAUTH group management.
- Description: Enables synchronization of user group memberships based on OAuth claims upon login. If `true`, user memberships in Open WebUI groups will be strictly managed based on the groups provided in the `OAUTH_GROUP_CLAIM`. Users will be added to matching groups and removed from any groups *not* present in the claim (including manually added ones). See also `ENABLE_OAUTH_GROUP_CREATION`.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `ENABLE_OAUTH_GROUP_CREATION`
- Type: `bool`
- Default: `False`
- Description: If `true` (and `ENABLE_OAUTH_GROUP_MANAGEMENT` is also `true`), Open WebUI will automatically create groups during OAuth login if they are present in the user's OAuth claims but do not yet exist in the system.
- Description: Enables **Just-in-Time (JIT) group creation** during OAuth login. If `true` (and `ENABLE_OAUTH_GROUP_MANAGEMENT` is also `true`), Open WebUI will automatically create groups if they are present in the user's OAuth claims (`OAUTH_GROUP_CLAIM`) but do not yet exist in the system. If `false`, only memberships in existing groups will be managed.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `OAUTH_MERGE_ACCOUNTS_BY_EMAIL`

27
docs/tutorials/integrations/okta-oidc-sso.md
View File

@ -11,7 +11,7 @@ This tutorial is a community contribution and is not supported by the Open WebUI
## Overview
This documentation page outlines the steps required to integrate Okta OIDC Single Sign-On (SSO) with Open WebUI. It also covers the **optional** features of managing Open WebUI user groups based on Okta group membership, including automatic group creation. By following these steps, you will enable users to log in to Open WebUI using their Okta credentials. If you choose to enable group syncing, users can be automatically assigned to relevant groups within Open WebUI based on their Okta groups, and groups present in Okta claims but missing in Open WebUI can be created automatically.
This documentation page outlines the steps required to integrate Okta OIDC Single Sign-On (SSO) with Open WebUI. It also covers the **optional** features of managing Open WebUI user groups based on Okta group membership, including **Just-in-Time (JIT) group creation**. By following these steps, you will enable users to log in to Open WebUI using their Okta credentials. If you choose to enable group syncing (`ENABLE_OAUTH_GROUP_MANAGEMENT`), users will be automatically assigned to relevant groups within Open WebUI based on their Okta groups upon login. If you *also* enable JIT group creation (`ENABLE_OAUTH_GROUP_CREATION`), groups present in Okta claims but missing in Open WebUI will be created automatically during login.
### Prerequisites
@ -77,19 +77,34 @@ OAUTH_PROVIDER_NAME="Okta"
# --- OAuth Group Management (Optional) ---
# Set to "true" only if you configured the Groups Claim in Okta (Step 2)
# and want Open WebUI groups to be managed based on Okta groups.
# and want Open WebUI groups to be managed based on Okta groups upon login.
# This syncs existing groups. Users will be added/removed from Open WebUI groups
# to match their Okta group claims.
# ENABLE_OAUTH_GROUP_MANAGEMENT="true"
# Required only if ENABLE_OAUTH_GROUP_MANAGEMENT is true.
# The claim name in the ID token containing group information (must match Okta config)
# OAUTH_GROUP_CLAIM="groups"
# Optional: Enable automatic creation of groups if they exist in Okta claims but not in Open WebUI.
# Optional: Enable Just-in-Time (JIT) creation of groups if they exist in Okta claims but not in Open WebUI.
# Requires ENABLE_OAUTH_GROUP_MANAGEMENT="true".
# ENABLE_OAUTH_GROUP_CREATION="false" # Default is false
# If set to false (default), only existing groups will be synced.
# ENABLE_OAUTH_GROUP_CREATION="false"
```
Replace `YOUR_OKTA_CLIENT_ID`, `YOUR_OKTA_CLIENT_SECRET`, and `YOUR_OKTA_OIDC_DISCOVERY_URL` with the actual values from your Okta application configuration. If enabling group management (`ENABLE_OAUTH_GROUP_MANAGEMENT="true"`), ensure `OAUTH_GROUP_CLAIM` matches the claim name you configured in Okta (default is `groups`). If you also want groups to be created automatically, set `ENABLE_OAUTH_GROUP_CREATION="true"`.
Replace `YOUR_OKTA_CLIENT_ID`, `YOUR_OKTA_CLIENT_SECRET`, and `YOUR_OKTA_OIDC_DISCOVERY_URL` with the actual values from your Okta application configuration.
To enable group synchronization based on Okta claims, set `ENABLE_OAUTH_GROUP_MANAGEMENT="true"` and ensure `OAUTH_GROUP_CLAIM` matches the claim name configured in Okta (default is `groups`).
To *also* enable automatic Just-in-Time (JIT) creation of groups that exist in Okta but not yet in Open WebUI, set `ENABLE_OAUTH_GROUP_CREATION="true"`. You can leave this as `false` if you only want to manage memberships for groups that already exist in Open WebUI.
:::warning Group Membership Management
When `ENABLE_OAUTH_GROUP_MANAGEMENT` is set to `true`, a user's group memberships in Open WebUI will be **strictly synchronized** with the groups received in their Okta claims upon each login. This means:
* Users will be **added** to Open WebUI groups that match their Okta claims.
* Users will be **removed** from any Open WebUI groups (including those manually created or assigned within Open WebUI) if those groups are **not** present in their Okta claims for that login session.
Ensure that all necessary groups are correctly configured and assigned within Okta and included in the group claim.
:::
:::info Session Persistence in Multi-Node Deployments
@ -124,7 +139,7 @@ Restart your Open WebUI instance after setting these environment variables.
1. Navigate to your Open WebUI login page. You should see a button labeled "Login with Okta" (or whatever you set for `OAUTH_PROVIDER_NAME`).
2. Click the button and authenticate through the Okta login flow.
3. Upon successful authentication, you should be redirected back to Open WebUI and logged in.
4. If `ENABLE_OAUTH_GROUP_MANAGEMENT` is true, log in as a non-admin user. Their groups within Open WebUI should reflect their group memberships in Okta (after their first login). If `ENABLE_OAUTH_GROUP_CREATION` is also true, any groups present in the user's Okta claims that did not exist in Open WebUI should now be created. Note that admin users' groups are not automatically updated via SSO.
4. If `ENABLE_OAUTH_GROUP_MANAGEMENT` is true, log in as a non-admin user. Their groups within Open WebUI should now strictly reflect their current group memberships in Okta (any memberships in groups *not* in the Okta claim will be removed). If `ENABLE_OAUTH_GROUP_CREATION` is also true, any groups present in the user's Okta claims that did not previously exist in Open WebUI should now have been created automatically. Note that admin users' groups are not automatically updated via SSO.
5. Check the Open WebUI server logs for any OIDC or group-related errors if you encounter issues.
## Troubleshooting