feat(auth): authorize hosted administrator applications through gateway SSO
Some checks failed
LiteLLM Rust / rust-lint (push) Has been cancelled
LiteLLM Rust / rust-test (push) Has been cancelled
LiteLLM Rust / rust-wheel (push) Has been cancelled
Terraform Modules / fmt, validate, test (aws) (push) Has been cancelled
Terraform Modules / fmt, validate, test (gcp) (push) Has been cancelled
Terraform Provider / gofmt, vet, build, test (push) Has been cancelled
Terraform Provider / Provider endpoints vs proxy OpenAPI schema (push) Has been cancelled

This commit is contained in:
Tin Chi Lo 2026-10-01 13:23:05 -07:00
parent ec605826d4
commit cb10fd0cdc
15 changed files with 2059 additions and 32 deletions

View file

@ -787,6 +787,9 @@ class RedisCache(BaseCache):
def _async_commands(self) -> _AsyncRedisCommands:
return self.init_async_client()
async def async_eval(self, script: str, numkeys: int, *keys_and_args: str | bytes | float) -> object:
return await self._async_commands().eval(script, numkeys, *keys_and_args)
def check_and_fix_namespace(self, key: str) -> str:
"""
Make sure each key starts with the given namespace

View file

@ -31,6 +31,36 @@ 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 access through the gateway's configured SSO provider. Proxy-API OAuth grants accept loopback redirects by default. Hosted access requires shared Redis and an exact callback URI configured on every gateway replica:
```shell
LITELLM_PROXY_API_OAUTH_REDIRECT_URIS=https://reports.example.com/oauth/callback
LITELLM_PROXY_API_OAUTH_ADMIN_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 register callbacks operated by trusted applications
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
The default `proxy:read` scope permits only GET requests to `/models`, `/v1/models`, `/global/activity`, `/global/activity/model`, `/global/spend`, `/global/spend/provider`, and `/global/spend/report`. Global reports also require the user's current proxy administrator or administrator viewer role. The selected team records attribution and requires current membership; it does not narrow an administrator's global reporting permissions. Credential/configuration endpoints, request contents, writes, and LLM calls are denied
Applications needing administrative access must explicitly request `scope=proxy:admin`. Only callbacks in `LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS` can receive it, and the consenting user must remain a full `proxy_admin`. This scope permits gateway management, usage, and model-inference APIs through their existing authorization checks. Authentication, credential delegation, vault, passthrough, and master-key-only routes are excluded. The consent screen lists these powers and model charges. Scope is fixed at consent and cannot increase on refresh
Discover support using `/.well-known/litellm-cli-auth`. Its `hosted_app` object advertises enabled scopes and token lifetimes; clients should check that contract instead of a gateway version or image tag. Configure the gateway URL and trusted callback once, then use normal gateway releases
Hosted access tokens expire after five minutes. Each user/application grant expires 24 hours after consent, including all refreshes. Refresh rotates both tokens; clients must serialize refresh requests and replace their saved pair. Already-issued access tokens remain valid until their original expiry so admitted work can finish. Do not retry an uncertain refresh; reconnect instead. A grant permits at most 512 refreshes, bounding replay-detection storage. Replaying a spent refresh token revokes the entire grant, including current API access. Send the current or spent refresh token, or an issued access token, and its `client_id` to `POST /revoke` when disconnecting. Demoting an administrative grant holder, deleting a user, deactivating them, removing their selected team membership, or blocking that team also stops access
Every authorized request reads the grant from shared Redis and the current user/team from the database. There is no local-cache or stale-permission fallback. Missing grants, Redis loss, database errors, and removed callback trust deny access. Callback configuration changes must reach every replica before removal is effective across the deployment. Grant records are separated by the gateway master key; rotating it invalidates hosted grants. Configure `PROXY_BASE_URL` consistently across replicas and use the same Redis namespace
Hosted issuance, refresh, and API access are disabled whenever `custom_auth` is configured or `enable_oauth2_auth` or `enable_oauth2_proxy_auth` is enabled. A custom hook also disables hosted access when its enterprise mode is `off`. Arbitrary custom or external identity and permission rules cannot safely be combined with these grants. Revocation remains available, including with expired or rotated access tokens, so existing grants can still be disconnected. Enabling an exclusive auth mode denies existing hosted grants; disabling it can restore unexpired grants that were not revoked
The hosted application's server must retain the PKCE verifier, verify OAuth state on return, exchange the code server-side, and keep both tokens out of browser storage. Give the browser a Secure, HttpOnly session cookie with CSRF protection. Its logout/disconnect handler must call `/revoke` before discarding the server session. The gateway never sends an access token in a redirect URL
Native loopback CLI grants and MCP grants retain their existing permissions. Hosted clients cannot use the native IdP token-exchange grant. Refresh tokens from earlier builds that issued personal credentials to hosted callbacks require a new sign-in. Previously issued personal access credentials cannot be distinguished from CLI credentials and remain valid until their original expiry; rotate the gateway's credential encryption key if they must be invalidated immediately. Removing the image override alone does not revoke those old credentials
---
### Folder Structure

View file

@ -344,10 +344,10 @@ async def load_active_user_by_id(
return "no_active_key"
if user_object is None:
return "no_active_key"
return _active_user_record(user_object)
return active_user_record(user_object)
def _active_user_record(user_object: "LiteLLM_UserTable") -> "LiteLLM_UserTable | Literal['no_active_key']":
def active_user_record(user_object: "LiteLLM_UserTable") -> "LiteLLM_UserTable | Literal['no_active_key']":
if isinstance(user_object.metadata, dict) and user_object.metadata.get("scim_active") is False:
return "no_active_key"
return user_object
@ -514,7 +514,7 @@ async def _resolve_jwt_auth(
parent_otel_span=None,
proxy_logging_obj=proxy_logging_obj,
)
if identity.user_object is not None and isinstance(_active_user_record(identity.user_object), str):
if identity.user_object is not None and isinstance(active_user_record(identity.user_object), str):
return None
return identity
authorized: Final = await JWTAuthManager.authorize_jwt(
@ -531,7 +531,7 @@ async def _resolve_jwt_auth(
request_method=request.method,
)
resolved_user: Final = authorized["user_object"]
if resolved_user is not None and isinstance(_active_user_record(resolved_user), str):
if resolved_user is not None and isinstance(active_user_record(resolved_user), str):
return None
return JWTAuthManager.user_api_key_auth_from_result(authorized)
except Exception as exc: # noqa: BLE001 # public OAuth exchange stays available; unvalidated identities never write credentials

View file

@ -1974,6 +1974,7 @@ async def authorize(
response_type=response_type,
session_user_id=_session_cookie_user_id(request),
lookup_consent_teams=lookup_consent_teams,
scope=scope,
)
return aggregate_authorize(
request=request,

View file

@ -50,11 +50,28 @@ from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
from fastapi import HTTPException, Request
from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse, Response
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
from typing_extensions import NotRequired, ReadOnly, TypedDict, assert_never
from litellm._logging import verbose_logger
from litellm.caching.caching import DualCache
from litellm.proxy._experimental.mcp_server.bridge_token_flow import load_active_user_by_id
from litellm.proxy._experimental.mcp_server.hosted_proxy_auth import (
HOSTED_ACCESS_PREFIX,
HOSTED_ACCESS_TTL,
HOSTED_ADMIN_SCOPE,
HOSTED_GRANT_TTL,
HOSTED_REFRESH_PREFIX,
HOSTED_SCOPE,
HostedFailure,
HostedProxyAuth,
HostedScope,
HostedTokens,
hosted_proxy_auth,
hosted_redirect_is_allowed,
hosted_scope_allows_role,
hosted_supported_scopes,
)
from litellm.proxy._experimental.mcp_server.oauth_utils import (
TOKEN_NO_CACHE_HEADERS,
canonical_resource_uri,
@ -302,6 +319,7 @@ class _ConnectFlow(BaseModel):
exp: int
resource_server_id: str | None = None
audience: SessionAudience | None = None
hosted_scope: HostedScope | None = None
class _GatewayAuthCode(BaseModel):
@ -321,6 +339,7 @@ class _GatewayAuthCode(BaseModel):
resource_server_id: str | None = None
audience: SessionAudience | None = None
team_id: str | None = None
hosted_scope: HostedScope | None = None
def is_gateway_dcr_client_id(client_id: str | None) -> bool:
@ -401,13 +420,15 @@ async def register_aggregate_client(
"invalid_redirect_uri",
f"redirect_uris must be a list of 1 to {MAX_REDIRECT_URIS} URIs",
)
if not all(isinstance(uri, str) and len(uri) <= MAX_REDIRECT_URI_LENGTH for uri in raw_uris):
candidates: Final = TypeAdapter(tuple[object, ...]).validate_python(raw_uris)
if not all(isinstance(uri, str) and len(uri) <= MAX_REDIRECT_URI_LENGTH for uri in candidates):
return _oauth_error(
400,
"invalid_redirect_uri",
f"each redirect URI must be a string of at most {MAX_REDIRECT_URI_LENGTH} characters",
)
for uri in raw_uris:
redirect_uris: Final = tuple(uri for uri in candidates if isinstance(uri, str))
for uri in redirect_uris:
parsed = urlparse(uri)
try:
if validate_redirect_uri_shape(parsed):
@ -425,7 +446,7 @@ async def register_aggregate_client(
)
now: Final = datetime.now(timezone.utc)
client_id: Final = _seal(
GATEWAY_DCR_CLIENT_ID_PREFIX, GatewayDcrClient(redirect_uris=tuple(raw_uris), iat=int(now.timestamp()))
GATEWAY_DCR_CLIENT_ID_PREFIX, GatewayDcrClient(redirect_uris=redirect_uris, iat=int(now.timestamp()))
)
if len(client_id) > MAX_CLIENT_ID_LENGTH:
return _oauth_error(400, "invalid_client_metadata", "registered metadata is too large")
@ -434,9 +455,11 @@ async def register_aggregate_client(
content={
"client_id": client_id,
"client_id_issued_at": int(now.timestamp()),
"redirect_uris": list(raw_uris),
"redirect_uris": redirect_uris,
"token_endpoint_auth_method": "none",
"grant_types": list(supported_grant_types(token_exchange_available)),
"grant_types": supported_grant_types(
token_exchange_available and all(is_loopback_redirect_host(urlparse(uri)) for uri in redirect_uris)
),
"response_types": ["code"],
},
)
@ -553,6 +576,16 @@ def aggregate_authorize(
return response
def _proxy_redirect_is_allowed(
audience: SessionAudience | None, redirect_uri: str, hosted_scope: HostedScope | None = None
) -> bool:
return (
audience != PROXY_API_AUDIENCE
or is_loopback_redirect_host(urlparse(redirect_uri))
or hosted_redirect_is_allowed(redirect_uri, hosted_scope or HOSTED_SCOPE)
)
async def native_client_authorize(
request: Request,
client_id: str,
@ -563,24 +596,39 @@ async def native_client_authorize(
response_type: str | None,
session_user_id: str | None,
lookup_consent_teams: LookupConsentTeams,
scope: str | None = None,
) -> 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 scope not in (None, HOSTED_SCOPE, HOSTED_ADMIN_SCOPE):
return _oauth_error(400, "invalid_scope", "the requested hosted application scope is not supported")
hosted_scope: Final[HostedScope | None] = (
(HOSTED_ADMIN_SCOPE if scope == HOSTED_ADMIN_SCOPE else HOSTED_SCOPE) if is_hosted else None
)
if is_hosted and not hosted_redirect_is_allowed(redirect_uri, hosted_scope or HOSTED_SCOPE):
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)
if hosted_scope == HOSTED_ADMIN_SCOPE:
user: Final = await load_active_user_by_id(session_user_id, source="database")
if isinstance(user, str):
return _consent_lookup_failure_response(user)
if not hosted_scope_allows_role(hosted_scope, user.user_role):
return _oauth_error(403, "access_denied", "application administration requires a current proxy admin")
teams: Final = await lookup_consent_teams(session_user_id)
if not isinstance(teams, tuple):
return _consent_lookup_failure_response(teams)
@ -593,6 +641,7 @@ async def native_client_authorize(
code_challenge=code_challenge or "",
resource_server_id=None,
audience=PROXY_API_AUDIENCE,
hosted_scope=hosted_scope,
)
page: Final = render_native_client_consent_page(
client_origin=_origin_only(redirect_uri),
@ -600,6 +649,8 @@ 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,
hosted_admin=hosted_scope == HOSTED_ADMIN_SCOPE,
)
response: Final = HTMLResponse(page, headers=_CONSENT_PAGE_HEADERS)
_set_flow_cookie(response, request, handle, flow)
@ -619,6 +670,12 @@ NATIVE_CLIENT_AUTH_CONTRACT_VERSION: Final = 1
Bump it only when an existing field changes meaning or goes away; adding fields is free."""
class HostedAppAuthContract(TypedDict):
scopes_supported: ReadOnly[tuple[HostedScope, ...]]
access_token_ttl: ReadOnly[int]
refresh_token_ttl: ReadOnly[int]
class NativeClientAuthContract(TypedDict):
contract_version: ReadOnly[int]
issuer: ReadOnly[str]
@ -632,6 +689,7 @@ class NativeClientAuthContract(TypedDict):
code_challenge_methods_supported: ReadOnly[tuple[str, ...]]
token_endpoint_auth_methods_supported: ReadOnly[tuple[str, ...]]
revocation_endpoint_auth_methods_supported: ReadOnly[tuple[str, ...]]
hosted_app: ReadOnly[HostedAppAuthContract]
def native_client_auth_contract(request: Request, token_exchange_available: bool) -> NativeClientAuthContract:
@ -653,6 +711,11 @@ def native_client_auth_contract(request: Request, token_exchange_available: bool
"code_challenge_methods_supported": ("S256",),
"token_endpoint_auth_methods_supported": ("none",),
"revocation_endpoint_auth_methods_supported": ("none",),
"hosted_app": {
"scopes_supported": hosted_supported_scopes(),
"access_token_ttl": HOSTED_ACCESS_TTL,
"refresh_token_ttl": HOSTED_GRANT_TTL,
},
}
return contract
@ -705,6 +768,7 @@ def _new_connect_flow(
code_challenge: str,
resource_server_id: str | None,
audience: SessionAudience | None,
hosted_scope: HostedScope | None = None,
) -> _ConnectFlow:
now: Final = datetime.now(timezone.utc)
return _ConnectFlow(
@ -717,6 +781,7 @@ def _new_connect_flow(
exp=int(now.timestamp()) + CONNECT_FLOW_TTL_SECONDS,
resource_server_id=resource_server_id,
audience=audience,
hosted_scope=hosted_scope,
)
@ -876,6 +941,8 @@ async def complete_connect_flow(
opened: Final = _open_flow_for(request, flow_handle, session_user_id, now)
if isinstance(opened, Response):
return opened
if not _proxy_redirect_is_allowed(opened.audience, opened.redirect_uri, opened.hosted_scope):
return _oauth_error(400, "invalid_request", "the application's callback is no longer trusted")
if decision != "deny":
described: Final = await _describe_opened_flow(opened, lookup_vendor_credential, lookup_server_reachability)
if isinstance(described, Response):
@ -927,6 +994,7 @@ def _approved_flow_response(flow: _ConnectFlow, delivery: str | None, team_id: s
resource_server_id=flow.resource_server_id,
audience=flow.audience,
team_id=(team_id or None) if flow.audience == PROXY_API_AUDIENCE else None,
hosted_scope=flow.hosted_scope,
),
)
callback_url: Final = _append_query_params(flow.redirect_uri, (("code", code), *_state_param(flow)))
@ -1193,6 +1261,7 @@ async def aggregate_token(
subject_token_type: str | None = None,
requested_token_type: str | None = None,
exchange_subject_token: ExchangeSubjectToken = _refuse_subject_token,
hosted_auth: HostedProxyAuth | None = None,
) -> Response:
"""The aggregate token verb: authorization_code and refresh_token grants for the
identity-only session pair, or for the proxy-API credential when the grant was issued
@ -1215,6 +1284,7 @@ async def aggregate_token(
reload_user=reload_user,
mint_proxy_credential=mint_proxy_credential,
guard=_SingleUseGuard(cache),
hosted_auth=hosted_auth,
)
if grant_type == "authorization_code":
return await _authorization_code_grant(
@ -1236,6 +1306,7 @@ async def aggregate_token(
keys=keys,
now=now,
issue=issue,
hosted_auth=hosted_auth,
)
if grant_type == TOKEN_EXCHANGE_GRANT_TYPE:
return await _token_exchange_grant(
@ -1268,6 +1339,7 @@ class _GrantIssuer:
reload_user: ReloadUser,
mint_proxy_credential: MintProxyCredential,
guard: _SingleUseGuard,
hosted_auth: HostedProxyAuth | None = None,
) -> None:
self._request: Final = request
self._resource: Final = resource
@ -1276,6 +1348,7 @@ class _GrantIssuer:
self._reload_user: Final = reload_user
self._mint_proxy_credential: Final = mint_proxy_credential
self._guard: Final = guard
self._hosted_auth: Final = hosted_auth
async def __call__(
self, principal: SessionPrincipal, claim_key: str, claim_ttl_seconds: int, replayed: str
@ -1313,12 +1386,38 @@ class _GrantIssuer:
return refusal
return _proxy_credential_response(minted, principal, self._keys, self._now)
async def issue_hosted(self, code: _GatewayAuthCode) -> Response:
if code.hosted_scope is None:
return _oauth_error(400, "invalid_grant", "restart application sign-in to grant an explicit scope")
target_refusal: Final = self._proxy_api_target_refusal()
if target_refusal is not None:
return target_refusal
service: Final = self._hosted_auth or hosted_proxy_auth()
if isinstance(service, HostedFailure):
return _hosted_token_response(service)
return _hosted_token_response(
await service.issue(
code.user_id,
code.team_id,
code.client_id,
code.redirect_uri,
get_request_base_url(self._request),
code.jti,
code.hosted_scope,
)
)
async def exchange(
self, subject_token: str, client_id: str, exchange_subject_token: ExchangeSubjectToken
) -> Response:
"""The RFC 8693 tail: prove the IdP token, then mint. No single-use marker, because
the subject token stays a valid proof for as long as the IdP says it is and every
exchange mints a fresh credential and refresh token of its own."""
client: Final = open_gateway_dcr_client(client_id)
if client is None or any(not is_loopback_redirect_host(urlparse(uri)) for uri in client.redirect_uris):
return _oauth_error(
400, "unauthorized_client", "hosted applications must use the consented authorization-code flow"
)
target_refusal: Final = self._proxy_api_target_refusal()
if target_refusal is not None:
return target_refusal
@ -1371,6 +1470,10 @@ async def _authorization_code_grant(
return _oauth_error(400, "invalid_target", "resource does not match the scope this code was issued for")
if not _pkce_verifier_matches(code_verifier, parsed.code_challenge):
return _oauth_error(400, "invalid_grant", "PKCE verification failed")
if not _proxy_redirect_is_allowed(parsed.audience, parsed.redirect_uri, parsed.hosted_scope):
return _oauth_error(400, "invalid_grant", "the application's callback is no longer trusted")
if parsed.audience == PROXY_API_AUDIENCE and not is_loopback_redirect_host(urlparse(parsed.redirect_uri)):
return await issue.issue_hosted(parsed)
# The marker's TTL derives from the code's own remaining lifetime so it outlives
# whichever lifetime the code was minted with.
return await issue(
@ -1395,12 +1498,31 @@ async def _refresh_token_grant(
keys: SessionSigningKeys,
now: datetime,
issue: _GrantIssuer,
hosted_auth: HostedProxyAuth | None = None,
) -> Response:
if not refresh_token:
return _oauth_error(400, "invalid_request", "refresh_token is required")
if refresh_token.startswith(HOSTED_REFRESH_PREFIX):
if resource is not None and not is_proxy_api_resource(request, resource):
return _oauth_error(400, "invalid_target", "resource does not match the hosted grant")
service: Final = hosted_auth or hosted_proxy_auth()
return _hosted_token_response(
service
if isinstance(service, HostedFailure)
else await service.refresh(
refresh_token,
client_id,
get_request_base_url(request),
)
)
opened: Final = open_session_refresh_bearer(refresh_token, keys, now, expected_client_id=client_id)
if not isinstance(opened, SessionRefreshOpened):
return _oauth_error(400, "invalid_grant", "the refresh token is invalid for this client")
client: Final = open_gateway_dcr_client(client_id)
if opened.principal.audience == PROXY_API_AUDIENCE and (
client is None or any(not is_loopback_redirect_host(urlparse(uri)) for uri in client.redirect_uris)
):
return _oauth_error(400, "invalid_grant", "this application must sign in again for a restricted grant")
if _resource_conflicts_with_scope(request, resource, opened.principal.resource_server_id):
return _oauth_error(400, "invalid_target", "resource does not match the scope this token was issued for")
# Refresh-token rotation (OAuth 2.0 Security BCP section 4.13): the presented refresh token is
@ -1440,7 +1562,19 @@ async def _token_exchange_grant(
return await issue.exchange(subject_token, client_id, exchange_subject_token)
async def revoke_refresh_token(token: str, client_id: str, master_key: str | None, cache: DualCache) -> Response:
def _hosted_token_response(result: HostedTokens | HostedFailure) -> Response:
if isinstance(result, HostedFailure):
return _oauth_error(503 if result.error == "temporarily_unavailable" else 400, result.error, result.description)
return JSONResponse(content=result.model_dump(), headers=TOKEN_NO_CACHE_HEADERS)
async def revoke_refresh_token(
token: str,
client_id: str,
master_key: str | None,
cache: DualCache,
hosted_auth: HostedProxyAuth | None = None,
) -> Response:
"""RFC 7009 revocation for the gateway's refresh tokens: burn the presented token's
``jti`` so neither the holder nor a thief can rotate it again. Access tokens are
stateless and expire on their own (the proxy-API credential within
@ -1451,6 +1585,12 @@ async def revoke_refresh_token(token: str, client_id: str, master_key: str | Non
never happened."""
if not is_gateway_dcr_client_id(client_id) or open_gateway_dcr_client(client_id) is None:
return _oauth_error(401, "invalid_client", "unknown or malformed client_id")
if token.startswith((HOSTED_ACCESS_PREFIX, HOSTED_REFRESH_PREFIX)):
service: Final = hosted_auth or hosted_proxy_auth()
result: Final = service if isinstance(service, HostedFailure) else await service.revoke(token, client_id)
if isinstance(result, HostedFailure):
return _hosted_token_response(result)
return Response(content="{}", media_type="application/json", headers=TOKEN_NO_CACHE_HEADERS)
if master_key is None:
verbose_logger.error("mcp_gateway_dcr revoke rejected: no master_key configured")
return _oauth_error(500, "server_error", "the gateway has no master key configured")

View file

@ -0,0 +1,571 @@
from __future__ import annotations
import hashlib
import hmac
import os
import re
import secrets
from collections.abc import Mapping
from datetime import datetime, timezone
from functools import partial
from types import MappingProxyType
from typing import Final, Literal, Protocol, TypeAlias
from urllib.parse import urlparse
from fastapi import HTTPException, Request
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from litellm.caching.redis_cache import RedisCache
from litellm.proxy._experimental.mcp_server.oauth_utils import get_request_base_url, validate_redirect_uri_shape
from litellm.proxy._types import LiteLLMRoutes, LitellmUserRoles, UserAPIKeyAuth
from litellm.proxy.auth.route_checks import RouteChecks
HOSTED_ACCESS_PREFIX: Final = "llm_hosted_"
HOSTED_REFRESH_PREFIX: Final = "llm_hrefresh_"
HOSTED_ACCESS_TTL: Final = 300
HOSTED_GRANT_TTL: Final = 86400
MAX_HOSTED_REFRESHES: Final = 512
HOSTED_SCOPE: Final = "proxy:read"
HOSTED_ADMIN_SCOPE: Final = "proxy:admin"
HostedScope: TypeAlias = Literal["proxy:read", "proxy:admin"]
_MODEL_ROUTES: Final = frozenset({"/models", "/v1/models"})
_REPORT_ROUTES: Final = frozenset(
{"/global/activity", "/global/activity/model", "/global/spend", "/global/spend/provider", "/global/spend/report"}
)
_ADMIN_OPERATIONS: Final = (
"/budget/new",
"/budget/update",
"/budget/info",
"/budget/delete",
"/team/bulk_member_add",
"/team/model/add",
"/team/model/delete",
"/team/{team_id}/disable_logging",
)
_TOKEN_SHAPE: Final = re.compile(r"[A-Za-z0-9_-]{32}\.[A-Za-z0-9_-]{43}\Z")
def hosted_redirect_is_allowed(redirect_uri: str, scope: HostedScope = HOSTED_SCOPE) -> bool:
try:
parsed: Final = urlparse(redirect_uri)
if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:
return False
if "?" in redirect_uri or "#" in redirect_uri:
return False
validate_redirect_uri_shape(parsed)
except (HTTPException, ValueError):
return False
settings: Final = (
("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS",)
if scope == HOSTED_ADMIN_SCOPE
else ("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", "LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS")
)
return any(
redirect_uri in tuple(entry.strip() for entry in os.environ.get(setting, "").split(",")) for setting in settings
)
def hosted_supported_scopes() -> tuple[HostedScope, ...]:
callbacks: Final = tuple(
entry.strip()
for entry in (
os.environ.get("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", "")
+ ","
+ os.environ.get("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", "")
).split(",")
)
scopes: Final[tuple[HostedScope, ...]] = (HOSTED_SCOPE, HOSTED_ADMIN_SCOPE)
return tuple(scope for scope in scopes if any(hosted_redirect_is_allowed(uri, scope) for uri in callbacks))
def hosted_scope_allows_role(scope: HostedScope, user_role: LitellmUserRoles | str | None) -> bool:
return scope == HOSTED_SCOPE or user_role == LitellmUserRoles.PROXY_ADMIN
def _admin_route_allowed(route: str) -> bool:
if any(segment in (".", "..") for segment in route.split("/")):
return False
if route in (
*LiteLLMRoutes.master_key_only_routes.value,
"/user/password/change",
"/session/logout",
) or route.startswith(("/server/oauth/", "/sso/", "/jwt/", "/v1/mcp/server/oauth/")):
return False
if route.startswith("/v1/mcp/server/") and any(
segment in ("user-credential", "user-credentials", "oauth-user-credential", "user-env-vars")
for segment in route.split("/")
):
return False
if "/realtime/" in route and route.endswith(("/client_secrets", "/transcription_sessions")):
return False
groups: Final = (
LiteLLMRoutes.management_routes,
LiteLLMRoutes.self_managed_routes,
LiteLLMRoutes.org_admin_only_routes,
LiteLLMRoutes.admin_viewer_routes,
LiteLLMRoutes.info_routes,
LiteLLMRoutes.spend_tracking_routes,
LiteLLMRoutes.global_spend_tracking_routes,
LiteLLMRoutes.openai_routes,
LiteLLMRoutes.anthropic_routes,
LiteLLMRoutes.google_routes,
LiteLLMRoutes.model_info_routes,
)
return RouteChecks.check_route_access(route=route, allowed_routes=_ADMIN_OPERATIONS) or any(
RouteChecks.check_route_access(route=route, allowed_routes=group.value) for group in groups
)
class HostedFailure(BaseModel):
model_config = ConfigDict(frozen=True)
error: Literal["invalid_grant", "temporarily_unavailable", "insufficient_scope"] = "invalid_grant"
description: str = "the hosted application grant is no longer valid; sign in again"
class HostedAccess(BaseModel):
model_config = ConfigDict(frozen=True, extra="forbid")
token_hash: str
expires_at: int
class HostedGrant(BaseModel):
model_config = ConfigDict(frozen=True, extra="forbid")
grant_id: str
user_id: str
team_id: str | None
client_id: str
redirect_uri: str
resource: str
scope: HostedScope
expires_at: int
access_expires_at: int
access_hash: str
refresh_hash: str
refresh_count: int = Field(default=0, ge=0, le=MAX_HOSTED_REFRESHES)
previous_access: tuple[HostedAccess, ...] = Field(default=(), max_length=MAX_HOSTED_REFRESHES)
class HostedTokens(BaseModel):
model_config = ConfigDict(frozen=True)
access_token: str = Field(repr=False)
refresh_token: str = Field(repr=False)
user_id: str
team_id: str | None
expires_in: int
refresh_expires_in: int
token_type: Literal["Bearer"] = "Bearer"
scope: HostedScope = HOSTED_SCOPE
class HostedGrantStore(Protocol):
async def read(self, grant_id: str) -> HostedGrant | HostedFailure: ...
async def replace(self, grant: HostedGrant, previous: HostedGrant | None, ttl: int) -> bool: ...
async def delete(self, grant_id: str) -> None: ...
async def revoke_replayed(self, grant_id: str, token_hash: str) -> None: ...
_REPLACE_GRANT: Final = """
local current = redis.call('GET', KEYS[1])
if ARGV[1] == '' and redis.call('EXISTS', KEYS[2]) == 1 then
return 0
end
if (ARGV[1] == '' and not current) or current == ARGV[1] then
redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])
redis.call('SET', KEYS[2], '1', 'EX', ARGV[3])
if ARGV[4] ~= '' then
redis.call('SADD', KEYS[3], ARGV[4], ARGV[5])
redis.call('EXPIRE', KEYS[3], ARGV[3])
end
return 1
end
return 0
"""
_REVOKE_REPLAYED: Final = """
if redis.call('SISMEMBER', KEYS[2], ARGV[1]) == 1 then
return redis.call('DEL', KEYS[1])
end
return 0
"""
class RedisHostedGrantStore:
def __init__(self, cache: RedisCache, master_key: str) -> None:
self._cache: Final = cache
self._gateway: Final = hashlib.sha256(master_key.encode()).hexdigest()
def _key(self, grant_id: str) -> str:
return self._cache.check_and_fix_namespace(f"hosted_proxy_grant:{{{self._gateway}:{grant_id}}}")
async def read(self, grant_id: str) -> HostedGrant | HostedFailure:
value: Final = await self._cache.async_eval("return redis.call('GET', KEYS[1])", 1, self._key(grant_id))
if not isinstance(value, (str, bytes)):
return HostedFailure()
try:
return HostedGrant.model_validate_json(value)
except ValidationError:
return HostedFailure()
async def replace(self, grant: HostedGrant, previous: HostedGrant | None, ttl: int) -> bool:
result: Final = await self._cache.async_eval(
_REPLACE_GRANT,
3,
self._key(grant.grant_id),
self._key(grant.grant_id) + ":issued",
self._key(grant.grant_id) + ":spent",
previous.model_dump_json() if previous is not None else "",
grant.model_dump_json(),
ttl,
previous.refresh_hash if previous is not None else "",
previous.access_hash if previous is not None else "",
)
return isinstance(result, int) and result == 1
async def delete(self, grant_id: str) -> None:
await self._cache.async_eval("return redis.call('DEL', KEYS[1])", 1, self._key(grant_id))
async def revoke_replayed(self, grant_id: str, token_hash: str) -> None:
await self._cache.async_eval(
_REVOKE_REPLAYED, 2, self._key(grant_id), self._key(grant_id) + ":spent", token_hash
)
class LoadHostedUser(Protocol):
async def __call__(self, user_id: str, team_id: str | None, /) -> UserAPIKeyAuth | HostedFailure: ...
def _digest(token: str) -> str:
return hashlib.sha256(token.encode()).hexdigest()
def _grant_id(token: str, prefix: str) -> str | None:
if not token.startswith(prefix):
return None
suffix: Final = token.removeprefix(prefix)
return suffix.split(".", 1)[0] if _TOKEN_SHAPE.fullmatch(suffix) else None
def _unavailable() -> HostedFailure:
return HostedFailure(error="temporarily_unavailable", description="hosted application authorization is unavailable")
class HostedProxyAuth:
def __init__(self, store: HostedGrantStore, load_user: LoadHostedUser, now: datetime) -> None:
self._store: Final = store
self._load_user: Final = load_user
self._now: Final = int(now.timestamp())
async def issue(
self,
user_id: str,
team_id: str | None,
client_id: str,
redirect_uri: str,
resource: str,
code_id: str,
scope: HostedScope = HOSTED_SCOPE,
) -> HostedTokens | HostedFailure:
if not hosted_redirect_is_allowed(redirect_uri, scope):
return HostedFailure()
identity: Final = await self._load_user(user_id, team_id)
if isinstance(identity, HostedFailure):
return identity
if not hosted_scope_allows_role(scope, identity.user_role):
return HostedFailure(
error="insufficient_scope",
description="administrator access requires a current proxy administrator role",
)
return await self._mint(
HostedGrant(
grant_id=hashlib.sha256(code_id.encode()).hexdigest()[:32],
user_id=user_id,
team_id=team_id,
client_id=client_id,
redirect_uri=redirect_uri,
resource=resource,
scope=scope,
expires_at=self._now + HOSTED_GRANT_TTL,
access_expires_at=0,
access_hash="",
refresh_hash="",
),
previous=None,
)
async def _read(
self,
token: str,
prefix: str,
client_id: str | None,
resource: str | None,
*,
purpose: Literal["authenticate", "revoke"] = "authenticate",
) -> HostedGrant | HostedFailure:
grant_id: Final = _grant_id(token, prefix)
if grant_id is None:
return HostedFailure()
try:
grant: Final = await self._store.read(grant_id)
except Exception: # noqa: BLE001 # authorization must fail closed on every store failure
return _unavailable()
if isinstance(grant, HostedFailure):
return grant
if (
grant.grant_id != grant_id
or self._now >= grant.expires_at
or (client_id is not None and client_id != grant.client_id)
or (resource is not None and resource != grant.resource)
):
return HostedFailure()
candidates: Final = (
(HostedAccess(token_hash=grant.refresh_hash, expires_at=grant.expires_at),)
if prefix == HOSTED_REFRESH_PREFIX
else (
HostedAccess(token_hash=grant.access_hash, expires_at=grant.access_expires_at),
*grant.previous_access,
)
)
valid: Final = any(
hmac.compare_digest(_digest(token), candidate.token_hash)
and (self._now < candidate.expires_at or purpose == "revoke")
for candidate in candidates
)
if not valid:
if prefix == HOSTED_REFRESH_PREFIX or purpose == "revoke":
try:
await self._store.revoke_replayed(grant_id, _digest(token))
except Exception: # noqa: BLE001 # a failed replay revocation must not be hidden
return _unavailable()
return HostedFailure()
return grant
async def refresh(self, token: str, client_id: str, resource: str) -> HostedTokens | HostedFailure:
grant: Final = await self._read(token, HOSTED_REFRESH_PREFIX, client_id, resource)
if isinstance(grant, HostedFailure):
return grant
if grant.refresh_count >= MAX_HOSTED_REFRESHES:
return HostedFailure(description="the application's refresh limit was reached; sign in again")
if not hosted_redirect_is_allowed(grant.redirect_uri, grant.scope):
return HostedFailure()
identity: Final = await self._load_user(grant.user_id, grant.team_id)
if isinstance(identity, HostedFailure):
return identity
if not hosted_scope_allows_role(grant.scope, identity.user_role):
return HostedFailure(
error="insufficient_scope",
description="administrator access requires a current proxy administrator role",
)
return await self._mint(grant, previous=grant)
async def _mint(self, grant: HostedGrant, previous: HostedGrant | None) -> HostedTokens | HostedFailure:
access: Final = f"{HOSTED_ACCESS_PREFIX}{grant.grant_id}.{secrets.token_urlsafe(32)}"
refresh: Final = f"{HOSTED_REFRESH_PREFIX}{grant.grant_id}.{secrets.token_urlsafe(32)}"
expires_in: Final = min(HOSTED_ACCESS_TTL, grant.expires_at - self._now)
updated: Final = grant.model_copy(
update=MappingProxyType(
{
"access_hash": _digest(access),
"refresh_hash": _digest(refresh),
"access_expires_at": self._now + expires_in,
"refresh_count": grant.refresh_count + 1 if previous is not None else 0,
"previous_access": tuple(
access
for access in (
*grant.previous_access,
HostedAccess(token_hash=grant.access_hash, expires_at=grant.access_expires_at),
)
if access.expires_at > self._now
),
}
)
)
try:
stored: Final = await self._store.replace(updated, previous, grant.expires_at - self._now)
except Exception: # noqa: BLE001 # never issue a credential whose shared grant was not stored
return _unavailable()
if not stored:
if previous is not None:
try:
await self._store.revoke_replayed(grant.grant_id, previous.refresh_hash)
except Exception: # noqa: BLE001 # concurrent refresh replay invalidates the grant or fails closed
return _unavailable()
return HostedFailure()
return HostedTokens(
access_token=access,
refresh_token=refresh,
expires_in=expires_in,
refresh_expires_in=grant.expires_at - self._now,
user_id=grant.user_id,
team_id=grant.team_id,
scope=grant.scope,
)
async def authenticate(self, token: str, resource: str, route: str, method: str) -> UserAPIKeyAuth | HostedFailure:
grant: Final = await self._read(token, HOSTED_ACCESS_PREFIX, None, resource)
if isinstance(grant, HostedFailure):
return grant
if not hosted_redirect_is_allowed(grant.redirect_uri, grant.scope):
return HostedFailure()
allowed: Final = (
method == "GET" and route in _MODEL_ROUTES | _REPORT_ROUTES
if grant.scope == HOSTED_SCOPE
else _admin_route_allowed(route)
)
if not allowed:
return HostedFailure(
error="insufficient_scope", description="this application grant does not permit this route"
)
identity: Final = await self._load_user(grant.user_id, grant.team_id)
if isinstance(identity, HostedFailure):
return identity
if not hosted_scope_allows_role(grant.scope, identity.user_role):
return HostedFailure(
error="insufficient_scope",
description="administrator access requires a current proxy administrator role",
)
if route in _REPORT_ROUTES and identity.user_role not in (
LitellmUserRoles.PROXY_ADMIN,
LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY,
):
return HostedFailure(
error="insufficient_scope", description="global usage requires a current proxy administrator role"
)
return identity.model_copy(update=MappingProxyType({"token": _digest(token), "api_key": _digest(token)}))
async def revoke(self, token: str, client_id: str) -> HostedFailure | None:
prefix: Final = HOSTED_REFRESH_PREFIX if token.startswith(HOSTED_REFRESH_PREFIX) else HOSTED_ACCESS_PREFIX
grant: Final = await self._read(token, prefix, client_id, None, purpose="revoke")
if isinstance(grant, HostedFailure):
return grant if grant.error == "temporarily_unavailable" else None
try:
await self._store.delete(grant.grant_id)
except Exception: # noqa: BLE001 # a failed revocation must be reported as retryable
return _unavailable()
return None
class _HostedAuthSettings(BaseModel):
model_config = ConfigDict(frozen=True)
general_settings: Mapping[str, object]
user_custom_auth: object
class _UserModelBudget(BaseModel):
model_config = ConfigDict(frozen=True, from_attributes=True)
model_max_budget: Mapping[str, object] | None
async def load_hosted_user(user_id: str, team_id: str | None) -> UserAPIKeyAuth | HostedFailure:
from litellm.proxy import proxy_server # noqa: PLC0415 # startup-owned dependencies
from litellm.proxy._experimental.mcp_server.bridge_token_flow import (
active_user_record, # noqa: PLC0415 # shared offboarding policy, proxy import cycle
)
from litellm.proxy.auth.auth_checks import ( # noqa: PLC0415 # proxy import cycle
effective_user_role,
get_team_membership,
get_team_object,
get_user_object,
)
from litellm.proxy.auth.resolvers.grants import ( # noqa: PLC0415 # shared live identity resolution
GrantResolver,
LookupDegraded,
ResolvedGrants,
UserLookup,
user_models,
)
from litellm.proxy.auth.team_grants import team_grants # noqa: PLC0415 # shared team permission projection
from litellm.proxy.management_endpoints.ui_sso import (
fetch_cli_sso_team_details, # noqa: PLC0415 # existing live team selection rules
)
from litellm.proxy.proxy_server import ( # noqa: PLC0415 # startup-owned dependencies
prisma_client,
user_api_key_cache,
)
settings: Final = _HostedAuthSettings.model_validate(vars(proxy_server))
if (
settings.user_custom_auth is not None
or settings.general_settings.get("enable_oauth2_auth") is True
or settings.general_settings.get("enable_oauth2_proxy_auth") is True
):
return HostedFailure(
description="hosted application authorization is disabled while custom or external auth is configured"
)
if prisma_client is None:
return _unavailable()
resolved: Final = await GrantResolver(
prisma_client,
user_api_key_cache,
load_user=partial(get_user_object, check_db_only=True),
load_team=partial(get_team_object, check_db_only=True),
load_membership=partial(get_team_membership, check_db_only=True),
).resolve(UserLookup(user_id=user_id), team_id)
if isinstance(resolved, LookupDegraded):
return _unavailable()
if not isinstance(resolved, ResolvedGrants) or resolved.user_object is None:
return HostedFailure()
user: Final = active_user_record(resolved.user_object)
if isinstance(user, str):
return HostedFailure()
if team_id is None and user.teams:
teams: Final = await fetch_cli_sso_team_details(prisma_client, user.teams)
if teams is None:
return _unavailable()
if any(team.team_id is not None for team in teams):
return HostedFailure(description="select a current team and sign in again")
team: Final = resolved.team_object
if team is not None and team.blocked:
return HostedFailure()
return UserAPIKeyAuth.model_validate(
MappingProxyType(
{
"user_id": user.user_id,
"user_role": effective_user_role(user.user_role),
"user_email": user.user_email,
"user_tpm_limit": user.tpm_limit,
"user_rpm_limit": user.rpm_limit,
"user_spend": user.spend,
"user_max_budget": user.max_budget,
"user_model_max_budget": _UserModelBudget.model_validate(user).model_max_budget,
"team_id": team_id,
"org_id": team.organization_id if team is not None else user.organization_id,
"models": user_models(user) if team is None else (),
**team_grants(team, resolved.team_membership, user.user_id),
}
)
)
def hosted_proxy_auth() -> HostedProxyAuth | HostedFailure:
from litellm.proxy.proxy_server import ( # noqa: PLC0415 # startup-owned shared authority
master_key,
redis_usage_cache,
)
if redis_usage_cache is None or not isinstance(master_key, str) or not master_key:
return _unavailable()
return HostedProxyAuth(
RedisHostedGrantStore(redis_usage_cache, master_key), load_hosted_user, datetime.now(timezone.utc)
)
async def authenticate_hosted_request(request: Request, token: str, route: str) -> UserAPIKeyAuth:
service: Final = hosted_proxy_auth()
result: Final = (
service
if isinstance(service, HostedFailure)
else await service.authenticate(
token,
get_request_base_url(request),
route,
request.method,
)
)
if isinstance(result, HostedFailure):
status: Final = (
503 if result.error == "temporarily_unavailable" else 403 if result.error == "insufficient_scope" else 401
)
raise HTTPException(status_code=status, detail=result.description)
return result

View file

@ -3432,7 +3432,7 @@ class UserAPIKeyAuth(LiteLLM_VerificationTokenView): # the expected response ob
normalized = api_key
if normalized[:7].lower() == "bearer ":
normalized = normalized[7:]
if normalized.startswith("sk-"):
if normalized.startswith(("sk-", "llm_hosted_", "llm_hrefresh_")):
return hash_token(normalized)
from litellm.proxy.auth.handle_jwt import JWTHandler

View file

@ -2344,9 +2344,13 @@ async def _fetch_team_membership_from_db(
user_api_key_cache: UserApiKeyCache,
parent_otel_span: Span | None = None,
proxy_logging_obj: ProxyLogging | None = None,
*,
use_writer: bool = False,
) -> LiteLLM_TeamMembership | None:
_ = parent_otel_span, proxy_logging_obj
response: Final = await _dictable_table(TeamMembershipRepository(prisma_client), "team_membership").find_unique(
response: Final = await _dictable_table(
TeamMembershipRepository(prisma_client, use_writer=use_writer), "team_membership"
).find_unique(
where={"user_id_team_id": {"user_id": user_id, "team_id": team_id}},
include={"litellm_budget_table": True},
)
@ -2398,6 +2402,7 @@ async def get_team_membership(
user_api_key_cache: UserApiKeyCache,
parent_otel_span: Span | None = None,
proxy_logging_obj: ProxyLogging | None = None,
check_db_only: bool = False,
) -> Optional["LiteLLM_TeamMembership"]:
"""
Returns team membership object if user is member of team.
@ -2406,6 +2411,18 @@ async def get_team_membership(
"""
if user_id is None or team_id is None:
return None
if check_db_only:
if prisma_client is None:
raise RuntimeError("No db connected")
return await _fetch_team_membership_from_db(
user_id=user_id,
team_id=team_id,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
parent_otel_span=parent_otel_span,
proxy_logging_obj=proxy_logging_obj,
use_writer=True,
)
_key: Final = team_membership_reservation_cache_key(user_id=user_id, team_id=team_id)
@ -3181,7 +3198,7 @@ async def _get_team_object_from_user_api_key_cache(
use_writer: bool = False,
) -> LiteLLM_TeamTableCachedObj:
db_access_time_key: Final = key
should_check_db: Final = _should_check_db(
should_check_db: Final = use_writer or _should_check_db(
key=db_access_time_key,
last_db_access_time=last_db_access_time,
db_cache_expiry=db_cache_expiry,

View file

@ -1545,6 +1545,15 @@ async def _user_api_key_auth_builder(
parent_otel_span = getattr(request.state, "parent_otel_span", None)
### USER-DEFINED AUTH FUNCTION ###
from litellm.proxy._experimental.mcp_server.hosted_proxy_auth import ( # noqa: PLC0415 # hosted OAuth depends on proxy startup
HOSTED_ACCESS_PREFIX,
HOSTED_REFRESH_PREFIX,
authenticate_hosted_request,
)
if api_key and api_key.startswith((HOSTED_ACCESS_PREFIX, HOSTED_REFRESH_PREFIX)):
return await authenticate_hosted_request(request, api_key, route)
if enterprise_custom_auth is not None:
with tracer.trace("litellm.proxy.auth.enterprise_custom_auth"):
response = await enterprise_custom_auth(

View file

@ -12,18 +12,36 @@ def render_native_client_consent_page(
teams: Sequence[tuple[str, str]],
flow_handle: str,
complete_url: str,
hosted: bool = False,
hosted_admin: 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."
permission_text: Final = (
"Approving allows this application to manage keys, users, teams and models, read gateway logs and usage, "
"and call models using your current administrator permissions. Model calls can incur charges. "
"Access expires after five minutes and can be renewed for up to 24 hours. "
"Disconnecting the application revokes access immediately."
if hosted_admin
else "Approving permits read-only model listings and aggregate usage reports within your current permissions. "
"It does not permit changes, credential access, request contents, or LLM calls. "
"Access expires after five minutes and can be renewed for up to 24 hours. "
"Disconnecting the application revokes access immediately."
if hosted
else f"Approving issues it a personal credential that expires within {CLI_JWT_EXPIRATION_HOURS} hours.{renewal}"
)
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 +75,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>{permission_text} 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

@ -0,0 +1,307 @@
import hashlib
import json
import os
import re
import secrets
from base64 import urlsafe_b64encode
from contextlib import ExitStack
from pathlib import Path
from types import MappingProxyType
from typing import Final
from urllib.parse import parse_qs, urlsplit
import httpx
import pytest
from fastapi import HTTPException
from fastapi import Request as FastAPIRequest
from integration._support.client import Gateway
from integration._support.oauth_server import oauth_server
from integration._support.process import owned_proxy_process
from integration._support.wire import Reply, Request, wire_server
from litellm.caching.redis_cache import RedisCache
from litellm.proxy._experimental.mcp_server.hosted_proxy_auth import HostedFailure, HostedGrant, RedisHostedGrantStore
from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth
CALLBACK: Final = "https://admin.example/oauth/callback"
async def hosted_custom_policy(request: FastAPIRequest, api_key: str) -> UserAPIKeyAuth:
if api_key == os.environ["LITELLM_MASTER_KEY"]:
return UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN)
raise HTTPException(status_code=403, detail="custom policy denied this request")
@pytest.mark.asyncio
@pytest.mark.parametrize("spent_token", ["first-refresh", "first-access"])
async def test_shared_redis_atomically_consumes_codes_and_rejects_stale_refresh_writes(spent_token: str) -> None:
cache: Final = RedisCache(host=os.environ["REDIS_HOST"], port=int(os.environ["REDIS_PORT"]))
store: Final = RedisHostedGrantStore(cache, "sk-" + secrets.token_urlsafe(32))
grant: Final = HostedGrant(
grant_id=secrets.token_urlsafe(24),
user_id="user",
team_id=None,
client_id="client",
redirect_uri=CALLBACK,
resource="https://gateway.example",
scope="proxy:read",
expires_at=200,
access_expires_at=100,
access_hash="first-access",
refresh_hash="first-refresh",
)
rotated: Final = grant.model_copy(update={"access_hash": "second-access", "refresh_hash": "second-refresh"})
try:
assert await store.replace(grant, None, 60)
assert not await store.replace(grant, None, 60)
assert await store.replace(rotated, grant, 60)
assert not await store.replace(grant, grant, 60)
assert await store.read(grant.grant_id) == rotated
await store.revoke_replayed(grant.grant_id, "unknown-refresh")
assert await store.read(grant.grant_id) == rotated
await store.revoke_replayed(grant.grant_id, spent_token)
assert isinstance(await store.read(grant.grant_id), HostedFailure)
assert not await store.replace(grant, None, 60)
assert not await store.replace(grant, rotated, 60)
finally:
await store.delete(grant.grant_id)
await cache.disconnect()
@pytest.mark.timeout(300)
@pytest.mark.parametrize("exclusive_auth", ["custom_auth", "enable_oauth2_auth", "enable_oauth2_proxy_auth"])
@pytest.mark.parametrize("scope", ["proxy:read", "proxy:admin"])
def test_hosted_sso_return_permissions_refresh_and_revocation(
gateway: Gateway, tmp_path: Path, exclusive_auth: str, scope: str
) -> None:
with oauth_server(scopes=("openid", "email", "profile")) as idp:
email: Final = f"hosted-{secrets.token_hex(8)}@example.com"
def userinfo(request: Request) -> Reply:
token: Final = request.headers.get("authorization", "").removeprefix("Bearer ")
assert idp.is_live(token)
return Reply(body=json.dumps({"sub": email, "email": email, "role": "proxy_admin"}).encode())
with (
wire_server(userinfo) as profile,
owned_proxy_process(
gateway,
tmp_path,
MappingProxyType(
{
"LITELLM_PROXY_API_OAUTH_REDIRECT_URIS": CALLBACK,
"LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS": CALLBACK,
"GENERIC_CLIENT_ID": "hosted-sso-test",
"GENERIC_CLIENT_SECRET": "hosted-sso-test-secret",
"GENERIC_AUTHORIZATION_ENDPOINT": idp.issuer + "/authorize",
"GENERIC_TOKEN_ENDPOINT": idp.issuer + "/token",
"GENERIC_USERINFO_ENDPOINT": profile.url + "/userinfo",
"GENERIC_CLIENT_USE_PKCE": "true",
"GENERIC_USER_ID_ATTRIBUTE": "sub",
"GENERIC_USER_ROLE_ATTRIBUTE": "role",
}
),
remove_environment=("PROXY_BASE_URL", "GOOGLE_CLIENT_ID", "MICROSOFT_CLIENT_ID"),
) as owned,
owned.gateway.scenario() as scenario,
ExitStack() as peers,
):
user_id: Final = scenario.user(user_id=email, user_email=email, user_role="proxy_admin")
base: Final = str(owned.gateway.client.base_url).rstrip("/")
policy_config: Final = tmp_path / "custom-policy.yaml"
policy: Final = (
"custom_auth: integration.mcp.test_hosted_proxy_oauth.hosted_custom_policy"
if exclusive_auth == "custom_auth"
else f"{exclusive_auth}: true"
)
policy_config.write_text(
(Path(__file__).resolve().parents[1] / "proxy_config.yaml")
.read_text()
.replace(
"general_settings:\n",
f"general_settings:\n {policy}\n",
)
)
restricted: Final = peers.enter_context(owned_proxy_process(
gateway,
tmp_path,
{"PROXY_BASE_URL": base, "LITELLM_PROXY_API_OAUTH_REDIRECT_URIS": CALLBACK,
"LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS": CALLBACK},
config=policy_config,
))
verifier: Final = secrets.token_urlsafe(32)
challenge: Final = urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
registered: Final = owned.gateway.client.post("/register", json={"redirect_uris": [CALLBACK]})
assert registered.status_code == 201, registered.text
client_id: Final = registered.json()["client_id"]
assert registered.json()["grant_types"] == ["authorization_code", "refresh_token"]
with httpx.Client(base_url=base, follow_redirects=False, trust_env=False, timeout=15) as browser:
started: Final = browser.get(
"/authorize",
params={
"client_id": client_id,
"redirect_uri": CALLBACK,
"resource": base,
"response_type": "code",
"code_challenge": challenge,
"code_challenge_method": "S256",
"state": "hosted-client-state",
"scope": scope,
},
)
assert started.status_code == 303, started.text
assert urlsplit(started.headers["location"]).path == "/sso/key/generate"
login: Final = browser.get(started.headers["location"])
assert login.status_code in (302, 303, 307), login.text
assert login.headers["location"].startswith(idp.issuer + "/authorize")
idp_approved: Final = browser.get(login.headers["location"])
assert idp_approved.status_code == 302, idp_approved.text
returned: Final = browser.get(idp_approved.headers["location"])
assert returned.status_code == 303, returned.text
assert returned.headers["location"].startswith("/authorize?")
consent: Final = browser.get(returned.headers["location"])
assert consent.status_code == 200, consent.text
assert ("administrator permissions" if scope == "proxy:admin" else "read-only model listings") in consent.text
assert "personal credential" not in consent.text
handle: Final = re.search(r'name="flow" value="([^"]+)"', consent.text)
assert handle is not None, consent.text
approved: Final = browser.post(
"/authorize/complete", data={"flow": handle.group(1), "decision": "approve"}
)
assert approved.status_code == 303, approved.text
location: Final = approved.headers["location"]
assert location.startswith(CALLBACK + "?"), location
params: Final = parse_qs(urlsplit(location).query)
assert params["state"] == ["hosted-client-state"]
assert set(params) == {"code", "state"}
code: Final = params["code"][0]
exchange: Final = {
"grant_type": "authorization_code",
"code": code,
"redirect_uri": CALLBACK,
"client_id": client_id,
"code_verifier": verifier,
"resource": base,
}
stolen: Final = owned.gateway.client.post("/token", data={**exchange, "code_verifier": "x" * 43})
assert stolen.status_code == 400 and stolen.json()["error"] == "invalid_grant", stolen.text
blocked_issue: Final = restricted.gateway.client.post("/token", data=exchange)
assert blocked_issue.status_code == 400, blocked_issue.text
assert "custom or external auth is configured" in blocked_issue.json()["error_description"]
redeemed: Final = owned.gateway.client.post("/token", data=exchange)
assert redeemed.status_code == 200, redeemed.text
tokens: Final = redeemed.json()
assert tokens["scope"] == scope and tokens["user_id"] == user_id
headers: Final = {"Authorization": "Bearer " + tokens["access_token"]}
other_gateway: Final = Gateway(gateway.client, "sk-other-hosted-test-master", gateway.upstream_url)
with owned_proxy_process(
other_gateway,
tmp_path,
{"LITELLM_PROXY_API_OAUTH_REDIRECT_URIS": CALLBACK},
remove_environment=("PROXY_BASE_URL",),
) as other:
cross_gateway: Final = other.gateway.client.get(
"/v1/models",
headers={**headers, "Host": urlsplit(base).netloc},
)
assert cross_gateway.status_code == 401, cross_gateway.text
models: Final = owned.gateway.client.get("/v1/models", headers=headers)
assert models.status_code == 200, models.text
for method, route in (() if scope == "proxy:admin" else (
("POST", "/key/generate"),
("GET", "/key/info"),
("POST", "/v1/chat/completions"),
)):
denied: Final = owned.gateway.client.request(method, route, headers=headers, json={})
assert denied.status_code == 403, denied.text
if scope == "proxy:admin":
_exercise_admin(owned.gateway, headers, user_id)
demoted: Final = owned.gateway.request(
"POST", "/user/update", {"user_id": user_id, "user_role": "internal_user"}
)
assert demoted.status_code == 200, demoted.text
report: Final = owned.gateway.client.get("/global/spend", headers=headers)
assert report.status_code == 403, report.text
if scope == "proxy:admin":
denied_refresh: Final = owned.gateway.client.post("/token", data={
"grant_type": "refresh_token", "client_id": client_id,
"refresh_token": tokens["refresh_token"], "resource": base,
})
assert denied_refresh.status_code == 400, denied_refresh.text
promoted: Final = owned.gateway.request(
"POST", "/user/update", {"user_id": user_id, "user_role": "proxy_admin"}
)
assert promoted.status_code == 200, promoted.text
rotated: Final = owned.gateway.client.post(
"/token",
data={
"grant_type": "refresh_token",
"client_id": client_id,
"refresh_token": tokens["refresh_token"],
"resource": base,
},
)
assert rotated.status_code == 200, rotated.text
current: Final = rotated.json()
in_flight: Final = owned.gateway.client.get("/v1/models", headers=headers)
assert in_flight.status_code == 200, in_flight.text
blocked_access: Final = restricted.gateway.client.get(
"/v1/models", headers={"Authorization": "Bearer " + current["access_token"]}
)
assert blocked_access.status_code == 401, blocked_access.text
assert "custom or external auth is configured" in blocked_access.text
blocked_refresh: Final = restricted.gateway.client.post(
"/token",
data={
"grant_type": "refresh_token",
"client_id": client_id,
"refresh_token": current["refresh_token"],
"resource": base,
},
)
assert blocked_refresh.status_code == 400, blocked_refresh.text
assert "custom or external auth is configured" in blocked_refresh.json()["error_description"]
revoked: Final = restricted.gateway.client.post(
"/revoke", data={"token": current["refresh_token"], "client_id": client_id}
)
assert revoked.status_code == 200, revoked.text
after: Final = owned.gateway.client.get(
"/v1/models", headers={"Authorization": "Bearer " + current["access_token"]}
)
assert after.status_code == 401, after.text
replayed: Final = owned.gateway.client.post("/token", data=exchange)
assert replayed.status_code == 400, replayed.text
log: Final = owned.log.read_text()
assert tokens["access_token"] not in log
assert tokens["refresh_token"] not in log
def _exercise_admin(gateway: Gateway, headers: dict[str, str], user_id: str) -> None:
user: Final = gateway.client.get("/user/info", headers=headers)
assert user.status_code == 200 and user.json()["user_id"] == user_id, user.text
created: Final = gateway.client.post("/key/generate", headers=headers, json={"user_id": user_id})
assert created.status_code == 200, created.text
key: Final = created.json()["key"]
try:
fetched: Final = gateway.client.get("/key/info", headers=headers, params={"key": key})
assert fetched.status_code == 200 and fetched.json()["info"]["user_id"] == user_id, fetched.text
finally:
deleted: Final = gateway.client.post("/key/delete", headers=headers, json={"keys": [key]})
assert deleted.status_code == 200, deleted.text
def completion(request: Request) -> Reply:
assert request.target == "/v1/chat/completions"
assert json.loads(request.body)["messages"] == [{"role": "user", "content": "hosted grant"}]
return Reply(body=json.dumps({
"id": "hosted-completion", "object": "chat.completion", "created": 1, "model": "test",
"choices": [{"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": "ok"}}],
"usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
}).encode())
with wire_server(completion) as upstream, gateway.scenario() as scenario:
model: Final = scenario.model(api_base=upstream.url + "/v1")
response: Final = gateway.client.post("/v1/chat/completions", headers=headers, json={
"model": model, "messages": [{"role": "user", "content": "hosted grant"}],
})
assert response.status_code == 200 and response.json()["choices"][0]["message"]["content"] == "ok", response.text

View file

@ -53,11 +53,14 @@ from litellm.proxy._experimental.mcp_server.outbound_credentials.session_credent
from litellm.proxy._experimental.mcp_server.outbound_credentials.session_token import (
SESSION_ISSUER,
SESSION_REFRESH_PREFIX,
MintedSessionToken,
SessionPrincipal,
mint_session_refresh_token,
mint_session_token,
)
from tests.unit.proxy._experimental.mcp_server.test_hosted_proxy_auth import DatabaseTable
MASTER_KEY = "sk-gateway-dcr-flow-tests"
REDIRECT_URI = "https://claude.ai/api/mcp/auth_callback"
VSCODE_REDIRECT_URIS: Final = (
@ -74,6 +77,8 @@ 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)
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", raising=False)
def _request(path="/authorize", query="", cookies=None, method="GET"):
@ -112,7 +117,7 @@ async def _reload_user_active(user_id: str):
async def test_register_mints_stateless_public_client():
body = await _register([REDIRECT_URI])
assert body["token_endpoint_auth_method"] == "none"
assert body["grant_types"] == ["authorization_code", "refresh_token", TOKEN_EXCHANGE_GRANT_TYPE]
assert body["grant_types"] == ["authorization_code", "refresh_token"]
assert "client_secret" not in body
assert body["redirect_uris"] == [REDIRECT_URI]
assert is_gateway_dcr_client_id(body["client_id"])
@ -1540,8 +1545,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 +1553,156 @@ 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"
from litellm.proxy._experimental.mcp_server.hosted_proxy_auth import HostedProxyAuth
from tests.unit.proxy._experimental.mcp_server.test_hosted_proxy_auth import GrantStore, NOW, UserLoader
service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
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,
hosted_auth=service,
)
assert redeemed.status_code == 200
assert json.loads(redeemed.body)["user_id"] == "u1"
assert json.loads(redeemed.body)["team_id"] == "team-b"
assert json.loads(redeemed.body)["scope"] == "proxy:read"
assert minter.calls == []
replay: Final = await _redeem(
code,
client_id,
redirect_uri=hosted,
cache=cache,
resource=PROXY_API_RESOURCE,
mint_proxy_credential=minter,
hosted_auth=service,
)
assert replay.status_code == 400
assert json.loads(replay.body)["error"] == "invalid_grant"
@pytest.mark.asyncio
@pytest.mark.parametrize("decision", ["approve", "deny"])
async def test_removed_hosted_callback_cannot_receive_a_pending_consent_redirect(monkeypatch: pytest.MonkeyPatch, decision: str) -> 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"]
consent: Final = await _native_authorize(client_id, redirect_uri=hosted)
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS")
response: Final = await _complete_consent(consent, cache=DualCache(), decision=decision)
assert response.status_code == 400
assert "location" not in response.headers
@pytest.mark.asyncio
async def test_removed_hosted_callback_cannot_redeem_a_pending_code(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"]
consent: Final = await _native_authorize(client_id, redirect_uri=hosted)
approved: Final = await _complete_consent(consent, cache=DualCache(), decision="approve")
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS")
minter: Final = _Minter()
response: Final = await _redeem(_code_from(approved), client_id, redirect_uri=hosted, mint_proxy_credential=minter)
assert response.status_code == 400
assert json.loads(response.body)["error"] == "invalid_grant"
assert minter.calls == []
@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",
],
)
@pytest.mark.parametrize("scope,setting", [
("proxy:read", "LITELLM_PROXY_API_OAUTH_REDIRECT_URIS"),
("proxy:admin", "LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS"),
])
async def test_hosted_callback_allowlist_requires_exact_uri(
monkeypatch: pytest.MonkeyPatch, hosted: str, scope: str, setting: str
) -> None:
monkeypatch.setenv(setting, "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, scope=scope)
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",
@ -1985,6 +2133,7 @@ def test_native_client_auth_contract_points_every_endpoint_at_this_proxy():
"code_challenge_methods_supported": ["S256"],
"token_endpoint_auth_methods_supported": ["none"],
"revocation_endpoint_auth_methods_supported": ["none"],
"hosted_app": {"scopes_supported": [], "access_token_ttl": 300, "refresh_token_ttl": 86400},
}
@ -2205,6 +2354,33 @@ async def _exchange_native(client_id, minter, exchanger, cache=None, **overrides
return await _redeem_native(None, client_id, minter, cache=cache, **{**arguments, **overrides})
@pytest.mark.asyncio
async def test_hosted_registration_cannot_exchange_an_idp_token_for_a_personal_credential() -> None:
client_id: Final = (await _register(["https://admin.example/oauth/callback"]))["client_id"]
minter: Final = _Minter()
exchanger: Final = _Exchanger()
response: Final = await _exchange_native(client_id, minter, exchanger)
assert response.status_code == 400
assert json.loads(response.body)["error"] == "unauthorized_client"
assert minter.calls == []
assert exchanger.calls == []
@pytest.mark.asyncio
async def test_legacy_hosted_refresh_cannot_renew_a_personal_credential() -> None:
client_id: Final = (await _register(["https://admin.example/oauth/callback"]))["client_id"]
refresh: Final = mint_session_refresh_token(
SessionPrincipal(user_id="u1", client_id=client_id, audience="proxy_api", team_id="team-b"),
session_keys_from_master_key(MASTER_KEY), datetime.now(timezone.utc),
)
assert isinstance(refresh, MintedSessionToken)
minter: Final = _Minter()
response: Final = await _refresh_native(refresh.token.get_secret_value(), client_id, minter, DualCache())
assert response.status_code == 400
assert json.loads(response.body)["error"] == "invalid_grant"
assert minter.calls == []
@pytest.mark.asyncio
async def test_token_exchange_mints_the_proxy_credential_for_the_idp_subject():
"""RFC 8693: a registered native client trades the IdP token it already holds for the
@ -2354,3 +2530,136 @@ async def test_token_exchange_relays_a_mint_refusal(failure, status, error):
response = await _exchange_native(client_id, _Minter(failure), _Exchanger())
assert response.status_code == status
assert json.loads(response.body)["error"] == error
@pytest.fixture
def hosted_admin_database(monkeypatch: pytest.MonkeyPatch) -> DatabaseTable:
from types import SimpleNamespace
from litellm.proxy import proxy_server
from litellm.proxy._types import LiteLLM_UserTable
from litellm.proxy.common_utils.user_api_key_cache import UserApiKeyCache
users: Final = DatabaseTable(LiteLLM_UserTable(user_id="u1", user_role="proxy_admin"))
writer: Final = SimpleNamespace(litellm_usertable=users)
monkeypatch.setattr(proxy_server, "prisma_client", SimpleNamespace(writer_db=writer, db=None))
monkeypatch.setattr(proxy_server, "user_api_key_cache", UserApiKeyCache())
monkeypatch.setattr(proxy_server, "user_custom_auth", None)
monkeypatch.setattr(proxy_server, "general_settings", {})
return users
@pytest.mark.asyncio
async def test_hosted_admin_scope_survives_consent_code_issue_and_refresh(
monkeypatch: pytest.MonkeyPatch, hosted_admin_database: DatabaseTable
) -> None:
from litellm.proxy._experimental.mcp_server.hosted_proxy_auth import HostedProxyAuth, load_hosted_user
from tests.unit.proxy._experimental.mcp_server.test_hosted_proxy_auth import GrantStore, NOW
hosted: Final = "https://admin.example/oauth/callback"
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", hosted)
client_id: Final = (await _register([hosted]))["client_id"]
consent: Final = await _native_authorize(
client_id, redirect_uri=hosted, scope="proxy:admin", lookup=_ConsentTeams(())
)
assert consent.status_code == 200
assert "current administrator permissions" in consent.body.decode()
handle, cookies = _consent_cookie_from(consent)
flow: Final = _sealed_wire_json(next(iter(cookies.values())), "", "gateway_connect_flow")
assert flow["hosted_scope"] == "proxy:admin"
approved: Final = await _complete_consent(consent, decision="approve")
code: Final = _code_from(approved)
opened: Final = _sealed_wire_json(code, GATEWAY_AUTH_CODE_PREFIX, _AUTH_CODE_DEBUG_KEY)
assert opened["hosted_scope"] == "proxy:admin" and opened["client_id"] == client_id
grants: Final = GrantStore()
service: Final = HostedProxyAuth(grants, load_hosted_user, NOW)
issued: Final = await _redeem(code, client_id, redirect_uri=hosted, resource=PROXY_API_RESOURCE, hosted_auth=service)
assert issued.status_code == 200, issued.body
tokens: Final = json.loads(issued.body)
assert tokens["scope"] == "proxy:admin" and tokens["user_id"] == "u1"
assert grants.grant is not None and grants.grant.scope == "proxy:admin"
refreshed: Final = await _redeem(
None, client_id, grant_type="refresh_token", refresh_token=tokens["refresh_token"],
resource=PROXY_API_RESOURCE, hosted_auth=service,
)
assert refreshed.status_code == 200, refreshed.body
assert json.loads(refreshed.body)["scope"] == tokens["scope"]
replayed: Final = await _redeem(code, client_id, redirect_uri=hosted, resource=PROXY_API_RESOURCE, hosted_auth=service)
assert replayed.status_code == 400 and json.loads(replayed.body)["error"] == "invalid_grant"
@pytest.mark.asyncio
@pytest.mark.parametrize("role", ["internal_user", "proxy_admin_viewer"])
async def test_hosted_admin_consent_checks_live_role_instead_of_cached_admin(
monkeypatch: pytest.MonkeyPatch, hosted_admin_database: DatabaseTable, role: str
) -> None:
from litellm.proxy import proxy_server
from litellm.proxy._types import LiteLLM_UserTable
hosted: Final = "https://admin.example/oauth/callback"
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", hosted)
client_id: Final = (await _register([hosted]))["client_id"]
await proxy_server.user_api_key_cache.async_set_cache(key="u1", value=hosted_admin_database.row)
hosted_admin_database.row = LiteLLM_UserTable(user_id="u1", user_role=role)
response: Final = await _native_authorize(client_id, redirect_uri=hosted, scope="proxy:admin")
assert response.status_code == 403 and json.loads(response.body)["error"] == "access_denied"
assert "set-cookie" not in response.headers
@pytest.mark.asyncio
async def test_hosted_admin_demotion_after_consent_prevents_credential_issuance(
monkeypatch: pytest.MonkeyPatch, hosted_admin_database: DatabaseTable
) -> None:
from litellm.proxy._experimental.mcp_server.hosted_proxy_auth import HostedProxyAuth, load_hosted_user
from litellm.proxy._types import LiteLLM_UserTable
from tests.unit.proxy._experimental.mcp_server.test_hosted_proxy_auth import GrantStore, NOW
hosted: Final = "https://admin.example/oauth/callback"
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", hosted)
client_id: Final = (await _register([hosted]))["client_id"]
consent: Final = await _native_authorize(
client_id, redirect_uri=hosted, scope="proxy:admin", lookup=_ConsentTeams(())
)
assert consent.status_code == 200
approved: Final = await _complete_consent(consent, decision="approve")
hosted_admin_database.row = LiteLLM_UserTable(user_id="u1", user_role="internal_user")
grants: Final = GrantStore()
response: Final = await _redeem(
_code_from(approved), client_id, redirect_uri=hosted, resource=PROXY_API_RESOURCE,
hosted_auth=HostedProxyAuth(grants, load_hosted_user, NOW),
)
assert response.status_code == 400 and json.loads(response.body)["error"] == "insufficient_scope"
assert grants.grant is None
@pytest.mark.asyncio
@pytest.mark.parametrize("scope,setting,error", [
("proxy:admin", "LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", "invalid_request"),
("proxy:write", "LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", "invalid_scope"),
("proxy:read proxy:admin", "LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", "invalid_scope"),
])
async def test_hosted_admin_requires_explicit_supported_scope_and_admin_callback_trust(
monkeypatch: pytest.MonkeyPatch, scope: str, setting: str, error: str
) -> None:
hosted: Final = "https://admin.example/oauth/callback"
monkeypatch.setenv(setting, hosted)
client_id: Final = (await _register([hosted]))["client_id"]
response: Final = await _native_authorize(client_id, redirect_uri=hosted, scope=scope, session_user_id=None)
assert response.status_code == 400 and json.loads(response.body)["error"] == error
assert "location" not in response.headers
@pytest.mark.parametrize("setting,scopes", [
("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", ("proxy:read",)),
("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", ("proxy:read", "proxy:admin")),
])
def test_discovery_advertises_only_currently_enabled_hosted_scopes(
monkeypatch: pytest.MonkeyPatch, setting: str, scopes: tuple[str, ...]
) -> None:
from litellm.proxy._experimental.mcp_server.hosted_proxy_auth import HOSTED_ACCESS_TTL, HOSTED_GRANT_TTL
monkeypatch.setenv(setting, "https://admin.example/oauth/callback")
contract: Final = native_client_auth_contract(_request("/.well-known/litellm-cli-auth"), False)
assert contract["hosted_app"] == {
"scopes_supported": scopes, "access_token_ttl": HOSTED_ACCESS_TTL, "refresh_token_ttl": HOSTED_GRANT_TTL,
}

View file

@ -0,0 +1,589 @@
import asyncio
import hashlib
from datetime import datetime, timedelta, timezone
from types import SimpleNamespace
from typing import Final
import pytest
from fastapi import HTTPException, Request
from pydantic import BaseModel
from litellm.caching.redis_cache import RedisCache
from litellm.proxy import proxy_server
from litellm.proxy._experimental.mcp_server.hosted_proxy_auth import (
HOSTED_ACCESS_TTL,
HOSTED_ADMIN_SCOPE,
HOSTED_GRANT_TTL,
MAX_HOSTED_REFRESHES,
HostedFailure,
HostedGrant,
HostedProxyAuth,
HostedScope,
HostedTokens,
RedisHostedGrantStore,
authenticate_hosted_request,
hosted_proxy_auth,
hosted_redirect_is_allowed,
hosted_supported_scopes,
load_hosted_user,
)
from litellm.proxy._types import (
LiteLLM_TeamMembership,
LiteLLM_TeamTableCachedObj,
LiteLLM_UserTable,
LitellmUserRoles,
UserAPIKeyAuth,
)
from litellm.proxy.common_utils.user_api_key_cache import UserApiKeyCache
from litellm.proxy.spend_tracking.budget_reservation import team_membership_reservation_cache_key
NOW: Final = datetime(2026, 1, 1, tzinfo=timezone.utc)
CALLBACK: Final = "https://admin.example/oauth/callback"
RESOURCE: Final = "https://gateway.example"
class GrantStore:
def __init__(self) -> None:
self.grant: HostedGrant | None = None
self.issued: bool = False
self.spent: frozenset[str] = frozenset()
self.available: bool = True
self.revocation_available: bool = True
async def read(self, grant_id: str) -> HostedGrant | HostedFailure:
if not self.available:
raise ConnectionError("store unavailable")
return self.grant if self.grant is not None and self.grant.grant_id == grant_id else HostedFailure()
async def replace(self, grant: HostedGrant, previous: HostedGrant | None, ttl: int) -> bool:
if not self.available:
raise ConnectionError("store unavailable")
if self.grant != previous or (previous is None and self.issued):
return False
if previous is not None:
self.spent = self.spent | frozenset({previous.refresh_hash, previous.access_hash})
self.grant = grant
self.issued = True
return True
async def delete(self, grant_id: str) -> None:
if not self.available or not self.revocation_available:
raise ConnectionError("store unavailable")
if self.grant is not None and self.grant.grant_id == grant_id:
self.grant = None
async def revoke_replayed(self, grant_id: str, token_hash: str) -> None:
if not self.available or not self.revocation_available:
raise ConnectionError("store unavailable")
if token_hash in self.spent:
await self.delete(grant_id)
class UserLoader:
def __init__(self) -> None:
self.role = LitellmUserRoles.PROXY_ADMIN
self.active = True
async def __call__(self, user_id: str, team_id: str | None) -> UserAPIKeyAuth | HostedFailure:
if not self.active:
return HostedFailure()
return UserAPIKeyAuth(user_id=user_id, team_id=team_id, user_role=self.role)
@pytest.fixture(autouse=True)
def trusted_callback(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", CALLBACK)
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", raising=False)
async def issued(service: HostedProxyAuth, scope: HostedScope = "proxy:read") -> HostedTokens:
result: Final = await service.issue("user", "team", "client", CALLBACK, RESOURCE, "code-id", scope)
assert isinstance(result, HostedTokens), result
return result
@pytest.mark.parametrize(
"callback",
[
"http://admin.example/callback",
"https://user:password@admin.example/callback",
"https://[bad",
"https://admin.example/#x",
],
)
def test_allowlisting_does_not_make_an_unsafe_callback_trusted(monkeypatch: pytest.MonkeyPatch, callback: str) -> None:
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", callback)
assert not hosted_redirect_is_allowed(callback)
@pytest.mark.asyncio
@pytest.mark.parametrize("mode", ["custom_auth", "enable_oauth2_auth", "enable_oauth2_proxy_auth"])
async def test_exclusive_authorization_configuration_denies_hosted_identity(
monkeypatch: pytest.MonkeyPatch, mode: str
) -> None:
async def custom_policy(request: Request, api_key: str) -> UserAPIKeyAuth:
raise HTTPException(status_code=403, detail="custom policy denied access")
monkeypatch.setattr(proxy_server, "user_custom_auth", custom_policy if mode == "custom_auth" else None)
monkeypatch.setattr(proxy_server, "general_settings", {mode: True} if mode != "custom_auth" else {})
result: Final = await load_hosted_user("user", None)
assert isinstance(result, HostedFailure)
assert result.error == "invalid_grant"
assert "custom or external auth is configured" in result.description
@pytest.mark.asyncio
async def test_missing_database_prevents_loading_hosted_identity(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(proxy_server, "prisma_client", None)
monkeypatch.setattr(proxy_server, "user_custom_auth", None)
monkeypatch.setattr(proxy_server, "general_settings", {})
result: Final = await load_hosted_user("user", None)
assert isinstance(result, HostedFailure)
assert result.error == "temporarily_unavailable"
@pytest.mark.asyncio
async def test_missing_shared_redis_prevents_service_and_api_admission(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(proxy_server, "redis_usage_cache", None)
service: Final = hosted_proxy_auth()
assert isinstance(service, HostedFailure)
assert service.error == "temporarily_unavailable"
request: Final = Request({"type": "http", "method": "GET", "path": "/v1/models", "headers": []})
with pytest.raises(HTTPException) as denied:
await authenticate_hosted_request(request, "llm_hosted_invalid", "/v1/models")
assert denied.value.status_code == 503
@pytest.mark.asyncio
async def test_tokens_are_opaque_and_only_hashes_are_stored() -> None:
store: Final = GrantStore()
tokens: Final = await issued(HostedProxyAuth(store, UserLoader(), NOW))
assert store.grant is not None
assert store.grant.access_hash == hashlib.sha256(tokens.access_token.encode()).hexdigest()
assert store.grant.refresh_hash == hashlib.sha256(tokens.refresh_token.encode()).hexdigest()
assert tokens.access_token not in store.grant.model_dump_json()
assert tokens.refresh_token not in store.grant.model_dump_json()
assert tokens.expires_in == HOSTED_ACCESS_TTL
assert tokens.scope == "proxy:read"
assert tokens.access_token not in repr(tokens)
assert tokens.refresh_token not in repr(tokens)
@pytest.mark.asyncio
async def test_issuance_rejects_removed_callback_and_inactive_user(monkeypatch: pytest.MonkeyPatch) -> None:
store: Final = GrantStore()
loader: Final = UserLoader()
service: Final = HostedProxyAuth(store, loader, NOW)
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS")
assert isinstance(await service.issue("user", "team", "client", CALLBACK, RESOURCE, "code-id"), HostedFailure)
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS", CALLBACK)
loader.active = False
assert isinstance(await service.issue("user", "team", "client", CALLBACK, RESOURCE, "code-id"), HostedFailure)
assert store.grant is None
@pytest.mark.asyncio
@pytest.mark.parametrize("replay", [False, True])
async def test_failed_revocation_is_retryable_and_never_reports_success(replay: bool) -> None:
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, UserLoader(), NOW)
tokens: Final = await issued(service)
rotated: Final = await service.refresh(tokens.refresh_token, "client", RESOURCE)
assert isinstance(rotated, HostedTokens)
store.revocation_available = False
failure: Final = (
await service.refresh(tokens.refresh_token, "client", RESOURCE)
if replay
else await service.revoke(rotated.refresh_token, "client")
)
assert isinstance(failure, HostedFailure)
assert failure.error == "temporarily_unavailable"
store.revocation_available = True
assert await service.revoke(rotated.refresh_token, "client") is None
assert isinstance(await service.refresh(rotated.refresh_token, "client", RESOURCE), HostedFailure)
@pytest.mark.asyncio
async def test_store_outage_fails_closed_and_does_not_consume_authorization_code() -> None:
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, UserLoader(), NOW)
store.available = False
failed: Final = await service.issue("user", "team", "client", CALLBACK, RESOURCE, "code-id")
assert isinstance(failed, HostedFailure)
assert failed.error == "temporarily_unavailable"
store.available = True
tokens: Final = await issued(service)
store.available = False
access: Final = await service.authenticate(tokens.access_token, RESOURCE, "/v1/models", "GET")
refresh: Final = await service.refresh(tokens.refresh_token, "client", RESOURCE)
revoke: Final = await service.revoke(tokens.refresh_token, "client")
assert isinstance(access, HostedFailure) and access.error == "temporarily_unavailable"
assert isinstance(refresh, HostedFailure) and refresh.error == "temporarily_unavailable"
assert isinstance(revoke, HostedFailure) and revoke.error == "temporarily_unavailable"
@pytest.mark.asyncio
@pytest.mark.parametrize(
("route", "method"),
[
("/key/generate", "POST"),
("/key/info", "GET"),
("/model/info", "GET"),
("/config/yaml", "GET"),
("/spend/logs", "GET"),
("/v1/chat/completions", "POST"),
("/mcp", "GET"),
("/sso/key/generate", "GET"),
("/global/spend", "POST"),
("/v1/models/../key/info", "GET"),
],
)
async def test_read_only_admin_token_cannot_write_read_secrets_or_call_llms(route: str, method: str) -> None:
service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
tokens: Final = await issued(service)
result: Final = await service.authenticate(tokens.access_token, RESOURCE, route, method)
assert isinstance(result, HostedFailure)
assert result.error == "insufficient_scope"
@pytest.mark.asyncio
async def test_read_only_authority_tracks_live_user_role_and_deactivation() -> None:
loader: Final = UserLoader()
service: Final = HostedProxyAuth(GrantStore(), loader, NOW)
tokens: Final = await issued(service)
assert isinstance(await service.authenticate(tokens.access_token, RESOURCE, "/global/spend", "GET"), UserAPIKeyAuth)
loader.role = LitellmUserRoles.INTERNAL_USER
denied: Final = await service.authenticate(tokens.access_token, RESOURCE, "/global/spend", "GET")
assert isinstance(denied, HostedFailure)
assert denied.error == "insufficient_scope"
models: Final = await service.authenticate(tokens.access_token, RESOURCE, "/v1/models", "GET")
assert isinstance(models, UserAPIKeyAuth)
assert models.user_role == LitellmUserRoles.INTERNAL_USER
loader.active = False
assert isinstance(await service.authenticate(tokens.access_token, RESOURCE, "/v1/models", "GET"), HostedFailure)
assert isinstance(await service.refresh(tokens.refresh_token, "client", RESOURCE), HostedFailure)
@pytest.mark.asyncio
async def test_removed_callback_stops_active_access_and_refresh(monkeypatch: pytest.MonkeyPatch) -> None:
service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
tokens: Final = await issued(service)
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS")
assert isinstance(await service.authenticate(tokens.access_token, RESOURCE, "/v1/models", "GET"), HostedFailure)
assert isinstance(await service.refresh(tokens.refresh_token, "client", RESOURCE), HostedFailure)
@pytest.mark.asyncio
async def test_rotation_does_not_extend_absolute_grant_lifetime() -> None:
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, UserLoader(), NOW)
tokens: Final = await issued(service)
later: Final = HostedProxyAuth(store, UserLoader(), NOW + timedelta(seconds=HOSTED_GRANT_TTL - 10))
rotated: Final = await later.refresh(tokens.refresh_token, "client", RESOURCE)
assert isinstance(rotated, HostedTokens)
assert rotated.expires_in == 10
expired: Final = HostedProxyAuth(store, UserLoader(), NOW + timedelta(seconds=HOSTED_GRANT_TTL))
assert isinstance(await expired.refresh(rotated.refresh_token, "client", RESOURCE), HostedFailure)
assert isinstance(await expired.authenticate(rotated.access_token, RESOURCE, "/v1/models", "GET"), HostedFailure)
@pytest.mark.asyncio
async def test_concurrent_refresh_is_single_use_and_revokes_the_compromised_family() -> None:
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, UserLoader(), NOW)
tokens: Final = await issued(service)
first_loaded: Final = asyncio.Event()
both_loaded: Final = asyncio.Event()
async def simultaneous_user_load(user_id: str, team_id: str | None) -> UserAPIKeyAuth:
if first_loaded.is_set():
both_loaded.set()
else:
first_loaded.set()
await both_loaded.wait()
return UserAPIKeyAuth(user_id=user_id, team_id=team_id, user_role=LitellmUserRoles.PROXY_ADMIN)
racer: Final = HostedProxyAuth(store, simultaneous_user_load, NOW)
results: Final = await asyncio.gather(
racer.refresh(tokens.refresh_token, "client", RESOURCE),
racer.refresh(tokens.refresh_token, "client", RESOURCE),
)
successes: Final = tuple(result for result in results if isinstance(result, HostedTokens))
assert len(successes) == 1
assert sum(isinstance(result, HostedFailure) for result in results) == 1
assert isinstance(
await service.authenticate(successes[0].access_token, RESOURCE, "/v1/models", "GET"), HostedFailure
)
@pytest.mark.asyncio
async def test_refresh_replay_revokes_family_but_random_secret_does_not() -> None:
service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
tokens: Final = await issued(service)
rotated: Final = await service.refresh(tokens.refresh_token, "client", RESOURCE)
assert isinstance(rotated, HostedTokens)
forged: Final = rotated.refresh_token[:-43] + "x" * 43
assert isinstance(await service.refresh(forged, "client", RESOURCE), HostedFailure)
assert isinstance(await service.authenticate(rotated.access_token, RESOURCE, "/v1/models", "GET"), UserAPIKeyAuth)
assert isinstance(await service.refresh(tokens.refresh_token, "client", RESOURCE), HostedFailure)
assert isinstance(await service.authenticate(rotated.access_token, RESOURCE, "/v1/models", "GET"), HostedFailure)
@pytest.mark.asyncio
async def test_revoking_grant_does_not_allow_authorization_code_reuse() -> None:
service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
tokens: Final = await issued(service)
assert await service.revoke(tokens.refresh_token, "client") is None
assert isinstance(await service.issue("user", "team", "client", CALLBACK, RESOURCE, "code-id"), HostedFailure)
@pytest.mark.asyncio
async def test_refresh_history_is_bounded() -> None:
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, UserLoader(), NOW)
tokens: Final = await issued(service)
assert store.grant is not None
store.grant = store.grant.model_copy(update={"refresh_count": MAX_HOSTED_REFRESHES - 1})
rotated: Final = await service.refresh(tokens.refresh_token, "client", RESOURCE)
assert isinstance(rotated, HostedTokens)
assert store.grant.refresh_count == MAX_HOSTED_REFRESHES
response: Final = await service.refresh(rotated.refresh_token, "client", RESOURCE)
assert isinstance(response, HostedFailure)
assert response.error == "invalid_grant"
assert store.spent == frozenset(
hashlib.sha256(token.encode()).hexdigest() for token in (tokens.refresh_token, tokens.access_token)
)
@pytest.mark.asyncio
@pytest.mark.parametrize("rotated", [False, True])
async def test_expired_or_rotated_access_can_revoke_the_entire_grant(rotated: bool) -> None:
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, UserLoader(), NOW)
tokens: Final = await issued(service)
current: Final = await service.refresh(tokens.refresh_token, "client", RESOURCE) if rotated else tokens
assert isinstance(current, HostedTokens)
later: Final = HostedProxyAuth(store, UserLoader(), NOW + timedelta(seconds=HOSTED_ACCESS_TTL))
forged: Final = tokens.access_token[:-43] + "x" * 43
assert await later.revoke(forged, "client") is None
assert store.grant is not None
assert await later.revoke(tokens.access_token, "different-client") is None
assert store.grant is not None
assert await later.revoke(tokens.access_token, "client") is None
assert store.grant is None
assert isinstance(await later.refresh(current.refresh_token, "client", RESOURCE), HostedFailure)
@pytest.mark.asyncio
@pytest.mark.parametrize("use_access_token", [False, True])
async def test_revocation_removes_refresh_and_active_api_access(use_access_token: bool) -> None:
service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
tokens: Final = await issued(service)
token: Final = tokens.access_token if use_access_token else tokens.refresh_token
assert await service.revoke(token, "different-client") is None
assert isinstance(await service.authenticate(tokens.access_token, RESOURCE, "/v1/models", "GET"), UserAPIKeyAuth)
assert await service.revoke(token, "client") is None
assert isinstance(await service.authenticate(tokens.access_token, RESOURCE, "/v1/models", "GET"), HostedFailure)
assert isinstance(await service.refresh(tokens.refresh_token, "client", RESOURCE), HostedFailure)
@pytest.mark.asyncio
async def test_tokens_cannot_cross_client_gateway_or_token_kind_boundaries() -> None:
service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
tokens: Final = await issued(service)
assert isinstance(await service.refresh(tokens.refresh_token, "other-client", RESOURCE), HostedFailure)
assert isinstance(await service.refresh(tokens.refresh_token, "client", "https://other.example"), HostedFailure)
assert isinstance(await service.refresh(tokens.access_token, "client", RESOURCE), HostedFailure)
assert isinstance(await service.authenticate(tokens.refresh_token, RESOURCE, "/v1/models", "GET"), HostedFailure)
assert isinstance(
await service.authenticate(tokens.access_token, "https://other.example", "/v1/models", "GET"), HostedFailure
)
@pytest.mark.asyncio
async def test_expired_access_requires_refresh_and_missing_store_grant_fails_closed() -> None:
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, UserLoader(), NOW)
tokens: Final = await issued(service)
expired: Final = HostedProxyAuth(store, UserLoader(), NOW + timedelta(seconds=HOSTED_ACCESS_TTL))
assert isinstance(await expired.authenticate(tokens.access_token, RESOURCE, "/v1/models", "GET"), HostedFailure)
rotated: Final = await expired.refresh(tokens.refresh_token, "client", RESOURCE)
assert isinstance(rotated, HostedTokens)
assert isinstance(await expired.authenticate(rotated.access_token, RESOURCE, "/v1/models", "GET"), UserAPIKeyAuth)
store.grant = None
assert isinstance(await expired.authenticate(rotated.access_token, RESOURCE, "/v1/models", "GET"), HostedFailure)
assert isinstance(await expired.refresh(rotated.refresh_token, "client", RESOURCE), HostedFailure)
def test_discovery_and_callback_approval_distinguish_admin_scope(monkeypatch: pytest.MonkeyPatch) -> None:
assert hosted_supported_scopes() == ("proxy:read",)
assert not hosted_redirect_is_allowed(CALLBACK, HOSTED_ADMIN_SCOPE)
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", CALLBACK)
assert hosted_supported_scopes() == ("proxy:read", "proxy:admin")
assert hosted_redirect_is_allowed(CALLBACK, HOSTED_ADMIN_SCOPE)
assert not hosted_redirect_is_allowed(CALLBACK + "/other", HOSTED_ADMIN_SCOPE)
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", "http://unsafe.example/callback")
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_REDIRECT_URIS")
assert hosted_supported_scopes() == ()
@pytest.mark.asyncio
@pytest.mark.parametrize("role", [LitellmUserRoles.INTERNAL_USER, LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY])
async def test_admin_scope_requires_approved_callback_and_current_full_admin(
monkeypatch: pytest.MonkeyPatch, role: LitellmUserRoles
) -> None:
loader: Final = UserLoader()
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, loader, NOW)
unapproved: Final = await service.issue("user", "team", "client", CALLBACK, RESOURCE, "code-id", HOSTED_ADMIN_SCOPE)
assert isinstance(unapproved, HostedFailure)
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", CALLBACK)
loader.role = role
denied: Final = await service.issue("user", "team", "client", CALLBACK, RESOURCE, "code-id", HOSTED_ADMIN_SCOPE)
assert isinstance(denied, HostedFailure) and denied.error == "insufficient_scope"
assert store.grant is None
loader.role = LitellmUserRoles.PROXY_ADMIN
tokens: Final = await issued(service, HOSTED_ADMIN_SCOPE)
assert tokens.scope == HOSTED_ADMIN_SCOPE
assert isinstance(await service.authenticate(tokens.access_token, RESOURCE, "/key/generate", "POST"), UserAPIKeyAuth)
loader.role = role
assert isinstance(await service.authenticate(tokens.access_token, RESOURCE, "/key/generate", "POST"), HostedFailure)
assert isinstance(await service.refresh(tokens.refresh_token, "client", RESOURCE), HostedFailure)
@pytest.mark.asyncio
async def test_callback_removal_revokes_admin_but_read_grant_never_upgrades(monkeypatch: pytest.MonkeyPatch) -> None:
read_service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
read: Final = await issued(read_service)
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", CALLBACK)
admin_service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
admin: Final = await issued(admin_service, HOSTED_ADMIN_SCOPE)
rotated: Final = await read_service.refresh(read.refresh_token, "client", RESOURCE)
assert isinstance(rotated, HostedTokens) and rotated.scope == "proxy:read"
assert isinstance(await read_service.authenticate(rotated.access_token, RESOURCE, "/key/generate", "POST"), HostedFailure)
monkeypatch.delenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS")
assert isinstance(await admin_service.authenticate(admin.access_token, RESOURCE, "/user/info", "GET"), HostedFailure)
assert isinstance(await admin_service.refresh(admin.refresh_token, "client", RESOURCE), HostedFailure)
assert isinstance(await read_service.authenticate(rotated.access_token, RESOURCE, "/models", "GET"), UserAPIKeyAuth)
@pytest.mark.asyncio
@pytest.mark.parametrize(
("route", "allowed"),
[
("/key/generate", True), ("/user/info", True), ("/team/member_add", True),
("/team/model/add", True), ("/team/team-a/disable_logging", True),
("/budget/new", True), ("/budget/info", True), ("/budget/list", True),
("/organization/info", True), ("/organization/daily/activity", True),
("/spend/logs/ui/request-a", True), ("/v1/chat/completions", True),
("/v1beta/models/gemini:generateContent", True), ("/v1/messages", True),
("/authorize", False), ("/token", False), ("/introspect", False),
("/sso/key/generate", False), ("/session/logout", False), ("/user/password/change", False),
("/jwt/key/mapping/new", False), ("/global/spend/reset", False),
("/v1/mcp/server/oauth/server-a/token", False),
("/v1/mcp/server/server-a/oauth-user-credential/status", False),
("/v1/mcp/server/server-a/user-env-vars", False),
("/v1/realtime/client_secrets", False), ("/anthropic/v1/messages", False),
("/mcp", False), ("/key/../token", False),
],
)
async def test_admin_scope_only_reaches_supported_operations(
monkeypatch: pytest.MonkeyPatch, route: str, allowed: bool
) -> None:
monkeypatch.setenv("LITELLM_PROXY_API_OAUTH_ADMIN_REDIRECT_URIS", CALLBACK)
service: Final = HostedProxyAuth(GrantStore(), UserLoader(), NOW)
tokens: Final = await issued(service, HOSTED_ADMIN_SCOPE)
result: Final = await service.authenticate(tokens.access_token, RESOURCE, route, "POST")
assert isinstance(result, UserAPIKeyAuth) == allowed
if not allowed:
assert isinstance(result, HostedFailure) and result.error == "insufficient_scope"
@pytest.mark.asyncio
async def test_refresh_preserves_unexpired_access_and_family_revocation_reaches_every_generation() -> None:
store: Final = GrantStore()
service: Final = HostedProxyAuth(store, UserLoader(), NOW)
original: Final = await issued(service)
later: Final = HostedProxyAuth(store, UserLoader(), NOW + timedelta(seconds=10))
refreshed: Final = await later.refresh(original.refresh_token, "client", RESOURCE)
assert isinstance(refreshed, HostedTokens)
assert refreshed.refresh_expires_in == HOSTED_GRANT_TTL - 10
for token in (original.access_token, refreshed.access_token):
assert isinstance(await later.authenticate(token, RESOURCE, "/models", "GET"), UserAPIKeyAuth)
expired: Final = HostedProxyAuth(store, UserLoader(), NOW + timedelta(seconds=HOSTED_ACCESS_TTL))
assert isinstance(await expired.authenticate(original.access_token, RESOURCE, "/models", "GET"), HostedFailure)
assert isinstance(await expired.authenticate(refreshed.access_token, RESOURCE, "/models", "GET"), UserAPIKeyAuth)
assert isinstance(await later.refresh(original.refresh_token, "client", RESOURCE), HostedFailure)
for token in (original.access_token, refreshed.access_token):
assert isinstance(await later.authenticate(token, RESOURCE, "/models", "GET"), HostedFailure)
class StoredGrantRedis(RedisCache):
def __init__(self, value: str) -> None:
self.value: Final = value
def check_and_fix_namespace(self, key: str) -> str:
return key
async def async_eval(self, script: str, numkeys: int, *keys_and_args: str | bytes | float) -> object:
return self.value
@pytest.mark.asyncio
async def test_pre_scope_redis_grant_requires_reconnection() -> None:
store: Final = GrantStore()
await issued(HostedProxyAuth(store, UserLoader(), NOW))
assert store.grant is not None
old_json: Final = store.grant.model_dump_json(exclude={"scope", "previous_access"})
shared: Final = RedisHostedGrantStore(StoredGrantRedis(old_json), "test-master")
assert isinstance(await shared.read(store.grant.grant_id), HostedFailure)
class DatabaseTable:
def __init__(self, row: BaseModel | None) -> None:
self.row = row
async def find_unique(self, **kwargs: object) -> BaseModel | None:
return self.row
@pytest.mark.asyncio
async def test_hosted_identity_reloads_user_team_and_member_limits_from_writer(
monkeypatch: pytest.MonkeyPatch,
) -> None:
cache: Final = UserApiKeyCache()
user: Final = LiteLLM_UserTable(user_id="user", user_role="proxy_admin", teams=["team"], organization_id="home-org")
team: Final = LiteLLM_TeamTableCachedObj(team_id="team", organization_id="team-org", rpm_limit=20, models=["allowed"])
member: Final = LiteLLM_TeamMembership.model_validate({
"user_id": "user", "team_id": "team", "spend": 1,
"litellm_budget_table": {"rpm_limit": 3, "tpm_limit": 70},
})
users: Final = DatabaseTable(user)
teams: Final = DatabaseTable(team)
members: Final = DatabaseTable(member)
writer: Final = SimpleNamespace(litellm_usertable=users, litellm_teamtable=teams, litellm_teammembership=members)
monkeypatch.setattr(proxy_server, "prisma_client", SimpleNamespace(writer_db=writer, db=None))
monkeypatch.setattr(proxy_server, "user_api_key_cache", cache)
monkeypatch.setattr(proxy_server, "user_custom_auth", None)
monkeypatch.setattr(proxy_server, "general_settings", {})
await cache.async_set_cache(key="user", value=user.model_copy(update={"user_role": "internal_user"}))
await cache.async_set_cache(key="team_id:team", value=team.model_copy(update={"rpm_limit": 999}))
await cache.async_set_cache(key=team_membership_reservation_cache_key("user", "team"), value=member.model_copy(
update={"litellm_budget_table": None}
))
loaded: Final = await load_hosted_user("user", "team")
assert isinstance(loaded, UserAPIKeyAuth), loaded
assert (loaded.user_role, loaded.team_rpm_limit, loaded.team_member_rpm_limit, loaded.team_member_tpm_limit) == (
LitellmUserRoles.PROXY_ADMIN, 20, 3, 70
)
assert loaded.org_id == "team-org"
assert loaded.team_models == ["allowed"]
assert loaded.object_permission is None
teams.row = team.model_copy(update={"blocked": True})
assert isinstance(await load_hosted_user("user", "team"), HostedFailure)
users.row = user.model_copy(update={"teams": [], "organization_id": "home-org"})
assert isinstance(await load_hosted_user("user", "team"), HostedFailure)
teamless: Final = await load_hosted_user("user", None)
assert isinstance(teamless, UserAPIKeyAuth) and teamless.org_id == "home-org"
users.row = user.model_copy(update={"teams": [], "metadata": {"scim_active": False}})
assert isinstance(await load_hosted_user("user", None), HostedFailure)

