Merge pull request #581 from jackthgu/features/sso/keycloak

feat(docs): add keycloak sso documentation and images, Ldap group env setting

docs/features/sso/keycloak.mdx

@@ -0,0 +1,151 @@
+---
+title: "OIDC SSO - Keycloak 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.
+:::
+
+This guide explains how to integrate Open WebUI with Keycloak for OIDC Single Sign-On (SSO).
+
+## 1. Environment Preparation and Port Change
+
+### Open WebUI Server Port
+- **Default Port**: `8080`
+
+### Keycloak Port Conflict Issue
+Keycloak also uses port `8080` by default, which causes a conflict. Change the Keycloak port to `9090`.
+
+```bash
+bin/kc.sh start-dev --http-port=9090
+```
+{/* TODO: Insert image of Keycloak port change console output */}
+
+## 2. Create a Keycloak Realm
+
+1.  Open your browser and go to `http://localhost:9090`. Create an administrator account.
+2.  Log in to the admin console at `http://localhost:9090/admin`.
+3.  From the realm dropdown at the top, click **Add realm**.
+4.  Enter `openwebui` as the **Realm name** and click **Create**.
+
+![create-realm](/images/features/auth/keycloak/create-realm.png)
+
+## 3. Create an OpenID Connect Client
+
+:::info
+Make sure you have selected the `openwebui` realm. The default is `master`.
+:::
+
+![select-realm](/images/features/auth/keycloak/select-realm.png)
+
+1.  Ensure the `openwebui` realm you just created is selected.
+2.  In the left menu, click **Clients** → **Create client**.
+3.  Set **Client ID** to `open-webui`.
+4.  Keep **Client protocol** as `openid-connect`.
+5.  Set **Access Type** to `confidential` and click **Save**.
+
+![access-setting-client](/images/features/auth/keycloak/access-setting-client.png)
+
+## 4. Enable Client Authentication and Get Credentials
+
+By default, Keycloak 26.x sets Client Authentication to "None", so it needs to be configured manually.
+
+1.  Go to **Clients** → **open-webui** → **Settings**.
+2.  Check the **Client Authenticator** dropdown.
+3.  Change "None" to **Client ID and secret** and click **Save**.
+4.  Click the **Advanced** tab.
+5.  In the **Client authentication** section, click **Reveal secret** and copy the secret.
+6.  Paste this secret into the `OAUTH_CLIENT_SECRET` variable in your `.env` file.
+
+{/* TODO: Insert image of Advanced tab Client Authenticator settings */}
+
+## 5. Create a Test User
+
+1.  In the left menu, go to **Users** → **Add user**.
+2.  Fill in the **Username**, **Email**, etc., and click **Save**.
+3.  Click on the newly created user, then go to the **Credentials** tab.
+4.  Enter a new password, uncheck **Temporary**, and click **Set Password**.
+    -   *Example: Username `testuser`, Password `Test1234!`*
+
+## 6. Configure Open WebUI .env
+
+Add or modify the following variables in your `.env` file.
+
+```env
+# Enable OAuth2/OIDC Login
+ENABLE_OAUTH_SIGNUP=true
+
+# Keycloak Client Information
+OAUTH_CLIENT_ID=open-webui
+OAUTH_CLIENT_SECRET=<YOUR_COPIED_SECRET>
+
+# OIDC Discovery Document URL
+OPENID_PROVIDER_URL=http://localhost:9090/realms/openwebui/.well-known/openid-configuration
+
+# (Optional) SSO Button Label
+OAUTH_PROVIDER_NAME=Keycloak
+
+# (Optional) OAuth Callback URL
+OPENID_REDIRECT_URI=http://localhost:8080/oauth/oidc/callback
+```
+**Restart the Open WebUI server after modifying the `.env` file.**
+
+## 7. HTTP vs. HTTPS
+
+-   **HTTP (Development/Test)**:
+    -   Scheme: `http://`
+    -   Example: `http://localhost:9090`
+-   **HTTPS (Production Recommended)**:
+    -   Requires Keycloak TLS setup or a reverse proxy with SSL termination.
+    ```bash
+    bin/kc.sh start --https-port=9090 \
+      --https-key-store=keystore.jks \
+      --https-key-store-password=<password>
+    ```
+
+## 8. Test the Integration
+
+1.  Go to `http://localhost:8080`. You should see a "Continue with Keycloak" button.
+2.  Click the button. You should be redirected to the Keycloak login page.
+3.  Log in with `testuser` / `Test1234!`. You should be successfully redirected back to Open WebUI.
+
+{/* TODO: Insert image of the actual login screen */}
+
+## 9. Configure Keycloak Group Mapping
+
+### 9.1. Overview
+By default, Keycloak clients do not include group information in tokens. Follow these steps to pass group information.
+
+### 9.2. Locate Mapper Creation
+1.  Go to the Keycloak Admin Console: `http://localhost:9090/admin`.
+2.  Select the `openwebui` realm.
+3.  Navigate to **Clients** and select the `open-webui` client.
+4.  Go to the **Client scopes** tab.
+5.  Select the scope that will contain the group information (e.g., `profile` or `open-webui-dedicated`).
+
+    ![scope-client](/images/features/auth/keycloak/scope-client.png)
+
+6.  In the selected scope's details, go to the **Mappers** tab.
+
+### 9.3. Create Mapper
+Click **Create** or **Add builtin** to start creating a new mapper.
+
+### 9.4. Mapper Settings
+Configure the mapper with the appropriate settings to include group membership.
+
+![mappers-setting-group-client](/images/features/auth/keycloak/mappers-setting-group-client.png)
+
+### 9.5. Save and Apply
+-   **Save** the mapper configuration.
+-   **Restart** the Open WebUI server to apply the changes.
+
+### 9.6. Configure Open WebUI Environment Variables
+Add or modify these variables in your `.env` file:
+
+```env
+# Enable group synchronization
+ENABLE_OAUTH_GROUP_MANAGEMENT=true
+# (Optional) Enable Just-In-Time group creation
+ENABLE_OAUTH_GROUP_CREATION=true
+# The claim key for groups in the token
+OAUTH_GROUPS_CLAIM=groups

docs/getting-started/env-configuration.md

@@ -2879,6 +2879,27 @@ If `OAUTH_PICTURE_CLAIM` is set to `''` (empty string), then the OAuth picture c
 - Description: Sets the ciphers to use for LDAP connection.
 - Persistence: This environment variable is a `PersistentConfig` variable.
 
+#### `ENABLE_LDAP_GROUP_MANAGEMENT`
+
+- Type: `bool`
+- Default: `False`
+- Description: Enables the group management feature.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `ENABLE_LDAP_GROUP_CREATION`
+
+- Type: `bool`
+- Default: `False`
+- Description: If a group from LDAP does not exist in Open WebUI, it will be created automatically.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
+#### `LDAP_ATTRIBUTE_FOR_GROUPS`
+
+- Type: `str`
+- Default: `memberOf`
+- Description: Specifies the LDAP attribute that contains the user's group memberships. `memberOf` is a standard attribute for this purpose in Active Directory environments.
+- Persistence: This environment variable is a `PersistentConfig` variable.
+
 ## User Permissions
 
 ### Chat Permissions