khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-01-04 10:46:26 +07:00
Code Issues Packages Projects Releases Wiki Activity

chore: format

Browse Source
This commit is contained in:
silentoplayz
2025-10-05 23:29:50 -04:00
parent c4ada90210
commit 3e3da9e0a0
152 changed files with 2247 additions and 1677 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/features/auth/ldap.mdx
View File

@@ -15,7 +15,7 @@ The easiest way to get a test OpenLDAP server running is by using Docker. This `
version: "3.9"
services:
ldap:
image: osixia/openldap:1.5.0
image: osixia/openldap:1.5.0
container_name: openldap
environment:
LDAP_ORGANISATION: "Example Inc"
@@ -29,7 +29,7 @@ services:
- "389:389"
networks: [ldapnet]
phpldapadmin:
phpldapadmin:
image: osixia/phpldapadmin:0.9.0
environment:
PHPLDAPADMIN_LDAP_HOSTS: "ldap"
@@ -68,6 +68,7 @@ userPassword: {PLAIN}password123
**Note on Passwords:** The `userPassword` field is set to a plain text value for simplicity in this test environment. In production, you should always use a hashed password. You can generate a hashed password using `slappasswd` or `openssl passwd`. For example:
```bash
# Using slappasswd (inside the container)
docker exec openldap slappasswd -s your_password
@@ -105,10 +106,13 @@ Now, configure your Open WebUI instance to use the LDAP server for authenticatio
Set the following environment variables for your Open WebUI instance.
:::info
Open WebUI reads these environment variables only on the first startup. Subsequent changes must be made in the Admin settings panel of the UI unless you have `ENABLE_PERSISTENT_CONFIG=false`.
:::
```env
# Enable LDAP
ENABLE_LDAP="true"
@@ -134,11 +138,11 @@ LDAP_SEARCH_FILTER="(uid=%(user)s)" # More secure and performant
Alternatively, you can configure these settings directly in the UI:
1. Log in as an administrator.
2. Navigate to **Settings** > **General**.
3. Enable **LDAP Authentication**.
4. Fill in the fields corresponding to the environment variables above.
5. Save the settings and restart Open WebUI.
1. Log in as an administrator.
2. Navigate to **Settings** > **General**.
3. Enable **LDAP Authentication**.
4. Fill in the fields corresponding to the environment variables above.
5. Save the settings and restart Open WebUI.
## 5. Logging In
@@ -187,15 +191,15 @@ openldap | ... conn=1001 op=0 RESULT tag=97 err=49 text=
**Cause:** The LDAP server rejected the bind attempt because the distinguished name (DN) or the password was incorrect. This happens during the second bind attempt, where Open WebUI tries to authenticate with the user's provided credentials.
**Solution:**
1. **Verify the Password:** Ensure you are using the correct plaintext password. The `userPassword` value in the LDIF file is what the server expects. If it's a hash, you must provide the original plaintext password.
2. **Check the User DN:** The DN used for the bind (`uid=jdoe,ou=users,dc=example,dc=org`) must be correct.
3. **Test with `ldapwhoami`:** Verify the credentials directly against the LDAP server to isolate the issue from Open WebUI.
1. **Verify the Password:** Ensure you are using the correct plaintext password. The `userPassword` value in the LDIF file is what the server expects. If it's a hash, you must provide the original plaintext password.
2. **Check the User DN:** The DN used for the bind (`uid=jdoe,ou=users,dc=example,dc=org`) must be correct.
3. **Test with `ldapwhoami`:** Verify the credentials directly against the LDAP server to isolate the issue from Open WebUI.
```bash
ldapwhoami -x -H ldap://localhost:389 \
-D "uid=jdoe,ou=users,dc=example,dc=org" -w "password123"
```
If this command fails with `ldap_bind: Invalid credentials (49)`, the problem is with the credentials or the LDAP server's password configuration, not Open WebUI.
4. **Reset the Password:** If you don't know the password, reset it using `ldapmodify` or `ldappasswd`. It's often easiest to use a `{PLAIN}` password for initial testing and then switch to a secure hash like `{SSHA}`.
4. **Reset the Password:** If you don't know the password, reset it using `ldapmodify` or `ldappasswd`. It's often easiest to use a `{PLAIN}` password for initial testing and then switch to a secure hash like `{SSHA}`.
**Example LDIF to change password:**
```ldif title="change_password.ldif"

8
docs/features/auth/scim.mdx
View File

