From 1bb2859dd031c11601c47cfb932379d74ec5b534 Mon Sep 17 00:00:00 2001 From: ryan-crabbe-berri Date: Mon, 21 Sep 2026 15:25:59 -0700 Subject: [PATCH 1/4] test(auth): assert jwt passthrough outcomes instead of the intermediate fake token Four JWT team tests mocked RouteChecks.check_passthrough_route_access and asserted the throwaway UserAPIKeyAuth passed into it. That pins how the gate is built and not what it decides, so drop the mock and the call_args assertions and let the real allowlist check run. Every status code and message assertion is unchanged --- .../proxy/auth/test_handle_jwt.py | 28 ------------------- 1 file changed, 28 deletions(-) diff --git a/tests/test_litellm/proxy/auth/test_handle_jwt.py b/tests/test_litellm/proxy/auth/test_handle_jwt.py index 0969a913605..44483fab0d4 100644 --- a/tests/test_litellm/proxy/auth/test_handle_jwt.py +++ b/tests/test_litellm/proxy/auth/test_handle_jwt.py @@ -185,10 +185,6 @@ async def test_find_team_with_model_access_reports_passthrough_allowlist_denial( "litellm.proxy.auth.handle_jwt.RouteChecks.is_auth_enforced_pass_through_route", return_value=True, ) as mock_is_auth_enforced_pass_through_route, - patch( - "litellm.proxy.auth.handle_jwt.RouteChecks.check_passthrough_route_access", - return_value=False, - ) as mock_passthrough_check, ): with pytest.raises(HTTPException) as exc_info: await JWTAuthManager.find_team_with_model_access( @@ -210,10 +206,6 @@ async def test_find_team_with_model_access_reports_passthrough_allowlist_denial( route="/my-pass-through", method="POST" ) - user_api_key_dict = mock_passthrough_check.call_args.kwargs["user_api_key_dict"] - assert user_api_key_dict.metadata == {} - assert user_api_key_dict.team_metadata == {} - @pytest.mark.asyncio async def test_find_team_with_model_access_uses_request_method_for_passthrough_auth(): @@ -2131,10 +2123,6 @@ async def test_auth_builder_header_team_denies_auth_passthrough_without_allowlis "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, - ) as mock_passthrough_check, ): mock_auth_jwt.return_value = { "sub": "user-1", @@ -2160,8 +2148,6 @@ async def test_auth_builder_header_team_denies_auth_passthrough_without_allowlis assert exc_info.value.status_code == 403 assert "allowed_passthrough_routes" in exc_info.value.detail mock_get_objects.assert_not_called() - user_api_key_dict = mock_passthrough_check.call_args.kwargs["user_api_key_dict"] - assert user_api_key_dict.team_metadata == {} @pytest.mark.asyncio @@ -2206,10 +2192,6 @@ async def test_auth_builder_specific_team_denies_auth_passthrough_without_allowl "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, - ) as mock_passthrough_check, ): mock_auth_jwt.return_value = { "sub": "user-1", @@ -2234,8 +2216,6 @@ async def test_auth_builder_specific_team_denies_auth_passthrough_without_allowl assert exc_info.value.status_code == 403 assert "allowed_passthrough_routes" in exc_info.value.detail mock_get_objects.assert_not_called() - user_api_key_dict = mock_passthrough_check.call_args.kwargs["user_api_key_dict"] - assert user_api_key_dict.team_metadata == {} @pytest.mark.asyncio @@ -2287,10 +2267,6 @@ async def test_auth_builder_rbac_team_loads_team_for_passthrough_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=True, - ) as mock_passthrough_check, ): mock_auth_jwt.return_value = {"scope": ""} @@ -2310,10 +2286,6 @@ async def test_auth_builder_rbac_team_loads_team_for_passthrough_allowlist(): assert result["team_id"] == "team-rbac" mock_get_team.assert_awaited_once() assert mock_get_team.await_args.kwargs["team_id"] == "team-rbac" - user_api_key_dict = mock_passthrough_check.call_args.kwargs["user_api_key_dict"] - assert user_api_key_dict.team_metadata == { - "allowed_passthrough_routes": ["/my-pass-through"] - } @pytest.mark.asyncio From dbb9ec79198d02eccaf2697b464a504cf912692c Mon Sep 17 00:00:00 2001 From: ryan-crabbe-berri Date: Mon, 21 Sep 2026 15:58:35 -0700 Subject: [PATCH 2/4] 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 --- litellm/proxy/auth/auth_checks.py | 4 + litellm/proxy/auth/handle_jwt.py | 44 ++-- litellm/proxy/auth/pass_through_access.py | 112 ++++++++++ litellm/proxy/auth/route_checks.py | 161 +++++---------- litellm/proxy/auth/user_api_key_auth.py | 3 + .../proxy/auth/test_auth_checks.py | 66 ++++++ .../proxy/auth/test_handle_jwt.py | 57 +++++- .../proxy/auth/test_pass_through_access.py | 193 ++++++++++++++++++ .../proxy/auth/test_route_checks.py | 23 +-- .../proxy/auth/test_user_api_key_auth.py | 73 +++++++ 10 files changed, 591 insertions(+), 145 deletions(-) create mode 100644 litellm/proxy/auth/pass_through_access.py create mode 100644 tests/test_litellm/proxy/auth/test_pass_through_access.py diff --git a/litellm/proxy/auth/auth_checks.py b/litellm/proxy/auth/auth_checks.py index b3efde7f05f..0172fd2e6d8 100644 --- a/litellm/proxy/auth/auth_checks.py +++ b/litellm/proxy/auth/auth_checks.py @@ -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 diff --git a/litellm/proxy/auth/handle_jwt.py b/litellm/proxy/auth/handle_jwt.py index 010a1b4536e..2dbf2f0fc7f 100644 --- a/litellm/proxy/auth/handle_jwt.py +++ b/litellm/proxy/auth/handle_jwt.py @@ -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: diff --git a/litellm/proxy/auth/pass_through_access.py b/litellm/proxy/auth/pass_through_access.py new file mode 100644 index 00000000000..dcf708dffa2 --- /dev/null +++ b/litellm/proxy/auth/pass_through_access.py @@ -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() diff --git a/litellm/proxy/auth/route_checks.py b/litellm/proxy/auth/route_checks.py index 38189a2d07b..93027b6f594 100644 --- a/litellm/proxy/auth/route_checks.py +++ b/litellm/proxy/auth/route_checks.py @@ -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: diff --git a/litellm/proxy/auth/user_api_key_auth.py b/litellm/proxy/auth/user_api_key_auth.py index 08f64e610bd..5db2edcca9d 100644 --- a/litellm/proxy/auth/user_api_key_auth.py +++ b/litellm/proxy/auth/user_api_key_auth.py @@ -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() diff --git a/tests/test_litellm/proxy/auth/test_auth_checks.py b/tests/test_litellm/proxy/auth/test_auth_checks.py index 0cab6535f3d..32f715dde7b 100644 --- a/tests/test_litellm/proxy/auth/test_auth_checks.py +++ b/tests/test_litellm/proxy/auth/test_auth_checks.py @@ -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." + ) diff --git a/tests/test_litellm/proxy/auth/test_handle_jwt.py b/tests/test_litellm/proxy/auth/test_handle_jwt.py index 44483fab0d4..d79371700fe 100644 --- a/tests/test_litellm/proxy/auth/test_handle_jwt.py +++ b/tests/test_litellm/proxy/auth/test_handle_jwt.py @@ -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": ""} diff --git a/tests/test_litellm/proxy/auth/test_pass_through_access.py b/tests/test_litellm/proxy/auth/test_pass_through_access.py new file mode 100644 index 00000000000..2bd1c90471a --- /dev/null +++ b/tests/test_litellm/proxy/auth/test_pass_through_access.py @@ -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() + ) diff --git a/tests/test_litellm/proxy/auth/test_route_checks.py b/tests/test_litellm/proxy/auth/test_route_checks.py index 8da93ba341b..55ce31a948b 100644 --- a/tests/test_litellm/proxy/auth/test_route_checks.py +++ b/tests/test_litellm/proxy/auth/test_route_checks.py @@ -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), ) diff --git a/tests/test_litellm/proxy/auth/test_user_api_key_auth.py b/tests/test_litellm/proxy/auth/test_user_api_key_auth.py index da36071a5b4..6615a1157c2 100644 --- a/tests/test_litellm/proxy/auth/test_user_api_key_auth.py +++ b/tests/test_litellm/proxy/auth/test_user_api_key_auth.py @@ -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 From cc2235ce733ab69db5a62a9d969bf27a476c6b6c Mon Sep 17 00:00:00 2001 From: ryan-crabbe-berri Date: Mon, 21 Sep 2026 17:01:15 -0700 Subject: [PATCH 3/4] fix(auth): grant team_allowed_routes only to tokens built by JWT auth JWT provenance was inferred from jwt_claims, token and team_id, which a custom auth handler can set. JWT auth now marks its token with the server-only via_jwt_auth field, stripped from validated input like via_virtual_key, and the pass-through grant checks that marker instead. --- litellm/proxy/_types.py | 9 ++++ litellm/proxy/auth/handle_jwt.py | 2 +- litellm/proxy/auth/pass_through_access.py | 6 +-- .../proxy/auth/test_auth_checks.py | 4 +- .../proxy/auth/test_pass_through_access.py | 50 +++++++++++++++---- .../proxy/auth/test_route_checks.py | 26 ++++------ .../proxy/auth/test_user_api_key_auth.py | 30 ++++++++++- tests/test_litellm/proxy/test__types.py | 1 + tests/test_litellm/proxy/test_proxy_types.py | 1 + 9 files changed, 97 insertions(+), 32 deletions(-) diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 3f2d2f57fd4..abc9fa0c843 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -3284,6 +3284,14 @@ class UserAPIKeyAuth(LiteLLM_VerificationTokenView): # the expected response ob "narrow the agent's access." ), ) + via_jwt_auth: bool = Field( + default=False, + exclude=True, + description=( + "Server-only marker set exclusively by JWT auth on the token it builds. Stripped from validated input so " + "custom auth handlers cannot forge it. Gates the `litellm_jwtauth.team_allowed_routes` pass-through grant." + ), + ) budget_reservation: dict[str, Any] | None = Field(default=None, exclude=True) team_budget_snapshot: TeamBudgetSnapshot | None = Field(default=None, exclude=True) user_budget_snapshot: UserBudgetSnapshot | None = Field(default=None, exclude=True) @@ -3317,6 +3325,7 @@ class UserAPIKeyAuth(LiteLLM_VerificationTokenView): # the expected response ob values.pop("mcp_toolset_id", None) values.pop("via_virtual_key", None) values.pop("agent_caller", None) + values.pop("via_jwt_auth", None) if values.get("api_key") is not None: values.update({"token": cls._safe_hash_litellm_api_key(values.get("api_key"))}) if isinstance(values.get("api_key"), str): diff --git a/litellm/proxy/auth/handle_jwt.py b/litellm/proxy/auth/handle_jwt.py index 2dbf2f0fc7f..d06917947a2 100644 --- a/litellm/proxy/auth/handle_jwt.py +++ b/litellm/proxy/auth/handle_jwt.py @@ -2765,4 +2765,4 @@ class JWTAuthManager: team_membership=result.get("team_membership"), user_id=result["user_id"], ), - ) + ).model_copy(update={"via_jwt_auth": True}) diff --git a/litellm/proxy/auth/pass_through_access.py b/litellm/proxy/auth/pass_through_access.py index dcf708dffa2..fbad1555569 100644 --- a/litellm/proxy/auth/pass_through_access.py +++ b/litellm/proxy/auth/pass_through_access.py @@ -49,10 +49,10 @@ def _jwt_team_routes(jwt_auth: LiteLLM_JWTAuth | None) -> tuple[str, ...]: 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. + A team token built by JWT auth. ``via_jwt_auth`` is server-only, so custom auth results and JWT-mapped virtual + keys never pick up the JWT config grants, whatever ``jwt_claims`` they carry. """ - return token.jwt_claims is not None and token.token is None and token.team_id is not None + return token.via_jwt_auth and token.team_id is not None @dataclass(frozen=True, slots=True) diff --git a/tests/test_litellm/proxy/auth/test_auth_checks.py b/tests/test_litellm/proxy/auth/test_auth_checks.py index 32f715dde7b..9cb87131d5e 100644 --- a/tests/test_litellm/proxy/auth/test_auth_checks.py +++ b/tests/test_litellm/proxy/auth/test_auth_checks.py @@ -9304,7 +9304,9 @@ async def _common_checks_for_jwt_caller_on_model_host_route(route: str, team_all route=route, llm_router=None, proxy_logging_obj=MagicMock(), - valid_token=UserAPIKeyAuth(team_id="team-a", jwt_claims={"sub": "user-1"}), + valid_token=UserAPIKeyAuth(team_id="team-a", jwt_claims={"sub": "user-1"}).model_copy( + update={"via_jwt_auth": True} + ), request=request, jwt_auth=LiteLLM_JWTAuth(team_allowed_routes=team_allowed_routes), ) diff --git a/tests/test_litellm/proxy/auth/test_pass_through_access.py b/tests/test_litellm/proxy/auth/test_pass_through_access.py index 2bd1c90471a..a8033aabd22 100644 --- a/tests/test_litellm/proxy/auth/test_pass_through_access.py +++ b/tests/test_litellm/proxy/auth/test_pass_through_access.py @@ -3,11 +3,13 @@ from typing import Final import pytest from litellm.proxy._types import ( + JWTAuthBuilderResult, LiteLLM_JWTAuth, LiteLLM_TeamTable, LiteLLMRoutes, UserAPIKeyAuth, ) +from litellm.proxy.auth.handle_jwt import JWTAuthManager from litellm.proxy.auth.pass_through_access import ( Denied, Granted, @@ -34,6 +36,27 @@ def _jwt_auth(*team_allowed_routes: str) -> LiteLLM_JWTAuth: return LiteLLM_JWTAuth(team_allowed_routes=list(team_allowed_routes)) +def _token_from_jwt_auth(team_id: str | None) -> UserAPIKeyAuth: + return JWTAuthManager.user_api_key_auth_from_result( + JWTAuthBuilderResult( + is_proxy_admin=False, + team_object=None, + user_object=None, + end_user_object=None, + org_object=None, + token="header.payload.signature", + team_id=team_id, + user_id="user-1", + user_email=None, + end_user_id=None, + org_id=None, + team_membership=None, + jwt_claims=JWT_CLAIMS, + agent_id=None, + ) + ) + + @pytest.mark.parametrize( "team_allowed_routes, route, expected", [ @@ -130,15 +153,26 @@ def test_a_non_empty_key_allowlist_shadows_the_team_allowlist(key_allowlist, tea @pytest.mark.parametrize( "token, expected", [ - (UserAPIKeyAuth(team_id="team-a", jwt_claims=JWT_CLAIMS), Granted()), + (_token_from_jwt_auth(team_id="team-a"), Granted()), + ( + UserAPIKeyAuth.model_validate({"team_id": "team-a", "jwt_claims": JWT_CLAIMS, "via_jwt_auth": True}), + Denied(), + ), (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()), + (_token_from_jwt_auth(team_id=None), Denied()), + ], + ids=[ + "jwt-team-caller", + "custom-auth-lookalike", + "virtual-key", + "jwt-mapped-virtual-key", + "keyless-non-jwt-caller", + "jwt-without-team", ], - 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): +def test_only_a_team_token_built_by_jwt_auth_receives_the_jwt_config_grants(token, expected): grants = PassThroughGrants.for_token(token=token, jwt_auth=_jwt_auth("/model-host/*")) assert ( @@ -148,16 +182,14 @@ def test_only_a_keyless_jwt_token_with_a_team_receives_the_jwt_config_grants(tok def test_a_jwt_token_without_a_jwt_config_has_no_config_grants(): - jwt_caller = UserAPIKeyAuth(team_id="team-a", jwt_claims=JWT_CLAIMS) + jwt_caller = _token_from_jwt_auth(team_id="team-a") 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"]}, + token = _token_from_jwt_auth(team_id="team-a").model_copy( + update={"team_metadata": {"allowed_passthrough_routes": ["/team-route"]}} ) grants = PassThroughGrants.for_token(token=token, jwt_auth=_jwt_auth("/model-host/*")) diff --git a/tests/test_litellm/proxy/auth/test_route_checks.py b/tests/test_litellm/proxy/auth/test_route_checks.py index 55ce31a948b..2135fe3fd58 100644 --- a/tests/test_litellm/proxy/auth/test_route_checks.py +++ b/tests/test_litellm/proxy/auth/test_route_checks.py @@ -1302,27 +1302,21 @@ def _check_model_host_route_as(valid_token: UserAPIKeyAuth, team_allowed_routes: ) -def test_non_proxy_admin_allows_auth_pass_through_for_jwt_team_allowed_routes_wildcard(): - jwt_token: Final = UserAPIKeyAuth( - user_id="test_user", - user_role=LitellmUserRoles.INTERNAL_USER.value, - team_id="team-a", - jwt_claims={"sub": "test_user"}, - ) +_JWT_TEAM_TOKEN: Final = UserAPIKeyAuth( + user_id="test_user", + user_role=LitellmUserRoles.INTERNAL_USER.value, + team_id="team-a", + jwt_claims={"sub": "test_user"}, +).model_copy(update={"via_jwt_auth": True}) - _check_model_host_route_as(jwt_token, team_allowed_routes=["openai_routes", "/model-host/*"]) + +def test_non_proxy_admin_allows_auth_pass_through_for_jwt_team_allowed_routes_wildcard(): + _check_model_host_route_as(_JWT_TEAM_TOKEN, team_allowed_routes=["openai_routes", "/model-host/*"]) def test_non_proxy_admin_denies_auth_pass_through_for_jwt_when_only_route_groups_configured(): - jwt_token: Final = UserAPIKeyAuth( - user_id="test_user", - user_role=LitellmUserRoles.INTERNAL_USER.value, - team_id="team-a", - jwt_claims={"sub": "test_user"}, - ) - with pytest.raises(HTTPException) as exc_info: - _check_model_host_route_as(jwt_token, team_allowed_routes=["openai_routes", "mapped_pass_through_routes"]) + _check_model_host_route_as(_JWT_TEAM_TOKEN, team_allowed_routes=["openai_routes", "mapped_pass_through_routes"]) assert exc_info.value.status_code == 403, exc_info.value.detail assert "allowed_passthrough_routes" in exc_info.value.detail diff --git a/tests/test_litellm/proxy/auth/test_user_api_key_auth.py b/tests/test_litellm/proxy/auth/test_user_api_key_auth.py index 6615a1157c2..472cb6cf714 100644 --- a/tests/test_litellm/proxy/auth/test_user_api_key_auth.py +++ b/tests/test_litellm/proxy/auth/test_user_api_key_auth.py @@ -5232,7 +5232,12 @@ 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): +_JWT_TEAM_TOKEN = UserAPIKeyAuth(team_id="team-a", jwt_claims={"sub": "user-1"}).model_copy( + update={"via_jwt_auth": True} +) + + +async def _centralized_denial_for_jwt_caller_on_auth_passthrough(jwt_handler, token=_JWT_TEAM_TOKEN): import litellm.proxy.proxy_server as _proxy_server_mod from fastapi import HTTPException, Request from starlette.datastructures import URL @@ -5270,7 +5275,7 @@ async def _centralized_denial_for_jwt_caller_on_auth_passthrough(jwt_handler): ): try: await _run_centralized_common_checks( - user_api_key_auth_obj=UserAPIKeyAuth(team_id="team-a", jwt_claims={"sub": "user-1"}), + user_api_key_auth_obj=token, request=request, request_data={}, route=route, @@ -5305,6 +5310,27 @@ async def test_centralized_common_checks_grant_auth_passthrough_from_the_live_jw ) +@pytest.mark.asyncio +async def test_centralized_common_checks_withhold_jwt_team_allowed_routes_from_a_custom_auth_lookalike_token(): + 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=["/model-host/*"]), + ) + custom_auth_result = UserAPIKeyAuth.model_validate( + {"team_id": "team-a", "jwt_claims": {"sub": "user-1"}, "via_jwt_auth": True} + ) + + assert await _centralized_denial_for_jwt_caller_on_auth_passthrough(configured, token=custom_auth_result) == ( + "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 diff --git a/tests/test_litellm/proxy/test__types.py b/tests/test_litellm/proxy/test__types.py index f5abe0561db..6f832aacef1 100644 --- a/tests/test_litellm/proxy/test__types.py +++ b/tests/test_litellm/proxy/test__types.py @@ -24,6 +24,7 @@ SERVER_ONLY_MARKERS = ( "mcp_source_team_rpm_limits", "mcp_session_resource_server_id", "via_virtual_key", + "via_jwt_auth", ) diff --git a/tests/test_litellm/proxy/test_proxy_types.py b/tests/test_litellm/proxy/test_proxy_types.py index 5d5273be243..eb0f86c282f 100644 --- a/tests/test_litellm/proxy/test_proxy_types.py +++ b/tests/test_litellm/proxy/test_proxy_types.py @@ -268,6 +268,7 @@ def test_an_llm_backed_injection_check_needs_the_call_it_would_make(): ("mcp_source_team_rpm_limits", {"team-1": 10_000}, None), ("mcp_session_resource_server_id", "server-1", None), ("via_virtual_key", "sk-someone-elses-key", False), + ("via_jwt_auth", True, False), ], ) def test_a_server_only_marker_is_not_taken_from_the_caller(field, forged, default): From 5f076ac96ab4c3a47b4ae62966ff5bc61a3fac62 Mon Sep 17 00:00:00 2001 From: ryan-crabbe-berri Date: Mon, 21 Sep 2026 17:23:15 -0700 Subject: [PATCH 4/4] test(auth): cover openai_routes keys hitting an auth-enforced pass-through --- .../proxy/auth/test_route_checks.py | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/tests/test_litellm/proxy/auth/test_route_checks.py b/tests/test_litellm/proxy/auth/test_route_checks.py index 2135fe3fd58..e7a22cae5ad 100644 --- a/tests/test_litellm/proxy/auth/test_route_checks.py +++ b/tests/test_litellm/proxy/auth/test_route_checks.py @@ -1117,6 +1117,49 @@ def test_virtual_key_llm_api_routes_denies_auth_pass_through_without_allowlist() assert "allowed_passthrough_routes" in exc_info.value.detail +def _openai_routes_key_calls_auth_pass_through_registered_on_chat_completions( + passthrough_allowlist: list[str] | None, +) -> bool: + request: Final = MagicMock(spec=Request) + request.method = "POST" + with ( + patch( + "litellm.proxy.pass_through_endpoints.pass_through_endpoints._registered_pass_through_routes", + { + "test-uuid-1:exact:/chat/completions:POST": { + "endpoint_id": "test-uuid-1", + "path": "/chat/completions", + "type": "exact", + "methods": ["POST"], + "auth": True, + }, + }, + ), + patch("litellm.proxy.utils.get_server_root_path", return_value="/"), + ): + return RouteChecks.is_virtual_key_allowed_to_call_route( + route="/chat/completions", + valid_token=UserAPIKeyAuth( + user_id="test_user", + allowed_routes=["openai_routes"], + metadata={"allowed_passthrough_routes": passthrough_allowlist}, + ), + request=request, + ) + + +def test_virtual_key_openai_routes_reaches_an_auth_pass_through_in_that_group_with_an_allowlist(): + assert _openai_routes_key_calls_auth_pass_through_registered_on_chat_completions(["/chat/completions"]) is True + + +def test_virtual_key_openai_routes_denies_an_auth_pass_through_in_that_group_without_an_allowlist(): + with pytest.raises(HTTPException) as exc_info: + _openai_routes_key_calls_auth_pass_through_registered_on_chat_completions(None) + + assert exc_info.value.status_code == 403 + assert "allowed_passthrough_routes" in exc_info.value.detail + + def test_virtual_key_llm_api_routes_uses_method_specific_auth_setting(): """Same-path pass-through routes must be checked against the request method."""