refactor(auth): plan the authentication path in Rust (#51605)

The auth flags read through python-compat's IsTrue adapter and public_routes
through RouteList on both hosts, and python-bridge reads those keys through
GeneralSettings' own serde rules. A flag is on only for a boolean true, and a
public_routes value that is not a list of strings adds no public route, so
the Rust gateway and the Python proxy read the same settings the same way.
This commit is contained in:
yujonglee 2026-11-16 19:36:57 +09:00 • committed by GitHub
parent 4aa00352bb
commit 76e45df333
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
33 changed files with 1988 additions and 578 deletions

View file

@ -0,0 +1,63 @@
"""What a gateway-auth-core call is made of on the Python side: the request and host facts it reads, and the
proxy's settings."""
from __future__ import annotations
from dataclasses import dataclass
from typing import Final
import litellm
from litellm.proxy.auth.route_checks import RouteChecks
from litellm.rust_bridge._native import RustAuthSettings
@dataclass(frozen=True, slots=True)
class HostFacts:
"""What the proxy knows that `general_settings` does not say. The defaults are a proxy that configured
none of them."""
premium: bool
metrics_require_auth: bool = True
@dataclass(frozen=True, slots=True)
class AuthRequest:
route: str
token: str | None
is_llm_api_route: bool
is_info_route: bool
pass_through_open: bool = False
from_custom_auth: bool = False
def request(
token: str | None,
route: str,
*,
pass_through_open: bool = False,
from_custom_auth: bool = False,
) -> AuthRequest:
return AuthRequest(
route=route,
token=token,
is_llm_api_route=RouteChecks.is_llm_api_route(route=route),
is_info_route=RouteChecks.is_info_route(route=route),
pass_through_open=pass_through_open,
from_custom_auth=from_custom_auth,
)
def proxy_settings() -> RustAuthSettings:
"""The auth settings as the proxy's globals stand now. A config load or a settings endpoint can change them
while the proxy serves, so a request builds its own."""
from litellm.proxy import proxy_server # noqa: PLC0415 # proxy_server imports this module
general_settings: Final = proxy_server.current_general_settings()
return RustAuthSettings(
general_settings,
proxy_server.jwt_handler.litellm_jwtauth if general_settings.get("enable_jwt_auth") is True else None,
HostFacts(
premium=proxy_server.premium_user is True,
metrics_require_auth=litellm.require_auth_for_metrics_endpoint is not False,
),
)

View file

@ -0,0 +1,14 @@
"""Turns a `RustDenial` into the public error the proxy raised for it before the decision moved to Rust."""
from __future__ import annotations
from litellm.proxy._types import ProxyErrorTypes, ProxyException
from litellm.rust_bridge._native import RustDenial
def denial_error(denial: RustDenial) -> Exception:
match denial:
case RustDenial.Proxy(status=status, message=message, error_type=error_type, param=param):
return ProxyException(message=message, type=ProxyErrorTypes(error_type), param=param, code=status)
case unknown:
raise RuntimeError(f"rust auth returned a denial this host does not know: {unknown!r}")

View file

@ -8,7 +8,6 @@ Returns a UserAPIKeyAuth object if the API key is valid
"""
import asyncio
import fnmatch
import re
import secrets
from collections.abc import Mapping, Sequence
@ -48,6 +47,8 @@ from litellm.models.end_user import LiteLLM_EndUserTable
from litellm.models.team import LiteLLM_TeamRebuiltFromToken
from litellm.proxy._types import *
from litellm.proxy.agent_endpoints.auth.agent_caller import agent_caller_from_headers
from litellm.proxy.auth import core
from litellm.proxy.auth import denial as auth_denial
from litellm.proxy.auth.access_group_rules import access_group_ids_for_identity
from litellm.proxy.auth.auth_checks import ( # noqa: F401 # legacy module exports
ExperimentalUIJWTToken,
@ -222,6 +223,7 @@ from litellm.router_api import (
references_provider_scoped_resource,
request_fallback_chain,
)
from litellm.rust_bridge._native import RustAuth, RustDenial, RustPlan
from litellm.secret_managers.main import get_secret_bool
from litellm.types.services import ServiceTypes
@ -238,27 +240,6 @@ except ImportError as e:
user_api_key_service_logger_obj: Final = ServiceLogging() # used for tracking latency on OTEL
def _normalize_public_auth_route(route: str) -> str:
if route != "/" and route.endswith("/"):
return route.rstrip("/")
return route
def _route_requires_auth_despite_public(route: str, general_settings: dict | None) -> bool:
normalized_route: Final = _normalize_public_auth_route(route)
if normalized_route == "/metrics":
return litellm.require_auth_for_metrics_endpoint is not False
return False
def _is_unauthenticated_public_route(route: str) -> bool:
"""A route the builder serves without credentials, so nothing on the request may create or charge anything."""
return not _route_requires_auth_despite_public(route=route, general_settings=None) and (
route in LiteLLMRoutes.public_routes.value or route_in_additonal_public_routes(current_route=route)
)
custom_litellm_key_header: Final = APIKeyHeader(
name=SpecialHeaders.custom_litellm_api_key.value,
auto_error=False,
@ -1242,95 +1223,6 @@ def _get_bearer_token_or_received_api_key(api_key: str) -> str:
return api_key
def _routing_selector_matches_claim(
selector_value: object,
claim_value: object,
*,
split_space_delimited: bool = False,
) -> bool:
if selector_value is None:
return True
selector_list: Final[list[str]] = (
[str(v) for v in selector_value] if isinstance(selector_value, list) else [str(selector_value)]
)
if claim_value is None:
return False
if isinstance(claim_value, list):
claim_list = [str(v) for v in claim_value]
elif split_space_delimited and isinstance(claim_value, str) and " " in claim_value.strip():
# OAuth/OIDC often sends scope as a single space-delimited string. Only split
# for the scope selector: iss/aud/client_id must stay exact full-string match
# on unverified claims (see routing override security review). The elif guard
# (`" " in claim_value.strip()`) ensures at least two non-empty tokens survive.
claim_list = [v for v in claim_value.strip().split(" ") if v]
else:
claim_list = [str(claim_value)]
def _selector_matches_claim(selector: str, claim: str) -> bool:
# NOTE: wildcard matching is case-sensitive (fnmatch.fnmatchcase).
if "*" in selector or "?" in selector:
# Without scope splitting, do not let `*` span whitespace: a malformed
# iss like "trusted.example.com evil.com" must not match "trusted.*".
# Scope uses split_space_delimited so each claim token is checked separately.
if not split_space_delimited and any(ch.isspace() for ch in claim):
return False
return fnmatch.fnmatchcase(claim, selector)
return selector == claim
return any(_selector_matches_claim(selector=s, claim=c) for s in selector_list for c in claim_list)
def _matches_routing_override(token_claims: dict, override: "JWTRoutingOverride") -> bool:
return (
_routing_selector_matches_claim(override.iss, token_claims.get("iss"))
and _routing_selector_matches_claim(override.client_id, token_claims.get("client_id"))
and _routing_selector_matches_claim(
override.scope,
token_claims.get("scope"),
split_space_delimited=True,
)
and _routing_selector_matches_claim(override.aud, token_claims.get("aud"))
)
def oauth2_introspection_applies(
api_key: str, route: str, *, enable_oauth2_auth: bool, enable_jwt_auth: bool, jwt_handler: JWTHandler
) -> bool:
"""Whether LiteLLM validates ``api_key`` on ``route`` by OAuth2 token introspection, on LLM API, info and
lens routes only: a non-JWT token when OAuth2 auth is on globally, or a JWT matched by a routing override."""
is_jwt: Final = enable_jwt_auth and jwt_handler.is_jwt(token=api_key)
# Routing uses unverified JWT claims only to choose auth path.
# Final authentication is enforced by the selected validator.
route_jwt_to_oauth2: Final = is_jwt and _should_route_jwt_to_oauth2_override(token=api_key, jwt_handler=jwt_handler)
covered_route: Final = (
RouteChecks.is_llm_api_route(route=route)
or RouteChecks.is_info_route(route=route)
or route == "/lens"
or route.startswith("/lens/")
)
return covered_route and ((enable_oauth2_auth and not is_jwt) or route_jwt_to_oauth2)
def _should_route_jwt_to_oauth2_override(token: str, jwt_handler: JWTHandler) -> bool:
routing_overrides: Final = jwt_handler.litellm_jwtauth.routing_overrides
if not routing_overrides:
return False
token_claims: Final = jwt_handler.get_unverified_claims(token=token)
if token_claims is None:
return False
for override in routing_overrides:
if override.path == "oauth2" and _matches_routing_override(token_claims=token_claims, override=override):
verbose_proxy_logger.debug("JWT routing override matched. Routing token to OAuth2 introspection.")
return True
return False
def get_bearer_token(
api_key: str,
) -> str:
@ -1671,6 +1563,15 @@ def get_api_key(
return api_key, passed_in_key
def pass_through_auth_off(route: str, pass_through_endpoints: list[dict] | None) -> bool:
"""A configured pass-through endpoint on ``route`` turns auth off. ``auth`` defaults to on: a raw config
dict without the key must never become an unauthenticated forwarder."""
return any(
isinstance(endpoint, dict) and endpoint.get("path", "") == route and endpoint.get("auth", True) is not True
for endpoint in pass_through_endpoints or ()
)
async def check_api_key_for_custom_headers_or_pass_through_endpoints(
request: Request,
route: str,
@ -2621,296 +2522,261 @@ async def user_api_key_auth_builder(
return validated
### LITELLM-DEFINED AUTH FUNCTION ###
#### IF JWT ####
"""
LiteLLM supports using JWTs.
planned: Final = RustAuth.plan(
core.request(
api_key,
route,
pass_through_open=pass_through_auth_off(route, pass_through_endpoints),
from_custom_auth=custom_auth_api_key,
),
core.proxy_settings(),
)
match planned:
case RustDenial() as denial:
raise auth_denial.denial_error(denial)
case RustPlan.Public:
return UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER_VIEW_ONLY)
case RustPlan.OAuth2Introspection:
return await Oauth2Handler.check_oauth2_token(token=api_key)
case RustPlan.OAuth2Proxy:
return await handle_oauth2_proxy_request(request=request)
case RustPlan.PassThroughOpen:
return UserAPIKeyAuth()
case _:
pass
Enable this in proxy config, by setting
```
general_settings:
enable_jwt_auth: true
```
"""
######## Route Checks Before Reading DB / Cache for "token" ################
if _is_unauthenticated_public_route(route):
# check if public endpoint
return UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER_VIEW_ONLY)
########## End of Route Checks Before Reading DB / Cache for "token" ########
enable_oauth2_auth: Final = general_settings.get("enable_oauth2_auth", False) is True
enable_jwt_auth: Final = general_settings.get("enable_jwt_auth", False) is True
if oauth2_introspection_applies(
api_key,
route,
enable_oauth2_auth=enable_oauth2_auth,
enable_jwt_auth=enable_jwt_auth,
jwt_handler=jwt_handler,
):
from litellm.proxy.proxy_server import premium_user
if planned in (RustPlan.Jwt, RustPlan.JwtWithOperatorCode):
# Try JWT-to-Virtual-Key mapping first to avoid
# unnecessary DB queries in auth_builder
do_standard_jwt_auth = True
pending_auto_register: _PendingAutoRegister | None = None
if jwt_handler.litellm_jwtauth.is_virtual_key_mapping_configured():
# Decode JWT to get claims without running full auth_builder
jwt_claims: dict | None = await jwt_handler.auth_jwt(token=api_key)
if premium_user is not True:
raise ProxyException(
message="Oauth2 token validation is only available for premium users. "
+ CommonProxyErrors.not_premium_user.value,
type=ProxyErrorTypes.auth_error,
param="premium_user",
code=status.HTTP_403_FORBIDDEN,
)
from litellm.proxy.agent_endpoints.identity_store import resolve_managed_agent
return await Oauth2Handler.check_oauth2_token(token=api_key)
if general_settings.get("enable_oauth2_proxy_auth", False) is True:
return await handle_oauth2_proxy_request(request=request)
if general_settings.get("enable_jwt_auth", False) is True:
is_jwt = jwt_handler.is_jwt(token=api_key)
verbose_proxy_logger.debug("is_jwt: %s", is_jwt)
if is_jwt:
from litellm.proxy.proxy_server import premium_user
if premium_user is not True:
raise ProxyException(
message=f"JWT Auth is an enterprise only feature. {CommonProxyErrors.not_premium_user.value}",
type=ProxyErrorTypes.auth_error,
param="premium_user",
code=status.HTTP_403_FORBIDDEN,
if (
jwt_claims
and await resolve_managed_agent(jwt_claims, prisma_client, cache=user_api_key_cache) is not None
):
raise HTTPException(
403, "Managed agents require direct JWT authentication without virtual-key mapping"
)
# Try JWT-to-Virtual-Key mapping first to avoid
# unnecessary DB queries in auth_builder
do_standard_jwt_auth = True
pending_auto_register: _PendingAutoRegister | None = None
if jwt_handler.litellm_jwtauth.is_virtual_key_mapping_configured():
# Decode JWT to get claims without running full auth_builder
jwt_claims: dict | None
if jwt_handler.litellm_jwtauth.oidc_userinfo_enabled and not is_jwt:
jwt_claims = await jwt_handler.get_oidc_userinfo(token=api_key)
else:
jwt_claims = await jwt_handler.auth_jwt(token=api_key)
from litellm.proxy.agent_endpoints.identity_store import resolve_managed_agent
if (
jwt_claims
and await resolve_managed_agent(jwt_claims, prisma_client, cache=user_api_key_cache) is not None
):
raise HTTPException(
403, "Managed agents require direct JWT authentication without virtual-key mapping"
resolve_result: Final = await _resolve_jwt_to_virtual_key(
jwt_claims=jwt_claims,
jwt_handler=jwt_handler,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
parent_otel_span=parent_otel_span,
proxy_logging_obj=proxy_logging_obj,
)
if isinstance(resolve_result, UserAPIKeyAuth):
mapped_end_user_id: Final = (
jwt_handler.get_end_user_id( # pyright: ignore[reportUnknownMemberType] # untyped dict token
token=jwt_claims or {}, default_value=None
)
or None
)
valid_token = resolve_result.model_copy(update={"end_user_id": mapped_end_user_id})
api_key = valid_token.token or ""
valid_token.jwt_claims = jwt_claims
do_standard_jwt_auth = False
# Fall through to virtual key checks
if valid_token.user_id is not None and valid_token.user_email is None:
mapped_claims = jwt_claims or {}
mapped_user_email = jwt_handler.get_user_email(token=mapped_claims, default_value=None)
mapped_jwt_user_id: Final = jwt_handler.get_user_id(token=mapped_claims, default_value=None)
if mapped_user_email is not None and mapped_jwt_user_id == valid_token.user_id:
try:
mapped_user_obj: Final = await get_user_object(
user_id=valid_token.user_id,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
user_id_upsert=False,
parent_otel_span=parent_otel_span,
proxy_logging_obj=proxy_logging_obj,
user_email=mapped_user_email,
email_verified=jwt_handler.get_email_verified(
mapped_claims # pyright: ignore[reportUnknownArgumentType] # untyped dict token
),
)
except Exception as e:
verbose_proxy_logger.debug("JWT mapped-key user_email backfill skipped: %s", e)
else:
if mapped_user_obj is not None:
valid_token.user_email = mapped_user_obj.user_email
elif isinstance(resolve_result, _PendingAutoRegister):
# Run full JWT policy (RBAC, scope, custom_validate,
# email-domain) via auth_builder, then create the key
# from the validated identity below.
pending_auto_register = resolve_result
# else: None → FALLBACK_TEAM_MAPPING, falls through to
# standard JWT auth_builder below
resolve_result: Final = await _resolve_jwt_to_virtual_key(
jwt_claims=jwt_claims,
if do_standard_jwt_auth:
with tracer.trace("litellm.proxy.auth.jwt_auth_builder"):
result: Final = await JWTAuthManager.auth_builder(
request_data=request_data,
general_settings=general_settings,
api_key=api_key,
jwt_handler=jwt_handler,
route=route,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
proxy_logging_obj=proxy_logging_obj,
parent_otel_span=parent_otel_span,
request_headers=safe_get_request_headers(request),
request_method=RouteChecks.get_request_method(request=request),
)
is_proxy_admin: Final = result["is_proxy_admin"]
team_id: Final = result["team_id"]
user_id: Final = result["user_id"]
user_email: Final = result["user_email"]
user_object: Final = result["user_object"]
end_user_id = result["end_user_id"]
org_id: Final = result["org_id"]
jwt_claims = result.get("jwt_claims", None)
agent_id: Final[str | None] = result.get("agent_id")
if (
user_object is not None
and isinstance(user_object.metadata, dict)
and user_object.metadata.get("scim_active") is False
):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=f"User={user_id} has been deactivated via SCIM. Keys owned by this user cannot be used.",
)
if is_proxy_admin:
# Proxy admins authenticate via auth_builder (full
# access), not via a mapped virtual key. If
# AUTO_REGISTER was pending, cache a sentinel so
# future requests from this JWT identity skip the
# DB mapping lookup in _resolve_jwt_to_virtual_key.
# Without this, every proxy-admin request under
# AUTO_REGISTER re-hits get_jwt_key_mapping_object.
if pending_auto_register is not None:
await user_api_key_cache.async_set_cache(
key=pending_auto_register.cache_key,
value=_JWT_PROXY_ADMIN_SENTINEL,
ttl=jwt_handler.litellm_jwtauth.virtual_key_mapping_cache_ttl,
)
return JWTAuthManager.user_api_key_auth_from_result(result, parent_otel_span)
valid_token = JWTAuthManager.user_api_key_auth_from_result(result, parent_otel_span)
# AUTO_REGISTER deferred from _resolve_jwt_to_virtual_key.
# JWT policy (RBAC, scope, custom_validate, email-domain)
# has now been enforced by auth_builder above. Create the
# mapping + virtual key from the *validated* identity, then
# replace valid_token with the new key so downstream checks
# use the key-scoped path.
auto_registered: Final = (
await _auto_register_jwt_mapping(
virtual_key_claim_field=pending_auto_register.claim_field,
claim_value=pending_auto_register.claim_value,
jwt_handler=jwt_handler,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
parent_otel_span=parent_otel_span,
proxy_logging_obj=proxy_logging_obj,
cache_key=pending_auto_register.cache_key,
jwt_issuer=pending_auto_register.jwt_issuer,
team_id=team_id,
user_id=user_id,
org_id=org_id,
end_user_id=end_user_id,
agent_id=agent_id,
behavior=pending_auto_register.behavior,
)
if isinstance(resolve_result, UserAPIKeyAuth):
mapped_end_user_id: Final = (
jwt_handler.get_end_user_id( # pyright: ignore[reportUnknownMemberType] # untyped dict token
token=jwt_claims or {}, default_value=None
)
or None
)
valid_token = resolve_result.model_copy(update={"end_user_id": mapped_end_user_id})
api_key = valid_token.token or ""
valid_token.jwt_claims = jwt_claims
do_standard_jwt_auth = False
# Fall through to virtual key checks
if valid_token.user_id is not None and valid_token.user_email is None:
mapped_claims = jwt_claims or {}
mapped_user_email = jwt_handler.get_user_email(token=mapped_claims, default_value=None)
mapped_jwt_user_id: Final = jwt_handler.get_user_id(token=mapped_claims, default_value=None)
if mapped_user_email is not None and mapped_jwt_user_id == valid_token.user_id:
try:
mapped_user_obj: Final = await get_user_object(
user_id=valid_token.user_id,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
user_id_upsert=False,
parent_otel_span=parent_otel_span,
proxy_logging_obj=proxy_logging_obj,
user_email=mapped_user_email,
email_verified=jwt_handler.get_email_verified(
mapped_claims # pyright: ignore[reportUnknownArgumentType] # untyped dict token
),
)
except Exception as e:
verbose_proxy_logger.debug("JWT mapped-key user_email backfill skipped: %s", e)
else:
if mapped_user_obj is not None:
valid_token.user_email = mapped_user_obj.user_email
elif isinstance(resolve_result, _PendingAutoRegister):
# Run full JWT policy (RBAC, scope, custom_validate,
# email-domain) via auth_builder, then create the key
# from the validated identity below.
pending_auto_register = resolve_result
# else: None → FALLBACK_TEAM_MAPPING, falls through to
# standard JWT auth_builder below
if pending_auto_register is not None and prisma_client is not None
else None
)
if isinstance(auto_registered, _JWTKeyMappingFailure):
raise HTTPException(status_code=403, detail=auto_registered.value)
if auto_registered is not None:
auto_registered.jwt_claims = jwt_claims
auto_registered.user_email = user_email
# The auto-registered token is built from the new key's
# columns, which carry no user budget. Carry over the
# already-loaded user row rather than re-reading it, or
# the budget check below has nothing to enforce.
auto_registered.user_model_max_budget = (
user_object.model_max_budget if user_object is not None else None
)
valid_token = auto_registered
api_key = valid_token.token or ""
if do_standard_jwt_auth:
with tracer.trace("litellm.proxy.auth.jwt_auth_builder"):
result: Final = await JWTAuthManager.auth_builder(
request_data=request_data,
general_settings=general_settings,
api_key=api_key,
jwt_handler=jwt_handler,
route=route,
falls_through_to_key_checks: Final = (
auto_registered is not None
and (
jwt_handler.litellm_jwtauth.auto_register_map_existing_key
or (
pending_auto_register is not None
and pending_auto_register.behavior == UnregisteredJWTClientBehavior.LINK_ONLY
)
)
and master_key is not None
)
if not falls_through_to_key_checks:
# Check if model has zero cost - if so, skip all budget checks
model = _get_model_from_request_context(
request_data=request_data,
route=route,
request=request,
llm_router=llm_router,
team_id=valid_token.team_id,
)
skip_budget_checks = request_skips_budget_checks(
route=route,
model=model,
llm_router=llm_router,
request_body=request_data,
http_method=RouteChecks.get_request_method(request),
)
# Fetch project object for JWT path if project_id is set
_jwt_project_obj = None
if valid_token.project_id is not None:
_jwt_project_obj = await get_project_object(
project_id=valid_token.project_id,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
proxy_logging_obj=proxy_logging_obj,
parent_otel_span=parent_otel_span,
request_headers=safe_get_request_headers(request),
request_method=RouteChecks.get_request_method(request=request),
)
if _jwt_project_obj is not None:
valid_token.project_metadata = _jwt_project_obj.metadata
valid_token.project_alias = _jwt_project_obj.project_alias
# JWT auth returns here rather than falling through to the
# virtual-key checks below, so the user's per-model budget
# has to be enforced on this path too. Without it the
# post-call increment still charges the counter and nothing
# ever reads it, which is worse than not tracking at all.
# Guarded by the same flag the virtual-key path uses, or a
# zero-cost model would be refused here and allowed there,
# while the log above claims all budget checks were skipped.
if not skip_budget_checks:
await _check_user_model_budget(
valid_token=cast(UserAPIKeyAuth, valid_token),
model_max_budget_limiter=model_max_budget_limiter,
models=_get_model_names_for_budget_checks(
model=_get_model_from_request_context(
request_data=request_data,
route=route,
request=request,
llm_router=llm_router,
team_id=valid_token.team_id,
)
),
)
is_proxy_admin: Final = result["is_proxy_admin"]
team_id: Final = result["team_id"]
user_id: Final = result["user_id"]
user_email: Final = result["user_email"]
user_object: Final = result["user_object"]
end_user_id = result["end_user_id"]
org_id: Final = result["org_id"]
jwt_claims = result.get("jwt_claims", None)
agent_id: Final[str | None] = result.get("agent_id")
if (
user_object is not None
and isinstance(user_object.metadata, dict)
and user_object.metadata.get("scim_active") is False
):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=f"User={user_id} has been deactivated via SCIM. Keys owned by this user cannot be used.",
)
if is_proxy_admin:
# Proxy admins authenticate via auth_builder (full
# access), not via a mapped virtual key. If
# AUTO_REGISTER was pending, cache a sentinel so
# future requests from this JWT identity skip the
# DB mapping lookup in _resolve_jwt_to_virtual_key.
# Without this, every proxy-admin request under
# AUTO_REGISTER re-hits get_jwt_key_mapping_object.
if pending_auto_register is not None:
await user_api_key_cache.async_set_cache(
key=pending_auto_register.cache_key,
value=_JWT_PROXY_ADMIN_SENTINEL,
ttl=jwt_handler.litellm_jwtauth.virtual_key_mapping_cache_ttl,
)
return JWTAuthManager.user_api_key_auth_from_result(result, parent_otel_span)
valid_token = JWTAuthManager.user_api_key_auth_from_result(result, parent_otel_span)
# AUTO_REGISTER deferred from _resolve_jwt_to_virtual_key.
# JWT policy (RBAC, scope, custom_validate, email-domain)
# has now been enforced by auth_builder above. Create the
# mapping + virtual key from the *validated* identity, then
# replace valid_token with the new key so downstream checks
# use the key-scoped path.
auto_registered: Final = (
await _auto_register_jwt_mapping(
virtual_key_claim_field=pending_auto_register.claim_field,
claim_value=pending_auto_register.claim_value,
jwt_handler=jwt_handler,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
parent_otel_span=parent_otel_span,
proxy_logging_obj=proxy_logging_obj,
cache_key=pending_auto_register.cache_key,
jwt_issuer=pending_auto_register.jwt_issuer,
team_id=team_id,
user_id=user_id,
org_id=org_id,
end_user_id=end_user_id,
agent_id=agent_id,
behavior=pending_auto_register.behavior,
)
if pending_auto_register is not None and prisma_client is not None
else None
)
if isinstance(auto_registered, _JWTKeyMappingFailure):
raise HTTPException(status_code=403, detail=auto_registered.value)
if auto_registered is not None:
auto_registered.jwt_claims = jwt_claims
auto_registered.user_email = user_email
# The auto-registered token is built from the new key's
# columns, which carry no user budget. Carry over the
# already-loaded user row rather than re-reading it, or
# the budget check below has nothing to enforce.
auto_registered.user_model_max_budget = (
user_object.model_max_budget if user_object is not None else None
)
valid_token = auto_registered
api_key = valid_token.token or ""
falls_through_to_key_checks: Final = (
auto_registered is not None
and (
jwt_handler.litellm_jwtauth.auto_register_map_existing_key
or (
pending_auto_register is not None
and pending_auto_register.behavior == UnregisteredJWTClientBehavior.LINK_ONLY
)
)
and master_key is not None
)
if not falls_through_to_key_checks:
# Check if model has zero cost - if so, skip all budget checks
model = _get_model_from_request_context(
request_data=request_data,
route=route,
request=request,
llm_router=llm_router,
team_id=valid_token.team_id,
)
skip_budget_checks = request_skips_budget_checks(
route=route,
model=model,
llm_router=llm_router,
request_body=request_data,
http_method=RouteChecks.get_request_method(request),
)
# Fetch project object for JWT path if project_id is set
_jwt_project_obj = None
if valid_token.project_id is not None:
_jwt_project_obj = await get_project_object(
project_id=valid_token.project_id,
prisma_client=prisma_client,
user_api_key_cache=user_api_key_cache,
proxy_logging_obj=proxy_logging_obj,
)
if _jwt_project_obj is not None:
valid_token.project_metadata = _jwt_project_obj.metadata
valid_token.project_alias = _jwt_project_obj.project_alias
# JWT auth returns here rather than falling through to the
# virtual-key checks below, so the user's per-model budget
# has to be enforced on this path too. Without it the
# post-call increment still charges the counter and nothing
# ever reads it, which is worse than not tracking at all.
# Guarded by the same flag the virtual-key path uses, or a
# zero-cost model would be refused here and allowed there,
# while the log above claims all budget checks were skipped.
if not skip_budget_checks:
await _check_user_model_budget(
valid_token=cast(UserAPIKeyAuth, valid_token),
model_max_budget_limiter=model_max_budget_limiter,
models=_get_model_names_for_budget_checks(
model=_get_model_from_request_context(
request_data=request_data,
route=route,
request=request,
llm_router=llm_router,
team_id=valid_token.team_id,
)
),
)
return cast(UserAPIKeyAuth, valid_token)
return cast(UserAPIKeyAuth, valid_token)
#### ELSE ####
## CHECK PASS-THROUGH ENDPOINTS ##
@ -2926,17 +2792,11 @@ async def user_api_key_auth_builder(
elif isinstance(response, UserAPIKeyAuth):
return response
if master_key is None:
if isinstance(api_key, str):
return UserAPIKeyAuth(
api_key=api_key,
user_role=LitellmUserRoles.INTERNAL_USER,
parent_otel_span=parent_otel_span,
)
else:
return UserAPIKeyAuth(
user_role=LitellmUserRoles.INTERNAL_USER,
parent_otel_span=parent_otel_span,
)
return UserAPIKeyAuth(
api_key=api_key,
user_role=LitellmUserRoles.INTERNAL_USER,
parent_otel_span=parent_otel_span,
)
elif api_key is None: # only require api key if master key is set
raise ProxyException(
message="Authentication Error, No api key passed in.",
@ -4600,7 +4460,7 @@ async def _authorize_authenticated_request_checks(
safe_get_request_headers(request) # pyright: ignore[reportUnknownArgumentType] # request headers are untyped
)
user_api_key_auth_obj.customer_hierarchy = None # rebind-ok: request state, never inherited from a cached key
if customer_identity is not None and not _is_unauthenticated_public_route(route):
if customer_identity is not None and not RustAuth.is_public_route(route, core.proxy_settings()):
with tracer.trace("litellm.proxy.auth.resolve_customer_hierarchy"): # pyright: ignore[reportUnknownMemberType] # tracer is the untyped proxy tracer
try:
hierarchy: Final = await resolve_customer_hierarchy(

View file

@ -50,7 +50,6 @@ from litellm.proxy.auth.oauth2_check import OAuth2TokenValidationError
from litellm.proxy.auth.user_api_key_auth import ( # noqa: F401 # legacy module exports
_get_bearer_token_or_received_api_key, # pyright: ignore[reportPrivateUsage] # shared x-litellm-api-key parser lives with user_api_key_auth
_run_centralized_common_checks, # pyright: ignore[reportPrivateUsage,reportUnusedImport] # backwards-compatible package export
oauth2_introspection_applies,
run_centralized_common_checks,
user_api_key_auth,
)
@ -94,6 +93,7 @@ from litellm.repositories.table_repositories import (
AgentsRepository,
MCPServerRepository,
)
from litellm.rust_bridge._native import RustAuth
from litellm.types.mcp_server.mcp_server_manager import MCPServer
from litellm.types.proxy.auth.auth_checks import UserNotFoundError
@ -290,23 +290,17 @@ async def _bearer_is_litellm_credential(token: str) -> bool:
def _identity_check(token: str, route: str, settings: Mapping[str, object]) -> _IdentityCheck | None:
"""The identity check LiteLLM's own auth would run on ``token`` for ``route``, in its order: OAuth2
introspection, then trusted reverse-proxy identity headers, then a JWT whose issuer may be LiteLLM's."""
from litellm.proxy.auth import core as auth_core # noqa: PLC0415 # proxy import cycle
from litellm.proxy.auth.handle_jwt import JWTHandler # noqa: PLC0415 # proxy import cycle
from litellm.proxy.mcp_server.bridge_token_flow import ( # noqa: PLC0415 # bridge flow imports this module
jwt_issuer_may_be_litellm,
)
from litellm.proxy.proxy_server import ( # noqa: PLC0415 # startup owns the active auth configuration
jwt_handler,
premium_user,
)
enable_jwt_auth: Final = settings.get("enable_jwt_auth") is True
if oauth2_introspection_applies(
token,
route,
enable_oauth2_auth=settings.get("enable_oauth2_auth") is True,
enable_jwt_auth=enable_jwt_auth,
jwt_handler=jwt_handler,
):
if RustAuth.oauth2_introspection_applies(auth_core.request(token, route), auth_core.proxy_settings()):
return "oauth2" if premium_user is True else None
if settings.get("enable_oauth2_proxy_auth") is True:
return "oauth2_proxy"

