refactor(auth): decide auth=true passthrough access in one module

Every gate that guards an auth: true pass-through route now builds a PassThroughGrants for the caller and asks authorize_pass_through in litellm/proxy/auth/pass_through_access.py. The virtual-key checks, the JWT team selection check and the shared route check share the same grant sources and matchers, and the JWT team_allowed_routes config reaches the shared route check as an argument instead of an import from proxy_server. Decisions and error messages are unchanged
This commit is contained in:
ryan-crabbe-berri 2026-09-21 15:58:35 -07:00
parent 1bb2859dd0
commit dbb9ec7919
10 changed files with 591 additions and 145 deletions

View file

@ -892,6 +892,7 @@ async def common_checks(
request: Request,
skip_budget_checks: bool = False,
project_object: LiteLLM_ProjectTableCachedObj | None = None,
jwt_auth: LiteLLM_JWTAuth | None = None,
) -> bool:
"""
Common checks across jwt + key-based auth.
@ -1214,6 +1215,7 @@ async def common_checks(
request_data=request_body_for_route_check,
valid_token=valid_token,
user_obj=user_object,
jwt_auth=jwt_auth,
)
# 11. [OPTIONAL] Vector store checks - is the object allowed to access the vector store
@ -1257,6 +1259,7 @@ def _is_api_route_allowed(
request_data: dict,
valid_token: UserAPIKeyAuth | None,
user_obj: LiteLLM_UserTable | None = None,
jwt_auth: LiteLLM_JWTAuth | None = None,
) -> bool:
"""
- Route b/w api token check and normal token check
@ -1274,6 +1277,7 @@ def _is_api_route_allowed(
request=request,
request_data=request_data,
valid_token=valid_token,
jwt_auth=jwt_auth,
)
return True

View file

@ -14,7 +14,7 @@ import hashlib
import os
import re
import time
from collections.abc import Awaitable, Callable, Collection, Mapping, Sequence
from collections.abc import Awaitable, Callable, Mapping, Sequence
from dataclasses import dataclass
from typing import Any, Final, Literal, NoReturn, Protocol, TypeVar, cast
@ -25,7 +25,7 @@ from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import serialization
from fastapi import HTTPException, status
from jwt.api_jwk import PyJWK
from typing_extensions import ReadOnly, TypedDict
from typing_extensions import ReadOnly, TypedDict, assert_never
from litellm._logging import verbose_proxy_logger
from litellm.litellm_core_utils.dot_notation_indexing import get_nested_value
@ -57,6 +57,13 @@ from litellm.proxy.auth.model_access_denied import (
ModelAccessDeniedHTTPException,
model_access_denied_client_message,
)
from litellm.proxy.auth.pass_through_access import (
Denied,
Granted,
NotAuthEnforced,
PassThroughGrants,
authorize_pass_through,
)
from litellm.proxy.auth.resolvers.grants import GrantResolver, UserLookup, canonical_user_id
from litellm.proxy.auth.route_checks import RouteChecks
from litellm.proxy.auth.team_grants import team_grants, team_model_aliases
@ -1602,24 +1609,21 @@ class JWTAuthManager:
team_object: LiteLLM_TeamTable | None,
route: str,
request_method: str | None = None,
team_allowed_routes: Collection[str] = (),
jwt_auth: LiteLLM_JWTAuth | None = None,
) -> bool:
normalized_request_method: Final = request_method.upper() if isinstance(request_method, str) else None
if not RouteChecks.is_auth_enforced_pass_through_route(
access: Final = authorize_pass_through(
route=route,
method=normalized_request_method,
):
return True
if RouteChecks.jwt_team_routes_grant_pass_through(route=route, team_allowed_routes=team_allowed_routes):
return True
# JWT team selection is team-scoped; key metadata is not available here,
# so beyond the JWT config grant above, only the selected team's metadata grants access.
return RouteChecks.check_passthrough_route_access(
route=route,
user_api_key_dict=UserAPIKeyAuth(team_metadata=(team_object.metadata or {}) if team_object else {}),
method=request_method.upper() if isinstance(request_method, str) else None,
grants=PassThroughGrants.for_jwt_team(team=team_object, jwt_auth=jwt_auth),
is_auth_enforced=RouteChecks.is_auth_enforced_pass_through_route,
)
match access:
case NotAuthEnforced() | Granted():
return True
case Denied():
return False
case _:
assert_never(access)
@staticmethod
def _raise_team_passthrough_route_denial(route: str) -> None:
@ -1693,7 +1697,7 @@ class JWTAuthManager:
team_object=team_object,
route=route,
request_method=request_method,
team_allowed_routes=jwt_handler.litellm_jwtauth.team_allowed_routes,
jwt_auth=jwt_handler.litellm_jwtauth,
):
is_allowed = False
denied_auth_enforced_pass_through_route = True
@ -2589,7 +2593,7 @@ class JWTAuthManager:
team_object=team_object,
route=route,
request_method=request_method,
team_allowed_routes=handler.litellm_jwtauth.team_allowed_routes,
jwt_auth=handler.litellm_jwtauth,
):
JWTAuthManager._raise_team_passthrough_route_denial(route=route)
@ -2659,7 +2663,7 @@ class JWTAuthManager:
team_object=team_object,
route=route,
request_method=request_method,
team_allowed_routes=handler.litellm_jwtauth.team_allowed_routes,
jwt_auth=handler.litellm_jwtauth,
):
JWTAuthManager._raise_team_passthrough_route_denial(route=route)
elif team_id is None:

