From 80d6b78caa4a83abe30147f72b44fa588b0c6cb3 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:01:56 +0100 Subject: [PATCH] webui secret key --- docs/faq.mdx | 8 ++++++++ docs/features/mcp.mdx | 4 ++++ .../features/plugin/tools/openapi-servers/mcp.mdx | 4 ++++ docs/getting-started/env-configuration.mdx | 15 +++++++++++++-- docs/tutorials/integrations/mcp-notion.mdx | 5 +++++ 5 files changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/faq.mdx b/docs/faq.mdx index c0ea4571..bc4b0bca 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -84,6 +84,14 @@ Everything you need to run Open WebUI, including your data, remains within your **A:** If your Open WebUI isn't launching post-update or installation of new software, it's likely related to a direct installation approach, especially if you didn't use a virtual environment for your backend dependencies. Direct installations can be sensitive to changes in the system's environment, such as updates or new installations that alter existing dependencies. To avoid conflicts and ensure stability, we recommend using a virtual environment for managing the `requirements.txt` dependencies of your backend. This isolates your Open WebUI dependencies from other system packages, minimizing the risk of such issues. +### Q: I updated/restarted and now I'm being logged out, or getting "Error decrypting tokens" for my tools? + +**A:** This happens because you haven't set a persistent `WEBUI_SECRET_KEY` in your environment variables. +* **Logouts:** Without this key, Open WebUI generates a random one every time it starts. This invalidates your previous session cookies (JWTs), forcing you to log in again. +* **Decryption Errors:** Essential secrets (like OAuth tokens for MCP tools or API keys) are encrypted using this key. If the key changes on restart, Open WebUI cannot decrypt them, leading to errors. + +**Fix:** Set `WEBUI_SECRET_KEY` to a constant, secure string in your Docker Compose or environment config. + ### Q: I updated/restarted and now my login isn't working anymore, I had to create a new account and all my chats are gone. **A:** This issue typically arises when a Docker container is created without mounting a volume for `/app/backend/data` or if the designated Open WebUI volume (usually named `open-webui` in our examples) was unintentionally deleted. Docker volumes are crucial for persisting your data across container lifecycles. If you find yourself needing to create a new account after a restart, it's likely you've initiated a new container without attaching the existing volume where your data resides. Ensure that your Docker run command includes a volume mount pointing to the correct data location to prevent data loss. diff --git a/docs/features/mcp.mdx b/docs/features/mcp.mdx index 6ca6d5e2..55839511 100644 --- a/docs/features/mcp.mdx +++ b/docs/features/mcp.mdx @@ -9,6 +9,10 @@ Open WebUI natively supports **MCP (Model Context Protocol)** starting in **v0.6 Requires **Open WebUI v0.6.31+**. ::: +:::danger Prerequisite: WEBUI_SECRET_KEY +You **MUST** set the `WEBUI_SECRET_KEY` environment variable in your Docker setup. Without it, **OAuth-connected MCP tools (like Notion)** will **break** every time you restart or recreate the container (Error: `Error decrypting tokens`), forcing you to re-authenticate everything. +::: + ## 🚀 Quick start 1. Open **⚙️ Admin Settings → External Tools**. diff --git a/docs/features/plugin/tools/openapi-servers/mcp.mdx b/docs/features/plugin/tools/openapi-servers/mcp.mdx index 20dbea48..aeb6c0ea 100644 --- a/docs/features/plugin/tools/openapi-servers/mcp.mdx +++ b/docs/features/plugin/tools/openapi-servers/mcp.mdx @@ -5,6 +5,10 @@ title: "MCP Support" This documentation explains how to easily set up and deploy the [**MCP (Model Context Protocol)-to-OpenAPI proxy server** (mcpo)](https://github.com/open-webui/mcpo) provided by Open WebUI. Learn how you can effortlessly expose MCP-based tool servers using standard, familiar OpenAPI endpoints suitable for end-users and developers. +:::danger Critical for Persistence +If you connect Open WebUI to this proxy using an API Key or Auth Token, you **MUST** set `WEBUI_SECRET_KEY` in your Open WebUI Docker config. If this key changes (e.g., on container restart), Open WebUI will fail to decrypt the stored credentials for your tool. +::: + ### 📌 What is the MCP Proxy Server? The MCP-to-OpenAPI proxy server lets you use tool servers implemented with MCP (Model Context Protocol) directly via standard REST/OpenAPI APIs—no need to manage unfamiliar or complicated custom protocols. If you're an end-user or application developer, this means you can interact easily with powerful MCP-based tooling directly through familiar REST-like endpoints. diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 8273ea02..580a658c 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -1255,9 +1255,20 @@ Invalid regex patterns will cause password validation to fail, potentially preve - Type: `str` - Default: `t0p-s3cr3t` - Docker Default: Randomly generated on first start -- Description: Overrides the randomly generated string used for JSON Web Token. +- Description: Overrides the randomly generated string used for JSON Web Token and **encryption of sensitive data** (like OAuth tokens for MCP). -:::warning +:::danger Critical for Docker/Production + +You **MUST** set `WEBUI_SECRET_KEY` to a secure, persistent value. + +If you do NOT set this: +1. It will be randomly generated each time the container restarts/recreates. +2. **All OAuth sessions will become invalid.** +3. **MCP Tools will break** (Error: `Error decrypting tokens`) because they cannot decrypt the tokens stored with the previous key. +4. You will be logged out. + +**Do not leave this unset in production.** +::: **Required for Multi-Worker and Multi-Node Deployments AND HIGHLY RECOMMENDED IN SINGLE-WORKER ENVIRONMENTS** diff --git a/docs/tutorials/integrations/mcp-notion.mdx b/docs/tutorials/integrations/mcp-notion.mdx index ce0111f5..ce9ae0e7 100644 --- a/docs/tutorials/integrations/mcp-notion.mdx +++ b/docs/tutorials/integrations/mcp-notion.mdx @@ -27,6 +27,11 @@ This method connects directly to Notion's hosted MCP endpoint (`https://mcp.noti **Streamable HTTP** is preferred for its simplicity and enhanced security. It handles authentication via Notion's official OAuth flow, meaning you do not need to manually manage secrets or integration tokens. ::: +:::danger Critical for OAuth Persistence +You **MUST** set the `WEBUI_SECRET_KEY` environment variable in your Docker setup to a persistent value. +If you do not, your Notion OAuth session will become invalid every time you restart the container, forcing you to re-authenticate repeatedly. +::: + ### 1. Configure Tool You can automatically prefill the connection settings by importing the JSON configuration below.