View file

@ -6035,7 +6035,7 @@ def _bind_general_settings_store(settings: SettingsStore) -> None:
general_settings = settings # pyright: ignore[reportAssignmentType] # legacy global accepts mappings
def _current_general_settings() -> Mapping[str, object]:
def current_general_settings() -> Mapping[str, object]:
"""The live ``general_settings``, whichever object a config reload has bound since the caller was created."""
return general_settings
@ -12090,14 +12090,14 @@ class ProxyStartupEvent:
scheduler=scheduler,
proxy_logging_obj=proxy_logging_obj,
prisma_client=prisma_client,
read_general_settings=_current_general_settings,
read_general_settings=current_general_settings,
)
from litellm.proxy.spend_tracking.performance_alerts import RUN_INTERVAL, run_performance_alerts
from litellm.repositories.performance_alert_repository import PerformanceAlertRepository
async def run_performance_alerts_job() -> None:
if _current_general_settings().get("performance_alerts_enabled", True) is True:
if current_general_settings().get("performance_alerts_enabled", True) is True:
await run_performance_alerts(PerformanceAlertRepository(prisma_client, enterprise=premium_user is True))
scheduler.add_job( # pyright: ignore[reportUnknownMemberType] # APScheduler does not provide typed job methods
@ -12119,7 +12119,7 @@ class ProxyStartupEvent:
email_connected: Final = bool(os.getenv("SMTP_HOST") and os.getenv("SMTP_SENDER_EMAIL"))
if not email_connected and not slack.performance_alert_webhooks():
return
if _current_general_settings().get("performance_alerts_enabled", True) is not True:
if current_general_settings().get("performance_alerts_enabled", True) is not True:
return
if not (
await PerformanceAlertRepository(prisma_client, enterprise=premium_user is True).monitoring()
@ -12183,7 +12183,7 @@ class ProxyStartupEvent:
)
### SPEND LOG CLEANUP ###
cleanup_settings: Final = _current_general_settings()
cleanup_settings: Final = current_general_settings()
_register_spend_log_cleanup_jobs(scheduler, prisma_client, cleanup_settings) # pyright: ignore[reportUnknownArgumentType, reportArgumentType] # apscheduler is untyped
if _wants_cleanup_jobs(cleanup_settings):
proxy_config.record_cleanup_schedule_attempt(cleanup_settings)
@ -12438,7 +12438,7 @@ class ProxyStartupEvent:
prisma_client=prisma_client,
cache=proxy_logging_obj.internal_usage_cache.dual_cache,
email_logger=expiry_email_logger,
default_days=lambda: configured_key_expiry_alert_days(_current_general_settings()),
default_days=lambda: configured_key_expiry_alert_days(current_general_settings()),
pod_lock_manager=proxy_logging_obj.db_spend_update_writer.pod_lock_manager,
)
except Exception: # noqa: BLE001 # a setup failure must not stop later background jobs registering

