diff --git a/docs/tutorials/auth-sso/azure-ad-ds-ldap.mdx b/docs/tutorials/auth-sso/azure-ad-ds-ldap.mdx index 364a86d418..7ade0d0578 100644 --- a/docs/tutorials/auth-sso/azure-ad-ds-ldap.mdx +++ b/docs/tutorials/auth-sso/azure-ad-ds-ldap.mdx @@ -174,7 +174,7 @@ LDAP_SERVER_HOST="1.222.222.222" LDAP_SERVER_PORT="636" # TLS Options -LDAP_USE_TLS="true" +LDAP_USE_TLS="true" # LDAPS from connect; there is no STARTTLS mode, so pair it with port 636 LDAP_VALIDATE_CERT="false" # Set to true for a public CA #LDAP_CA_CERT_FILE="/etc/ssl/certs/openwebui_ca.crt" @@ -217,7 +217,7 @@ To enable full TLS validation (`LDAP_VALIDATE_CERT="true"`): sudo cp certificate_wildcard.crt /usr/local/share/ca-certificates/openwebui.crt sudo update-ca-certificates ``` -Restart Open WebUI after making this change. +Restart Open WebUI after making this change. This only helps when Open WebUI runs directly on the host: with `LDAP_CA_CERT_FILE` empty, the LDAP client uses the system CA store of the machine or container it runs in, and a Docker container does not see the host's store. In Docker, mount the certificate into the container and point `LDAP_CA_CERT_FILE` at that path (it is shown commented out in section 7); on an instance that has already started once, set the same path in **Admin Panel > Settings > Authentication > LDAP > Certificate Path** instead, because the stored value takes precedence over the environment variable. ## 10. Test LDAPS Connection diff --git a/docs/tutorials/auth-sso/dual-oauth-configuration.mdx b/docs/tutorials/auth-sso/dual-oauth-configuration.mdx index 260daee3bb..eb619c55c0 100644 --- a/docs/tutorials/auth-sso/dual-oauth-configuration.mdx +++ b/docs/tutorials/auth-sso/dual-oauth-configuration.mdx @@ -2,20 +2,18 @@ title: "Dual OAuth Setup" sidebar_label: Dual OAuth Configuration sidebar_position: 30 -description: Learn how to configure both Microsoft and Google OAuth providers simultaneously in Open WebUI using an unofficial community workaround. +description: Learn how to configure both Microsoft and Google OAuth providers simultaneously in Open WebUI. --- # Dual OAuth Configuration (Microsoft & Google) -:::caution Unofficial Workaround -This configuration is a community-contributed workaround and is **not officially supported** by the Open WebUI team. While it works in current versions, behavior may change in future updates. This tutorial serves as a demonstration for advanced users. +:::info Supported configuration +Google, Microsoft, GitHub and Feishu are separate built-in providers, each registered independently of the generic OIDC provider (`OPENID_PROVIDER_URL`). Only the generic OIDC slot is single, so Microsoft plus Google is a supported setup rather than a workaround. ::: ## Overview -While Open WebUI officially supports only one **OpenID Connect (OIDC)** provider at a time via the `OPENID_PROVIDER_URL` variable, it is possible to support both **Microsoft** and **Google** simultaneously. - -The trick is to configure one provider (e.g., Microsoft) as the primary OIDC provider and the other (e.g., Google) as a standard OAuth provider by utilizing Open WebUI's built-in support for specific providers. +Open WebUI registers Google, Microsoft, GitHub and Feishu as separate built-in providers alongside one generic OIDC provider, so **Microsoft** and **Google** can be enabled at the same time. ## Prerequisites @@ -25,7 +23,7 @@ The trick is to configure one provider (e.g., Microsoft) as the primary OIDC pro ## Configuration logic -Open WebUI uses `OPENID_PROVIDER_URL` as a generic "catch-all" for OIDC. However, it also has native modules for Google and Microsoft. By leaving the `OPENID_PROVIDER_URL` for Microsoft and providing only the Client IDs for Google, the system can internalize both flows. +Each built-in provider is registered from its own `*_CLIENT_ID` and `*_CLIENT_SECRET` (Microsoft also needs `MICROSOFT_CLIENT_TENANT_ID`). `OPENID_PROVIDER_URL` registers only the generic OIDC provider (together with `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`, or `OAUTH_CODE_CHALLENGE_METHOD` for PKCE); apart from that it is only a sign-out fallback for providers without their own discovery URL. ## Environment Variables @@ -36,12 +34,13 @@ Add the following to your `docker-compose.yaml` or environment config: ENABLE_OAUTH_SIGNUP=true OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true -# 1. Microsoft as the primary OIDC provider -# This uses the generic OIDC flow via the OPENID_PROVIDER_URL +# 1. Microsoft (built-in provider) +# Registered as the built-in Microsoft provider from the first three variables MICROSOFT_CLIENT_ID=your_microsoft_client_id MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret MICROSOFT_CLIENT_TENANT_ID=your_tenant_id MICROSOFT_REDIRECT_URI=https://your-webui.com/oauth/microsoft/callback +# Optional: not used to register Microsoft; a sign-out fallback that also silences the startup logout warning OPENID_PROVIDER_URL=https://login.microsoftonline.com/your_tenant_id/v2.0/.well-known/openid-configuration # Optional: Custom scope for Microsoft OAuth (required if using custom API scopes) @@ -59,13 +58,13 @@ GOOGLE_CLIENT_SECRET=your_google_client_secret ## Why This Works -1. **Microsoft** is handled via the generic OIDC flow because `OPENID_PROVIDER_URL` is set to the Microsoft endpoint. -2. **Google** is handled via the dedicated internal Google OAuth module because the system detects `GOOGLE_CLIENT_ID` but sees that the global `OPENID_PROVIDER_URL` is already "claimed" by Microsoft or simply isn't needed for the built-in Google module. +1. **Microsoft** is registered as the built-in Microsoft provider from `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET` and `MICROSOFT_CLIENT_TENANT_ID`, with its own tenant discovery URL. `OPENID_PROVIDER_URL` registers nothing here, because the generic OIDC provider also needs `OAUTH_CLIENT_ID`. +2. **Google** is registered as the built-in Google provider whenever `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are set, regardless of any other provider. 3. **Account Merging**: Since both providers return the user's email, `OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true` ensures the user logs into the same profile whether they click "Sign in with Google" or "Sign in with Microsoft." ## Troubleshooting -- **Redirect Mismatch**: Ensure your Redirect URIs in both consoles match your `WEBUI_URL`. +- **Redirect Mismatch**: Ensure the Redirect URIs in both consoles match `MICROSOFT_REDIRECT_URI` and `GOOGLE_REDIRECT_URI` if set, or otherwise the URL Open WebUI is reached at, since the callback URL is built from the incoming request; `WEBUI_URL` does not set the callback URL, only where the browser lands after sign-in. - **Merge Failures**: Double-check that `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` is set to `true`. -- **Microsoft Logout**: Microsoft often requires the `OPENID_PROVIDER_URL` to handle the logout redirect correctly. If logout fails, ensure this URL is correct for your tenant. +- **Microsoft Logout**: Sign-out discovers the end-session endpoint from the provider the session logged in with, so a Microsoft session logs out without `OPENID_PROVIDER_URL`; `OPENID_END_SESSION_ENDPOINT` overrides it if set. - **Azure AD Refresh Token Failures (`AADSTS90009`)**: If token refresh fails with the error "Application is requesting a token for itself", set `OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE=true`. Azure AD requires the scope to be explicitly included in refresh token requests. You may also need to set `MICROSOFT_OAUTH_SCOPE` to include `offline_access` and any custom API scopes. diff --git a/docs/tutorials/auth-sso/entra-group-name-sync.md b/docs/tutorials/auth-sso/entra-group-name-sync.md index 2879e2c122..52a1567483 100644 --- a/docs/tutorials/auth-sso/entra-group-name-sync.md +++ b/docs/tutorials/auth-sso/entra-group-name-sync.md @@ -152,14 +152,11 @@ 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 +OAUTH_GROUPS_CLAIM=groups ENABLE_OAUTH_GROUP_MANAGEMENT=true ENABLE_OAUTH_GROUP_CREATION=true @@ -171,7 +168,7 @@ WEBUI_SECRET_KEY=your_secure_secret_key | Variable | Default | Description | | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `OAUTH_GROUP_CLAIM` | `groups` | The claim in the ID/access token containing the user's group memberships. | +| `OAUTH_GROUPS_CLAIM` | `groups` | The claim in the ID/access token containing the user's group memberships (`OAUTH_GROUP_CLAIM` is still read as a fallback). | | `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. | @@ -180,7 +177,7 @@ WEBUI_SECRET_KEY=your_secure_secret_key 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. +- 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. If the claim is missing or empty, no memberships are touched, and groups matching `OAUTH_BLOCKED_GROUPS` are never added or removed. ::: @@ -189,12 +186,12 @@ When `ENABLE_OAUTH_GROUP_MANAGEMENT` is set to `true`, a user's group membership 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. +2. **Log in as a test user**: admin and non-admin accounts are synced the same way since v0.8.11. 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. +Admin users' group memberships are synced exactly like other users' since v0.8.11, so an admin account works for testing. ::: diff --git a/docs/tutorials/auth-sso/okta-oidc-sso.md b/docs/tutorials/auth-sso/okta-oidc-sso.md index f3052c6312..4f0908ff55 100644 --- a/docs/tutorials/auth-sso/okta-oidc-sso.md +++ b/docs/tutorials/auth-sso/okta-oidc-sso.md @@ -134,7 +134,7 @@ OAUTH_PROVIDER_NAME="Okta" # The claim name in the ID token containing group information (must match Okta config) -# OAUTH_GROUP_CLAIM="groups" +# OAUTH_GROUPS_CLAIM="groups" # Optional: Enable Just-in-Time (JIT) creation of groups if they exist in Okta claims but not in Open WebUI. @@ -147,7 +147,7 @@ OAUTH_PROVIDER_NAME="Okta" 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 enable group synchronization based on Okta claims, set `ENABLE_OAUTH_GROUP_MANAGEMENT="true"` and ensure `OAUTH_GROUPS_CLAIM` (the older `OAUTH_GROUP_CLAIM` is still read as a fallback) 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. @@ -156,7 +156,7 @@ To *also* enable automatic Just-in-Time (JIT) creation of groups that exist in O 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. +* 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. If the claim is missing or empty, no memberships are touched, and groups matching `OAUTH_BLOCKED_GROUPS` are never added or removed. Ensure that all necessary groups are correctly configured and assigned within Okta and included in the group claim. @@ -205,13 +205,13 @@ 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 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. +4. If `ENABLE_OAUTH_GROUP_MANAGEMENT` is true, log in as a test 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. Admin users' groups are synced the same way since v0.8.11. 5. Check the Open WebUI server logs for any OIDC or group-related errors if you encounter issues. ## Troubleshooting * **400 Bad Request/Redirect URI Mismatch:** Double-check that the **Sign-in redirect URI** in your Okta application exactly matches `/oauth/oidc/callback`. -* **Groups Not Syncing:** Verify that the `OAUTH_GROUP_CLAIM` environment variable matches the claim name configured in the Okta ID Token settings. Ensure the user has logged out and back in after group changes - a login flow is required to update OIDC. Remember admin groups are not synced. +* **Groups Not Syncing:** Verify that the `OAUTH_GROUPS_CLAIM` environment variable matches the claim name configured in the Okta ID Token settings. Ensure the user has logged out and back in after group changes - a login flow is required to update OIDC. Admin groups are synced too since v0.8.11. * **Configuration Errors:** Review the Open WebUI server logs for detailed error messages related to OIDC configuration. * Refer to the official [Open WebUI SSO Documentation](/features/authentication-access/auth/sso). diff --git a/docs/tutorials/integrations/mcp-notion.mdx b/docs/tutorials/integrations/mcp-notion.mdx index 72165a9a8a..67a6059c97 100644 --- a/docs/tutorials/integrations/mcp-notion.mdx +++ b/docs/tutorials/integrations/mcp-notion.mdx @@ -38,7 +38,7 @@ Click **Register Client**, then **Save**. Use `OAuth 2.1 (Static)` if you have p
Alternative: Import JSON -You can also click **Import** in the modal and paste this configuration: +You can also save this configuration to a `.json` file and load it with **Import** in the modal, which opens a file chooser; you still need to click Register Client and Save afterwards: ```json [ diff --git a/docs/tutorials/integrations/onedrive-sharepoint.mdx b/docs/tutorials/integrations/onedrive-sharepoint.mdx index 8ecfcfc441..72ac4eb902 100644 --- a/docs/tutorials/integrations/onedrive-sharepoint.mdx +++ b/docs/tutorials/integrations/onedrive-sharepoint.mdx @@ -101,7 +101,7 @@ ONEDRIVE_SHAREPOINT_URL="https://your-tenant-name.sharepoint.com" :::info -After setting these variables and restarting Open WebUI, you must also enable the OneDrive toggle in the admin panel. See the Final Step section below for details. +After setting these variables and restarting Open WebUI, check the OneDrive toggle in the admin panel; see the Final Step section below. ::: @@ -140,7 +140,7 @@ ONEDRIVE_CLIENT_ID_PERSONAL="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz" ## Final Step: Enable OneDrive Integration in Admin Settings -After setting your environment variables and restarting your Open WebUI instance, you must explicitly enable the feature in the admin panel. **The environment variables alone do not activate the integration.** +After setting your environment variables and restarting your Open WebUI instance, check that the feature is enabled in the admin panel. On a fresh database `ENABLE_ONEDRIVE_INTEGRATION=true` seeds the toggle on; on a database that already holds the setting from an earlier start, the stored value wins over the environment variable and the toggle must be switched on here. 1. Navigate to **Settings → Admin → Documents**. 2. Toggle on the **"OneDrive"** switch. @@ -148,9 +148,9 @@ After setting your environment variables and restarting your Open WebUI instance :::warning -Admin Toggle is Required +Check the Admin Toggle -This step is mandatory even though you've set `ENABLE_ONEDRIVE_INTEGRATION=true` in your environment. Some configuration options in Open WebUI are persistent database settings that are initialized on first startup but must be activated through the admin interface. +This matters when `ENABLE_ONEDRIVE_INTEGRATION=true` was added after the first start: the toggle is a persistent database setting that the environment variable seeds only once, so a value stored by an earlier start is what applies until you change it here. :::