Merge pull request #508 from taylorwilsdon/ENABLE_OAUTH_GROUP_CREATION_docs

docs: Docs for ENABLE_OAUTH_GROUP_CREATION & friends

docs/features/sso.md

@@ -88,19 +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`.
+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.
 
 :::
 

docs/tutorials/integrations/okta-oidc-sso.md

@@ -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 **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,15 +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 Just-in-Time (JIT) creation of groups if they exist in Okta claims but not in Open WebUI.
+# Requires ENABLE_OAUTH_GROUP_MANAGEMENT="true".
+# 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, 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.
+
+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
 
@@ -120,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). 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