[PR #23604] [CLOSED] fix: include token in terminal orchestrator websocket URL #42905

New Issue

GiteaMirror · 2026-04-25T14:40:30-05:00

GiteaMirror commented

2026-04-25 14:40:30 -05:00

📋 Pull Request Information

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

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

📝 Commits (2)

44963f2 fix: include token in terminal orchestrator websocket URL
3cabede fix: restore x-session-id header forwarding in terminal proxy

📊 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

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.

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/23604 **Author:** [@kaplanmaxe](https://github.com/kaplanmaxe) **Created:** 4/11/2026 **Status:** ❌ Closed **Base:** `dev` ← **Head:** `fix-terminal-orchestrator-ws-auth` --- ### 📝 Commits (2) - [`44963f2`](https://github.com/open-webui/open-webui/commit/44963f2efd4937e6889feb218db7ef7028fe6abb) fix: include token in terminal orchestrator websocket URL - [`3cabede`](https://github.com/open-webui/open-webui/commit/3cabedefd5c43dd18039daeb03bb649624d9eb4c) fix: restore x-session-id header forwarding in terminal proxy ### 📊 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  # 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-04-25 14:40:30 -05:00

GiteaMirror closed this issue

2026-04-25 14:40:31 -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#42905