mirror of
https://github.com/BerriAI/litellm.git
synced 2026-11-18 09:45:23 +00:00
feat(auth): allow explicitly trusted hosted proxy OAuth callbacks
This commit is contained in:
parent
3106d9c573
commit
445c1cc0e0
5 changed files with 169 additions and 18 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)}
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue