diff --git a/docs/features/sso.md b/docs/features/sso/index.mdx similarity index 100% rename from docs/features/sso.md rename to docs/features/sso/index.mdx diff --git a/docs/features/sso/keycloak.mdx b/docs/features/sso/keycloak.mdx new file mode 100644 index 0000000..1225251 --- /dev/null +++ b/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= + +# 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= + ``` + +## 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 diff --git a/docs/getting-started/env-configuration.md b/docs/getting-started/env-configuration.md index 9bf6c94..beef916 100644 --- a/docs/getting-started/env-configuration.md +++ b/docs/getting-started/env-configuration.md @@ -2844,6 +2844,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 diff --git a/static/images/features/auth/keycloak/access-setting-client.png b/static/images/features/auth/keycloak/access-setting-client.png new file mode 100644 index 0000000..b319c4c Binary files /dev/null and b/static/images/features/auth/keycloak/access-setting-client.png differ diff --git a/static/images/features/auth/keycloak/create-realm.png b/static/images/features/auth/keycloak/create-realm.png new file mode 100644 index 0000000..f2e76a0 Binary files /dev/null and b/static/images/features/auth/keycloak/create-realm.png differ diff --git a/static/images/features/auth/keycloak/mappers-setting-group-client.png b/static/images/features/auth/keycloak/mappers-setting-group-client.png new file mode 100644 index 0000000..302a1e1 Binary files /dev/null and b/static/images/features/auth/keycloak/mappers-setting-group-client.png differ diff --git a/static/images/features/auth/keycloak/scope-client.png b/static/images/features/auth/keycloak/scope-client.png new file mode 100644 index 0000000..452f0e9 Binary files /dev/null and b/static/images/features/auth/keycloak/scope-client.png differ diff --git a/static/images/features/auth/keycloak/select-realm.png b/static/images/features/auth/keycloak/select-realm.png new file mode 100644 index 0000000..fccea1b Binary files /dev/null and b/static/images/features/auth/keycloak/select-realm.png differ