View file

@ -4055,10 +4055,15 @@ dependencies = [
name = "litellm-gateway-auth-core"
version = "0.1.0"
dependencies = [
"base64 0.22.1",
"http 1.4.2",
"jsonwebtoken",
"litellm-config",
"litellm-fnmatch",
"litellm-secret-value",
"litellm-starlette",
"rstest",
"serde_json",
"strum",
"thiserror 2.0.19",
]

View file

@ -0,0 +1,53 @@
use serde::Deserialize;
use crate::AdditionalFields;
/// A config value YAML may give as one string or a list of them.
#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
#[serde(untagged)]
pub enum OneOrMany {
One(String),
Many(Box<[String]>),
}
impl OneOrMany {
pub fn values(&self) -> &[String] {
match self {
Self::One(value) => std::slice::from_ref(value),
Self::Many(values) => values,
}
}
}
#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq, Eq)]
pub enum RoutingPath {
#[default]
#[serde(rename = "oauth2")]
OAuth2,
}
#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct JwtRoutingOverride {
pub iss: OneOrMany,
#[serde(default)]
pub client_id: Option<OneOrMany>,
#[serde(default)]
pub scope: Option<OneOrMany>,
#[serde(default)]
pub aud: Option<OneOrMany>,
#[serde(default)]
pub path: RoutingPath,
}
/// `general_settings.litellm_jwtauth`, with `LiteLLM_JWTAuth`'s defaults. `custom_validate` is
/// the operator's import path: only the host can run it, so the core only learns that it is set.
#[derive(Clone, Default, Deserialize, veil::Redact)]
#[serde(default)]
pub struct JwtAuthSettings {
pub custom_validate: Option<String>,
pub routing_overrides: Option<Box<[JwtRoutingOverride]>>,
#[serde(flatten)]
#[redact(with = "[REDACTED]")]
pub additional_fields: AdditionalFields,
}

View file

@ -1,3 +1,4 @@
mod auth;
mod error;
mod mcp;
mod model;
@ -9,6 +10,7 @@ mod value;
use serde::Deserialize;
pub use auth::{JwtAuthSettings, JwtRoutingOverride, OneOrMany, RoutingPath};
pub use error::Error;
pub use litellm_router_types::{LitellmParams, Spelled};
pub use mcp::{McpAuth, McpServer, McpTransport};

View file

@ -1,10 +1,12 @@
use litellm_python_compat::lenient::IsTrue;
use litellm_secret_value::SecretValue;
use serde::Deserialize;
use serde_with::serde_as;
use veil::Redact;
use crate::{
AdditionalFields, CacheSettings, Object, PassThroughEndpoint, RedisSettings, Spelled, Value,
value::one_or_many,
AdditionalFields, CacheSettings, JwtAuthSettings, Object, PassThroughEndpoint, RedisSettings,
RouteList, Spelled, Value, value::one_or_many,
};
#[derive(Clone, Debug, Deserialize)]
@ -37,6 +39,7 @@ pub struct TracingSettings {
pub additional_fields: AdditionalFields,
}
#[serde_as]
#[derive(Clone, Debug, Deserialize)]
#[serde(default)]
pub struct GeneralSettings {
@ -71,6 +74,15 @@ pub struct GeneralSettings {
pub mcp_allowed_hosts: Option<Box<[String]>>,
pub mcp_allowed_origins: Box<[String]>,
pub pass_through_endpoints: Option<Box<[PassThroughEndpoint]>>,
/// `general_settings.get(...) is True`, how the proxy reads each auth flag.
#[serde_as(as = "IsTrue")]
pub enable_jwt_auth: bool,
#[serde_as(as = "IsTrue")]
pub enable_oauth2_auth: bool,
#[serde_as(as = "IsTrue")]
pub enable_oauth2_proxy_auth: bool,
pub public_routes: Option<RouteList>,
pub litellm_jwtauth: Option<JwtAuthSettings>,
#[serde(flatten)]
pub additional_fields: AdditionalFields,
}
@ -109,6 +121,11 @@ impl Default for GeneralSettings {
mcp_allowed_hosts: None,
mcp_allowed_origins: Box::default(),
pass_through_endpoints: None,
enable_jwt_auth: false,
enable_oauth2_auth: false,
enable_oauth2_proxy_auth: false,
public_routes: None,
litellm_jwtauth: None,
additional_fields: AdditionalFields::default(),
}
}
@ -172,3 +189,20 @@ pub struct LiteLlmSettings {
#[serde(flatten)]
pub additional_fields: AdditionalFields,
}
#[cfg(test)]
mod tests {
use crate::JwtAuthSettings;
#[test]
fn jwt_auth_settings_hide_unknown_fields() {
let settings: JwtAuthSettings =
serde_json::from_value(serde_json::json!({"future_secret": "credential-value"}))
.unwrap();
let debug = format!("{settings:?}");
assert!(!debug.contains("credential-value"), "{debug}");
assert!(debug.contains("[REDACTED]"), "{debug}");
}
}

View file

@ -1,4 +1,4 @@
use litellm_config::{Config, Error, Spelled, TracingStoreSettings};
use litellm_config::{Config, Error, RouteList, Spelled, TracingStoreSettings};
use rstest::rstest;
#[rstest]
@ -446,6 +446,28 @@ fn pass_through_flags_read_like_python(
);
}
#[rstest]
#[case::bool_true("true", true)]
#[case::bool_false("false", false)]
#[case::string_true("'true'", false)]
#[case::environment_reference("os.environ/ENABLE_JWT_AUTH", false)]
#[case::number("1", false)]
fn auth_flags_are_on_only_for_boolean_true(#[case] value: &str, #[case] expected: bool) {
let config = Config::from_yaml(&format!(
"general_settings: {{enable_jwt_auth: {value}, enable_oauth2_auth: {value}, enable_oauth2_proxy_auth: {value}}}"
))
.unwrap();
let general = config.general_settings;
assert_eq!(
[
general.enable_jwt_auth,
general.enable_oauth2_auth,
general.enable_oauth2_proxy_auth
],
[expected; 3]
);
}
#[rstest]
fn a_pass_through_endpoint_without_a_path_fails_the_load_like_registration() {
assert!(
@ -477,3 +499,14 @@ fn debug_hides_inline_callback_settings(#[case] field: &str) {
.unwrap();
assert!(!format!("{config:?}").contains("callback-list-secret"));
}
#[rstest]
#[case::list("[/a/*, /b]", Some(RouteList::Valid(["/a/*".to_owned(), "/b".to_owned()].into())))]
#[case::bare_string("/a/*", Some(RouteList::Malformed))]
#[case::non_string_entry("[/a, 5, /b/*]", Some(RouteList::Malformed))]
#[case::null("null", None)]
fn public_routes_never_fail_the_load(#[case] value: &str, #[case] expected: Option<RouteList>) {
let config =
Config::from_yaml(&format!("general_settings: {{public_routes: {value}}}")).unwrap();
assert_eq!(config.general_settings.public_routes, expected);
}

View file

@ -7,10 +7,15 @@ repository.workspace = true
[dependencies]
http.workspace = true
jsonwebtoken = { workspace = true, features = ["rust_crypto"] }
litellm-config.workspace = true
litellm-fnmatch.workspace = true
litellm-secret-value.workspace = true
litellm-starlette.workspace = true
serde_json.workspace = true
strum.workspace = true
thiserror.workspace = true
[dev-dependencies]
base64.workspace = true
rstest.workspace = true

View file

@ -0,0 +1,3 @@
mod verify;
pub use verify::{Claims, is_jwt, unverified_claims};

View file

@ -0,0 +1,48 @@
use jsonwebtoken::dangerous::insecure_decode_claims;
use serde_json::{Map, Value};
#[derive(Clone, Debug, PartialEq)]
pub struct Claims(pub Map<String, Value>);
pub fn is_jwt(token: &str) -> bool {
token.split('.').count() == 3
}
/// `get_unverified_claims`: the payload of a well-formed token, signature unchecked.
pub fn unverified_claims(token: &str) -> Option<Claims> {
if !is_jwt(token) {
return None;
}
insecure_decode_claims(token).ok().map(Claims)
}
#[cfg(test)]
mod tests {
use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
use rstest::rstest;
use serde_json::json;
use super::*;
use crate::test_support::unsigned_jwt;
fn b64(value: &Value) -> String {
URL_SAFE_NO_PAD.encode(serde_json::to_vec(value).unwrap())
}
fn raw_token(header: &str, payload: &str) -> String {
format!("{header}.{payload}.AAAA")
}
#[rstest]
#[case::bad_signature_still_read(&unsigned_jwt(&json!({"a": 1})), Some(json!({"a": 1})))]
#[case::two_segments("e30.e30", None)]
#[case::payload_not_object(&raw_token(&b64(&json!({"alg": "RS256"})), &b64(&json!([1]))), None)]
#[case::detached_payload(&raw_token(&b64(&json!({"alg": "RS256", "b64": false, "crit": ["b64"]})), ""), None)]
fn unverified_claims_read_the_payload(#[case] token: &str, #[case] expected: Option<Value>) {
let expected = expected.map(|claims| match claims {
Value::Object(map) => Claims(map),
other => panic!("claims must be an object: {other}"),
});
assert_eq!(unverified_claims(token), expected);
}
}

View file

@ -0,0 +1 @@
pub mod jwt;

View file

@ -0,0 +1,11 @@
const NOT_PREMIUM_USER: &str = "You must be a LiteLLM Enterprise user to use this feature. If you have a license please \
set `LITELLM_LICENSE` in your env. Get a 7 day trial key here: https://www.litellm.ai/enterprise#trial. \n\
Pricing: https://www.litellm.ai/#pricing";
#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
pub enum PremiumRequired {
#[error("Oauth2 token validation is only available for premium users. {NOT_PREMIUM_USER}")]
OAuth2,
#[error("JWT Auth is an enterprise only feature. {NOT_PREMIUM_USER}")]
Jwt,
}

View file

@ -1,7 +1,16 @@
pub mod authn;
mod error;
pub mod plan;
mod public;
pub mod routes;
#[cfg(test)]
mod test_support;
mod token;
mod value;
pub use error::PremiumRequired;
pub use public::{ErrorType, PublicDenial};
pub use routes::{
ManagedRoute, MissingRouteGroup, RouteAllowlist, RouteGroup, RouteGroups, matches_wildcard,
};
pub use token::Token;

View file

@ -0,0 +1,273 @@
//! Which bearer tokens LiteLLM validates by calling the IdP's OAuth2 introspection endpoint instead
//! of validating them itself. A deployment can run JWT auth for one IdP and introspection for
//! another whose access tokens are also JWTs, so `general_settings.litellm_jwtauth.routing_overrides`
//! lists the JWTs that belong to introspection. Their claims are read unverified, only to pick the
//! validator, and introspection then authenticates the token.
use litellm_config::{GeneralSettings, JwtRoutingOverride, OneOrMany, RoutingPath};
use litellm_fnmatch::Pattern;
use serde_json::Value;
use super::{BearerToken, Request};
use crate::{
authn::jwt::{Claims, unverified_claims},
routes::table::is_lens_route,
value::{id_text, is_separator, trim},
};
#[derive(Clone, Debug, Default)]
pub struct Introspection {
/// [`general_settings.enable_oauth2_auth`](GeneralSettings::enable_oauth2_auth)
opaque_tokens: bool,
/// [`general_settings.litellm_jwtauth.routing_overrides`](litellm_config::JwtAuthSettings::routing_overrides),
/// each a [`JwtRoutingOverride`]
jwts: Box<[JwtSelector]>,
}
impl Introspection {
pub fn new(general: &GeneralSettings) -> Self {
Self {
opaque_tokens: general.enable_oauth2_auth,
jwts: general
.litellm_jwtauth
.as_ref()
.and_then(|jwt| jwt.routing_overrides.as_deref())
.unwrap_or_default()
.iter()
.map(JwtSelector::new)
.collect(),
}
}
pub(super) fn applies(&self, request: &Request<'_>, token: BearerToken<'_>) -> bool {
(request.is_llm_api_route || request.is_info_route || is_lens_route(request.route))
&& self.validates(token)
}
fn validates(&self, token: BearerToken<'_>) -> bool {
match token {
BearerToken::Opaque => self.opaque_tokens,
BearerToken::Jwt(token) => {
!self.jwts.is_empty()
&& unverified_claims(token.expose())
.is_some_and(|claims| self.jwts.iter().any(|jwt| jwt.matches(&claims)))
}
}
}
}
/// One `routing_overrides` entry. Every selector it sets has to match.
#[derive(Clone, Debug)]
struct JwtSelector {
iss: ClaimPattern,
client_id: Option<ClaimPattern>,
aud: Option<ClaimPattern>,
scope: Option<ScopePattern>,
}
impl JwtSelector {
fn new(routing: &JwtRoutingOverride) -> Self {
let JwtRoutingOverride {
iss,
client_id,
scope,
aud,
path: RoutingPath::OAuth2,
} = routing;
Self {
iss: ClaimPattern(selectors(iss)),
client_id: client_id
.as_ref()
.map(|values| ClaimPattern(selectors(values))),
aud: aud.as_ref().map(|values| ClaimPattern(selectors(values))),
scope: scope.as_ref().map(|values| ScopePattern(selectors(values))),
}
}
fn matches(&self, claims: &Claims) -> bool {
let claim = |name: &str| claims.0.get(name);
self.iss.matches(claim("iss"))
&& self
.client_id
.as_ref()
.is_none_or(|pattern| pattern.matches(claim("client_id")))
&& self
.aud
.as_ref()
.is_none_or(|pattern| pattern.matches(claim("aud")))
&& self
.scope
.as_ref()
.is_none_or(|pattern| pattern.matches(claim("scope")))
}
}
#[derive(Clone, Debug)]
enum Selector {
Exact(String),
Glob(Pattern),
}
fn selectors(values: &OneOrMany) -> Box<[Selector]> {
values
.values()
.iter()
.map(|value| match value.contains(['*', '?']) {
true => Selector::Glob(Pattern::new(value)),
false => Selector::Exact(value.clone()),
})
.collect()
}
/// Matches a claim value whole. A wildcard never spans whitespace, so `trusted.*` cannot match an
/// unsigned `trusted.example.com evil.com`.
#[derive(Clone, Debug)]
struct ClaimPattern(Box<[Selector]>);
impl ClaimPattern {
fn matches(&self, claim: Option<&Value>) -> bool {
whole_values(claim).iter().any(|value| {
self.0.iter().any(|selector| match selector {
Selector::Exact(exact) => exact == value,
Selector::Glob(glob) => !value.contains(is_separator) && glob.matches(value),
})
})
}
}
/// OAuth sends `scope` as one space-separated string, so each scope is matched on its own.
#[derive(Clone, Debug)]
struct ScopePattern(Box<[Selector]>);
impl ScopePattern {
fn matches(&self, claim: Option<&Value>) -> bool {
scope_values(claim).iter().any(|value| {
self.0.iter().any(|selector| match selector {
Selector::Exact(exact) => exact == value,
Selector::Glob(glob) => glob.matches(value),
})
})
}
}
fn whole_values(claim: Option<&Value>) -> Vec<String> {
match claim {
Some(Value::Array(items)) => items.iter().filter_map(id_text).collect(),
Some(other) => id_text(other).into_iter().collect(),
None => Vec::new(),
}
}
fn scope_values(claim: Option<&Value>) -> Vec<String> {
match claim {
Some(Value::String(text)) if trim(text).contains(' ') => trim(text)
.split(' ')
.filter(|scope| !scope.is_empty())
.map(str::to_owned)
.collect(),
other => whole_values(other),
}
}
#[cfg(test)]
mod tests {
use rstest::rstest;
use serde_json::json;
use super::*;
use crate::{
Token,
test_support::{many, one, unsigned_jwt},
};
const ISSUER: &str = "oauth-issuer.example.com";
fn routing(
client_id: Option<OneOrMany>,
scope: Option<OneOrMany>,
aud: Option<OneOrMany>,
) -> JwtRoutingOverride {
JwtRoutingOverride {
iss: OneOrMany::One(ISSUER.to_owned()),
client_id,
scope,
aud,
path: RoutingPath::OAuth2,
}
}
fn claim_pattern(values: Option<OneOrMany>) -> ClaimPattern {
ClaimPattern(selectors(&values.unwrap()))
}
fn scope_pattern(values: Option<OneOrMany>) -> ScopePattern {
ScopePattern(selectors(&values.unwrap()))
}
#[rstest]
#[case::exact(one("issuer.example.com"), Some(json!("issuer.example.com")), true)]
#[case::other_value(one("issuer.example.com"), Some(json!("other-issuer.example.com")), false)]
#[case::not_split(one("trusted.example.com"), Some(json!("trusted.example.com attacker.example.com")), false)]
#[case::wildcard_never_spans_spaces(one("trusted.*"), Some(json!("trusted.example.com attacker.example.com")), false)]
#[case::wildcard(one("trusted.*"), Some(json!("trusted.example.com")), true)]
#[case::any_selector(many(&["issuer-a.example.com", "issuer-b.example.com"]), Some(json!("issuer-b.example.com")), true)]
#[case::leading_star(one("*MID_LITELLM"), Some(json!("STREAM_MID_LITELLM")), true)]
#[case::leading_star_miss(one("*MID_LITELLM"), Some(json!("REDIS_LITELLM")), false)]
#[case::question_marks(one("machine-??"), Some(json!("machine-01")), true)]
#[case::question_marks_count(one("machine-??"), Some(json!("machine-001")), false)]
#[case::wildcard_is_case_sensitive(one("*litellm"), Some(json!("BATCH_LITELLM")), false)]
#[case::wildcard_same_case(one("*LITELLM"), Some(json!("BATCH_LITELLM")), true)]
#[case::any_wildcard(many(&["service-*", "batch-*"]), Some(json!("batch-123")), true)]
#[case::no_wildcard_matches(many(&["service-*", "batch-*"]), Some(json!("other-123")), false)]
#[case::list_claim(one("App:LiteLLM"), Some(json!(["openid", "App:LiteLLM"])), true)]
#[case::missing_claim(one("App:LiteLLM"), None, false)]
#[case::null_claim(one("App:LiteLLM"), Some(Value::Null), false)]
#[case::number_claim(one("42"), Some(json!(42)), true)]
#[case::bool_claim_is_no_value(one("True"), Some(json!(true)), false)]
fn claim_patterns_match_whole_values(
#[case] values: Option<OneOrMany>,
#[case] claim: Option<Value>,
#[case] expected: bool,
) {
assert_eq!(claim_pattern(values).matches(claim.as_ref()), expected);
}
#[rstest]
#[case::split(one("App:LiteLLM"), Some(json!("App:LiteLLM openid")), true)]
#[case::wildcard(one("App:*"), Some(json!("App:LiteLLM openid")), true)]
#[case::any_selector(many(&["openid", "App:LiteLLM"]), Some(json!("openid profile")), true)]
#[case::list(one("App:LiteLLM"), Some(json!(["openid", "App:LiteLLM"])), true)]
#[case::missing(one("App:LiteLLM"), None, false)]
#[case::no_scope_matches(one("App:LiteLLM"), Some(json!("openid profile")), false)]
fn scope_patterns_match_each_scope(
#[case] values: Option<OneOrMany>,
#[case] claim: Option<Value>,
#[case] expected: bool,
) {
assert_eq!(scope_pattern(values).matches(claim.as_ref()), expected);
}
#[rstest]
#[case::issuer_only(routing(None, None, None), json!({"iss": ISSUER}), true)]
#[case::other_issuer(routing(None, None, None), json!({"iss": "other.example.com"}), false)]
#[case::scope_narrows(routing(None, one("App:LiteLLM"), None), json!({"iss": ISSUER, "scope": "App:LiteLLM openid"}), true)]
#[case::client_id_wildcard(routing(one("*MID_LITELLM"), None, None), json!({"iss": ISSUER, "client_id": "BATCH_MID_LITELLM"}), true)]
#[case::client_id_miss(routing(one("*MID_LITELLM"), None, None), json!({"iss": ISSUER, "client_id": "BATCH_PORTAL"}), false)]
#[case::list_audience(routing(None, None, many(&["api://litellm", "api://fallback"])), json!({"iss": ISSUER, "aud": ["api://other", "api://litellm"]}), true)]
#[case::selectors_are_anded(routing(one("*MID_LITELLM"), one("App:LiteLLM"), None), json!({"iss": ISSUER, "scope": "App:Other openid", "client_id": "BATCH_MID_LITELLM"}), false)]
fn routing_override_selects_jwts(
#[case] routing: JwtRoutingOverride,
#[case] claims: Value,
#[case] expected: bool,
) {
let introspection = Introspection::new(&GeneralSettings {
litellm_jwtauth: Some(litellm_config::JwtAuthSettings {
routing_overrides: Some(Box::new([routing])),
..litellm_config::JwtAuthSettings::default()
}),
..GeneralSettings::default()
});
let token = Token::new(unsigned_jwt(&claims));
assert_eq!(introspection.validates(BearerToken::Jwt(&token)), expected);
}
}

View file

@ -0,0 +1,393 @@
mod introspection;
mod public_routes;
use litellm_config::GeneralSettings;
use strum::VariantArray;
pub use self::{introspection::Introspection, public_routes::PublicRoutes};
use crate::{PremiumRequired, Token, routes::RouteGroups};
#[derive(Clone, Debug, Default)]
pub struct Settings {
public_routes: PublicRoutes,
introspection: Introspection,
/// [`general_settings.enable_oauth2_proxy_auth`](GeneralSettings::enable_oauth2_proxy_auth)
oauth2_proxy: bool,
/// [`general_settings.enable_jwt_auth`](GeneralSettings::enable_jwt_auth)
jwt_auth: bool,
/// [`litellm_jwtauth.custom_validate`](litellm_config::JwtAuthSettings::custom_validate) is set
jwt_operator_code: bool,
/// An enterprise license (`HostFacts::premium`), which JWT auth and
/// OAuth2 introspection need.
premium: bool,
}
impl Settings {
pub fn new(
general: &GeneralSettings,
premium: bool,
metrics_require_auth: bool,
route_groups: &RouteGroups,
) -> Self {
Self {
public_routes: PublicRoutes::new(general, premium, metrics_require_auth, route_groups),
introspection: Introspection::new(general),
oauth2_proxy: general.enable_oauth2_proxy_auth,
jwt_auth: general.enable_jwt_auth,
jwt_operator_code: general
.litellm_jwtauth
.as_ref()
.is_some_and(|jwt| jwt.custom_validate.is_some()),
premium,
}
}
}
#[derive(Clone, Copy, Debug, Default)]
pub struct Request<'a> {
pub route: &'a str,
pub token: Option<&'a Token>,
pub is_llm_api_route: bool,
pub is_info_route: bool,
pub pass_through_open: bool,
/// Custom auth handed back the token, so an open pass-through route still authenticates it.
pub from_custom_auth: bool,
}
/// Declared in the proxy's order: the first plan that applies wins. Custom auth runs before all of
/// them, in the host.
#[derive(Clone, Copy, Debug, PartialEq, Eq, VariantArray)]
pub enum Plan {
Public,
OAuth2Introspection,
OAuth2Proxy,
/// A JWT the operator's `custom_validate` also judges. Only a host with
/// `OperatorHooks` authenticates it, and any other hands the request
/// to one before authenticating.
JwtWithOperatorCode,
Jwt,
/// A configured pass-through endpoint with `auth: false`.
PassThroughOpen,
Key,
}
impl Plan {
fn applies(self, request: &Request<'_>, settings: &Settings) -> bool {
match self {
Self::Public => settings.public_routes.contains(request.route),
Self::OAuth2Introspection => oauth2_introspection_applies(request, settings),
Self::OAuth2Proxy => settings.oauth2_proxy,
Self::JwtWithOperatorCode => {
settings.jwt_operator_code
&& matches!(bearer_token(request, settings), BearerToken::Jwt(_))
}
Self::Jwt => matches!(bearer_token(request, settings), BearerToken::Jwt(_)),
Self::PassThroughOpen => request.pass_through_open && !request.from_custom_auth,
Self::Key => true,
}
}
fn license(self) -> Option<PremiumRequired> {
match self {
Self::OAuth2Introspection => Some(PremiumRequired::OAuth2),
Self::JwtWithOperatorCode | Self::Jwt => Some(PremiumRequired::Jwt),
Self::Public | Self::OAuth2Proxy | Self::PassThroughOpen | Self::Key => None,
}
}
}
/// With JWT auth off, a JWT-shaped token is just an opaque token.
#[derive(Clone, Copy, Debug)]
enum BearerToken<'a> {
Opaque,
Jwt(&'a Token),
}
fn bearer_token<'a>(request: &Request<'a>, settings: &Settings) -> BearerToken<'a> {
match request.token {
Some(token) if settings.jwt_auth && token.is_jwt() => BearerToken::Jwt(token),
_ => BearerToken::Opaque,
}
}
pub fn is_public_route(route: &str, settings: &Settings) -> bool {
settings.public_routes.contains(route)
}
pub fn oauth2_introspection_applies(request: &Request<'_>, settings: &Settings) -> bool {
settings
.introspection
.applies(request, bearer_token(request, settings))
}
pub fn plan(request: &Request<'_>, settings: &Settings) -> Result<Plan, PremiumRequired> {
let plan = Plan::VARIANTS
.iter()
.copied()
.find(|plan| plan.applies(request, settings))
.unwrap_or(Plan::Key);
match plan.license() {
Some(feature) if !settings.premium => Err(feature),
_ => Ok(plan),
}
}
#[cfg(test)]
mod tests {
use litellm_config::{
GeneralSettings, JwtAuthSettings, JwtRoutingOverride, OneOrMany, RouteList, RoutingPath,
};
use rstest::{fixture, rstest};
use serde_json::json;
use super::*;
use crate::test_support::{route_groups, unsigned_jwt};
const JWT: &str = "header.claims.signature";
const KEY: &str = "sk-plan-test-key";
const ISSUER: &str = "oauth-issuer.example.com";
fn configured(premium: bool, metrics_require_auth: bool) -> Settings {
let general = GeneralSettings {
enable_jwt_auth: true,
public_routes: Some(RouteList::Valid(Box::new([
"/public-api/*".to_owned(),
"/spend/calculate".to_owned(),
"/metrics".to_owned(),
"/metrics/".to_owned(),
]))),
..GeneralSettings::default()
};
Settings::new(&general, premium, metrics_require_auth, &route_groups())
}
#[fixture]
fn settings() -> Settings {
configured(true, true)
}
fn request<'a>(route: &'a str, token: &'a Token) -> Request<'a> {
Request {
route,
token: Some(token),
..Request::default()
}
}
#[rstest]
#[case::jwt(JWT, Ok(Plan::Jwt))]
#[case::key(KEY, Ok(Plan::Key))]
#[case::two_dots_is_not_a_jwt("a.b", Ok(Plan::Key))]
#[case::four_parts_is_not_a_jwt("a.b.c.d", Ok(Plan::Key))]
#[case::empty_parts_still_count("..", Ok(Plan::Jwt))]
fn tells_jwt_from_key(
settings: Settings,
#[case] token: &str,
#[case] expected: Result<Plan, PremiumRequired>,
) {
assert_eq!(
plan(&request("/chat/completions", &Token::new(token)), &settings),
expected
);
}
#[rstest]
fn jwt_off_sends_jwts_to_keys(settings: Settings) {
let settings = Settings {
jwt_auth: false,
..settings
};
assert_eq!(
plan(&request("/chat/completions", &Token::new(JWT)), &settings),
Ok(Plan::Key)
);
}
#[rstest]
#[case::a_jwt_needs_the_operators_code(JWT, Ok(Plan::JwtWithOperatorCode))]
#[case::a_key_does_not(KEY, Ok(Plan::Key))]
fn custom_validate_plans_jwts_for_a_host_with_operator_code(
#[case] token: &str,
#[case] expected: Result<Plan, PremiumRequired>,
) {
let general = GeneralSettings {
enable_jwt_auth: true,
litellm_jwtauth: Some(JwtAuthSettings {
custom_validate: Some("hooks.validate".to_owned()),
..JwtAuthSettings::default()
}),
..GeneralSettings::default()
};
let settings = Settings::new(&general, true, true, &route_groups());
assert_eq!(
plan(&request("/chat/completions", &Token::new(token)), &settings),
expected
);
}
#[rstest]
fn jwt_without_license_is_refused(settings: Settings) {
let settings = Settings {
premium: false,
..settings
};
assert_eq!(
plan(&request("/chat/completions", &Token::new(JWT)), &settings),
Err(PremiumRequired::Jwt)
);
assert_eq!(
plan(&request("/chat/completions", &Token::new(KEY)), &settings),
Ok(Plan::Key)
);
}
#[rstest]
#[case::builtin("/", true, Ok(Plan::Public))]
#[case::additional_exact("/spend/calculate", true, Ok(Plan::Public))]
#[case::additional_wildcard("/public-api/users/1", true, Ok(Plan::Public))]
#[case::additional_needs_license("/spend/calculate", false, Ok(Plan::Key))]
#[case::builtin_without_license("/", false, Ok(Plan::Public))]
fn public_routes(
#[case] route: &str,
#[case] premium: bool,
#[case] expected: Result<Plan, PremiumRequired>,
) {
assert_eq!(
plan(
&request(route, &Token::new(KEY)),
&configured(premium, true)
),
expected
);
}
#[rstest]
#[case::requires_auth("/metrics", true, Ok(Plan::Key))]
#[case::trailing_slash_requires_auth("/metrics/", true, Ok(Plan::Key))]
#[case::trailing_slash_public("/metrics/", false, Ok(Plan::Public))]
#[case::public("/metrics", false, Ok(Plan::Public))]
fn metrics(
#[case] route: &str,
#[case] metrics_require_auth: bool,
#[case] expected: Result<Plan, PremiumRequired>,
) {
assert_eq!(
plan(
&request(route, &Token::new(KEY)),
&configured(true, metrics_require_auth)
),
expected
);
}
#[rstest]
#[case::llm_route_key("/chat/completions", true, false, KEY, Ok(Plan::OAuth2Introspection))]
#[case::info_route_key("/key/info", false, true, KEY, Ok(Plan::OAuth2Introspection))]
#[case::lens_route("/lens/x", false, false, KEY, Ok(Plan::OAuth2Introspection))]
#[case::lens_lookalike("/lensx", false, false, KEY, Ok(Plan::Key))]
#[case::uncovered_route("/team/new", false, false, KEY, Ok(Plan::Key))]
#[case::jwt_stays_jwt("/chat/completions", true, false, JWT, Ok(Plan::Jwt))]
fn oauth2_introspection(
settings: Settings,
#[case] route: &str,
#[case] is_llm_api_route: bool,
#[case] is_info_route: bool,
#[case] token: &str,
#[case] expected: Result<Plan, PremiumRequired>,
) {
let token = Token::new(token);
let request = Request {
is_llm_api_route,
is_info_route,
..request(route, &token)
};
let settings = Settings {
introspection: Introspection::new(&GeneralSettings {
enable_oauth2_auth: true,
..GeneralSettings::default()
}),
..settings
};
assert_eq!(plan(&request, &settings), expected);
}
#[rstest]
fn routed_jwt_needs_a_license(settings: Settings) {
let settings = Settings {
premium: false,
introspection: Introspection::new(&GeneralSettings {
litellm_jwtauth: Some(JwtAuthSettings {
routing_overrides: Some(Box::new([JwtRoutingOverride {
iss: OneOrMany::One(ISSUER.to_owned()),
client_id: None,
scope: None,
aud: None,
path: RoutingPath::OAuth2,
}])),
..JwtAuthSettings::default()
}),
..GeneralSettings::default()
}),
..settings
};
let token = Token::new(unsigned_jwt(&json!({"iss": ISSUER})));
let routed = Request {
is_llm_api_route: true,
..request("/chat/completions", &token)
};
assert_eq!(plan(&routed, &settings), Err(PremiumRequired::OAuth2));
assert_eq!(
plan(&request("/team/new", &token), &settings),
Err(PremiumRequired::Jwt)
);
}
#[rstest]
fn oauth2_proxy_wins_over_jwt(settings: Settings) {
let settings = Settings {
oauth2_proxy: true,
..settings
};
assert_eq!(
plan(&request("/chat/completions", &Token::new(JWT)), &settings),
Ok(Plan::OAuth2Proxy)
);
}
#[rstest]
#[case::key_on_an_open_route(KEY, Ok(Plan::PassThroughOpen))]
#[case::jwt_is_planned_before_it(JWT, Ok(Plan::Jwt))]
fn auth_off_pass_through_route(
settings: Settings,
#[case] token: &str,
#[case] expected: Result<Plan, PremiumRequired>,
) {
let token = Token::new(token);
let open = Request {
pass_through_open: true,
..request("/forwarder", &token)
};
assert_eq!(plan(&open, &settings), expected);
}
#[rstest]
fn key_from_custom_auth_skips_the_open_pass_through(settings: Settings) {
let key = Token::new(KEY);
let handed_back = Request {
pass_through_open: true,
from_custom_auth: true,
..request("/forwarder", &key)
};
assert_eq!(plan(&handed_back, &settings), Ok(Plan::Key));
}
#[rstest]
fn public_route_wins_over_an_open_pass_through(settings: Settings) {
let key = Token::new(KEY);
let open = Request {
pass_through_open: true,
..request("/", &key)
};
assert_eq!(plan(&open, &settings), Ok(Plan::Public));
}
}