View file

@ -0,0 +1,112 @@
"""Decides whether a caller may reach an ``auth: true`` pass-through route.
Build a ``PassThroughGrants`` for the caller and ask ``authorize_pass_through``. Every gate asks here, so a new grant
source is added in one place.
"""
from collections.abc import Mapping
from dataclasses import dataclass
from typing import Final, Protocol, TypeAlias
from litellm.proxy._types import LiteLLM_JWTAuth, LiteLLM_TeamTable, UserAPIKeyAuth
_ALLOWLIST_KEY: Final = "allowed_passthrough_routes"
class AuthEnforcedLookup(Protocol):
def __call__(self, *, route: str, method: str | None) -> bool: ...
def covered_by_prefix(route: str, prefix: str) -> bool:
"""Exact match, or ``route`` sits under ``prefix``: ``/a`` covers ``/a/b`` and not ``/ab``."""
return route == prefix or route.startswith(prefix + "/")
def covered_by_pattern(route: str, pattern: str) -> bool:
"""Exact match, or a prefix match when ``pattern`` ends in ``*``: ``/a/*`` covers ``/a/b`` and not ``/a``."""
if pattern.endswith("*"):
return route.startswith(pattern[:-1])
return route == pattern
def _metadata_allowlist(
metadata: Mapping[str, object] | None,
team_metadata: Mapping[str, object] | None = None,
) -> tuple[str, ...]:
"""``allowed_passthrough_routes`` from metadata. A non-empty key allowlist shadows the team's."""
raw: Final = (metadata and metadata.get(_ALLOWLIST_KEY)) or (team_metadata and team_metadata.get(_ALLOWLIST_KEY))
if not isinstance(raw, (list, tuple)):
return ()
return tuple(entry for entry in raw if isinstance(entry, str))
def _jwt_team_routes(jwt_auth: LiteLLM_JWTAuth | None) -> tuple[str, ...]:
"""``team_allowed_routes`` entries that name a path. Blanket entries (``*``, ``/*``) never grant."""
if jwt_auth is None:
return ()
return tuple(entry for entry in jwt_auth.team_allowed_routes if entry.rstrip("*").strip("/"))
def _is_jwt_team_caller(token: UserAPIKeyAuth) -> bool:
"""
A keyless JWT token with a team. ``team_allowed_routes`` is a team grant, and JWT-mapped virtual keys carry
``jwt_claims`` too but stay scoped to their key.
"""
return token.jwt_claims is not None and token.token is None and token.team_id is not None
@dataclass(frozen=True, slots=True)
class PassThroughGrants:
"""``prefix_routes`` cover a path and everything under it; ``pattern_routes`` are exact or end in ``*``."""
prefix_routes: tuple[str, ...] = ()
pattern_routes: tuple[str, ...] = ()
@staticmethod
def for_token(token: UserAPIKeyAuth, jwt_auth: LiteLLM_JWTAuth | None = None) -> "PassThroughGrants":
return PassThroughGrants(
prefix_routes=_metadata_allowlist(token.metadata, token.team_metadata),
pattern_routes=_jwt_team_routes(jwt_auth) if _is_jwt_team_caller(token) else (),
)
@staticmethod
def for_jwt_team(team: LiteLLM_TeamTable | None, jwt_auth: LiteLLM_JWTAuth | None) -> "PassThroughGrants":
return PassThroughGrants(
prefix_routes=_metadata_allowlist(team.metadata if team is not None else None),
pattern_routes=_jwt_team_routes(jwt_auth),
)
def covers(self, route: str) -> bool:
return any(covered_by_prefix(route=route, prefix=grant) for grant in self.prefix_routes) or any(
covered_by_pattern(route=route, pattern=grant) for grant in self.pattern_routes
)
@dataclass(frozen=True, slots=True)
class NotAuthEnforced:
pass
@dataclass(frozen=True, slots=True)
class Granted:
pass
@dataclass(frozen=True, slots=True)
class Denied:
pass
PassThroughAccess: TypeAlias = NotAuthEnforced | Granted | Denied
def authorize_pass_through(
*,
route: str,
method: str | None,
grants: PassThroughGrants,
is_auth_enforced: AuthEnforcedLookup,
) -> PassThroughAccess:
if not is_auth_enforced(route=route, method=method):
return NotAuthEnforced()
return Granted() if grants.covers(route) else Denied()