@@ -26,17 +26,21 @@ Configure SCIM by setting these environment variables:
- **`SCIM_ENABLED`**: Set to `true` to enable SCIM support (default: `false`)
- **`SCIM_TOKEN`**: The bearer token for SCIM authentication (required when SCIM is enabled)
:::warning Security Note
:::warning
Security Note
The SCIM token should be a secure, randomly generated string. You can generate one using:
```bash
openssl rand -base64 32
```
Keep this token secure as it provides access to user management operations.
:::
### Example Configuration
```bash
# Enable SCIM
export SCIM_ENABLED=true
@@ -60,7 +64,6 @@ When configuring your identity provider, use the following settings:
3. Set authentication to "HTTP Header"
4. Add Authorization header with value: `Bearer your-scim-token`
## Supported SCIM Operations
Open WebUI's SCIM implementation supports the following operations:
@@ -137,6 +140,7 @@ Supported filter operators:
You can test SCIM endpoints using curl:
```bash
# Test authentication and list users
curl -H "Authorization: Bearer your-scim-token" \
https://your-domain.com/api/v1/scim/v2/Users

40
docs/features/auth/sso/index.mdx
View File

@@ -28,17 +28,17 @@ You cannot have Microsoft **and** Google as providers simultaneously.
| Environment Variable | Default | Description |
|---------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `WEBUI_URL` | — | **Required.** Your public WebUI address, e.g., `http://localhost:8080`. |
| `ENABLE_OAUTH_PERSISTENT_CONFIG` | `true` | Persist OAuth config to the database; set to `false` for stateless/containerized environments. |
| `ENABLE_OAUTH_SIGNUP` | `false` | Allows account creation upon OAuth login (separate from `ENABLE_SIGNUP`). |
| `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` | `false` | Merge OAuth logins based on matching email (caution: can be insecure if provider doesn't verify emails). |
| `OAUTH_UPDATE_PICTURE_ON_LOGIN` | `true` | Update user profile pictures from OAuth provider with each login. |
| `WEBUI_URL` | — | **Required.** Your public WebUI address, e.g., `http://localhost:8080`. |
| `ENABLE_OAUTH_PERSISTENT_CONFIG` | `true` | Persist OAuth config to the database; set to `false` for stateless/containerized environments. |
| `ENABLE_OAUTH_SIGNUP` | `false` | Allows account creation upon OAuth login (separate from `ENABLE_SIGNUP`). |
| `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` | `false` | Merge OAuth logins based on matching email (caution: can be insecure if provider doesn't verify emails). |
| `OAUTH_UPDATE_PICTURE_ON_LOGIN` | `true` | Update user profile pictures from OAuth provider with each login. |
| `OAUTH_PICTURE_CLAIM` | `picture` | Field in the claim containing the profile picture. Set to empty string to disable picture updates (users receive default icon).|
| `WEBUI_AUTH_SIGNOUT_REDIRECT_URL` | *empty* | Redirect users to this URL after signout. E.g., `https://your-company.com/logout-success` |
| `WEBUI_SECRET_KEY` | *empty* | MUST be set - especially in clustered environments. Otherwise session issues and weird OAuth issues will occur |
| `OAUTH_SESSION_TOKEN_ENCRYPTION_KEY` | `WEBUI_SECRET_KEY` | A secret key for encrypting OAuth tokens stored on the server. Must be shared across all instances in a cluster. |
| `OAUTH_SESSION_TOKEN_ENCRYPTION_KEY` | `WEBUI_SECRET_KEY` | A secret key for encrypting OAuth tokens stored on the server. Must be shared across all instances in a cluster. |
| `OAUTH_CLIENT_INFO_ENCRYPTION_KEY` | `WEBUI_SECRET_KEY` | A secret key for encrypting OAuth client information stored on the server - used for OAuth 2.1 authentication for MCP servers. |
| `ENABLE_OAUTH_ID_TOKEN_COOKIE` | `true` | For backward compatibility. Controls if the legacy `oauth_id_token` cookie is set. Recommended to set to `false`. |
| `ENABLE_OAUTH_ID_TOKEN_COOKIE` | `true` | For backward compatibility. Controls if the legacy `oauth_id_token` cookie is set. Recommended to set to `false`. |
:::warning
@@ -60,10 +60,10 @@ To solve issues related to large tokens (e.g., with AD FS group claims exceeding
**How It Works:**
1. **Server-Side Storage:** Instead of storing large `access_token` and `id_token` values in browser cookies, the entire token payload is now encrypted and stored securely in the Open WebUI database in a new `oauth_session` table.
2. **Secure Session Cookie:** The user's browser is sent a single, small, and secure `httponly` cookie named `oauth_session_id`. This cookie acts as an opaque identifier, containing no sensitive information itself.
3. **Automatic Refresh:** When a token is required by a downstream service (like a tool or an OpenAI-compatible endpoint), the backend uses the `oauth_session_id` to retrieve the tokens. If the tokens are expired or close to expiring, the system automatically uses the stored `refresh_token` to fetch new ones from the provider before forwarding them. This ensures services always receive a valid token and prevents silent failures.
4. **Clean Token Access:** This architecture provides a clean and reliable way for internal tools and other services to access user tokens without fragile cookie-scraping.
1. **Server-Side Storage:** Instead of storing large `access_token` and `id_token` values in browser cookies, the entire token payload is now encrypted and stored securely in the Open WebUI database in a new `oauth_session` table.
2. **Secure Session Cookie:** The user's browser is sent a single, small, and secure `httponly` cookie named `oauth_session_id`. This cookie acts as an opaque identifier, containing no sensitive information itself.
3. **Automatic Refresh:** When a token is required by a downstream service (like a tool or an OpenAI-compatible endpoint), the backend uses the `oauth_session_id` to retrieve the tokens. If the tokens are expired or close to expiring, the system automatically uses the stored `refresh_token` to fetch new ones from the provider before forwarding them. This ensures services always receive a valid token and prevents silent failures.
4. **Clean Token Access:** This architecture provides a clean and reliable way for internal tools and other services to access user tokens without fragile cookie-scraping.
This system is enabled by default but can be fine-tuned with the environment variables detailed above.
@@ -156,20 +156,28 @@ You can configure the following environment variables:
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
:::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`).
:::
:::warning Admin Users
:::warning
Admin Users
Admin users' group memberships are **not** automatically updated via OAuth group management.
:::
:::info Login Required for Updates
:::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.
@@ -193,10 +201,9 @@ When the `WEBUI_AUTH_TRUSTED_EMAIL_HEADER` environment variable is set, Open Web
For example, setting `WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email` and passing a HTTP header of `X-User-Email: example@example.com` would authenticate the request with the email `example@example.com`.
Optionally, you can also define the `WEBUI_AUTH_TRUSTED_NAME_HEADER` to determine the name of any user being created using trusted headers. This has no effect if the user already exists.
Optionally, you can also define the `WEBUI_AUTH_TRUSTED_NAME_HEADER` to determine the name of any user being created using trusted headers. This has no effect if the user already exists.
If `WEBUI_AUTH_TRUSTED_NAME_HEADER` is not set, the email address is used as user name.
#### Group Management
You can use the `WEBUI_AUTH_TRUSTED_GROUPS_HEADER` environment variable to synchronize user groups in Open WebUI. Set this variable to the name of the HTTP header that will contain a comma-separated list of group names for the authenticated user.
@@ -344,7 +351,6 @@ services:
- 4180:4180/tcp
```
### Authentik
To configure a [Authentik](https://goauthentik.io/) OAuth client, please refer to [documentation](https://integrations.goauthentik.io/miscellaneous/open-webui/) on how to create an application and `OAuth2/OpenID Provider`.

64
docs/features/auth/sso/keycloak.mdx
View File

@@ -3,7 +3,9 @@ title: "🔑 Keycloak"
---
:::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).
@@ -23,26 +25,28 @@ bin/kc.sh start-dev --http-port=9090
## 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**.
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**.
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)
@@ -50,21 +54,21 @@ Make sure you have selected the `openwebui` realm. The default is `master`.
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.
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**.
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
@@ -72,6 +76,7 @@ By default, Keycloak 26.x sets Client Authentication to "None", so it needs to b
Add or modify the following variables in your `.env` file.
```env
# Enable OAuth2/OIDC Login
ENABLE_OAUTH_SIGNUP=true
@@ -105,9 +110,9 @@ OPENID_REDIRECT_URI=http://localhost:8080/oauth/oidc/callback
## 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.
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 */}
@@ -117,15 +122,15 @@ OPENID_REDIRECT_URI=http://localhost:8080/oauth/oidc/callback
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`).
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.
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.
@@ -143,9 +148,12 @@ Configure the mapper with the appropriate settings to include group membership.
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_GROUP_CLAIM=groups