feat(auth): allow explicitly trusted hosted proxy OAuth callbacks

This commit is contained in:
Tin Chi Lo 2026-09-21 21:28:41 -07:00
parent 3106d9c573
commit 445c1cc0e0
5 changed files with 169 additions and 18 deletions

View file

@ -31,6 +31,21 @@ print(response)
[**See how to call Huggingface,Bedrock,TogetherAI,Anthropic, etc.**](https://docs.litellm.ai/docs/simple_proxy)
## Hosted applications using gateway SSO
A trusted web application can request a personal proxy-API session through the gateway’s configured SSO provider. By default, proxy-API OAuth grants only accept loopback redirects. To permit a hosted application, configure its exact callback URI on the gateway:
```shell
LITELLM_PROXY_API_OAUTH_REDIRECT_URIS=https://admin.example.com/oauth/callback
```
Multiple URIs are comma-separated. Each hosted URI must use HTTPS and contain no userinfo, query string, or fragment. Matching includes the complete path and port; wildcards and subdomain matching are not supported. Only allow callbacks operated by applications trusted to hold users’ personal proxy credentials
The application registers the same URI at `/register` and uses `/authorize` with `resource` set to the gateway base URL, S256 PKCE, and state. LiteLLM handles SSO and presents an approval page with team selection before returning an authorization code. The application exchanges the code at `/token` using the original verifier and callback URI. Applications must validate state and bind the callback to the browser that started sign-in
This setting does not grant an admin role or change existing native-client and MCP grants. The resulting credential uses the signed-in user’s permissions. Hosted applications must protect access and refresh tokens and handle expiry and revocation
---
### Folder Structure

View file

@ -40,6 +40,7 @@ from __future__ import annotations
import hashlib
import hmac
import html
import os
import secrets
from base64 import urlsafe_b64encode
from collections.abc import Awaitable, Callable, Iterable, Mapping
@ -553,6 +554,24 @@ def aggregate_authorize(
return response
def _hosted_proxy_redirect_is_allowed(redirect_uri: str) -> bool:
parsed: Final = urlparse(redirect_uri)
if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:
return False
if parsed.query or parsed.fragment or "?" in redirect_uri or "#" in redirect_uri:
return False
try:
validate_redirect_uri_shape(parsed)
except HTTPException:
return False
allowed: Final = tuple(
entry.strip()
for entry in os.environ.get("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", "").split(",")
if entry.strip()
)
return redirect_uri in allowed
async def native_client_authorize(
request: Request,
client_id: str,
@ -564,20 +583,23 @@ async def native_client_authorize(
session_user_id: str | None,
lookup_consent_teams: LookupConsentTeams,
) -> Response:
"""The authorize verb for a native client that named the proxy API itself as its
RFC 8707 ``resource``: the same client, redirect, PKCE, and sign-in checks as the
aggregate verb plus a loopback-only redirect (the credential this grant mints is the
user's personal proxy key, which belongs on their own machine and never behind a hosted
callback), then the consent page rendered right here (no connect-page interlude, since
there is no per-server vaulting to do) with the flow sealed into the per-flow cookie
and its handle carried only in the form, never in a URL."""
"""Authorize a proxy-API credential for a native or explicitly trusted hosted client.
Hosted callbacks require an exact operator-configured HTTPS URI in addition to
client registration, S256 PKCE, SSO, and the user's deliberate consent.
"""
rejected: Final = _rejected_authorize_request(
client_id, redirect_uri, state, code_challenge, code_challenge_method, response_type
)
if rejected is not None:
return rejected
if not is_loopback_redirect_host(urlparse(redirect_uri)):
return _oauth_error(400, "invalid_request", "a proxy-API grant may only redirect to a loopback address")
is_hosted: Final = not is_loopback_redirect_host(urlparse(redirect_uri))
if is_hosted and not _hosted_proxy_redirect_is_allowed(redirect_uri):
return _oauth_error(
400,
"invalid_request",
"a proxy-API grant may only redirect to a loopback address or an explicitly allowed HTTPS callback",
)
base_url: Final = get_request_base_url(request)
if session_user_id is None:
return _login_redirect(base_url, request)
@ -600,6 +622,7 @@ async def native_client_authorize(
teams=tuple((team.team_id, team.team_alias or team.team_id) for team in teams),
flow_handle=handle,
complete_url=f"{base_url}/authorize/complete",
hosted=is_hosted,
)
response: Final = HTMLResponse(page, headers=_CONSENT_PAGE_HEADERS)
_set_flow_cookie(response, request, handle, flow)

View file

@ -12,18 +12,22 @@ def render_native_client_consent_page(
teams: Sequence[tuple[str, str]],
flow_handle: str,
complete_url: str,
hosted: bool = False,
) -> str:
"""The consent page a native client's sign-in lands on: who is signed in, which
loopback client asked, which team the credential is attributed to, and an explicit
Approve or Deny that POSTs back to ``complete_url``. Every value is client- or
user-influenced and HTML-escaped; the flow handle travels only in the form body."""
title: Final = "Authorize application access" if hosted else "Authorize CLI access"
client_type: Final = "A web application" if hosted else "A command-line client"
renewal: Final = "" if hosted else " <code>lite logout</code> stops it from being renewed."
return f"""<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="referrer" content="no-referrer">
<title>Authorize CLI access - LiteLLM</title>
<title>{title} - LiteLLM</title>
<style>
body {{
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
@ -57,9 +61,9 @@ button {{ flex: 1; padding: 10px; border-radius: 6px; font-size: 15px; cursor: p
</head>
<body>
<div class="container">
<h1>Authorize CLI access</h1>
<p>A command-line client at <code>{escape(client_origin)}</code> wants to call LiteLLM as <strong>{escape(user_id)}</strong>.</p>
<p>Approving issues it a personal credential that expires within {CLI_JWT_EXPIRATION_HOURS} hours. <code>lite logout</code> stops it from being renewed. Only approve if you started this sign-in yourself.</p>
<h1>{title}</h1>
<p>{client_type} at <code>{escape(client_origin)}</code> wants to call LiteLLM as <strong>{escape(user_id)}</strong>.</p>
<p>Approving issues it a personal credential that expires within {CLI_JWT_EXPIRATION_HOURS} hours.{renewal} Only approve if you started this sign-in yourself.</p>
<form method="post" action="{escape(complete_url)}">
<input type="hidden" name="flow" value="{escape(flow_handle)}">
{_team_field(teams)}

View file

@ -74,6 +74,7 @@ CODE_CHALLENGE = urlsafe_b64encode(hashlib.sha256(CODE_VERIFIER.encode("ascii"))
@pytest.fixture(autouse=True)
def _salt_key(monkeypatch):
monkeypatch.setenv("LITELLM_SALT_KEY", MASTER_KEY)
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", raising=False)
def _request(path="/authorize", query="", cookies=None, method="GET"):
@ -1540,8 +1541,7 @@ async def test_native_authorize_validation_failures_never_reach_consent():
@pytest.mark.asyncio
async def test_native_authorize_refuses_a_hosted_redirect_for_the_proxy_api():
"""Registration accepts any https redirect because MCP clients can be hosted, but a
proxy-API grant hands out the user's personal key, so it only ever goes back to loopback."""
"""Public MCP registration must not grant permission to receive proxy credentials."""
hosted = "https://evil.example/cb"
client_id = (await _register([hosted]))["client_id"]
lookup = _ConsentTeams()
@ -1549,12 +1549,114 @@ async def test_native_authorize_refuses_a_hosted_redirect_for_the_proxy_api():
assert response.status_code == 400
assert json.loads(response.body) == {
"error": "invalid_request",
"error_description": "a proxy-API grant may only redirect to a loopback address",
"error_description": (
"a proxy-API grant may only redirect to a loopback address or an explicitly allowed HTTPS callback"
),
}
assert "set-cookie" not in response.headers
assert lookup.calls == []
@pytest.mark.asyncio
async def test_explicit_hosted_callback_preserves_consent_pkce_identity_and_one_use(
monkeypatch: pytest.MonkeyPatch,
) -> None:
hosted: Final = "https://admin.example/oauth/callback"
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", hosted)
client_id: Final = (await _register([hosted]))["client_id"]
login: Final = await _native_authorize(client_id, redirect_uri=hosted, session_user_id=None)
assert login.status_code == 303
assert urlparse(login.headers["location"]).path == "/sso/key/generate"
invalid_pkce: Final = await _native_authorize(client_id, redirect_uri=hosted, code_challenge_method="plain")
assert invalid_pkce.status_code == 400
consent: Final = await _native_authorize(client_id, redirect_uri=hosted)
assert consent.status_code == 200
assert "Authorize application access" in consent.body.decode()
assert "<code>https://admin.example</code>" in consent.body.decode()
cache: Final = DualCache()
approved: Final = await _complete_consent(consent, cache=cache, decision="approve", team_id="team-b")
assert approved.headers["location"].startswith(hosted + "?")
code: Final = _code_from(approved)
minter: Final = _Minter()
stolen: Final = await _redeem(
code,
client_id,
redirect_uri=hosted,
cache=cache,
code_verifier="wrong-" + "v" * 43,
resource=PROXY_API_RESOURCE,
mint_proxy_credential=minter,
)
assert stolen.status_code == 400
assert minter.calls == []
redeemed: Final = await _redeem(
code,
client_id,
redirect_uri=hosted,
cache=cache,
resource=PROXY_API_RESOURCE,
mint_proxy_credential=minter,
)
assert redeemed.status_code == 200
assert json.loads(redeemed.body)["user_id"] == "u1"
assert json.loads(redeemed.body)["team_id"] == "team-b"
replay: Final = await _redeem(
code,
client_id,
redirect_uri=hosted,
cache=cache,
resource=PROXY_API_RESOURCE,
mint_proxy_credential=minter,
)
assert replay.status_code == 400
assert json.loads(replay.body)["error"] == "invalid_grant"
@pytest.mark.asyncio
@pytest.mark.parametrize(
"hosted",
[
"https://admin.example/other",
"https://admin.example/oauth/callback/child",
"https://admin.example.evil.example/oauth/callback",
"https://sub.admin.example/oauth/callback",
"https://admin.example/oauth/callback?next=https://evil.example",
"https://admin.example:444/oauth/callback",
],
)
async def test_hosted_callback_allowlist_requires_exact_uri(monkeypatch: pytest.MonkeyPatch, hosted: str) -> None:
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", "https://admin.example/oauth/callback")
client_id: Final = (await _register([hosted]))["client_id"]
lookup: Final = _ConsentTeams()
response: Final = await _native_authorize(client_id, redirect_uri=hosted, lookup=lookup)
assert response.status_code == 400
assert "location" not in response.headers
assert lookup.calls == []
@pytest.mark.asyncio
@pytest.mark.parametrize(
"hosted", ("https://admin.example/oauth/callback?", "https://admin.example/oauth/callback?next=other")
)
async def test_hosted_allowlist_cannot_enable_query_callbacks(monkeypatch: pytest.MonkeyPatch, hosted: str) -> None:
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", hosted)
client_id: Final = (await _register([hosted]))["client_id"]
lookup: Final = _ConsentTeams()
response: Final = await _native_authorize(client_id, redirect_uri=hosted, lookup=lookup)
assert response.status_code == 400
assert lookup.calls == []
@pytest.mark.asyncio
async def test_hosted_callback_allowlist_does_not_replace_client_registration(monkeypatch: pytest.MonkeyPatch) -> None:
hosted: Final = "https://admin.example/oauth/callback"
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", hosted)
client_id: Final = (await _register([LOOPBACK_REDIRECT_URI]))["client_id"]
response: Final = await _native_authorize(client_id, redirect_uri=hosted)
assert response.status_code == 400
assert "not registered" in json.loads(response.body)["error_description"]
@pytest.mark.asyncio
@pytest.mark.parametrize(
"failure, status, error",

View file

@ -1,5 +1,3 @@
from litellm.constants import CLI_JWT_EXPIRATION_HOURS
from litellm.proxy.common_utils.html_forms.native_client_consent import render_native_client_consent_page
@ -65,3 +63,12 @@ def test_consent_page_promises_only_what_logout_can_deliver():
assert f"expires within {CLI_JWT_EXPIRATION_HOURS} hours" in page
assert "<code>lite logout</code> stops it from being renewed" in page
assert "revoked" not in page
def test_hosted_consent_names_the_web_application_without_terminal_instructions():
page = _render(hosted=True, client_origin="https://admin.example")
assert "Authorize application access" in page
assert "A web application at <code>https://admin.example</code>" in page
assert "lite logout" not in page
assert 'name="decision" value="approve"' in page
assert 'name="decision" value="deny"' in page