View file

@ -3,11 +3,13 @@ from collections.abc import Collection
from typing import Final
from fastapi import HTTPException, Request, status
from typing_extensions import assert_never
from litellm._logging import verbose_proxy_logger
from litellm.proxy._types import (
CommonProxyErrors,
KeyManagementRoutes,
LiteLLM_JWTAuth,
LiteLLM_UserTable,
LiteLLMRoutes,
LitellmUserRoles,
@ -15,6 +17,16 @@ from litellm.proxy._types import (
)
from .auth_checks_organization import _user_is_org_admin
from .pass_through_access import (
Denied,
Granted,
NotAuthEnforced,
PassThroughAccess,
PassThroughGrants,
authorize_pass_through,
covered_by_pattern,
covered_by_prefix,
)
# Management write routes denied to PROXY_ADMIN_VIEW_ONLY. Adding a new write
# endpoint to a management router REQUIRES adding it here too — the surrounding
@ -123,18 +135,15 @@ class RouteChecks:
route=route,
allowed_routes=LiteLLMRoutes._member_map_[allowed_route].value,
):
if (
allowed_route in _AUTH_ENFORCED_PASS_THROUGH_ROUTE_GROUPS
and RouteChecks.is_auth_enforced_pass_through_route(
route=route,
method=RouteChecks._get_request_method(request=request),
)
):
if RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=valid_token):
return True
denied_auth_enforced_pass_through_route = True
else:
if allowed_route not in _AUTH_ENFORCED_PASS_THROUGH_ROUTE_GROUPS:
return True
match RouteChecks._pass_through_access(route=route, request=request, valid_token=valid_token):
case NotAuthEnforced() | Granted():
return True
case Denied():
denied_auth_enforced_pass_through_route = True
case unreachable:
assert_never(unreachable)
################################################
# For llm_api_routes, also check registered pass-through endpoints
@ -148,17 +157,15 @@ class RouteChecks:
)
if InitPassThroughEndpointHelpers.is_registered_pass_through_route(route=route):
if RouteChecks.is_auth_enforced_pass_through_route(
route=route,
method=RouteChecks._get_request_method(request=request),
match RouteChecks._pass_through_access(
route=route, request=request, valid_token=valid_token
):
if RouteChecks.check_passthrough_route_access(
route=route, user_api_key_dict=valid_token
):
case NotAuthEnforced() | Granted():
return True
denied_auth_enforced_pass_through_route = True
else:
return True
case Denied():
denied_auth_enforced_pass_through_route = True
case unreachable:
assert_never(unreachable)
# Method-aware carve-out: allow GET on the two
# read-only MCP-server discovery endpoints
@ -264,6 +271,7 @@ class RouteChecks:
request: Request,
valid_token: UserAPIKeyAuth,
request_data: dict,
jwt_auth: LiteLLM_JWTAuth | None = None,
):
"""
Checks if Non Proxy Admin User is allowed to access the route
@ -274,16 +282,20 @@ class RouteChecks:
route=route,
)
if RouteChecks.is_auth_enforced_pass_through_route(
route=route,
method=RouteChecks._get_request_method(request=request),
):
RouteChecks._require_auth_pass_through_access(
route=route,
valid_token=valid_token,
jwt_team_allowed_routes=RouteChecks._jwt_team_allowed_routes(valid_token=valid_token),
)
elif RouteChecks.is_llm_api_route(route=route):
pass_through_access: Final = RouteChecks._pass_through_access(
route=route, request=request, valid_token=valid_token, jwt_auth=jwt_auth
)
match pass_through_access:
case Denied():
raise RouteChecks._auth_pass_through_denied_exception(route=route)
case Granted():
return
case NotAuthEnforced():
pass
case _:
assert_never(pass_through_access)
if RouteChecks.is_llm_api_route(route=route):
pass
elif RouteChecks.is_info_route(route=route):
# check if user allowed to call an info route
@ -575,13 +587,7 @@ class RouteChecks:
- returns: True
"""
if pattern.endswith("*"):
# Get the prefix (everything before the wildcard)
prefix: Final = pattern[:-1]
return route.startswith(prefix)
else:
# If there's no wildcard, the pattern and route should match exactly
return route == pattern
return covered_by_pattern(route=route, pattern=pattern)
@staticmethod
def _route_matches_allowed_route(route: str, allowed_route: str) -> bool:
@ -601,13 +607,7 @@ class RouteChecks:
Returns:
bool: True if route matches (exact or prefix), False otherwise
"""
# Exact match
if route == allowed_route:
return True
# Prefix match - ensure we add "/" to prevent false matches like /fake-openai-proxy-600
if route.startswith(allowed_route + "/"):
return True
return False
return covered_by_prefix(route=route, prefix=allowed_route)
@staticmethod
def check_route_access(route: str, allowed_routes: Collection[str]) -> bool:
@ -694,72 +694,23 @@ class RouteChecks:
)
@staticmethod
def jwt_team_routes_grant_pass_through(route: str, team_allowed_routes: Collection[str]) -> bool:
"""
Explicit paths and trailing-wildcard prefixes grant auth=true pass-through. Blanket grants never do:
a named route group like ``openai_routes`` is only ever compared as a path, and an entry that names
no path segment (``*``, ``/*``) is skipped.
"""
return any(
RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route)
for allowed_route in team_allowed_routes
if allowed_route.rstrip("*").strip("/")
)
@staticmethod
def _jwt_team_allowed_routes(valid_token: UserAPIKeyAuth) -> Collection[str]:
"""``team_allowed_routes`` for team tokens built by JWT auth; JWT-mapped virtual keys stay key-scoped."""
if valid_token.jwt_claims is None or valid_token.token is not None or valid_token.team_id is None:
return ()
from litellm.proxy.proxy_server import jwt_handler
return jwt_handler.litellm_jwtauth.team_allowed_routes
@staticmethod
def _require_auth_pass_through_access(
def _pass_through_access(
route: str,
request: Request | None,
valid_token: UserAPIKeyAuth,
jwt_team_allowed_routes: Collection[str] = (),
) -> None:
"""
Require an explicit grant for auth=true pass-through: ``allowed_passthrough_routes`` on the
key or team, or an explicit JWT ``team_allowed_routes`` entry.
"""
if RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=valid_token):
return
if RouteChecks.jwt_team_routes_grant_pass_through(route=route, team_allowed_routes=jwt_team_allowed_routes):
return
raise RouteChecks._auth_pass_through_denied_exception(route=route)
jwt_auth: LiteLLM_JWTAuth | None = None,
) -> PassThroughAccess:
return authorize_pass_through(
route=route,
method=RouteChecks._get_request_method(request=request),
grants=PassThroughGrants.for_token(token=valid_token, jwt_auth=jwt_auth),
is_auth_enforced=RouteChecks.is_auth_enforced_pass_through_route,
)
@staticmethod
def check_passthrough_route_access(route: str, user_api_key_dict: UserAPIKeyAuth) -> bool:
"""
Check if route is a passthrough route.
Supports both exact match and prefix match.
"""
metadata: Final = user_api_key_dict.metadata
team_metadata: Final = user_api_key_dict.team_metadata or {}
if metadata is None and team_metadata is None:
return False
if "allowed_passthrough_routes" not in metadata and "allowed_passthrough_routes" not in team_metadata:
return False
if (
metadata.get("allowed_passthrough_routes") is None
and team_metadata.get("allowed_passthrough_routes") is None
):
return False
allowed_passthrough_routes: Final = (
metadata.get("allowed_passthrough_routes") or team_metadata.get("allowed_passthrough_routes") or []
)
# Check if route matches any allowed passthrough route (exact or prefix match)
for allowed_route in allowed_passthrough_routes:
if RouteChecks._route_matches_allowed_route(route=route, allowed_route=allowed_route):
return True
return False
"""Whether the key's or team's ``allowed_passthrough_routes`` metadata covers the route (exact or subpath)."""
return PassThroughGrants.for_token(token=user_api_key_dict).covers(route)
@staticmethod
def _is_assistants_api_request(request: Request) -> bool:

View file

@ -2696,6 +2696,7 @@ async def _run_centralized_common_checks(
"""
from litellm.proxy.proxy_server import (
general_settings,
jwt_handler,
litellm_proxy_admin_name,
llm_router,
master_key,
@ -2971,6 +2972,7 @@ async def _run_centralized_common_checks(
)
bind_admission_counter_keys(user_api_key_auth_obj, end_user_id=end_user_id)
jwt_auth: Final[LiteLLM_JWTAuth | None] = getattr(jwt_handler, "litellm_jwtauth", None)
try:
_ = await common_checks(
request=request,
@ -2986,6 +2988,7 @@ async def _run_centralized_common_checks(
valid_token=user_api_key_auth_obj,
skip_budget_checks=skip_budget_checks,
project_object=project_object,
jwt_auth=jwt_auth,
)
finally:
release_spend_counter_batch()

View file

@ -9269,3 +9269,69 @@ async def test_agent_key_without_an_echoed_caller_keeps_its_own_models():
await _check_caller_models(agent_key, "claude-sonnet", load_team, load_user)
assert asked == []
async def _common_checks_for_jwt_caller_on_model_host_route(route: str, team_allowed_routes: list) -> bool:
from litellm.proxy._types import LiteLLM_JWTAuth
from litellm.proxy.auth.auth_checks import common_checks
mock_registered_routes = {
"test-uuid-1:subpath:/model-host/v1/demographics-extractor:POST": {
"endpoint_id": "test-uuid-1",
"path": "/model-host/v1/demographics-extractor",
"type": "subpath",
"methods": ["POST"],
"auth": True,
},
}
request = MagicMock(spec=Request)
request.method = "POST"
with (
patch(
"litellm.proxy.pass_through_endpoints.pass_through_endpoints._registered_pass_through_routes",
mock_registered_routes,
),
patch("litellm.proxy.utils.get_server_root_path", return_value="/"),
):
return await common_checks(
request_body={},
team_object=LiteLLM_TeamTable(team_id="team-a", metadata={}),
user_object=None,
end_user_object=None,
global_proxy_spend=None,
general_settings={},
route=route,
llm_router=None,
proxy_logging_obj=MagicMock(),
valid_token=UserAPIKeyAuth(team_id="team-a", jwt_claims={"sub": "user-1"}),
request=request,
jwt_auth=LiteLLM_JWTAuth(team_allowed_routes=team_allowed_routes),
)
@pytest.mark.asyncio
async def test_common_checks_allows_auth_enforced_passthrough_granted_by_jwt_team_allowed_routes_path():
assert (
await _common_checks_for_jwt_caller_on_model_host_route(
route="/model-host/v1/demographics-extractor/predict",
team_allowed_routes=["openai_routes", "/model-host/*"],
)
is True
)
@pytest.mark.asyncio
async def test_common_checks_denies_auth_enforced_passthrough_when_jwt_config_has_only_route_groups():
from fastapi import HTTPException
route = "/model-host/v1/demographics-extractor/predict"
with pytest.raises(HTTPException) as exc_info:
await _common_checks_for_jwt_caller_on_model_host_route(route=route, team_allowed_routes=["openai_routes"])
assert exc_info.value.status_code == 403
assert exc_info.value.detail == (
f"Key/team not allowed to access passthrough route {route}. "
"Configure `allowed_passthrough_routes` on the team or key."
)

View file

@ -327,6 +327,59 @@ async def test_find_team_with_model_access_team_allowed_routes_wildcard_grants_a
assert team_obj == team_without_passthrough_allowlist
@pytest.mark.asyncio
@pytest.mark.parametrize(
"team_allowed_routes",
[
pytest.param(["openai_routes", "mapped_pass_through_routes"], id="route_groups_only"),
pytest.param(["openai_routes", "*"], id="blanket_star"),
pytest.param(["/*"], id="blanket_slash_star"),
pytest.param(["/other-host/*"], id="wildcard_for_another_path"),
pytest.param(["/model-host/v1/extractor/predict/*"], id="wildcard_below_the_route"),
],
)
async def test_find_team_with_model_access_denies_auth_passthrough_not_named_by_team_allowed_routes(
team_allowed_routes: list[str],
):
jwt_handler = JWTHandler()
jwt_handler.litellm_jwtauth = LiteLLM_JWTAuth(team_allowed_routes=team_allowed_routes)
with (
patch(
"litellm.proxy.auth.handle_jwt.get_team_object",
new_callable=AsyncMock,
return_value=LiteLLM_TeamTable(team_id="team-a", models=["all-proxy-models"], metadata={}),
),
patch(
"litellm.proxy.auth.handle_jwt.allowed_routes_check",
return_value=True,
),
patch(
"litellm.proxy.pass_through_endpoints.pass_through_endpoints._registered_pass_through_routes",
_AUTH_ENFORCED_MODEL_HOST_ROUTES,
),
patch("litellm.proxy.utils.get_server_root_path", return_value="/"),
):
with pytest.raises(HTTPException) as exc_info:
await JWTAuthManager.find_team_with_model_access(
team_ids={"team-a"},
requested_model=None,
route="/model-host/v1/extractor/predict",
jwt_handler=jwt_handler,
prisma_client=None,
user_api_key_cache=MagicMock(),
parent_otel_span=None,
proxy_logging_obj=MagicMock(),
request_method="POST",
)
assert exc_info.value.status_code == 403
assert exc_info.value.detail == (
"Team not allowed to access passthrough route /model-host/v1/extractor/predict. "
"Configure `allowed_passthrough_routes` on the team."
)
@pytest.mark.asyncio
async def test_auth_builder_header_team_allows_auth_passthrough_for_team_allowed_routes_wildcard():
from litellm.proxy.utils import ProxyLogging
@ -2324,10 +2377,6 @@ async def test_auth_builder_rbac_team_denies_passthrough_without_allowlist():
"litellm.proxy.auth.handle_jwt.RouteChecks.is_auth_enforced_pass_through_route",
return_value=True,
),
patch(
"litellm.proxy.auth.handle_jwt.RouteChecks.check_passthrough_route_access",
return_value=False,
),
):
mock_auth_jwt.return_value = {"scope": ""}

View file

@ -0,0 +1,193 @@
from typing import Final
import pytest
from litellm.proxy._types import (
LiteLLM_JWTAuth,
LiteLLM_TeamTable,
LiteLLMRoutes,
UserAPIKeyAuth,
)
from litellm.proxy.auth.pass_through_access import (
Denied,
Granted,
NotAuthEnforced,
PassThroughGrants,
authorize_pass_through,
)
from litellm.proxy.auth.route_checks import RouteChecks
ENDPOINT: Final = "/model-host/v1/demographics-extractor"
SUBPATH: Final = f"{ENDPOINT}/predict"
JWT_CLAIMS: Final = {"sub": "user-1"}
def _always_enforced(*, route: str, method: str | None) -> bool:
return True
def _never_enforced(*, route: str, method: str | None) -> bool:
return False
def _jwt_auth(*team_allowed_routes: str) -> LiteLLM_JWTAuth:
return LiteLLM_JWTAuth(team_allowed_routes=list(team_allowed_routes))
@pytest.mark.parametrize(
"team_allowed_routes, route, expected",
[
(("/model-host/*",), SUBPATH, Granted()),
(("/model-host/*",), ENDPOINT, Granted()),
(("/model-host/*",), "/model-host", Denied()),
(("/model-host/*",), "/model-hosting/v1", Denied()),
((ENDPOINT,), ENDPOINT, Granted()),
((ENDPOINT,), SUBPATH, Denied()),
(tuple(LiteLLMRoutes.__members__), SUBPATH, Denied()),
(tuple(LiteLLMRoutes.__members__), "/v1/chat/completions", Denied()),
(("openai_routes", "/model-host/*"), SUBPATH, Granted()),
(("*",), SUBPATH, Denied()),
(("/*",), SUBPATH, Denied()),
(("/",), "/", Denied()),
(("/*", "/model-host/*"), SUBPATH, Granted()),
((), SUBPATH, Denied()),
],
)
def test_jwt_team_is_granted_only_by_team_allowed_routes_entries_that_name_a_path(team_allowed_routes, route, expected):
grants = PassThroughGrants.for_jwt_team(
team=LiteLLM_TeamTable(team_id="team-a", metadata={}),
jwt_auth=_jwt_auth(*team_allowed_routes),
)
assert (
authorize_pass_through(route=route, method="POST", grants=grants, is_auth_enforced=_always_enforced) == expected
)
@pytest.mark.parametrize(
"allowlist, route, expected",
[
(["/model-host"], SUBPATH, Granted()),
(["/model-host"], "/model-host", Granted()),
(["/model-host"], "/model-hosting/v1", Denied()),
(["/model-host/*"], SUBPATH, Denied()),
(["/other", ENDPOINT], SUBPATH, Granted()),
([], SUBPATH, Denied()),
(None, SUBPATH, Denied()),
("/model-host", SUBPATH, Denied()),
([7, "/model-host"], SUBPATH, Granted()),
],
)
def test_team_metadata_allowlist_covers_a_path_and_its_subpaths_and_treats_star_literally(allowlist, route, expected):
grants = PassThroughGrants.for_jwt_team(
team=LiteLLM_TeamTable(team_id="team-a", metadata={"allowed_passthrough_routes": allowlist}),
jwt_auth=_jwt_auth("openai_routes"),
)
assert (
authorize_pass_through(route=route, method="POST", grants=grants, is_auth_enforced=_always_enforced) == expected
)
def test_jwt_team_without_a_team_object_or_metadata_has_only_the_config_grants():
without_team_object = PassThroughGrants.for_jwt_team(team=None, jwt_auth=_jwt_auth("/model-host/*"))
without_metadata_or_config = PassThroughGrants.for_jwt_team(
team=LiteLLM_TeamTable(team_id="team-a", metadata=None), jwt_auth=None
)
assert without_team_object.covers(SUBPATH) is True
assert without_team_object.covers("/elsewhere") is False
assert without_metadata_or_config.covers(SUBPATH) is False
@pytest.mark.parametrize(
"key_allowlist, team_allowlist, route, allowed",
[
(["/key-route"], ["/team-route"], "/key-route/v1", True),
(["/key-route"], ["/team-route"], "/team-route/v1", False),
([], ["/team-route"], "/team-route/v1", True),
(None, ["/team-route"], "/team-route/v1", True),
(None, None, "/team-route/v1", False),
],
)
def test_a_non_empty_key_allowlist_shadows_the_team_allowlist(key_allowlist, team_allowlist, route, allowed):
token = UserAPIKeyAuth(
metadata={"allowed_passthrough_routes": key_allowlist},
team_metadata={"allowed_passthrough_routes": team_allowlist},
)
access = authorize_pass_through(
route=route,
method="POST",
grants=PassThroughGrants.for_token(token=token),
is_auth_enforced=_always_enforced,
)
assert access == (Granted() if allowed else Denied())
assert RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=token) is allowed
@pytest.mark.parametrize(
"token, expected",
[
(UserAPIKeyAuth(team_id="team-a", jwt_claims=JWT_CLAIMS), Granted()),
(UserAPIKeyAuth(token="sk-virtual-key", team_id="team-a"), Denied()),
(UserAPIKeyAuth(token="sk-jwt-mapped-key", team_id="team-a", jwt_claims=JWT_CLAIMS), Denied()),
(UserAPIKeyAuth(team_id="team-a"), Denied()),
(UserAPIKeyAuth(jwt_claims=JWT_CLAIMS), Denied()),
],
ids=["jwt-team-caller", "virtual-key", "jwt-mapped-virtual-key", "keyless-non-jwt-caller", "jwt-without-team"],
)
def test_only_a_keyless_jwt_token_with_a_team_receives_the_jwt_config_grants(token, expected):
grants = PassThroughGrants.for_token(token=token, jwt_auth=_jwt_auth("/model-host/*"))
assert (
authorize_pass_through(route=SUBPATH, method="POST", grants=grants, is_auth_enforced=_always_enforced)
== expected
)
def test_a_jwt_token_without_a_jwt_config_has_no_config_grants():
jwt_caller = UserAPIKeyAuth(team_id="team-a", jwt_claims=JWT_CLAIMS)
assert PassThroughGrants.for_token(token=jwt_caller, jwt_auth=None).covers(SUBPATH) is False
def test_jwt_caller_metadata_and_config_grants_are_both_honored():
token = UserAPIKeyAuth(
team_id="team-a",
jwt_claims=JWT_CLAIMS,
team_metadata={"allowed_passthrough_routes": ["/team-route"]},
)
grants = PassThroughGrants.for_token(token=token, jwt_auth=_jwt_auth("/model-host/*"))
assert grants.covers("/team-route/v1") is True
assert grants.covers(SUBPATH) is True
assert grants.covers("/elsewhere") is False
def test_routes_that_are_not_auth_enforced_are_left_to_the_callers_own_rules():
seen = []
def _record(*, route: str, method: str | None) -> bool:
seen.append((route, method))
return False
access = authorize_pass_through(
route=SUBPATH,
method="GET",
grants=PassThroughGrants(),
is_auth_enforced=_record,
)
assert access == NotAuthEnforced()
assert seen == [(SUBPATH, "GET")]
assert (
authorize_pass_through(
route=SUBPATH,
method="GET",
grants=PassThroughGrants(prefix_routes=("/model-host",)),
is_auth_enforced=_never_enforced,
)
== NotAuthEnforced()
)

View file

@ -7,6 +7,7 @@ import pytest
from fastapi import HTTPException, Request
from litellm.proxy._types import (
LiteLLM_JWTAuth,
LiteLLM_OrganizationMembershipTable,
LiteLLM_UserTable,
LiteLLMRoutes,
@ -14,6 +15,7 @@ from litellm.proxy._types import (
UserAPIKeyAuth,
)
from litellm.proxy.auth.auth_checks_organization import _user_is_org_admin
from litellm.proxy.auth.pass_through_access import PassThroughGrants
from litellm.proxy.auth.route_checks import RouteChecks
@ -1264,11 +1266,12 @@ def test_non_proxy_admin_allows_auth_pass_through_with_team_allowlist():
],
)
def test_jwt_team_routes_grant_pass_through_only_for_explicit_paths(route, team_allowed_routes, expected):
assert (
RouteChecks.jwt_team_routes_grant_pass_through(route=route, team_allowed_routes=team_allowed_routes)
is expected
grants: Final = PassThroughGrants.for_jwt_team(
team=None, jwt_auth=LiteLLM_JWTAuth(team_allowed_routes=team_allowed_routes)
)
assert grants.covers(route) is expected
_AUTH_ENFORCED_MODEL_HOST_ROUTES: Final = {
"test-uuid-1:subpath:/model-host/v1/extractor:GET,POST": {
@ -1280,15 +1283,6 @@ _AUTH_ENFORCED_MODEL_HOST_ROUTES: Final = {
}
def _jwt_handler_with_team_allowed_routes(team_allowed_routes: list[str]):
from litellm.proxy._types import LiteLLM_JWTAuth
from litellm.proxy.auth.handle_jwt import JWTHandler
jwt_handler: Final = JWTHandler()
jwt_handler.litellm_jwtauth = LiteLLM_JWTAuth(team_allowed_routes=team_allowed_routes)
return jwt_handler
def _check_model_host_route_as(valid_token: UserAPIKeyAuth, team_allowed_routes: list[str]) -> None:
with (
patch(
@ -1296,10 +1290,6 @@ def _check_model_host_route_as(valid_token: UserAPIKeyAuth, team_allowed_routes:
_AUTH_ENFORCED_MODEL_HOST_ROUTES,
),
patch("litellm.proxy.utils.get_server_root_path", return_value="/"),
patch(
"litellm.proxy.proxy_server.jwt_handler",
_jwt_handler_with_team_allowed_routes(team_allowed_routes),
),
):
RouteChecks.non_proxy_admin_allowed_routes_check(
user_obj=None,
@ -1308,6 +1298,7 @@ def _check_model_host_route_as(valid_token: UserAPIKeyAuth, team_allowed_routes:
request=MagicMock(spec=Request),
valid_token=valid_token,
request_data={},
jwt_auth=LiteLLM_JWTAuth(team_allowed_routes=team_allowed_routes),
)

View file

@ -5232,6 +5232,79 @@ async def test_centralized_common_checks_runs_for_passthrough_endpoint_with_auth
setattr(_proxy_server_mod, k, v)
async def _centralized_denial_for_jwt_caller_on_auth_passthrough(jwt_handler):
import litellm.proxy.proxy_server as _proxy_server_mod
from fastapi import HTTPException, Request
from starlette.datastructures import URL
route = "/model-host/v1/demographics-extractor/predict"
request = Request(scope={"type": "http", "method": "POST"})
request._url = URL(url=route)
mock_registered_routes = {
"test-uuid-1:subpath:/model-host/v1/demographics-extractor:POST": {
"endpoint_id": "test-uuid-1",
"path": "/model-host/v1/demographics-extractor",
"type": "subpath",
"methods": ["POST"],
"auth": True,
},
}
user_api_key_cache = DualCache()
await user_api_key_cache.async_set_cache(
key="team_id:team-a",
value=LiteLLM_TeamTableCachedObj(team_id="team-a"),
)
attrs = {
**_proxy_attrs_for_centralized_checks(user_custom_auth=None),
"user_api_key_cache": user_api_key_cache,
}
with (
patch.multiple(_proxy_server_mod, jwt_handler=jwt_handler, **attrs),
patch(
"litellm.proxy.pass_through_endpoints.pass_through_endpoints._registered_pass_through_routes",
mock_registered_routes,
),
patch("litellm.proxy.utils.get_server_root_path", return_value="/"),
):
try:
await _run_centralized_common_checks(
user_api_key_auth_obj=UserAPIKeyAuth(team_id="team-a", jwt_claims={"sub": "user-1"}),
request=request,
request_data={},
route=route,
)
except HTTPException as denial:
return denial.detail
return None
@pytest.mark.asyncio
async def test_centralized_common_checks_grant_auth_passthrough_from_the_live_jwt_team_allowed_routes():
from litellm.proxy._types import LiteLLM_JWTAuth
from litellm.proxy.auth.handle_jwt import JWTHandler
configured = JWTHandler()
configured.update_environment(
prisma_client=None,
user_api_key_cache=DualCache(),
litellm_jwtauth=LiteLLM_JWTAuth(
team_allowed_routes=["openai_routes", "/model-host/*"]
),
)
assert (
await _centralized_denial_for_jwt_caller_on_auth_passthrough(configured) is None
)
assert await _centralized_denial_for_jwt_caller_on_auth_passthrough(
JWTHandler()
) == (
"Key/team not allowed to access passthrough route /model-host/v1/demographics-extractor/predict. "
"Configure `allowed_passthrough_routes` on the team or key."
)
@pytest.mark.asyncio
async def test_centralized_common_checks_master_key_admin_overrides_db_user_role():
"""Regression: master_key tokens have user_id=litellm_proxy_admin_name