View file

@ -1,4 +1,4 @@
from typing import Final
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 +65,24 @@ 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
def test_hosted_admin_consent_names_write_authority_and_billing_without_changing_read_only_consent() -> None:
admin: Final = _render(hosted=True, hosted_admin=True, client_origin="https://admin.example")
reports: Final = _render(hosted=True, client_origin="https://admin.example")
assert "manage keys, users, teams and models" in admin
assert "current administrator permissions" in admin
assert "Model calls can incur charges" in admin
assert "Disconnecting the application revokes access immediately" in admin
assert "read-only model listings and aggregate usage reports" in reports
assert "It does not permit changes, credential access, request contents, or LLM calls" in reports
assert "manage keys" not in reports

View file

@ -1,4 +1,6 @@
import hashlib
import json
from typing import Final
import pytest
from pydantic import ValidationError
@ -73,6 +75,16 @@ def test_a_bearer_prefixed_key_hashes_the_same_as_the_bare_key():
assert UserAPIKeyAuth(api_key=f"Bearer {raw_key}").token == UserAPIKeyAuth(api_key=raw_key).token
@pytest.mark.parametrize("prefix", ["llm_hosted_", "llm_hrefresh_"])
def test_hosted_bearers_are_hashed_before_auth_failure_logging(prefix: str) -> None:
token: Final = prefix + "secret"
identity: Final = UserAPIKeyAuth(api_key="Bearer " + token)
expected: Final = hashlib.sha256(token.encode()).hexdigest()
assert identity.api_key == expected
assert identity.token == expected
assert token not in identity.model_dump_json()
def test_an_absent_api_key_leaves_the_token_unset():
auth = UserAPIKeyAuth()