OpenWebUI/docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs synced 2025-05-20 03:08:56 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

add docs for ENABLE_OAUTH_GROUP_CREATION

Browse Source
This commit is contained in:
Taylor Wilsdon 2025-04-19 07:33:21 -07:00
parent 61a37d525b
commit 1762b338bd
3 changed files with 15 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/features/sso.md
View File

@ -93,6 +93,7 @@ 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:
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`.
:::warning
Admin users do not get their groups updated

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

@ -1733,6 +1733,13 @@ the search query. Example: `http://searxng.local/search?q=<query>`
- Description: Enables or disables OAUTH group management.
- 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.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `OAUTH_MERGE_ACCOUNTS_BY_EMAIL`
- Type: `bool`

10
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** feature of managing Open WebUI user groups based on Okta group membership. 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 also be automatically assigned to relevant groups within Open WebUI based on their Okta groups.
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.
### Prerequisites
@ -83,9 +83,13 @@ OAUTH_PROVIDER_NAME="Okta"
# 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.
# Requires ENABLE_OAUTH_GROUP_MANAGEMENT="true".
# ENABLE_OAUTH_GROUP_CREATION="false" # Default is 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, ensure `OAUTH_GROUP_CLAIM` matches the claim name you configured in Okta (default is `groups`).
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"`.
:::info Session Persistence in Multi-Node Deployments
@ -120,7 +124,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). 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 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.
5. Check the Open WebUI server logs for any OIDC or group-related errors if you encounter issues.
## Troubleshooting