github-starred/open-webui
2
0
Fork 0
mirror of https://github.com/open-webui/open-webui.git synced 2026-08-30 17:25:30 -05:00
Code Issues 2.4k Packages Projects Releases 129 Wiki Activity

[PR #23603] [CLOSED] Fix terminal orchestrator ws auth #82147

New Issue
Closed
opened 2026-05-13 16:37:23 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-05-13 16:37:23 -05:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/open-webui/open-webui/pull/23603
Author: @kaplanmaxe
Created: 4/11/2026
Status: ❌ Closed

Base: dev ← Head: fix-terminal-orchestrator-ws-auth

📝 Commits (10+)

📊 Changes

3 files changed (+80 additions, -20 deletions)

View changed files

📝 backend/open_webui/routers/terminals.py (+12 -20)
➕ backend/open_webui/test/util/test_terminals.py (+44 -0)
➕ backend/open_webui/utils/terminals.py (+24 -0)

📄 Description

Pull Request Checklist

Note to first-time contributors

I did not open a discussion before submitting this fix because this is a narrow bugfix with a focused regression test and manual validation, not a large feature or architectural change.

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

  • Target branch: This PR targets the dev branch.
  • Description: A concise description of the changes is included below.
  • Changelog: A changelog entry following the requested format is included below.
  • Documentation: I do not believe this requires docs in the docs repository because it fixes internal terminal WebSocket auth behavior rather than changing user-facing configuration or deployment steps.
  • Dependencies: No new or upgraded dependencies were added.
  • Testing: I performed unit tests and manual validation in Kubernetes, with reproducible before/after behavior documented below.
  • Agentic AI Code: This change has gone through additional human review and manual testing before submission.
  • Code review: I performed a self-review of the code and kept the change narrow.
  • Design & Architecture: This uses the existing terminal connection model and avoids introducing new settings.
  • Git Hygiene: This PR is atomic and scoped to one logical fix.
  • Title Prefix: The PR title uses the fix prefix.

Description

This PR fixes terminal WebSocket proxy connections to the terminals orchestrator by including the bearer token in the upstream WebSocket query string.

Today Open WebUI opens the upstream terminal WebSocket with user_id only, then sends an auth message after the connection is established. The terminals orchestrator validates bearer auth during the WebSocket handshake, so the connection is rejected with 403 before that auth frame can be sent.

This patch:

  • adds token to the upstream WebSocket query params for bearer-auth terminal connections
  • keeps the existing post-connect auth frame for compatibility with backends that still expect it
  • adds regression tests for bearer, non-bearer, and policy-scoped terminal routes

Repro / Root Cause

When Open WebUI is configured to use the terminals orchestrator, terminal session creation succeeds but interactive attach fails with a WebSocket handshake error:

WSServerHandshakeError: 403

In my case, the failure was reproducible because:

  • POST /api/terminals succeeded
  • proxied HTTP calls to the terminal backend succeeded
  • WebSocket connect to the orchestrator without token failed with 403
  • WebSocket connect to the same orchestrator with ?token=...&user_id=... succeeded

So the issue is isolated to the upstream WebSocket auth shape.

The root cause is that the terminals orchestrator validates WebSocket auth during the handshake and expects the bearer token to be present on the upstream WebSocket request.

Open WebUI was building the upstream WebSocket URL with only:

  • user_id

and then sending:

  • {"type":"auth","token":"..."}

after the socket connected.

That does not work when the upstream rejects the handshake before accepting the connection.

Testing

Unit tests

PYTHONPATH=backend python3 -m pytest backend/open_webui/test/util/test_terminals.py -q

Result:

3 passed

Manual validation

I am also running this successfully in a Kubernetes cluster using the terminals orchestrator flow.

Tested setup:

  • terminals orchestrator: ghcr.io/open-webui/terminals:0.0.2
  • terminals operator: ghcr.io/open-webui/terminals-operator:0.0.2
  • terminal image: ghcr.io/open-webui/open-terminal:0.11.34
  • Open WebUI configured to connect to the orchestrator service over the in-cluster service URL
  • per-user terminal pods created dynamically via the operator

Before this patch:

  • terminal session creation succeeded
  • terminal backend HTTP proxying succeeded
  • interactive terminal attach failed with WSServerHandshakeError: 403

After this patch:

  • terminal session creation still succeeds
  • interactive terminal attach succeeds
  • I can open and use the terminal normally through the Open WebUI interface

I also reproduced the orchestrator behavior directly by connecting to the orchestrator WebSocket endpoint:

  • without token in the query string: 403
  • with token in the query string: connection succeeds

Edge cases covered by tests

  • bearer auth adds token
  • non-bearer auth does not add token
  • policy-scoped routes generate the correct path

Changelog Entry

Description

  • Fix terminal WebSocket proxying to the terminals orchestrator by including the bearer token in the upstream WebSocket query string during handshake.

Added

  • A small helper to build terminal WebSocket URLs.
  • Regression tests covering bearer, non-bearer, and policy-scoped terminal routes.

Changed

  • Upstream terminal WebSocket URL construction now includes token when auth_type == "bearer" and a key is present.
  • The existing post-connect auth frame is preserved for compatibility.

Deprecated

  • None.

Removed

  • None.

Fixed

  • Fixed terminal attach failures where the terminals orchestrator rejects the upstream WebSocket handshake with 403 because the bearer token is missing from the query string.

Security

  • No new security features or dependency changes.
  • This change aligns Open WebUI's upstream WebSocket auth behavior with the orchestrator's existing handshake validation requirements.

Breaking Changes

  • BREAKING CHANGE: None.

Additional Information

  • This is intentionally narrow and does not add new settings or change non-bearer terminal behavior.
  • No dependencies were added or upgraded.
  • The existing auth frame sent after connection establishment is still preserved for compatibility with backends that expect it.

Screenshots or Videos

  • No screenshots attached.
  • This change affects the terminal WebSocket handshake path rather than visible UI layout.
  • If needed, I can add a short screen recording showing terminal attach failure before the fix and successful attach after the fix.

Contributor License Agreement

Note

Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in.

🔄 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/23603 **Author:** [@kaplanmaxe](https://github.com/kaplanmaxe) **Created:** 4/11/2026 **Status:** ❌ Closed **Base:** `dev` ← **Head:** `fix-terminal-orchestrator-ws-auth` --- ### 📝 Commits (10+) - [`fe6783c`](https://github.com/open-webui/open-webui/commit/fe6783c16699911c7be17392596d579333fb110c) Merge pull request #19030 from open-webui/dev - [`fc05e0a`](https://github.com/open-webui/open-webui/commit/fc05e0a6c5d39da60b603b4d520f800d6e36f748) Merge pull request #19405 from open-webui/dev - [`e3faec6`](https://github.com/open-webui/open-webui/commit/e3faec62c58e3a83d89aa3df539feacefa125e0c) Merge pull request #19416 from open-webui/dev - [`9899293`](https://github.com/open-webui/open-webui/commit/9899293f050ad50ae12024cbebee7e018acd851e) Merge pull request #19448 from open-webui/dev - [`140605e`](https://github.com/open-webui/open-webui/commit/140605e660b8186a7d5c79fb3be6ffb147a2f498) Merge pull request #19462 from open-webui/dev - [`6f1486f`](https://github.com/open-webui/open-webui/commit/6f1486ffd0cb288d0e21f41845361924e0d742b3) Merge pull request #19466 from open-webui/dev - [`d95f533`](https://github.com/open-webui/open-webui/commit/d95f533214e3fe5beb5e41ec1f349940bc4c7043) Merge pull request #19729 from open-webui/dev - [`a727153`](https://github.com/open-webui/open-webui/commit/a7271532f8a38da46785afcaa7e65f9a45e7d753) 0.6.43 (#20093) - [`6adde20`](https://github.com/open-webui/open-webui/commit/6adde203cd292a9e3af9c64a2ae36b603fed096a) Merge pull request #20394 from open-webui/dev - [`f9b0534`](https://github.com/open-webui/open-webui/commit/f9b0534e0c442631d1cb7205169588b9b6204179) Merge pull request #20522 from open-webui/dev ### 📊 Changes **3 files changed** (+80 additions, -20 deletions) <details> <summary>View changed files</summary> 📝 `backend/open_webui/routers/terminals.py` (+12 -20) ➕ `backend/open_webui/test/util/test_terminals.py` (+44 -0) ➕ `backend/open_webui/utils/terminals.py` (+24 -0) </details> ### 📄 Description <!-- ⚠️ CRITICAL CHECKS FOR CONTRIBUTORS (READ, DON'T DELETE) ⚠️ 1. Target the `dev` branch. PRs targeting `main` will be automatically closed. 2. Do NOT delete the CLA section at the bottom. It is required for the bot to accept your PR. --> # Pull Request Checklist ### Note to first-time contributors I did not open a discussion before submitting this fix because this is a narrow bugfix with a focused regression test and manual validation, not a large feature or architectural change. **Before submitting, make sure you've checked the following:** - [x] **Target branch:** This PR targets the `dev` branch. - [x] **Description:** A concise description of the changes is included below. - [x] **Changelog:** A changelog entry following the requested format is included below. - [ ] **Documentation:** I do not believe this requires docs in the docs repository because it fixes internal terminal WebSocket auth behavior rather than changing user-facing configuration or deployment steps. - [x] **Dependencies:** No new or upgraded dependencies were added. - [x] **Testing:** I performed unit tests and manual validation in Kubernetes, with reproducible before/after behavior documented below. - [x] **Agentic AI Code:** This change has gone through additional human review and manual testing before submission. - [x] **Code review:** I performed a self-review of the code and kept the change narrow. - [x] **Design & Architecture:** This uses the existing terminal connection model and avoids introducing new settings. - [x] **Git Hygiene:** This PR is atomic and scoped to one logical fix. - [x] **Title Prefix:** The PR title uses the `fix` prefix. ## Description This PR fixes terminal WebSocket proxy connections to the terminals orchestrator by including the bearer token in the upstream WebSocket query string. Today `Open WebUI` opens the upstream terminal WebSocket with `user_id` only, then sends an auth message after the connection is established. The terminals orchestrator validates bearer auth during the WebSocket handshake, so the connection is rejected with `403` before that auth frame can be sent. This patch: - adds `token` to the upstream WebSocket query params for bearer-auth terminal connections - keeps the existing post-connect auth frame for compatibility with backends that still expect it - adds regression tests for bearer, non-bearer, and policy-scoped terminal routes ## Repro / Root Cause When `Open WebUI` is configured to use the terminals orchestrator, terminal session creation succeeds but interactive attach fails with a WebSocket handshake error: ```text WSServerHandshakeError: 403 ``` In my case, the failure was reproducible because: - `POST /api/terminals` succeeded - proxied HTTP calls to the terminal backend succeeded - WebSocket connect to the orchestrator without `token` failed with `403` - WebSocket connect to the same orchestrator with `?token=...&user_id=...` succeeded So the issue is isolated to the upstream WebSocket auth shape. The root cause is that the terminals orchestrator validates WebSocket auth during the handshake and expects the bearer token to be present on the upstream WebSocket request. `Open WebUI` was building the upstream WebSocket URL with only: - `user_id` and then sending: - `{"type":"auth","token":"..."}` after the socket connected. That does not work when the upstream rejects the handshake before accepting the connection. ## Testing ### Unit tests ```bash PYTHONPATH=backend python3 -m pytest backend/open_webui/test/util/test_terminals.py -q ``` Result: ```text 3 passed ``` ### Manual validation I am also running this successfully in a Kubernetes cluster using the terminals orchestrator flow. Tested setup: - terminals orchestrator: `ghcr.io/open-webui/terminals:0.0.2` - terminals operator: `ghcr.io/open-webui/terminals-operator:0.0.2` - terminal image: `ghcr.io/open-webui/open-terminal:0.11.34` - `Open WebUI` configured to connect to the orchestrator service over the in-cluster service URL - per-user terminal pods created dynamically via the operator Before this patch: - terminal session creation succeeded - terminal backend HTTP proxying succeeded - interactive terminal attach failed with `WSServerHandshakeError: 403` After this patch: - terminal session creation still succeeds - interactive terminal attach succeeds - I can open and use the terminal normally through the `Open WebUI` interface I also reproduced the orchestrator behavior directly by connecting to the orchestrator WebSocket endpoint: - without `token` in the query string: `403` - with `token` in the query string: connection succeeds ### Edge cases covered by tests - bearer auth adds `token` - non-bearer auth does not add `token` - policy-scoped routes generate the correct path # Changelog Entry ### Description - Fix terminal WebSocket proxying to the terminals orchestrator by including the bearer token in the upstream WebSocket query string during handshake. ### Added - A small helper to build terminal WebSocket URLs. - Regression tests covering bearer, non-bearer, and policy-scoped terminal routes. ### Changed - Upstream terminal WebSocket URL construction now includes `token` when `auth_type == "bearer"` and a key is present. - The existing post-connect auth frame is preserved for compatibility. ### Deprecated - None. ### Removed - None. ### Fixed - Fixed terminal attach failures where the terminals orchestrator rejects the upstream WebSocket handshake with `403` because the bearer token is missing from the query string. ### Security - No new security features or dependency changes. - This change aligns `Open WebUI`'s upstream WebSocket auth behavior with the orchestrator's existing handshake validation requirements. ### Breaking Changes - **BREAKING CHANGE**: None. --- ### Additional Information - This is intentionally narrow and does not add new settings or change non-bearer terminal behavior. - No dependencies were added or upgraded. - The existing auth frame sent after connection establishment is still preserved for compatibility with backends that expect it. ### Screenshots or Videos - No screenshots attached. - This change affects the terminal WebSocket handshake path rather than visible UI layout. - If needed, I can add a short screen recording showing terminal attach failure before the fix and successful attach after the fix. ### Contributor License Agreement - [X] 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. > [!NOTE] > Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in. --- <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-05-13 16:37:23 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
confirmed
confirmed issue
core
documentation
enhancement
good first issue
help wanted
non-core
pull-request
Mirrored from GitHub Pull Request
 python
question
testing wanted
No labels pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
GiteaMirror ninjasurge (Kaehlen Rog)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/open-webui#82147