View file

@ -0,0 +1,58 @@
use litellm_config::{GeneralSettings, RouteList};
use crate::routes::{RouteGroup, RouteGroups, matches_wildcard, table::METRICS};
/// Routes a request reaches without any credential.
#[derive(Clone, Debug, Default)]
pub struct PublicRoutes {
route_groups: RouteGroups,
/// [`general_settings.public_routes`](GeneralSettings::public_routes), exact or ending in `*`.
/// Empty without an enterprise license (`HostFacts::premium`).
configured: Box<[String]>,
/// `litellm.require_auth_for_metrics_endpoint` (`HostFacts::metrics_require_auth`)
/// keeps `/metrics` behind auth even when `public_routes` lists it.
metrics_require_auth: bool,
}
impl PublicRoutes {
pub fn new(
general: &GeneralSettings,
premium: bool,
metrics_require_auth: bool,
route_groups: &RouteGroups,
) -> Self {
Self {
route_groups: route_groups.clone(),
configured: if premium {
general
.public_routes
.as_ref()
.map(RouteList::items)
.unwrap_or_default()
.into()
} else {
Box::default()
},
metrics_require_auth,
}
}
/// `route in LiteLLMRoutes.public_routes.value or route_in_additonal_public_routes(route)`
pub(super) fn contains(&self, route: &str) -> bool {
if self.metrics_require_auth && without_trailing_slash(route) == METRICS {
return false;
}
self.route_groups.lists(route, RouteGroup::Public)
|| self
.configured
.iter()
.any(|pattern| matches_wildcard(route, pattern))
}
}
fn without_trailing_slash(route: &str) -> &str {
match route {
"/" => route,
_ => route.trim_end_matches('/'),
}
}

