From 5106fee3a570bf92ab16067efcfe4b48049c4231 Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Mon, 7 Apr 2025 15:24:18 -0400 Subject: [PATCH 1/7] Add Okta SSO Integration documentation --- docs/tutorials/integrations/okta-oidc-sso.md | 104 +++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 docs/tutorials/integrations/okta-oidc-sso.md diff --git a/docs/tutorials/integrations/okta-oidc-sso.md b/docs/tutorials/integrations/okta-oidc-sso.md new file mode 100644 index 0000000..23d3f27 --- /dev/null +++ b/docs/tutorials/integrations/okta-oidc-sso.md @@ -0,0 +1,104 @@ +--- +sidebar_position: 40 +title: "🔗 Okta OIDC SSO Integration" +--- + +:::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. +::: + +# 🔗 Okta OIDC SSO Integration + +## Overview + +This documentation page outlines the steps required to integrate Okta OIDC Single Sign-On (SSO) with Open WebUI, including support for managing 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 and automatically assign them to relevant groups within Open WebUI. + +### Prerequisites + +* A valid Open WebUI instance. +* An Okta account with administrative privileges to create and configure applications. +* Basic understanding of OIDC, Okta application configuration, and Open WebUI environment variables. + +## Setting up Okta + +First, you need to configure an OIDC application within your Okta organization and set up a groups claim to pass group information to Open WebUI. + +### 1. Create/Configure OIDC Application in Okta + +1. Log in to your Okta Admin Console. +2. Navigate to **Applications > Applications**. +3. Either create a new **OIDC - OpenID Connect** application (choose **Web Application** as the type) or select an existing one you wish to use for Open WebUI. +4. During setup or in the application's **General** settings tab, configure the **Sign-in redirect URIs**. Add the URI for your Open WebUI instance, followed by `/oauth/oidc/callback`. For example: `https://your-open-webui.com/oauth/oidc/callback`. +5. Take note of the **Client ID** and **Client secret** provided on the application's **General** tab. You will need these for the Open WebUI configuration. +6. Ensure the correct users or groups are assigned to this application under the **Assignments** tab. + +### 2. Add a Groups Claim to the ID Token + +To enable group management in Open WebUI, you need to configure Okta to send the user's group memberships in the ID token. + +1. In the Admin Console, go to **Applications > Applications** and select your OIDC client app. +2. Go to the **Sign On** tab and click **Edit** in the **OpenID Connect ID Token** section. +3. In the **Group claim type** section, select **Filter**. +4. In the **Group claims filter** section: + * Enter `groups` as the claim name (or use the default if present). + * Select **Matches regex** from the dropdown. + * Enter `.*` in the regex field. This will include all groups the user is a member of. You can use a more specific regex if needed. +5. Click **Save**. +6. Click the **Back to applications** link. +7. From the **More** button dropdown menu for your application, click **Refresh Application Data**. + +*For more advanced group claim configurations, refer to the Okta documentation on [customizing tokens](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/) and [group functions](https://developer.okta.com/docs/reference/okta-expression-language/#group-functions).* + +## Configuring Open WebUI + +To enable Okta OIDC SSO and group management in Open WebUI, you need to set the following environment variables for your Open WebUI instance: + +```bash +# --- OIDC Core Settings --- +# Enable OAuth signup if you want users to be able to create accounts via Okta +# ENABLE_OAUTH_SIGNUP="true" + +# Your Okta application's Client ID +OAUTH_CLIENT_ID="YOUR_OKTA_CLIENT_ID" + +# Your Okta application's Client Secret +OAUTH_CLIENT_SECRET="YOUR_OKTA_CLIENT_SECRET" + +# Your Okta organization's OIDC discovery URL +# Format: https:///.well-known/openid-configuration +# Or for a specific authorization server: https:///oauth2//.well-known/openid-configuration +OPENID_PROVIDER_URL="YOUR_OKTA_OIDC_DISCOVERY_URL" + +# Name displayed on the login button (e.g., "Login with Okta") +OAUTH_PROVIDER_NAME="Okta" + +# Scopes to request (default is usually sufficient) +# OAUTH_SCOPES="openid email profile groups" # Ensure 'groups' is included if not default + +# --- OAuth Group Management --- +# Enable group management feature +ENABLE_OAUTH_GROUP_MANAGEMENT="true" + +# The claim name in the ID token containing group information (must match Okta config) +OAUTH_GROUP_CLAIM="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. Ensure `OAUTH_GROUP_CLAIM` matches the claim name you configured in Okta (default is `groups`). + +Restart your Open WebUI instance after setting these environment variables. + +## Verification + +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. +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 logged out and back in after group changes. Remember admin groups are not synced. +* **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/sso.md). +* Consult the [Okta Developer Documentation](https://developer.okta.com/docs/). \ No newline at end of file From 6b7392c1480c63db707d30a510680f52e55069dd Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Mon, 7 Apr 2025 15:27:44 -0400 Subject: [PATCH 2/7] Add warning about login form env var --- docs/tutorials/integrations/okta-oidc-sso.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/integrations/okta-oidc-sso.md b/docs/tutorials/integrations/okta-oidc-sso.md index 23d3f27..eb90bec 100644 --- a/docs/tutorials/integrations/okta-oidc-sso.md +++ b/docs/tutorials/integrations/okta-oidc-sso.md @@ -85,6 +85,18 @@ OAUTH_GROUP_CLAIM="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. Ensure `OAUTH_GROUP_CLAIM` matches the claim name you configured in Okta (default is `groups`). +:::tip Disabling the Standard Login Form + +If you intend to *only* allow logins via Okta (and potentially other configured OAuth providers), you can disable the standard email/password login form by setting the following environment variable: + +```bash +ENABLE_LOGIN_FORM="false" +``` + +:::danger Important Prerequisite +Setting `ENABLE_LOGIN_FORM="false"` **requires** `ENABLE_OAUTH_SIGNUP="true"` to be set as well. If you disable the login form without enabling OAuth signup, **users (including administrators) will be unable to log in.** Ensure at least one OAuth provider is configured and `ENABLE_OAUTH_SIGNUP` is enabled before disabling the standard login form. +::: + Restart your Open WebUI instance after setting these environment variables. ## Verification @@ -98,7 +110,7 @@ Restart your Open WebUI instance after setting these environment variables. ## 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 logged out and back in after group changes. Remember admin groups are not synced. +* **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. * **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/sso.md). * Consult the [Okta Developer Documentation](https://developer.okta.com/docs/). \ No newline at end of file From c5a2cbf91a71681d4116f0a8e4a40ae338167566 Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Mon, 7 Apr 2025 15:28:12 -0400 Subject: [PATCH 3/7] update verbiage --- docs/tutorials/integrations/okta-oidc-sso.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/integrations/okta-oidc-sso.md b/docs/tutorials/integrations/okta-oidc-sso.md index eb90bec..fb64949 100644 --- a/docs/tutorials/integrations/okta-oidc-sso.md +++ b/docs/tutorials/integrations/okta-oidc-sso.md @@ -15,7 +15,7 @@ This documentation page outlines the steps required to integrate Okta OIDC Singl ### Prerequisites -* A valid Open WebUI instance. +* A new or existing Open WebUI instance. * An Okta account with administrative privileges to create and configure applications. * Basic understanding of OIDC, Okta application configuration, and Open WebUI environment variables. @@ -28,7 +28,7 @@ First, you need to configure an OIDC application within your Okta organization a 1. Log in to your Okta Admin Console. 2. Navigate to **Applications > Applications**. 3. Either create a new **OIDC - OpenID Connect** application (choose **Web Application** as the type) or select an existing one you wish to use for Open WebUI. -4. During setup or in the application's **General** settings tab, configure the **Sign-in redirect URIs**. Add the URI for your Open WebUI instance, followed by `/oauth/oidc/callback`. For example: `https://your-open-webui.com/oauth/oidc/callback`. +4. During setup or in the application's **General** settings tab, configure the **Sign-in redirect URIs**. Add the URI for your Open WebUI instance, followed by `/oauth/oidc/callback`. Example: `https://your-open-webui.com/oauth/oidc/callback`. 5. Take note of the **Client ID** and **Client secret** provided on the application's **General** tab. You will need these for the Open WebUI configuration. 6. Ensure the correct users or groups are assigned to this application under the **Assignments** tab. From a9aba99167261f7697da523bb2ea8b0e69d56b10 Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Mon, 7 Apr 2025 15:29:06 -0400 Subject: [PATCH 4/7] clarify optional groups & native group management --- docs/tutorials/integrations/okta-oidc-sso.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/tutorials/integrations/okta-oidc-sso.md b/docs/tutorials/integrations/okta-oidc-sso.md index fb64949..ed8eb37 100644 --- a/docs/tutorials/integrations/okta-oidc-sso.md +++ b/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, including support for managing 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 and automatically assign them to relevant groups within Open WebUI. +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. ### Prerequisites @@ -34,7 +34,7 @@ First, you need to configure an OIDC application within your Okta organization a ### 2. Add a Groups Claim to the ID Token -To enable group management in Open WebUI, you need to configure Okta to send the user's group memberships in the ID token. +**(Optional)** To enable automatic group management in Open WebUI based on Okta groups, you need to configure Okta to send the user's group memberships in the ID token. If you only need SSO login and prefer to manage groups manually within Open WebUI, you can skip this section. 1. In the Admin Console, go to **Applications > Applications** and select your OIDC client app. 2. Go to the **Sign On** tab and click **Edit** in the **OpenID Connect ID Token** section. @@ -51,7 +51,7 @@ To enable group management in Open WebUI, you need to configure Okta to send the ## Configuring Open WebUI -To enable Okta OIDC SSO and group management in Open WebUI, you need to set the following environment variables for your Open WebUI instance: +To enable Okta OIDC SSO in Open WebUI, you need to set the following core environment variables. Additional variables are required if you wish to enable the optional group management feature. ```bash # --- OIDC Core Settings --- @@ -75,15 +75,17 @@ OAUTH_PROVIDER_NAME="Okta" # Scopes to request (default is usually sufficient) # OAUTH_SCOPES="openid email profile groups" # Ensure 'groups' is included if not default -# --- OAuth Group Management --- -# Enable group management feature -ENABLE_OAUTH_GROUP_MANAGEMENT="true" +# --- 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. +# 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" +# OAUTH_GROUP_CLAIM="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. 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, ensure `OAUTH_GROUP_CLAIM` matches the claim name you configured in Okta (default is `groups`). :::tip Disabling the Standard Login Form From c3cd50e0e6044a2e62ab630dd134af958fdaf319 Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Mon, 7 Apr 2025 15:31:25 -0400 Subject: [PATCH 5/7] Add secret key info for transparent sessions across multiple nodes --- docs/tutorials/integrations/okta-oidc-sso.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/tutorials/integrations/okta-oidc-sso.md b/docs/tutorials/integrations/okta-oidc-sso.md index ed8eb37..6a3c9ec 100644 --- a/docs/tutorials/integrations/okta-oidc-sso.md +++ b/docs/tutorials/integrations/okta-oidc-sso.md @@ -87,6 +87,18 @@ 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. If enabling group management, ensure `OAUTH_GROUP_CLAIM` matches the claim name you configured in Okta (default is `groups`). +:::info Session Persistence in Multi-Node Deployments + +When deploying Open WebUI across multiple nodes (e.g., in a Kubernetes cluster or behind a load balancer), it is crucial to ensure session persistence for a seamless user experience, especially with SSO. Set the `WEBUI_SECRET_KEY` environment variable to the **same secure, unique value** on **all** Open WebUI instances. + +```bash +# Example: Generate a strong secret key (e.g., using openssl rand -hex 32) +WEBUI_SECRET_KEY="YOUR_UNIQUE_AND_SECURE_SECRET_KEY" +``` + +If this key is not consistent across all nodes, users may be forced to log in again if their session is routed to a different node, as the session token signed by one node will not be valid on another. By default, the Docker image generates a random key on first start, which is unsuitable for multi-node setups. +::: + :::tip Disabling the Standard Login Form If you intend to *only* allow logins via Okta (and potentially other configured OAuth providers), you can disable the standard email/password login form by setting the following environment variable: From 9930a0caf6e70990f64abc796a8574f44895ed6b Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Mon, 7 Apr 2025 15:36:43 -0400 Subject: [PATCH 6/7] fix admonition block closing --- docs/tutorials/integrations/okta-oidc-sso.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tutorials/integrations/okta-oidc-sso.md b/docs/tutorials/integrations/okta-oidc-sso.md index 6a3c9ec..258993c 100644 --- a/docs/tutorials/integrations/okta-oidc-sso.md +++ b/docs/tutorials/integrations/okta-oidc-sso.md @@ -102,6 +102,8 @@ If this key is not consistent across all nodes, users may be forced to log in ag :::tip Disabling the Standard Login Form If you intend to *only* allow logins via Okta (and potentially other configured OAuth providers), you can disable the standard email/password login form by setting the following environment variable: +::: + ```bash ENABLE_LOGIN_FORM="false" From df5e819472b5c8f762762f051b1c447a01a31fee Mon Sep 17 00:00:00 2001 From: Taylor Wilsdon Date: Mon, 7 Apr 2025 15:39:14 -0400 Subject: [PATCH 7/7] fix last block close --- docs/tutorials/integrations/okta-oidc-sso.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/integrations/okta-oidc-sso.md b/docs/tutorials/integrations/okta-oidc-sso.md index 258993c..64c641a 100644 --- a/docs/tutorials/integrations/okta-oidc-sso.md +++ b/docs/tutorials/integrations/okta-oidc-sso.md @@ -90,6 +90,7 @@ Replace `YOUR_OKTA_CLIENT_ID`, `YOUR_OKTA_CLIENT_SECRET`, and `YOUR_OKTA_OIDC_DI :::info Session Persistence in Multi-Node Deployments When deploying Open WebUI across multiple nodes (e.g., in a Kubernetes cluster or behind a load balancer), it is crucial to ensure session persistence for a seamless user experience, especially with SSO. Set the `WEBUI_SECRET_KEY` environment variable to the **same secure, unique value** on **all** Open WebUI instances. +::: ```bash # Example: Generate a strong secret key (e.g., using openssl rand -hex 32) @@ -97,7 +98,6 @@ WEBUI_SECRET_KEY="YOUR_UNIQUE_AND_SECURE_SECRET_KEY" ``` If this key is not consistent across all nodes, users may be forced to log in again if their session is routed to a different node, as the session token signed by one node will not be valid on another. By default, the Docker image generates a random key on first start, which is unsuitable for multi-node setups. -::: :::tip Disabling the Standard Login Form