diff --git a/litellm/proxy/auth/core.py b/litellm/proxy/auth/core.py new file mode 100644 index 00000000000..a3045453107 --- /dev/null +++ b/litellm/proxy/auth/core.py @@ -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, + ), + ) diff --git a/litellm/proxy/auth/denial.py b/litellm/proxy/auth/denial.py new file mode 100644 index 00000000000..54d189f7418 --- /dev/null +++ b/litellm/proxy/auth/denial.py @@ -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}") diff --git a/litellm/proxy/auth/user_api_key_auth.py b/litellm/proxy/auth/user_api_key_auth.py index e763a7f25a1..b6dcc1bac11 100644 --- a/litellm/proxy/auth/user_api_key_auth.py +++ b/litellm/proxy/auth/user_api_key_auth.py @@ -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( diff --git a/litellm/proxy/mcp_server/auth/user_api_key_auth_mcp.py b/litellm/proxy/mcp_server/auth/user_api_key_auth_mcp.py index bcb979d720b..c08b97240c8 100644 --- a/litellm/proxy/mcp_server/auth/user_api_key_auth_mcp.py +++ b/litellm/proxy/mcp_server/auth/user_api_key_auth_mcp.py @@ -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" diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py index cf0306ab005..15c3440aa0f 100644 --- a/litellm/proxy/proxy_server.py +++ b/litellm/proxy/proxy_server.py @@ -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 diff --git a/litellm/rust/Cargo.lock b/litellm/rust/Cargo.lock index 513cd84524f..736ca4b2862 100644 --- a/litellm/rust/Cargo.lock +++ b/litellm/rust/Cargo.lock @@ -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", ] diff --git a/litellm/rust/crates/config/src/auth.rs b/litellm/rust/crates/config/src/auth.rs new file mode 100644 index 00000000000..52bc1e8ad87 --- /dev/null +++ b/litellm/rust/crates/config/src/auth.rs @@ -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, + #[serde(default)] + pub scope: Option, + #[serde(default)] + pub aud: Option, + #[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, + pub routing_overrides: Option>, + #[serde(flatten)] + #[redact(with = "[REDACTED]")] + pub additional_fields: AdditionalFields, +} diff --git a/litellm/rust/crates/config/src/lib.rs b/litellm/rust/crates/config/src/lib.rs index fc7b81f9192..b7cbb33a970 100644 --- a/litellm/rust/crates/config/src/lib.rs +++ b/litellm/rust/crates/config/src/lib.rs @@ -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}; diff --git a/litellm/rust/crates/config/src/settings.rs b/litellm/rust/crates/config/src/settings.rs index cd4bc5e5bc7..7956a116817 100644 --- a/litellm/rust/crates/config/src/settings.rs +++ b/litellm/rust/crates/config/src/settings.rs @@ -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>, pub mcp_allowed_origins: Box<[String]>, pub pass_through_endpoints: Option>, + /// `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, + pub litellm_jwtauth: Option, #[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}"); + } +} diff --git a/litellm/rust/crates/config/tests/config.rs b/litellm/rust/crates/config/tests/config.rs index 5c5ddb3568b..412adcba49a 100644 --- a/litellm/rust/crates/config/tests/config.rs +++ b/litellm/rust/crates/config/tests/config.rs @@ -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) { + let config = + Config::from_yaml(&format!("general_settings: {{public_routes: {value}}}")).unwrap(); + assert_eq!(config.general_settings.public_routes, expected); +} diff --git a/litellm/rust/crates/gateway-auth-core/Cargo.toml b/litellm/rust/crates/gateway-auth-core/Cargo.toml index 1a8f933498b..b02c8dbd3f7 100644 --- a/litellm/rust/crates/gateway-auth-core/Cargo.toml +++ b/litellm/rust/crates/gateway-auth-core/Cargo.toml @@ -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 diff --git a/litellm/rust/crates/gateway-auth-core/src/authn/jwt/mod.rs b/litellm/rust/crates/gateway-auth-core/src/authn/jwt/mod.rs new file mode 100644 index 00000000000..4935a8c4fa5 --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/authn/jwt/mod.rs @@ -0,0 +1,3 @@ +mod verify; + +pub use verify::{Claims, is_jwt, unverified_claims}; diff --git a/litellm/rust/crates/gateway-auth-core/src/authn/jwt/verify.rs b/litellm/rust/crates/gateway-auth-core/src/authn/jwt/verify.rs new file mode 100644 index 00000000000..1928f9eba3a --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/authn/jwt/verify.rs @@ -0,0 +1,48 @@ +use jsonwebtoken::dangerous::insecure_decode_claims; +use serde_json::{Map, Value}; + +#[derive(Clone, Debug, PartialEq)] +pub struct Claims(pub Map); + +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 { + 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) { + 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); + } +} diff --git a/litellm/rust/crates/gateway-auth-core/src/authn/mod.rs b/litellm/rust/crates/gateway-auth-core/src/authn/mod.rs new file mode 100644 index 00000000000..417233c0836 --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/authn/mod.rs @@ -0,0 +1 @@ +pub mod jwt; diff --git a/litellm/rust/crates/gateway-auth-core/src/error.rs b/litellm/rust/crates/gateway-auth-core/src/error.rs new file mode 100644 index 00000000000..a480a81d458 --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/error.rs @@ -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, +} diff --git a/litellm/rust/crates/gateway-auth-core/src/lib.rs b/litellm/rust/crates/gateway-auth-core/src/lib.rs index 4aeaecbb447..8cb7ea002f5 100644 --- a/litellm/rust/crates/gateway-auth-core/src/lib.rs +++ b/litellm/rust/crates/gateway-auth-core/src/lib.rs @@ -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; diff --git a/litellm/rust/crates/gateway-auth-core/src/plan/introspection.rs b/litellm/rust/crates/gateway-auth-core/src/plan/introspection.rs new file mode 100644 index 00000000000..4d6f7d4237c --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/plan/introspection.rs @@ -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, + aud: Option, + scope: Option, +} + +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 { + 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 { + 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, + scope: Option, + aud: Option, + ) -> JwtRoutingOverride { + JwtRoutingOverride { + iss: OneOrMany::One(ISSUER.to_owned()), + client_id, + scope, + aud, + path: RoutingPath::OAuth2, + } + } + + fn claim_pattern(values: Option) -> ClaimPattern { + ClaimPattern(selectors(&values.unwrap())) + } + + fn scope_pattern(values: Option) -> 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, + #[case] claim: Option, + #[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, + #[case] claim: Option, + #[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); + } +} diff --git a/litellm/rust/crates/gateway-auth-core/src/plan/mod.rs b/litellm/rust/crates/gateway-auth-core/src/plan/mod.rs new file mode 100644 index 00000000000..a93fa948627 --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/plan/mod.rs @@ -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 { + 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 { + 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, + ) { + 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, + ) { + 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, + ) { + 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, + ) { + 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, + ) { + 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, + ) { + 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)); + } +} diff --git a/litellm/rust/crates/gateway-auth-core/src/plan/public_routes.rs b/litellm/rust/crates/gateway-auth-core/src/plan/public_routes.rs new file mode 100644 index 00000000000..819903b3774 --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/plan/public_routes.rs @@ -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('/'), + } +} diff --git a/litellm/rust/crates/gateway-auth-core/src/public.rs b/litellm/rust/crates/gateway-auth-core/src/public.rs new file mode 100644 index 00000000000..e98ad6ee140 --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/public.rs @@ -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, + }, +} + +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()), + } + ); + } +} diff --git a/litellm/rust/crates/gateway-auth-core/src/routes/table.rs b/litellm/rust/crates/gateway-auth-core/src/routes/table.rs index 65534566119..e4f7c90143e 100644 --- a/litellm/rust/crates/gateway-auth-core/src/routes/table.rs +++ b/litellm/rust/crates/gateway-auth-core/src/routes/table.rs @@ -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", diff --git a/litellm/rust/crates/gateway-auth-core/src/test_support.rs b/litellm/rust/crates/gateway-auth-core/src/test_support.rs index defbdd7e72f..b5783de4e57 100644 --- a/litellm/rust/crates/gateway-auth-core/src/test_support.rs +++ b/litellm/rust/crates/gateway-auth-core/src/test_support.rs @@ -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 { + Some(OneOrMany::One(value.to_owned())) +} + +pub fn many(values: &[&str]) -> Option { + 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") } diff --git a/litellm/rust/crates/gateway-auth-core/src/token.rs b/litellm/rust/crates/gateway-auth-core/src/token.rs new file mode 100644 index 00000000000..f854981e547 --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/token.rs @@ -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) -> 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}"); + } +} diff --git a/litellm/rust/crates/gateway-auth-core/src/value.rs b/litellm/rust/crates/gateway-auth-core/src/value.rs new file mode 100644 index 00000000000..79816437f51 --- /dev/null +++ b/litellm/rust/crates/gateway-auth-core/src/value.rs @@ -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 { + 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); + } +} diff --git a/litellm/rust/crates/python-bridge/src/auth/call.rs b/litellm/rust/crates/python-bridge/src/auth/call.rs new file mode 100644 index 00000000000..6e569c5695c --- /dev/null +++ b/litellm/rust/crates/python-bridge/src/auth/call.rs @@ -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> { + Ok(token.extract::>()?.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, + #[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 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, + }, +} + +impl From 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) + } +} diff --git a/litellm/rust/crates/python-bridge/src/auth/mod.rs b/litellm/rust/crates/python-bridge/src/auth/mod.rs index 22daf244a10..effe72cffaf 100644 --- a/litellm/rust/crates/python-bridge/src/auth/mod.rs +++ b/litellm/rust/crates/python-bridge/src/auth/mod.rs @@ -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; diff --git a/litellm/rust/crates/python-bridge/src/auth/settings.rs b/litellm/rust/crates/python-bridge/src/auth/settings.rs new file mode 100644 index 00000000000..57bb3fe7106 --- /dev/null +++ b/litellm/rust/crates/python-bridge/src/auth/settings.rs @@ -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>> { + 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 { + 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 { + 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::(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 { + 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, + ))) + } +} diff --git a/litellm/rust/crates/python-bridge/src/lib.rs b/litellm/rust/crates/python-bridge/src/lib.rs index 6b4886e8970..28b888dca7c 100644 --- a/litellm/rust/crates/python-bridge/src/lib.rs +++ b/litellm/rust/crates/python-bridge/src/lib.rs @@ -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"); diff --git a/litellm/rust_bridge/AGENTS.md b/litellm/rust_bridge/AGENTS.md index be4c0306673..88b6678e462 100644 --- a/litellm/rust_bridge/AGENTS.md +++ b/litellm/rust_bridge/AGENTS.md @@ -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/` diff --git a/litellm/rust_bridge/_native.pyi b/litellm/rust_bridge/_native.pyi index 06d2d77e41e..3ccb7e9fef6 100644 --- a/litellm/rust_bridge/_native.pyi +++ b/litellm/rust_bridge/_native.pyi @@ -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", diff --git a/tests/unit/proxy/auth/test_core.py b/tests/unit/proxy/auth/test_core.py new file mode 100644 index 00000000000..6e45a4d76c1 --- /dev/null +++ b/tests/unit/proxy/auth/test_core.py @@ -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 diff --git a/tests/unit/proxy/auth/test_denial.py b/tests/unit/proxy/auth/test_denial.py new file mode 100644 index 00000000000..a03ad04c0ef --- /dev/null +++ b/tests/unit/proxy/auth/test_denial.py @@ -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") diff --git a/tests/unit/proxy/auth/test_user_api_key_auth_request_flow.py b/tests/unit/proxy/auth/test_user_api_key_auth_request_flow.py index 6cb6052b223..dfc974afc81 100644 --- a/tests/unit/proxy/auth/test_user_api_key_auth_request_flow.py +++ b/tests/unit/proxy/auth/test_user_api_key_auth_request_flow.py @@ -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,