View file

@ -0,0 +1,63 @@
use crate::PremiumRequired;
/// `ProxyErrorTypes` values a denial carries.
#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::IntoStaticStr)]
pub enum ErrorType {
#[strum(serialize = "auth_error")]
Auth,
}
/// A denial as the caller sees it: the exception the Python proxy raised for it, with its status
/// and message. Each host builds its error from this alone.
#[derive(Clone, Debug, PartialEq)]
pub enum PublicDenial {
/// `ProxyException(message, type, param, code)`
Proxy {
status: u16,
message: String,
error_type: ErrorType,
param: Option<String>,
},
}
fn proxy(
status: u16,
denial: &impl ToString,
error_type: ErrorType,
param: Option<&str>,
) -> PublicDenial {
PublicDenial::Proxy {
status,
message: denial.to_string(),
error_type,
param: param.map(str::to_owned),
}
}
impl PremiumRequired {
pub fn public(&self) -> PublicDenial {
proxy(403, self, ErrorType::Auth, Some("premium_user"))
}
}
#[cfg(test)]
mod tests {
use rstest::rstest;
use super::*;
#[rstest]
#[case::jwt(PremiumRequired::Jwt)]
#[case::oauth2(PremiumRequired::OAuth2)]
fn premium_required_is_a_403_naming_the_license(#[case] premium: PremiumRequired) {
assert_eq!(
premium.public(),
PublicDenial::Proxy {
status: 403,
message: premium.to_string(),
error_type: ErrorType::Auth,
param: Some("premium_user".to_owned()),
}
);
}
}

View file

@ -14,6 +14,12 @@ pub enum RouteGroup {
AgentInference,
}
pub(crate) const METRICS: &str = "/metrics";
pub(crate) fn is_lens_route(route: &str) -> bool {
route == "/lens" || route.starts_with("/lens/")
}
pub(crate) const MANAGED_DISCOVERY_ROUTES: &[&str] = &["/agents", "/v1/agents"];
pub(crate) const MANAGED_REALTIME_ROUTES: &[&str] = &[
"/realtime",

View file

@ -1,5 +1,29 @@
use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
use litellm_config::OneOrMany;
use serde_json::{Value, json};
use crate::routes::RouteGroups;
pub fn one(value: &str) -> Option<OneOrMany> {
Some(OneOrMany::One(value.to_owned()))
}
pub fn many(values: &[&str]) -> Option<OneOrMany> {
Some(OneOrMany::Many(
values.iter().map(|value| (*value).to_owned()).collect(),
))
}
/// An RS256-shaped JWT whose signature is not real, for code that reads claims unverified.
pub fn unsigned_jwt(claims: &Value) -> String {
let segment = |value: &Value| URL_SAFE_NO_PAD.encode(serde_json::to_vec(value).unwrap());
format!(
"{}.{}.AAAA",
segment(&json!({"alg": "RS256"})),
segment(claims)
)
}
pub fn route_groups() -> RouteGroups {
RouteGroups::new(route_table()).expect("the stand-in table holds every group the core reads")
}

View file

@ -0,0 +1,33 @@
use litellm_secret_value::SecretValue;
use crate::authn::jwt::is_jwt;
/// The credential a request presents.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Token(SecretValue);
impl Token {
pub fn new(value: impl Into<SecretValue>) -> Self {
Self(value.into())
}
pub fn expose(&self) -> &str {
self.0.expose()
}
pub fn is_jwt(&self) -> bool {
is_jwt(self.expose())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn debug_redacts_plaintext() {
let debug = format!("{:?}", Token::new("credential-value"));
assert!(!debug.contains("credential-value"), "{debug}");
assert!(debug.contains("[REDACTED]"), "{debug}");
}
}

View file

@ -0,0 +1,49 @@
use serde_json::Value;
/// A claim used as an id: strings as they are, integers in decimal, anything else is no id.
pub(crate) fn id_text(value: &Value) -> Option<String> {
match value {
Value::String(text) => Some(text.clone()),
Value::Number(number) if number.is_i64() || number.is_u64() => Some(number.to_string()),
_ => None,
}
}
/// Unicode whitespace plus the ASCII information separators U+001C to U+001F.
pub(crate) fn is_separator(c: char) -> bool {
c.is_whitespace() || ('\u{1c}'..='\u{1f}').contains(&c)
}
pub(crate) fn trim(text: &str) -> &str {
text.trim_matches(is_separator)
}
#[cfg(test)]
mod tests {
use rstest::rstest;
use serde_json::{Value, json};
use super::{id_text, trim};
#[rstest]
#[case::string(json!("u-1"), Some("u-1"))]
#[case::int(json!(12345), Some("12345"))]
#[case::negative(json!(-7), Some("-7"))]
#[case::large(json!(u64::MAX), Some("18446744073709551615"))]
#[case::float(json!(1.5), None)]
#[case::bool(json!(true), None)]
#[case::object(json!({"a": 1}), None)]
#[case::array(json!(["a"]), None)]
#[case::null(json!(null), None)]
fn ids(#[case] value: Value, #[case] expected: Option<&str>) {
assert_eq!(id_text(&value).as_deref(), expected);
}
#[rstest]
#[case::ascii(" a b \n", "a b")]
#[case::information_separators("\u{1c}a\u{1f}", "a")]
#[case::unicode("\u{a0}a\u{3000}", "a")]
fn trims_separators(#[case] text: &str, #[case] expected: &str) {
assert_eq!(trim(text), expected);
}
}

View file

@ -0,0 +1,135 @@
use litellm_gateway_auth_core::{
PublicDenial, Token,
plan::{self, Plan},
};
use pyo3::prelude::*;
use super::settings::AuthSettings;
fn presented_token(token: &Bound<'_, PyAny>) -> PyResult<Option<Token>> {
Ok(token.extract::<Option<String>>()?.map(Token::new))
}
/// The request facts Python passes in, read from a frozen dataclass (`core.AuthRequest`).
#[derive(FromPyObject)]
pub(crate) struct RequestFacts {
#[pyo3(attribute)]
route: String,
#[pyo3(attribute, from_py_with = presented_token)]
token: Option<Token>,
#[pyo3(attribute)]
is_llm_api_route: bool,
#[pyo3(attribute)]
is_info_route: bool,
#[pyo3(attribute)]
pass_through_open: bool,
#[pyo3(attribute)]
from_custom_auth: bool,
}
impl RequestFacts {
fn request(&self) -> plan::Request<'_> {
plan::Request {
route: &self.route,
token: self.token.as_ref(),
is_llm_api_route: self.is_llm_api_route,
is_info_route: self.is_info_route,
pass_through_open: self.pass_through_open,
from_custom_auth: self.from_custom_auth,
}
}
}
/// Which path authenticates the request, for the host's dispatch.
#[pyclass(
frozen,
eq,
skip_from_py_object,
name = "RustPlan",
module = "litellm.rust_bridge._native"
)]
#[derive(Clone, Copy, PartialEq, Eq)]
pub(crate) enum PlanView {
Public,
OAuth2Introspection,
OAuth2Proxy,
JwtWithOperatorCode,
Jwt,
PassThroughOpen,
Key,
}
impl From<Plan> for PlanView {
fn from(plan: Plan) -> Self {
match plan {
Plan::Public => Self::Public,
Plan::OAuth2Introspection => Self::OAuth2Introspection,
Plan::OAuth2Proxy => Self::OAuth2Proxy,
Plan::JwtWithOperatorCode => Self::JwtWithOperatorCode,
Plan::Jwt => Self::Jwt,
Plan::PassThroughOpen => Self::PassThroughOpen,
Plan::Key => Self::Key,
}
}
}
/// The path to run, or the license error for a path the proxy may not run.
#[derive(IntoPyObject)]
enum Planned {
Plan(PlanView),
Denial(DenialView),
}
/// A denial as the exception the proxy raises for it; `denial.denial_error` only constructs it.
#[pyclass(frozen, name = "RustDenial", module = "litellm.rust_bridge._native")]
pub(crate) enum DenialView {
Proxy {
status: u16,
message: String,
error_type: String,
param: Option<String>,
},
}
impl From<PublicDenial> for DenialView {
fn from(denial: PublicDenial) -> Self {
match denial {
PublicDenial::Proxy {
status,
message,
error_type,
param,
} => Self::Proxy {
status,
message,
error_type: <&'static str>::from(error_type).to_owned(),
param,
},
}
}
}
/// The auth core's calls, for the Python host.
#[pyclass(frozen, name = "RustAuth", module = "litellm.rust_bridge._native")]
pub(crate) struct AuthCall;
#[pymethods]
impl AuthCall {
#[staticmethod]
fn plan(request: RequestFacts, settings: &AuthSettings) -> Planned {
match plan::plan(&request.request(), &settings.0) {
Ok(plan) => Planned::Plan(plan.into()),
Err(premium) => Planned::Denial(premium.public().into()),
}
}
#[staticmethod]
fn is_public_route(route: &str, settings: &AuthSettings) -> bool {
plan::is_public_route(route, &settings.0)
}
#[staticmethod]
fn oauth2_introspection_applies(request: RequestFacts, settings: &AuthSettings) -> bool {
plan::oauth2_introspection_applies(&request.request(), &settings.0)
}
}

