The fastest, litest AI Gateway. Rust core with Python SDK. Call 100+ LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]
Python ai-gatewayanthropicazure-openaibedrockgatewaylangchainlitellmllmllm-gatewayllmopsmcp-gatewayopenaiopenai-proxyrustrust-aivertex-ai
fix(ui_sso): seal the litellm_cp_return_to cookie so edge firewalls stop blocking the MCP OAuth sign-in (#47595)
Yassin Kortamf9d9466f2bed
diff --git a/litellm/constants.py b/litellm/constants.pyindex 919122d6e4d..70be1e56341 100644--- a/litellm/constants.py+++ b/litellm/constants.py@@ -1814,6 +1814,7 @@ LITELLM_EXECUTED_BATCH_CONCURRENCY: Final = max(1, get_env_int("LITELLM_EXECUTED########################### CLI SSO AUTHENTICATION CONSTANTS ###########################LITELLM_CLI_SOURCE_IDENTIFIER: Final = "litellm-cli"LITELLM_CLI_SESSION_TOKEN_PREFIX: Final = "litellm-session-token"+CP_RETURN_TO_COOKIE_PREFIX: Final = "return_to.v1."CLI_SSO_SESSION_CACHE_KEY_PREFIX: Final = "cli_sso_session"CLI_SSO_SESSION_TTL_SECONDS: Final = 600CLI_SESSION_KEY_PREFIX: Final = "cli-session"diff --git a/litellm/proxy/management_endpoints/ui_sso.py b/litellm/proxy/management_endpoints/ui_sso.pyindex 4cc849762aa..19bca3d2bf8 100644--- a/litellm/proxy/management_endpoints/ui_sso.py+++ b/litellm/proxy/management_endpoints/ui_sso.py@@ -55,6 +55,7 @@ from litellm.constants import (CLI_SSO_CLAIM_MAX_SCALAR_LENGTH,CLI_SSO_SESSION_CACHE_KEY_PREFIX,CLI_SSO_SESSION_TTL_SECONDS,+ CP_RETURN_TO_COOKIE_PREFIX,LITELLM_CLI_SOURCE_IDENTIFIER,LITELLM_UI_SESSION_DURATION,MAX_SPENDLOG_ROWS_TO_QUERY,@@ -2285,9 +2286,7 @@ async def auth_callback(request: Request, state: str | None = None):sso_assertion=sso_assertion,)- # Control-plane cross-origin: read return_to from cookie.- # Starlette's cookie_parser already handles RFC 2109 unquoting.- cp_return_to: Final[str | None] = request.cookies.get("litellm_cp_return_to")+ cp_return_to: Final[str | None] = read_return_to_cookie(request)return await SSOAuthenticationHandler.get_redirect_response_from_openid(result=result,@@ -3090,10 +3089,11 @@ def _persist_return_to_cookie(response: Response, return_to: str | None, requestsafe: Final = _is_same_origin_return_path(return_to) or SSOAuthenticationHandler.validate_return_to(return_to)except HTTPException:return # a non-matching absolute return_to is ignored, never blocks sign-in- if safe:+ sealed: Final = _seal_return_to(return_to) if safe else None+ if sealed is not None:response.set_cookie(key="litellm_cp_return_to",- value=return_to,+ value=sealed,max_age=600,httponly=True,samesite="lax",@@ -3101,6 +3101,45 @@ def _persist_return_to_cookie(response: Response, return_to: str | None, request)+def _seal_return_to(return_to: str) -> str | None:+ """``return_to`` sealed under the salt key as an opaque cookie value. The plaintext URL carries the+ client's loopback ``redirect_uri`` (``http://127.0.0.1:<port>/...`` for Codex or Claude Code), which+ edge firewalls read as an SSRF probe and block before the proxy sees the request. None when there+ is no salt or master key yet, so the login entrypoint still renders."""+ from litellm.proxy.common_utils.encrypt_decrypt_utils import encrypt_bearer_token++ try:+ return encrypt_bearer_token(return_to, prefix=CP_RETURN_TO_COOKIE_PREFIX)+ except ValueError:+ return None+++def _clear_rejected_return_to_cookie(response: Response, request: Request) -> None:+ """Expire a ``litellm_cp_return_to`` that ``read_return_to_cookie`` rejected (plaintext, stale, or sealed+ under another key) so the browser stops replaying it until it expires on its own."""+ if "litellm_cp_return_to" in request.cookies:+ response.delete_cookie("litellm_cp_return_to")+++def _dashboard_redirect_response(request: Request, jwt_token: str, litellm_dashboard_ui: str) -> RedirectResponse:+ """The post-SSO dashboard landing, used when there is no honored ``return_to``. Sets the session+ cookie and expires a ``litellm_cp_return_to`` the reader rejected."""+ verbose_proxy_logger.info("Redirecting to %s", litellm_dashboard_ui)+ redirect_response: Final = RedirectResponse(url=litellm_dashboard_ui, status_code=303)+ set_session_token_cookie(redirect_response, request, jwt_token)+ _clear_rejected_return_to_cookie(redirect_response, request)+ return redirect_response+++def read_return_to_cookie(request: Request) -> str | None:+ """The ``return_to`` this proxy sealed into ``litellm_cp_return_to``, or None when the cookie is+ missing, was not sealed here, or was tampered with."""+ from litellm.proxy.common_utils.encrypt_decrypt_utils import decrypt_bearer_token++ sealed: Final = request.cookies.get("litellm_cp_return_to")+ return None if sealed is None else decrypt_bearer_token(sealed, prefix=CP_RETURN_TO_COOKIE_PREFIX)++def _is_blank_sso_user_id(user_id: object) -> bool:return isinstance(user_id, str) and not user_id.strip()@@ -3976,10 +4015,7 @@ class SSOAuthenticationHandler:if user_id is not None and isinstance(user_id, str):litellm_dashboard_ui += "?login=success"- verbose_proxy_logger.info("Redirecting to %s", litellm_dashboard_ui)- redirect_response: Final = RedirectResponse(url=litellm_dashboard_ui, status_code=303)- set_session_token_cookie(redirect_response, request, jwt_token)- return redirect_response+ return _dashboard_redirect_response(request, jwt_token, litellm_dashboard_ui)@staticmethod@with_service_target(SSO_SESSIONS_TARGET)diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.pyindex c6d3e12a378..967cae27990 100644--- a/litellm/proxy/proxy_server.py+++ b/litellm/proxy/proxy_server.py@@ -18400,6 +18400,7 @@ async def login(request: Request):# _is_same_origin_return_path (strictly relative path) so it can never be an open redirect, and the# one-shot cookie is cleared after use.from litellm.proxy.management_endpoints.ui_sso import (+ read_return_to_cookie,set_session_token_cookie,sso_return_to_redirect,)@@ -18411,7 +18412,7 @@ async def login(request: Request):# return_to is honored for EVERY sign-in branch, so the write and read sets cannot diverge: it# sets the token cookie on the same-origin arm and hands off via a one-time login code on the# cross-origin arm, and clears the one-shot cookie in both.- cp_return_to: Final = request.cookies.get("litellm_cp_return_to")+ cp_return_to: Final = read_return_to_cookie(request)if cp_return_to:try:resumed = await sso_return_to_redirect( # rebind-ok: pre-existing rebinding on a rename-only line@@ -18435,7 +18436,7 @@ async def login(request: Request):# Create redirect response with cookieredirect_response: Final = RedirectResponse(url=litellm_dashboard_ui, status_code=303)set_session_token_cookie(redirect_response, request, jwt_token)- if cp_return_to:+ if "litellm_cp_return_to" in request.cookies:redirect_response.delete_cookie(key="litellm_cp_return_to")return redirect_responsediff --git a/tests/unit/proxy/management_endpoints/test_ui_sso.py b/tests/unit/proxy/management_endpoints/test_ui_sso.pyindex 873182a5145..479391e54fe 100644--- a/tests/unit/proxy/management_endpoints/test_ui_sso.py+++ b/tests/unit/proxy/management_endpoints/test_ui_sso.py@@ -33,6 +33,7 @@ from litellm.proxy.management_endpoints.ui_sso import (insert_sso_user,normalize_email,process_sso_jwt_access_token,+ read_return_to_cookie,sso_lookup_user_ids,)from litellm.types.proxy.management_endpoints.ui_sso import (@@ -10603,6 +10604,10 @@ class TestPersistReturnToCookieSharedHelper:def _cookie(resp) -> str:return resp.headers.get("set-cookie", "")+ @pytest.fixture(autouse=True)+ def _master_key(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr("litellm.proxy.proxy_server.master_key", "sk-test-master")+def test_sets_cookie_for_same_origin_relative_path(self, monkeypatch):from fastapi import Response@@ -10648,6 +10653,62 @@ class TestPersistReturnToCookieSharedHelper:_persist_return_to_cookie(resp, "https://cp.example.com/ui?page=models", _make_https_request())assert "litellm_cp_return_to=" in self._cookie(resp)+ def test_cookie_is_opaque_and_round_trips_the_loopback_redirect_uri(self, monkeypatch: pytest.MonkeyPatch) -> None:+ """The DCR authorize round-trip for a local coding agent stores a return_to carrying+ ``redirect_uri=http://127.0.0.1:<port>/...``. An edge firewall (AWS WAF+ ``EC2MetaDataSSRF_COOKIE``) reads that loopback URL in a cookie as an SSRF probe and 403s the+ callback, so the cookie must carry nothing a middlebox can pattern-match, while the proxy+ itself still reads the exact return_to back."""+ from fastapi import Response++ from litellm.proxy.management_endpoints.ui_sso import _persist_return_to_cookie, read_return_to_cookie++ monkeypatch.setattr("litellm.proxy.proxy_server.general_settings", {})+ return_to: Final = "/mcp/authorize?client_id=llm_dcrc_abc&redirect_uri=http%3A%2F%2F127.0.0.1%3A1455%2Fauth%2Fcallback"+ resp: Final = Response()+ _persist_return_to_cookie(resp, return_to, _make_https_request())+ cookie: Final = self._cookie(resp)+ value: Final = cookie.split("litellm_cp_return_to=", 1)[1].split(";", 1)[0]+ assert "127.0.0.1" not in cookie and "authorize" not in cookie, cookie+ request: Final = _make_https_request()+ request.cookies = {"litellm_cp_return_to": value}+ assert read_return_to_cookie(request) == return_to++ def test_a_cookie_this_proxy_did_not_seal_reads_as_nothing(self) -> None:+ from litellm.proxy.management_endpoints.ui_sso import read_return_to_cookie++ request: Final = _make_https_request()+ request.cookies = {"litellm_cp_return_to": "/mcp/authorize?client_id=llm_dcrc_abc"}+ assert read_return_to_cookie(request) is None++ def test_no_master_key_means_no_cookie_and_no_error(self, monkeypatch: pytest.MonkeyPatch) -> None:+ from fastapi import Response++ from litellm.proxy.management_endpoints.ui_sso import _persist_return_to_cookie++ monkeypatch.setattr("litellm.proxy.proxy_server.general_settings", {})+ monkeypatch.setattr("litellm.proxy.proxy_server.master_key", None)+ monkeypatch.delenv("LITELLM_SALT_KEY", raising=False)+ resp: Final = Response()+ _persist_return_to_cookie(resp, "/mcp/authorize", _make_https_request())+ assert "litellm_cp_return_to=" not in self._cookie(resp)++ def test_sso_dashboard_fallback_clears_a_return_to_cookie_it_rejected(self, monkeypatch: pytest.MonkeyPatch) -> None:+ """A plaintext (pre-upgrade or client-planted) litellm_cp_return_to is not honored by /sso/callback,+ and the dashboard landing must also expire it so the browser stops replaying the URL-bearing cookie+ (and tripping the edge firewall) for the rest of its lifetime."""+ from litellm.proxy.management_endpoints.ui_sso import _dashboard_redirect_response++ monkeypatch.setattr("litellm.proxy.proxy_server.general_settings", {})+ request: Final = _make_https_request()+ request.cookies = {"litellm_cp_return_to": "/mcp/authorize?client_id=llm_dcrc_abc"}+ assert read_return_to_cookie(request) is None+ response: Final = _dashboard_redirect_response(request, "jwt", "/ui?login=success")+ set_cookies: Final = response.headers.getlist("set-cookie")+ assert response.status_code == 303 and response.headers["location"] == "/ui?login=success"+ assert any(c.startswith("token=jwt") for c in set_cookies), set_cookies+ assert any(c.startswith('litellm_cp_return_to=""') and "Max-Age=0" in c for c in set_cookies), set_cookies+def test_cookie_is_secure_and_httponly_over_https(self, monkeypatch):from fastapi import Responsediff --git a/tests/unit/proxy/proxy_server/test_routes_login_sso.py b/tests/unit/proxy/proxy_server/test_routes_login_sso.pyindex 75e14a89148..43629b926ad 100644--- a/tests/unit/proxy/proxy_server/test_routes_login_sso.py+++ b/tests/unit/proxy/proxy_server/test_routes_login_sso.py@@ -11,8 +11,12 @@ Routes covered:from __future__ import annotationsfrom datetime import datetime, timezone+from typing import Finalfrom unittest.mock import AsyncMock, MagicMock+import pytest+from fastapi.testclient import TestClient+from .conftest import normalize# ---------------------------------------------------------------------------@@ -398,6 +402,29 @@ def test_v3_login_exchange_success_returns_token_and_redirect(client, monkeypatc}+def _sealed_return_to(return_to: str) -> str:+ """The cookie value /sso/key/generate writes: return_to sealed under the master key, never plaintext."""+ from litellm.constants import CP_RETURN_TO_COOKIE_PREFIX+ from litellm.proxy.common_utils.encrypt_decrypt_utils import encrypt_bearer_token++ return encrypt_bearer_token(return_to, prefix=CP_RETURN_TO_COOKIE_PREFIX)+++def test_login_form_ignores_a_plaintext_return_to_cookie(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:+ """A return_to the proxy did not seal (a client-planted or pre-upgrade plaintext cookie) is not+ honored: /login lands on the dashboard and clears the cookie."""+ _install_login_mocks(monkeypatch)+ response: Final = client.post(+ "/login",+ data={"username": "admin", "password": "password"},+ cookies={"litellm_cp_return_to": "/mcp/authorize?client_id=llm_dcrc_abc"},+ follow_redirects=False,+ )+ assert response.status_code == 303+ assert "/ui" in response.headers.get("location", "")+ assert 'litellm_cp_return_to=""' in response.headers.get("set-cookie", "")++def test_login_form_honors_same_origin_return_to_cookie(client, monkeypatch):"""The aggregate DCR connect flow preserves a same-origin return_to in the litellm_cp_return_tocookie; /login must RESUME there after password sign-in instead of dead-ending at the dashboard."""@@ -406,7 +433,7 @@ def test_login_form_honors_same_origin_return_to_cookie(client, monkeypatch):response = client.post("/login",data={"username": "admin", "password": "password"},- cookies={"litellm_cp_return_to": return_to},+ cookies={"litellm_cp_return_to": _sealed_return_to(return_to)},follow_redirects=False,)assert response.status_code == 303@@ -425,7 +452,7 @@ def test_login_form_honors_control_plane_return_to_cookie(client, monkeypatch):response = client.post("/login",data={"username": "admin", "password": "password"},- cookies={"litellm_cp_return_to": "https://cp.example.com/console"},+ cookies={"litellm_cp_return_to": _sealed_return_to("https://cp.example.com/console")},follow_redirects=False,)location = response.headers.get("location", "")@@ -447,7 +474,7 @@ def test_login_form_survives_stale_control_plane_return_to(client, monkeypatch):response = client.post("/login",data={"username": "admin", "password": "password"},- cookies={"litellm_cp_return_to": "https://old-cp.example.com/console"},+ cookies={"litellm_cp_return_to": _sealed_return_to("https://old-cp.example.com/console")},follow_redirects=False,)assert response.status_code == 303, "login must not break on a stale return_to cookie"@@ -463,7 +490,7 @@ def test_login_form_ignores_open_redirect_return_to(client, monkeypatch):response = client.post("/login",data={"username": "admin", "password": "password"},- cookies={"litellm_cp_return_to": "https://evil.example.com/steal"},+ cookies={"litellm_cp_return_to": _sealed_return_to("https://evil.example.com/steal")},follow_redirects=False,)assert response.status_code == 303