khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-01-02 17:59:41 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #688 from open-webui/dev

Browse Source 
Docs Update: 0.6.27 changes and more
This commit is contained in:
Classic298
2025-09-09 17:02:03 +02:00
committed by GitHub
parent e5716d0262 30deecd530
commit 258ee79c75
4 changed files with 155 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/features/plugin/tools/development.mdx
View File

@@ -65,9 +65,52 @@ Below is a list of optional arguments your tools can depend on:
- `__messages__`: List of previous messages
- `__files__`: Attached files
- `__model__`: A dictionary with model information
- `__oauth_token__`: A dictionary containing the user's valid, automatically refreshed OAuth token payload. This is the **new, recommended, and secure** way to access user tokens for making authenticated API calls. The dictionary typically contains `access_token`, `id_token`, and other provider-specific data.
For more information about `__oauth_token__` and how to configure this token to be sent to tools, check out the OAuth section in the [environment variable docs page](https://docs.openwebui.com/getting-started/env-configuration/) and the [SSO documentation](https://docs.openwebui.com/features/sso/).
Just add them as argument to any method of your Tool class just like `__user__` in the example above.
#### Using the OAuth Token in a Tool
When building tools that need to interact with external APIs on the user's behalf, you can now directly access their OAuth token. This removes the need for fragile cookie scraping and ensures the token is always valid.
**Example:** A tool that calls an external API using the user's access token.
```python
import httpx
from typing import Optional
class Tools:
# ... other class setup ...
async def get_user_profile_from_external_api(self, __oauth_token__: Optional[dict] = None) -> str:
"""
Fetches user profile data from a secure external API using their OAuth access token.
:param __oauth_token__: Injected by Open WebUI, contains the user's token data.
"""
if not __oauth_token__ or "access_token" not in __oauth_token__:
return "Error: User is not authenticated via OAuth or token is unavailable."
access_token = __oauth_token__["access_token"]
headers = {
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json"
}
try:
async with httpx.AsyncClient() as client:
response = await client.get("https://api.my-service.com/v1/profile", headers=headers)
response.raise_for_status() # Raise an exception for bad status codes
return f"API Response: {response.json()}"
except httpx.HTTPStatusError as e:
return f"Error: Failed to fetch data from API. Status: {e.response.status_code}"
except Exception as e:
return f"An unexpected error occurred: {e}"
```
### Event Emitters
Event Emitters are used to add additional information to the chat interface. Similarly to Filter Outlets, Event Emitters are capable of appending content to the chat. Unlike Filter Outlets, they are not capable of stripping information. Additionally, emitters can be activated at any stage during the Tool.

19
docs/features/sso/index.mdx
View File

@@ -38,7 +38,24 @@ You cannot have Microsoft **and** Google as providers simultaneously.
| `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_URI` | *empty* | Redirect users to this URL after signout. E.g., `https://your-company.com/logout-success` |
| `WEBUI_AUTH_SIGNOUT_REDIRECT_URL` | *empty* | Redirect users to this URL after signout. E.g., `https://your-company.com/logout-success` |
| `OAUTH_SESSION_TOKEN_ENCRYPTION_KEY` | `WEBUI_SECRET_KEY` | **Required.** A secret key for encrypting OAuth tokens stored on the server. Must be shared across all instances in a cluster. |
| `ENABLE_OAUTH_ID_TOKEN_COOKIE` | `true` | For backward compatibility. Controls if the legacy `oauth_id_token` cookie is set. Recommended to set to `false`. |
### Server-Side OAuth Session Management
To solve issues related to large tokens (e.g., with AD FS group claims exceeding cookie size limits) and to enable automatic token refreshing, Open WebUI now supports a robust server-side session management system.
**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.
This system is enabled by default but can be fine-tuned with the environment variables detailed above.
For more information, check out the [environment variable docs page](https://docs.openwebui.com/getting-started/env-configuration/).
### Google

89
docs/getting-started/env-configuration.md
View File

@@ -1342,6 +1342,18 @@ pip install open-webui[all]
- Default: `1536`
- Description: Specifies the maximum vector length for PGVector initialization.
#### `PGVECTOR_CREATE_EXTENSION`
- Type: `str`
- Default `true`
- Description: Creates the vector extension in the database
:::info
If set to `false`, open-webui will assume the postgreSQL database where embeddings will be stored is pre-configured with the `vector` extension. This also allows open-webui to run as a non superuser database user.
:::
### Qdrant
#### `QDRANT_API_KEY`
@@ -2745,6 +2757,13 @@ Strictly return in JSON format:
- Description: Sets the OpenAI-compatible base URL to use for DALL-E image generation.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `IMAGES_OPENAI_API_VERSION`
- Type: `str`
- Default: `${OPENAI_API_VERSION}`
- Description: Optional setting. If provided it sets the `api-version` query parameter when calling the image generation. If the Azure OpenAI service is used, this needs to be configured.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `IMAGES_OPENAI_API_KEY`
- Type: `str`
@@ -2813,6 +2832,26 @@ If the OAuth picture claim is disabled by setting `OAUTH_PICTURE_CLAIM` to `''`
:::
#### `ENABLE_OAUTH_ID_TOKEN_COOKIE`
- Type: `bool`
- Default: `True`
- Description: Controls whether the **legacy** `oauth_id_token` cookie (unsafe, not recommended, token can go stale/orphaned) is set in the browser upon a successful OAuth login. This is provided for **backward compatibility** with custom tools or older versions that might rely on scraping this cookie. **The new, recommended approach is to use the server-side session management.**
- Usage: For new and secure deployments, **it is recommended to set this to `False`** to minimize the information exposed to the client-side. Keep it as `True` only if you have integrations that depend on the old cookie-based method.
#### `OAUTH_SESSION_TOKEN_ENCRYPTION_KEY`
- Type: `str`
- Default: Falls back to the value of `WEBUI_SECRET_KEY`.
- Description: Specifies the secret key used to encrypt and decrypt OAuth tokens stored server-side in the database. This is a critical security component for protecting user credentials at rest. If not set, it defaults to using the main `WEBUI_SECRET_KEY`, but it is highly recommended to set it to a unique, securely generated value for production environments.
:::warning
**Required for Multi-Replica Deployments**
In any production environment running more than one instance of Open WebUI (e.g., Docker Swarm, Kubernetes), this variable **MUST** be explicitly set to a persistent, shared secret. If left unset, each replica will generate or use a different key, causing session decryption to fail intermittently as user requests are load-balanced across instances.
:::
#### `WEBUI_AUTH_TRUSTED_EMAIL_HEADER`
- Type: `str`
@@ -3656,7 +3695,7 @@ If the endpoint is an S3-compatible provider like MinIO that uses a TLS certific
- Type: `str`
- Default: `sqlite:///${DATA_DIR}/webui.db`
- Description: Specifies the database URL to connect to.
- Description: Specifies the complete database connection URL, following SQLAlchemy's URL scheme. This variable takes precedence over individual database connection parameters if explicitly set.
:::info
@@ -3668,10 +3707,56 @@ Documentation on the URL scheme is available [here](https://docs.sqlalchemy.org/
If your database password contains special characters, please ensure they are properly URL-encoded. For example, a password like `p@ssword` should be encoded as `p%40ssword`.
For encrypted SQLite, see the "SQLite with SQLCipher Encryption" section below for configuration details.
For configuration using individual parameters or encrypted SQLite, see the relevant sections below.
:::
#### `DATABASE_TYPE`
- Type: `str`
- Default: `None` (automatically set to `sqlite` if `DATABASE_URL` uses default SQLite path)
- Description: Specifies the database type (e.g., `sqlite`, `postgresql`, `mysql`, `sqlite+sqlcipher`). This is used in conjunction with other individual parameters to construct the `DATABASE_URL` if a complete `DATABASE_URL` is not explicitly defined.
- Persistence: No
#### `DATABASE_USER`
- Type: `str`
- Default: `None`
- Description: Specifies the username for database authentication. This is used to construct the `DATABASE_URL` when a complete `DATABASE_URL` is not explicitly defined.
- Persistence: No
#### `DATABASE_PASSWORD`
- Type: `str`
- Default: `None`
- Description: Specifies the password for database authentication. This is used to construct the `DATABASE_URL` when a complete `DATABASE_URL` is not explicitly defined. If your password contains special characters, please ensure they are properly URL-encoded.
- Persistence: No
#### `DATABASE_HOST`
- Type: `str`
- Default: `None`
- Description: Specifies the hostname or IP address of the database server. This is used to construct the `DATABASE_URL` when a complete `DATABASE_URL` is not explicitly defined.
- Persistence: No
#### `DATABASE_PORT`
- Type: `int`
- Default: `None`
- Description: Specifies the port number of the database server. This is used to construct the `DATABASE_URL` when a complete `DATABASE_URL` is not explicitly defined.
- Persistence: No
#### `DATABASE_NAME`
- Type: `str`
- Default: `None`
- Description: Specifies the name of the database to connect to. This is used to construct the `DATABASE_URL` when a complete `DATABASE_URL` is not explicitly defined.
- Persistence: No
:::info
When `DATABASE_URL` is not explicitly set, Open WebUI will attempt to construct it using a combination of `DATABASE_TYPE`, `DATABASE_USER`, `DATABASE_PASSWORD`, `DATABASE_HOST`, `DATABASE_PORT`, and `DATABASE_NAME`. For this automatic construction to occur, **all** of these individual parameters must be provided. If any are missing, the default `DATABASE_URL` (SQLite file) or any explicitly set `DATABASE_URL` will be used instead.
:::
### Encrypted SQLite with SQLCipher
For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed.

8
docs/tutorials/images.md
View File

@@ -157,7 +157,13 @@ Open WebUI also supports image generation through the **OpenAI APIs**. This opti
### Azure OpenAI
Using Azure OpenAI Dall-E directly is unsupported, but you can [set up a LiteLLM proxy](https://litellm.vercel.app/docs/image_generation) which is compatible with the `Open AI (Dall-E)` Image Generation Engine.
Image generation with a Azure OpenAI Dall-E or GPT-Image is supported with OpenWeb UI. Configure the Image Generation as follows:
1. In Open WebUI, navigate to the **Admin Panel** > **Settings** > **Images** menu.
2. Set the `Image Generation Engine` field to `Open AI` (Azure OpenAI uses the same syntax as OpenAI).
3. Change the API endpoint URL to `https://<instance-id>.cognitiveservices.azure.com/openai/deployments/<model>/`. Set the instance and model id as you find it in the settings of the Azure AI Foundry.
4. Configure the API version to the value you find in the settings of the Azure AI Fountry.
5. Enter your Azure OpenAI API key.
## Image Router