[PR #18094] [CLOSED] fix: Handle OAuth decryption failures gracefully on startup #24669

New Issue

GiteaMirror · 2026-04-20T05:31:54-05:00

GiteaMirror commented

2026-04-20 05:31:54 -05:00

📋 Pull Request Information

Original PR: https://github.com/open-webui/open-webui/pull/18094
Author: @NeilMazumdar
Created: 10/7/2025
Status: ❌ Closed

Base: dev ← Head: fix/oauth-decryption-graceful-handling

📝 Commits (1)

136bb1c fix: Handle OAuth decryption failures gracefully on startup

📊 Changes

3 files changed (+41 additions, -8 deletions)

View changed files

📝 backend/open_webui/main.py (+18 -4)
📝 backend/open_webui/routers/configs.py (+7 -0)
📝 backend/open_webui/utils/oauth.py (+16 -4)

📄 Description

Pull Request Checklist

Before submitting, make sure you've checked the following:

Target branch: Please verify that the pull request targets the dev branch.
Description: Provide a concise description of the changes made in this pull request.
Changelog: Ensure a changelog entry following the format of Keep a Changelog is added at the bottom of the PR description.
Documentation: Have you updated relevant documentation Open WebUI Docs, or other documentation sources?
Dependencies: Are there any new dependencies? Have you updated the dependency versions in the documentation?
Testing: Have you written and run sufficient tests to validate the changes?
Code review: Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
Prefix: fix: - Bug fix or error correction

Changelog Entry

Description

This PR addresses a critical issue where the application crashes on startup with cryptography.fernet.InvalidToken when OAuth credentials cannot be decrypted due to WEBUI_SECRET_KEY mismatch. This typically occurs when:

The WEBUI_SECRET_KEY environment variable changes
A database is migrated between environments (e.g., dev → staging → production)
A database backup is restored with a different encryption key

The fix implements graceful error handling that logs clear error messages and disables affected MCP connections while allowing the application to start successfully, preventing complete service outages.

Added

Error handling with clear, actionable error messages in decrypt_data() function
Try-except blocks around OAuth credential decryption in startup code
None checks for graceful degradation when decryption fails
Recovery instructions in error logs to guide administrators

Changed

Modified decrypt_data() in backend/open_webui/utils/oauth.py to return Optional[dict] instead of raising exceptions on decryption failures
Enhanced error logging in backend/open_webui/main.py during OAuth client initialization with detailed failure messages
Updated backend/open_webui/routers/configs.py to handle None return values from decrypt_data()

Deprecated

None

Removed

None

Fixed

Critical: Application crash on startup when OAuth credentials encrypted with different WEBUI_SECRET_KEY cannot be decrypted
Complete service outages caused by encryption key mismatches during database migrations
Lack of error visibility when OAuth decryption fails - now provides clear diagnostic information

Security

No security vulnerabilities introduced
Maintains existing encryption/decryption behavior for valid credentials
Fails gracefully without exposing sensitive information in error messages

Breaking Changes

None - This is a backward-compatible bug fix that maintains existing functionality while adding resilience

Additional Information

Root Cause:
The application stores encrypted OAuth credentials for MCP (Model Context Protocol) tool server connections in the SQLite database. When the WEBUI_SECRET_KEY used for Fernet encryption doesn't match the key used during encryption, the decrypt_data() function raises an InvalidToken exception. This exception was previously unhandled at the module level in main.py, causing the entire FastAPI application to crash during initialization.

Solution Approach:

Modified decrypt_data() to return None instead of raising exceptions when decryption fails
Added comprehensive error logging with:
- Clear explanation of the likely cause (WEBUI_SECRET_KEY mismatch)
- Actionable recovery instructions
- Identification of affected MCP connections
Used continue to skip failed connections rather than crashing the application
Applied consistent error handling in both startup (main.py) and runtime (configs.py) code paths

Testing Performed:

✅ Tested with valid OAuth credentials - application starts normally
✅ Tested with invalid encrypted data (wrong WEBUI_SECRET_KEY) - application starts with clear error messages
✅ Verified error logs provide actionable recovery guidance
✅ Confirmed affected MCP connections are properly disabled
✅ Validated that core application functionality remains available

Real-World Impact:
This fix prevents complete service outages in production environments, particularly when:

Deploying to Azure Web Apps or similar container platforms
Migrating databases between environments
Rotating encryption keys as part of security best practices

Related Issue:
Closes #18092

Additional Context:
The fix maintains the security of OAuth credentials while preventing catastrophic failures. Administrators can now:

Access the running application even with decryption failures
See clear error messages in logs explaining the issue
Reconfigure affected OAuth connections via the UI
Restore the original WEBUI_SECRET_KEY if available

Screenshots or Videos

N/A - Backend infrastructure fix with no UI changes

Contributor License Agreement

By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/open-webui/pull/18094 **Author:** [@NeilMazumdar](https://github.com/NeilMazumdar) **Created:** 10/7/2025 **Status:** ❌ Closed **Base:** `dev` ← **Head:** `fix/oauth-decryption-graceful-handling` --- ### 📝 Commits (1) - [`136bb1c`](https://github.com/open-webui/open-webui/commit/136bb1c2b896285dba90819c45386720f30fd4ed) fix: Handle OAuth decryption failures gracefully on startup ### 📊 Changes **3 files changed** (+41 additions, -8 deletions) <details> <summary>View changed files</summary> 📝 `backend/open_webui/main.py` (+18 -4) 📝 `backend/open_webui/routers/configs.py` (+7 -0) 📝 `backend/open_webui/utils/oauth.py` (+16 -4) </details> ### 📄 Description # Pull Request Checklist **Before submitting, make sure you've checked the following:** - [x] **Target branch:** Please verify that the pull request targets the `dev` branch. - [x] **Description:** Provide a concise description of the changes made in this pull request. - [x] **Changelog:** Ensure a changelog entry following the format of [Keep a Changelog](https://keepachangelog.com/) is added at the bottom of the PR description. - [x] **Documentation:** Have you updated relevant documentation [Open WebUI Docs](https://github.com/open-webui/docs), or other documentation sources? - [x] **Dependencies:** Are there any new dependencies? Have you updated the dependency versions in the documentation? - [x] **Testing:** Have you written and run sufficient tests to validate the changes? - [x] **Code review:** Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards? - [x] **Prefix:** `fix:` - Bug fix or error correction # Changelog Entry ### Description This PR addresses a critical issue where the application crashes on startup with `cryptography.fernet.InvalidToken` when OAuth credentials cannot be decrypted due to `WEBUI_SECRET_KEY` mismatch. This typically occurs when: - The `WEBUI_SECRET_KEY` environment variable changes - A database is migrated between environments (e.g., dev → staging → production) - A database backup is restored with a different encryption key The fix implements graceful error handling that logs clear error messages and disables affected MCP connections while allowing the application to start successfully, preventing complete service outages. ### Added - Error handling with clear, actionable error messages in `decrypt_data()` function - Try-except blocks around OAuth credential decryption in startup code - None checks for graceful degradation when decryption fails - Recovery instructions in error logs to guide administrators ### Changed - Modified `decrypt_data()` in `backend/open_webui/utils/oauth.py` to return `Optional[dict]` instead of raising exceptions on decryption failures - Enhanced error logging in `backend/open_webui/main.py` during OAuth client initialization with detailed failure messages - Updated `backend/open_webui/routers/configs.py` to handle None return values from `decrypt_data()` ### Deprecated - None ### Removed - None ### Fixed - **Critical:** Application crash on startup when OAuth credentials encrypted with different `WEBUI_SECRET_KEY` cannot be decrypted - Complete service outages caused by encryption key mismatches during database migrations - Lack of error visibility when OAuth decryption fails - now provides clear diagnostic information ### Security - No security vulnerabilities introduced - Maintains existing encryption/decryption behavior for valid credentials - Fails gracefully without exposing sensitive information in error messages ### Breaking Changes - None - This is a backward-compatible bug fix that maintains existing functionality while adding resilience --- ### Additional Information **Root Cause:** The application stores encrypted OAuth credentials for MCP (Model Context Protocol) tool server connections in the SQLite database. When the `WEBUI_SECRET_KEY` used for Fernet encryption doesn't match the key used during encryption, the `decrypt_data()` function raises an `InvalidToken` exception. This exception was previously unhandled at the module level in `main.py`, causing the entire FastAPI application to crash during initialization. **Solution Approach:** 1. Modified `decrypt_data()` to return `None` instead of raising exceptions when decryption fails 2. Added comprehensive error logging with: - Clear explanation of the likely cause (WEBUI_SECRET_KEY mismatch) - Actionable recovery instructions - Identification of affected MCP connections 3. Used `continue` to skip failed connections rather than crashing the application 4. Applied consistent error handling in both startup (main.py) and runtime (configs.py) code paths **Testing Performed:** - ✅ Tested with valid OAuth credentials - application starts normally - ✅ Tested with invalid encrypted data (wrong WEBUI_SECRET_KEY) - application starts with clear error messages - ✅ Verified error logs provide actionable recovery guidance - ✅ Confirmed affected MCP connections are properly disabled - ✅ Validated that core application functionality remains available **Real-World Impact:** This fix prevents complete service outages in production environments, particularly when: - Deploying to Azure Web Apps or similar container platforms - Migrating databases between environments - Rotating encryption keys as part of security best practices **Related Issue:** Closes #18092 **Additional Context:** The fix maintains the security of OAuth credentials while preventing catastrophic failures. Administrators can now: 1. Access the running application even with decryption failures 2. See clear error messages in logs explaining the issue 3. Reconfigure affected OAuth connections via the UI 4. Restore the original WEBUI_SECRET_KEY if available ### Screenshots or Videos N/A - Backend infrastructure fix with no UI changes ### Contributor License Agreement By submitting this pull request, I confirm that I have read and fully agree to the [Contributor License Agreement (CLA)](https://github.com/open-webui/open-webui/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT), and I am providing my contributions under its terms. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-04-20 05:31:54 -05:00

GiteaMirror closed this issue

2026-04-20 05:31:55 -05:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/open-webui#24669