View file

@ -1,9 +1,13 @@
mod call;
mod convert;
mod passthrough;
mod route_groups;
mod settings;
pub(crate) use call::{AuthCall, DenialView, PlanView};
pub(crate) use passthrough::{
auth_allowed_routes_grant, auth_first_denied_route, auth_jwt_team_routes_grant,
auth_managed_agent_route_allowed, auth_managed_route, auth_route_matches_denied,
auth_route_matches_prefix, auth_route_matches_wildcard,
};
pub(crate) use settings::AuthSettings;

View file

@ -0,0 +1,101 @@
use litellm_config::{GeneralSettings, JwtAuthSettings};
use litellm_gateway_auth_core::plan::Settings;
use litellm_host_python::from_py;
use pyo3::{
prelude::*,
types::{PyDict, PySet, PyString},
};
/// `general_settings.get(key)`. The proxy's settings are a dict or its `SettingsStore` mapping.
fn get<'py>(general: &Bound<'py, PyAny>, key: &str) -> PyResult<Option<Bound<'py, PyAny>>> {
let value = general.call_method1("get", (key,))?;
Ok((!value.is_none()).then_some(value))
}
/// The validated `LiteLLM_JWTAuth`. `custom_validate` is a callable only Python can run, so the
/// core only learns that one is set.
pub(crate) fn jwt_auth(litellm_jwtauth: &Bound<'_, PyAny>) -> PyResult<JwtAuthSettings> {
let py = litellm_jwtauth.py();
let kwargs = PyDict::new(py);
kwargs.set_item("mode", "json")?;
kwargs.set_item(
"exclude",
PySet::new(py, [PyString::new(py, "custom_validate")])?,
)?;
let dumped = litellm_jwtauth.call_method("model_dump", (), Some(&kwargs))?;
let custom_validate = litellm_jwtauth.getattr("custom_validate")?;
Ok(JwtAuthSettings {
custom_validate: (!custom_validate.is_none())
.then(|| custom_validate.repr().map(|r| r.to_string()))
.transpose()?,
..from_py(&dumped)?
})
}
/// The `general_settings` keys the auth core reads.
const AUTH_KEYS: [&str; 4] = [
"enable_jwt_auth",
"enable_oauth2_auth",
"enable_oauth2_proxy_auth",
"public_routes",
];
/// Reads the live `general_settings` through `GeneralSettings`'s own serde rules, the ones the
/// gateway's YAML load uses, so both hosts hand the core the same settings. A value that does not
/// convert at all, such as a Python object, is left out, so it reads as the field's default.
fn general_settings(
general: &Bound<'_, PyAny>,
litellm_jwtauth: Option<&Bound<'_, PyAny>>,
) -> PyResult<GeneralSettings> {
let py = general.py();
let selected = PyDict::new(py);
for key in AUTH_KEYS {
let Some(value) = get(general, key)? else {
continue;
};
let alone = PyDict::new(py);
alone.set_item(key, &value)?;
if from_py::<GeneralSettings>(alone.as_any()).is_ok() {
selected.set_item(key, value)?;
}
}
Ok(GeneralSettings {
litellm_jwtauth: litellm_jwtauth.map(jwt_auth).transpose()?,
..from_py(selected.as_any())?
})
}
#[pyclass(
frozen,
name = "RustAuthSettings",
module = "litellm.rust_bridge._native"
)]
pub(crate) struct AuthSettings(pub(crate) Settings);
/// The host facts Python passes in, read from a frozen dataclass (`core.HostFacts`).
#[derive(FromPyObject)]
struct Facts {
#[pyo3(attribute)]
premium: bool,
#[pyo3(attribute)]
metrics_require_auth: bool,
}
#[pymethods]
impl AuthSettings {
#[new]
fn new(
general_settings: &Bound<'_, PyAny>,
litellm_jwtauth: Option<&Bound<'_, PyAny>>,
facts: Facts,
) -> PyResult<Self> {
let general = self::general_settings(general_settings, litellm_jwtauth)?;
let route_groups = super::route_groups::route_groups(general_settings.py())?;
Ok(Self(Settings::new(
&general,
facts.premium,
facts.metrics_require_auth,
&route_groups,
)))
}
}

View file

@ -28,6 +28,8 @@ mod _native {
use litellm_host_python::{ForkedAfterNativeRuntimeStarted, ProcessReservedForForking};
use pyo3::{prelude::*, types::PyModule};
#[pymodule_export]
use crate::auth::{AuthCall, AuthSettings, DenialView, PlanView};
#[pymodule_export]
use crate::auth::{
auth_allowed_routes_grant, auth_first_denied_route, auth_jwt_team_routes_grant,
@ -230,6 +232,10 @@ mod tests {
"auth_route_matches_denied",
"auth_route_matches_prefix",
"auth_route_matches_wildcard",
"RustAuth",
"RustAuthSettings",
"RustDenial",
"RustPlan",
];
#[cfg(feature = "huggingface")]
expected.push("HuggingFaceEncoding");

View file

@ -67,4 +67,8 @@
- Check cross-language behavior against a freshly installed extension, covering unstarted-call release, setup ordering, exception identity, sync and async streams, cancellation and GC
- Keep `_native.pyi` accurate about which APIs return a Future and which return a coroutine
- `_native.pyi` is hand-written, so declare what PyO3 builds at runtime, not what reads nicer ([classes](https://pyo3.rs/v0.29.2/class.html), [typing](https://pyo3.rs/v0.29.2/python-typing-hints.html))
- A fieldless `#[pyclass]` enum is a plain class, never an `enum.Enum`. Stub each variant as `Variant: ClassVar[Cls]`, and match it with value patterns, which pyright cannot check for exhaustiveness
- An enum with fields exposes each variant as a nested subclass of the enum class, with getters for its fields, `__match_args__`, and a `__new__` that takes the fields in order
- `eq` without `hash` makes instances unhashable, so stub `__hash__: ClassVar[None] # type: ignore[assignment]`, the way typeshed does. `make test-rust-extension` runs mypy stubtest over the stub, and it stops at the first mypy error
- Unit tests of this package live in `tests/unit/rust_bridge/`, end-to-end Rust path tests in `tests/test_litellm_rust/`

View file

@ -1,12 +1,13 @@
from asyncio import Future
from collections.abc import Callable, Mapping, Sequence
from typing import Generic, Literal, Never, NotRequired, Protocol, TypedDict, TypeVar, final
from typing import ClassVar, Generic, Literal, Never, NotRequired, Protocol, TypedDict, TypeVar, final
import httpx
from pydantic import JsonValue
from typing_extensions import disjoint_base
from litellm.integrations.custom_logger_v2.rust import RustHandle
from litellm.proxy._types import LiteLLM_JWTAuth
from litellm.redis.store_settings import RedisBreakerSettings, RedisStoreSettings
from litellm.redis.stores.router_session_pins.keys import PinKey
from litellm.rust_bridge.database import NativeDatabaseEndpoint, NativeDatabaseEvents
@ -531,6 +532,72 @@ def auth_route_matches_denied(route: str, denied_route: str) -> bool: ...
def auth_first_denied_route(forwarded_routes: Sequence[str], denied_sources: Sequence[object]) -> str | None: ...
def auth_jwt_team_routes_grant(route: str, team_allowed_routes: object) -> bool: ...
def auth_allowed_routes_grant(route: str, *, key: object, team: object) -> bool: ...
class _AuthRequest(Protocol):
@property
def route(self) -> str: ...
@property
def token(self) -> str | None: ...
@property
def is_llm_api_route(self) -> bool: ...
@property
def is_info_route(self) -> bool: ...
@property
def pass_through_open(self) -> bool: ...
@property
def from_custom_auth(self) -> bool: ...
class _HostFacts(Protocol):
@property
def premium(self) -> bool: ...
@property
def metrics_require_auth(self) -> bool: ...
@final
class RustAuthSettings:
def __new__(
cls, general_settings: Mapping[str, object], litellm_jwtauth: LiteLLM_JWTAuth | None, facts: _HostFacts
) -> RustAuthSettings: ...
@final
class RustPlan:
__hash__: ClassVar[None] # type: ignore[assignment] # pyright: ignore[reportIncompatibleMethodOverride] # PyO3 `eq` without `hash` sets it to None
Public: ClassVar[RustPlan]
OAuth2Introspection: ClassVar[RustPlan]
OAuth2Proxy: ClassVar[RustPlan]
JwtWithOperatorCode: ClassVar[RustPlan]
Jwt: ClassVar[RustPlan]
PassThroughOpen: ClassVar[RustPlan]
Key: ClassVar[RustPlan]
@disjoint_base
class RustDenial:
@final
class Proxy(RustDenial):
__match_args__: tuple[Literal["status"], Literal["message"], Literal["error_type"], Literal["param"]] = (
"status",
"message",
"error_type",
"param",
)
def __new__(cls, status: int, message: str, error_type: str, param: str | None) -> RustDenial.Proxy: ...
@property
def status(self) -> int: ...
@property
def message(self) -> str: ...
@property
def error_type(self) -> str: ...
@property
def param(self) -> str | None: ...
@final
class RustAuth:
@staticmethod
def plan(request: _AuthRequest, settings: RustAuthSettings) -> RustPlan | RustDenial: ...
@staticmethod
def is_public_route(route: str, settings: RustAuthSettings) -> bool: ...
@staticmethod
def oauth2_introspection_applies(request: _AuthRequest, settings: RustAuthSettings) -> bool: ...
@final
class NativeAuthCache:
def __new__(
@ -868,7 +935,11 @@ __all__ = [
"ResponsesWebSocketConnection",
"RouterCall",
"RouterCoreHandle",
"RustAuth",
"RustAuthSettings",
"RustBridgeDeclined",
"RustDenial",
"RustPlan",
"RustUpstreamError",
"SpendRead",
"TokenCounter",

View file

@ -0,0 +1,164 @@
import base64
import json
from collections.abc import Callable
from typing import Final
import pytest
import litellm
from litellm.proxy import proxy_server
from litellm.proxy._types import JWTRoutingOverride, LiteLLM_JWTAuth
from litellm.proxy.auth import core
from litellm.rust_bridge._native import RustAuth, RustAuthSettings, RustDenial, RustPlan
JWT: Final = "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsifQ.eyJzdWIiOiJ1In0.c2ln"
ISSUER: Final = "oauth-issuer.example.com"
def _unsigned_jwt(claims: dict[str, object]) -> str:
def segment(value: dict[str, object]) -> str:
return base64.urlsafe_b64encode(json.dumps(value).encode()).rstrip(b"=").decode()
return f"{segment({'alg': 'RS256'})}.{segment(claims)}.c2ln"
def _accept(claims: dict[str, object]) -> bool:
return True
@pytest.mark.parametrize(
("custom_validate", "expected"),
[(None, RustPlan.Jwt), (_accept, RustPlan.JwtWithOperatorCode)],
ids=["no_operator_code", "custom_validate_set"],
)
def test_a_jwt_is_planned_for_operator_code_only_when_custom_validate_is_set(
custom_validate: Callable[[dict[str, object]], bool] | None, expected: RustPlan
) -> None:
settings: Final = RustAuthSettings(
{"enable_jwt_auth": True},
LiteLLM_JWTAuth().model_copy(update={"custom_validate": custom_validate}),
core.HostFacts(premium=True),
)
assert RustAuth.plan(core.request(JWT, "/chat/completions"), settings) == expected
@pytest.mark.parametrize(
("enable_jwt_auth", "expected"),
[(True, RustPlan.Jwt), ("true", RustPlan.Key), (1, RustPlan.Key), (object(), RustPlan.Key)],
ids=["true", "string_true", "one", "object"],
)
def test_jwt_auth_is_on_only_for_the_boolean_true(enable_jwt_auth: object, expected: RustPlan) -> None:
settings: Final = RustAuthSettings(
{"enable_jwt_auth": enable_jwt_auth}, LiteLLM_JWTAuth(), core.HostFacts(premium=True)
)
assert RustAuth.plan(core.request(JWT, "/chat/completions"), settings) == expected
@pytest.mark.parametrize(
("iss", "expected"),
[(ISSUER, True), ("other-issuer.example.com", False)],
ids=["routed_issuer", "other_issuer"],
)
def test_a_routing_override_sends_its_jwts_to_introspection(iss: str, expected: bool) -> None:
settings: Final = RustAuthSettings(
{"enable_jwt_auth": True},
LiteLLM_JWTAuth(routing_overrides=[JWTRoutingOverride(iss=ISSUER)]),
core.HostFacts(premium=True),
)
request: Final = core.request(_unsigned_jwt({"iss": iss}), "/chat/completions")
assert RustAuth.oauth2_introspection_applies(request, settings) is expected
assert RustAuth.plan(request, settings) == (RustPlan.OAuth2Introspection if expected else RustPlan.Jwt)
@pytest.mark.parametrize(
("public_routes", "route", "expected"),
[
(["/custom/route", 5, "/after/*"], "/after/x", RustPlan.Key),
(["/custom/route", None], "/custom/route", RustPlan.Key),
({"/custom/route"}, "/custom/route", RustPlan.Public),
(["/custom/route", 5], "/chat/completions", RustPlan.Key),
(["/custom/route", 5], "/health/liveliness", RustPlan.Public),
("/custom/*", "/custom/route", RustPlan.Key),
("/custom/*", "/health/liveliness", RustPlan.Public),
(5, "/custom/route", RustPlan.Key),
],
ids=[
"non_string_entry_voids_the_list",
"null_entry_voids_the_list",
"set_of_routes",
"non_string_entry_grants_nothing",
"built_in_route_beside_a_non_string_entry",
"bare_string_is_not_a_route_list",
"built_in_route_beside_a_bare_string",
"number_is_not_a_route_list",
],
)
def test_a_malformed_public_routes_setting_never_fails_the_request(
public_routes: object, route: str, expected: RustPlan
) -> None:
settings: Final = RustAuthSettings({"public_routes": public_routes}, None, core.HostFacts(premium=True))
assert RustAuth.plan(core.request(None, route), settings) == expected
def _planned(route: str, token: str | None) -> RustPlan | RustDenial:
return RustAuth.plan(core.request(token, route), core.proxy_settings())
def _write_general_settings_in_place(monkeypatch: pytest.MonkeyPatch) -> None:
settings: Final = proxy_server.current_general_settings()
assert isinstance(settings, dict)
monkeypatch.setitem(settings, "enable_jwt_auth", True)
def _rebind_general_settings(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(proxy_server, "general_settings", {"enable_jwt_auth": True})
def _switch_to_a_premium_license(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(proxy_server, "premium_user", True)
def _make_metrics_public(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(litellm, "require_auth_for_metrics_endpoint", False)
@pytest.mark.parametrize(
("premium", "general_settings", "route", "token", "change", "expected"),
[
(True, {}, "/chat/completions", JWT, _write_general_settings_in_place, RustPlan.Jwt),
(True, {}, "/chat/completions", JWT, _rebind_general_settings, RustPlan.Jwt),
(
False,
{"public_routes": ["/custom/route"]},
"/custom/route",
None,
_switch_to_a_premium_license,
RustPlan.Public,
),
(True, {"public_routes": ["/metrics"]}, "/metrics", None, _make_metrics_public, RustPlan.Public),
],
ids=["general_settings_written_in_place", "general_settings_rebound", "license_switched", "metrics_made_public"],
)
def test_a_config_change_while_serving_decides_the_next_request(
monkeypatch: pytest.MonkeyPatch,
premium: bool,
general_settings: dict[str, object],
route: str,
token: str | None,
change: Callable[[pytest.MonkeyPatch], None],
expected: RustPlan,
) -> None:
monkeypatch.setattr(proxy_server, "general_settings", dict(general_settings))
monkeypatch.setattr(proxy_server, "premium_user", premium)
monkeypatch.setattr(proxy_server.jwt_handler, "litellm_jwtauth", LiteLLM_JWTAuth(), raising=False)
monkeypatch.setattr(litellm, "require_auth_for_metrics_endpoint", True)
before: Final = _planned(route, token)
change(monkeypatch)
assert before == RustPlan.Key
assert _planned(route, token) == expected

View file

@ -0,0 +1,46 @@
from typing import Final
import pytest
from litellm.proxy._types import LiteLLM_JWTAuth, ProxyErrorTypes, ProxyException
from litellm.proxy.auth import core
from litellm.proxy.auth import denial as auth_denial
from litellm.rust_bridge._native import RustAuth, RustAuthSettings, RustDenial
JWT: Final = "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsifQ.eyJzdWIiOiJ1In0.c2ln"
def test_proxy_denial_keeps_its_status_type_and_param() -> None:
error: Final = auth_denial.denial_error(
RustDenial.Proxy(status=401, message="expired", error_type="expired_key", param="sk-...abcd")
)
assert isinstance(error, ProxyException)
assert (error.message, error.type, error.param, error.code) == (
"expired",
ProxyErrorTypes.expired_key,
"sk-...abcd",
"401",
)
@pytest.mark.parametrize(
("general_settings", "token", "feature"),
[
({"enable_jwt_auth": True}, JWT, "JWT Auth is an enterprise only feature."),
({"enable_oauth2_auth": True}, "sk-opaque", "Oauth2 token validation is only available for premium users."),
],
ids=["jwt", "oauth2"],
)
def test_a_licensed_path_without_a_license_is_a_403_naming_premium_user(
general_settings: dict[str, object], token: str, feature: str
) -> None:
settings: Final = RustAuthSettings(general_settings, LiteLLM_JWTAuth(), core.HostFacts(premium=False))
planned: Final = RustAuth.plan(core.request(token, "/chat/completions"), settings)
assert isinstance(planned, RustDenial)
error: Final = auth_denial.denial_error(planned)
assert isinstance(error, ProxyException)
assert error.message.startswith(feature)
assert (error.type, error.param, error.code) == (ProxyErrorTypes.auth_error, "premium_user", "403")

View file

@ -85,10 +85,7 @@ from litellm.proxy.auth.user_api_key_auth import (
_ensure_parent_otel_span_on_request_state,
_load_team_member_default_model_budget,
_PendingAutoRegister,
_matches_routing_override,
_reserve_budget_after_common_checks,
_route_requires_auth_despite_public,
_routing_selector_matches_claim,
_authorize_authenticated_request,
run_centralized_common_checks,
_run_post_custom_auth_checks,
@ -204,17 +201,6 @@ def test_get_api_key():
) == (api_key, passed_in_key)
def test_route_requires_auth_despite_public_for_metrics(monkeypatch):
monkeypatch.setattr(litellm, "require_auth_for_metrics_endpoint", True)
assert _route_requires_auth_despite_public("/metrics", {}) is True
assert _route_requires_auth_despite_public("/metrics/", {}) is True
monkeypatch.setattr(litellm, "require_auth_for_metrics_endpoint", False)
assert _route_requires_auth_despite_public("/metrics", {}) is False
def test_public_ai_hub_routes_remain_public():
for route in (
"/public/model_hub",
@ -224,7 +210,6 @@ def test_public_ai_hub_routes_remain_public():
"/public/skill_hub",
):
assert route in LiteLLMRoutes.public_routes.value
assert _route_requires_auth_despite_public(route, {}) is False
@pytest.mark.asyncio
@ -866,146 +851,6 @@ def _assert_get_api_key_with_custom_litellm_key_header(custom_litellm_key_header
) == (api_key, passed_in_key)
@pytest.mark.parametrize(
"selector_value, claim_value, expected, split_space_delimited",
[
(None, "any-value", True, False),
("issuer.example.com", "issuer.example.com", True, False),
("issuer.example.com", "other-issuer.example.com", False, False),
# iss (and other non-scope claims) must not match via space-split injection
(
"trusted.example.com",
"trusted.example.com attacker.example.com",
False,
False,
),
# Wildcard iss must not match space-containing claim strings (fnmatch * spans spaces)
(
"trusted.*",
"trusted.example.com attacker.example.com",
False,
False,
),
("trusted.*", "trusted.example.com", True, False),
(
["issuer-a.example.com", "issuer-b.example.com"],
"issuer-b.example.com",
True,
False,
),
("*MID_LITELLM", "STREAM_MID_LITELLM", True, False),
("*MID_LITELLM", "REDIS_LITELLM", False, False),
("machine-??", "machine-01", True, False),
("machine-??", "machine-001", False, False),
# Wildcard matching is case-sensitive (fnmatch.fnmatchcase)
("*litellm", "BATCH_LITELLM", False, False),
("*LITELLM", "BATCH_LITELLM", True, False),
("App:LiteLLM", "App:LiteLLM openid", True, True),
("App:*", "App:LiteLLM openid", True, True),
(["openid", "App:LiteLLM"], "openid profile", True, True),
(["service-*", "batch-*"], "batch-123", True, False),
(["service-*", "batch-*"], "other-123", False, False),
("App:LiteLLM", ["openid", "App:LiteLLM"], True, False),
("App:LiteLLM", None, False, False),
],
)
def test_routing_selector_matches_claim_parametrized(selector_value, claim_value, expected, split_space_delimited):
assert (
_routing_selector_matches_claim(
selector_value=selector_value,
claim_value=claim_value,
split_space_delimited=split_space_delimited,
)
is expected
)
@pytest.mark.parametrize(
"override, token_claims, expected",
[
# Only iss selector is required and should match.
(
JWTRoutingOverride(iss="oauth-issuer.example.com", path="oauth2"),
{"iss": "oauth-issuer.example.com"},
True,
),
# Scope selector narrows the match.
(
JWTRoutingOverride(
iss="oauth-issuer.example.com",
scope="App:LiteLLM",
path="oauth2",
),
{"iss": "oauth-issuer.example.com", "scope": "App:LiteLLM openid"},
True,
),
# client_id wildcard selector narrows the match.
(
JWTRoutingOverride(
iss="oauth-issuer.example.com",
client_id="*MID_LITELLM",
path="oauth2",
),
{"iss": "oauth-issuer.example.com", "client_id": "BATCH_MID_LITELLM"},
True,
),
(
JWTRoutingOverride(
iss="oauth-issuer.example.com",
client_id="*MID_LITELLM",
path="oauth2",
),
{"iss": "oauth-issuer.example.com", "client_id": "BATCH_PORTAL"},
False,
),
# aud selector still works with list claims.
(
JWTRoutingOverride(
iss="oauth-issuer.example.com",
aud=["api://litellm", "api://fallback"],
path="oauth2",
),
{
"iss": "oauth-issuer.example.com",
"aud": ["api://other", "api://litellm"],
},
True,
),
# All provided selectors are AND-ed.
(
JWTRoutingOverride(
iss="oauth-issuer.example.com",
scope="App:LiteLLM",
client_id="*MID_LITELLM",
path="oauth2",
),
{
"iss": "oauth-issuer.example.com",
"scope": "App:LiteLLM openid",
"client_id": "BATCH_MID_LITELLM",
},
True,
),
(
JWTRoutingOverride(
iss="oauth-issuer.example.com",
scope="App:LiteLLM",
client_id="*MID_LITELLM",
path="oauth2",
),
{
"iss": "oauth-issuer.example.com",
"scope": "App:Other openid",
"client_id": "BATCH_MID_LITELLM",
},
False,
),
],
)
def test_matches_routing_override_parametrized(override, token_claims, expected):
assert _matches_routing_override(token_claims=token_claims, override=override) is expected
def test_get_api_key_with_custom_litellm_key_header_bearer_prefix():
token = "sk-" + "1" * 8
header = f"Bearer {token}"
@ -2129,7 +1974,7 @@ async def test_standard_jwt_auth_propagates_user_email():
):
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -2199,7 +2044,7 @@ async def test_jwt_auth_propagates_agent_id_to_user_api_key_auth(is_proxy_admin:
):
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -2764,7 +2609,7 @@ async def test_auto_register_map_existing_key_first_request_runs_key_checks(
):
call = user_api_key_auth(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -2873,7 +2718,7 @@ async def test_auto_register_first_request_propagates_user_email(active: bool) -
with pytest.raises(ProxyException, match="deactivated via SCIM") as exc:
await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -2885,7 +2730,7 @@ async def test_auto_register_first_request_propagates_user_email(active: bool) -
return
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -3105,7 +2950,7 @@ async def test_jwt_auto_register_forwards_bound_agent_id():
):
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -3423,7 +3268,7 @@ class TestJWTOAuth2Coexistence:
):
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -3504,7 +3349,7 @@ class TestJWTOAuth2Coexistence:
):
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -3580,7 +3425,7 @@ class TestJWTOAuth2Coexistence:
):
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -3652,7 +3497,7 @@ class TestJWTOAuth2Coexistence:
):
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,
@ -12716,7 +12561,7 @@ async def test_auth_flow_enters_virtual_key_mapping_when_only_an_issuer_configur
):
result = await user_api_key_auth_builder(
request=mock_request,
api_key=jwt_token,
api_key=f"Bearer {jwt_token}",
azure_api_key_header="",
anthropic_api_key_header=None,
google_ai_studio_api_key_header=None,