fix(admin-mcp): align permissions with registered HTTP routes

This commit is contained in:
Tin 2026-10-29 14:19:56 -07:00
parent a5ee74d8de
commit 45fb345a32
3 changed files with 179 additions and 43 deletions

View file

@ -1,13 +1,13 @@
import os
import re
from collections.abc import AsyncGenerator, Mapping
from collections.abc import AsyncGenerator, Iterator, Mapping
from contextlib import asynccontextmanager
from contextvars import ContextVar
from fnmatch import fnmatchcase
from typing import Final
from urllib.parse import urlsplit
from urllib.parse import unquote, urlsplit
from fastapi import FastAPI, HTTPException, Request
from fastapi.routing import APIRoute
from pydantic import TypeAdapter
from starlette.datastructures import Headers
from starlette.routing import Mount
@ -71,38 +71,65 @@ def _admin_route_allowed(auth: UserAPIKeyAuth, request: Request, method: str, pa
return True
def _admin_route_intersects(template: str, grant: str) -> bool:
template_parts: Final = template.strip("/").split("/")
grant_parts: Final = grant.strip("/").split("/")
for segment, allowed in zip(template_parts, grant_parts):
if allowed == "*":
return True
if segment.startswith("{") and segment.endswith("}"):
def _admin_routes(request: Request) -> Iterator[tuple[tuple[str, str], APIRoute]]:
app: Final = request.app
if not isinstance(app, FastAPI):
return
for route in app.routes:
if not isinstance(route, APIRoute):
continue
if not fnmatchcase(segment, allowed):
return False
return len(grant_parts) <= len(template_parts)
for method in route.methods:
yield (method, route.path_format), route
def _admin_tool_visible(auth: UserAPIKeyAuth, request: Request, method: str, path: str) -> bool:
if _admin_route_allowed(auth, request, method, path):
def _admin_grant_paths(route: APIRoute, grant: str) -> Iterator[str]:
if route.path_regex.fullmatch(grant) is not None:
yield grant
prefix: Final = grant[:-1] if grant.endswith("*") else grant + "/"
representative: Final = re.sub(r"\{[^}]+\}", "_", route.path_format)
# A matching suffix supplies the rest of a concrete route for prefix grants,
# including grants ending inside a static segment or a path parameter.
for candidate in (prefix + representative[offset:] for offset in range(len(representative) + 1)):
if route.path_regex.fullmatch(candidate) is not None:
yield candidate
def _admin_grant_allowed(auth: UserAPIKeyAuth, request: Request, method: str, route: APIRoute, grant: str) -> bool:
return any(_admin_route_allowed(auth, request, method, path) for path in _admin_grant_paths(route, grant))
def _admin_tool_visible(auth: UserAPIKeyAuth, request: Request, method: str, route: APIRoute) -> bool:
try:
RouteChecks.check_route_enabled(route.path)
except HTTPException:
return False
if _admin_route_allowed(auth, request, method, route.path):
return True
grants: Final = _ROUTE_GRANTS.validate_python(getattr(auth, "allowed_routes", None) or ())
return "{" in path and any(_admin_route_intersects(path, grant) for grant in grants if grant.startswith("/"))
return bool(route.param_convertors) and any(
_admin_grant_allowed(auth, request, method, route, grant) for grant in grants if grant.startswith("/")
)
def get_admin_mcp_permissions(
auth: UserAPIKeyAuth, request: Request, tool: str | None = None, path: str | None = None
) -> AdminMCPPermissions:
from litellm_admin_mcp.catalog import ( # pyright: ignore[reportMissingTypeStubs] # connector has no py.typed marker
BY_NAME,
OPERATIONS,
)
try:
from litellm_admin_mcp.catalog import ( # pyright: ignore[reportMissingTypeStubs] # connector has no py.typed marker
BY_NAME,
OPERATIONS,
)
except ImportError as exc:
raise HTTPException(
status_code=503, detail="Admin MCP permissions require the admin-mcp dependency group (Python 3.12+)"
) from exc
routes: Final = dict(_admin_routes(request))
allowed: Final = tuple(
operation.name
for operation in OPERATIONS
if _admin_tool_visible(auth, request, operation.method, operation.path)
if (route := routes.get((operation.method, operation.path))) is not None
and _admin_tool_visible(auth, request, operation.method, route)
)
if tool is None:
return AdminMCPPermissions(tools=allowed)
@ -111,8 +138,10 @@ def get_admin_mcp_permissions(
return AdminMCPPermissions(tools=allowed, action_allowed=False)
if path is None:
return AdminMCPPermissions(tools=allowed, action_allowed=True)
action_allowed: Final = RouteChecks.check_route_access(path, (operation.path,)) and _admin_route_allowed(
auth, request, operation.method, path
registered: Final = routes[(operation.method, operation.path)]
decoded_path: Final = unquote(path)
action_allowed: Final = registered.path_regex.fullmatch(decoded_path) is not None and _admin_route_allowed(
auth, request, operation.method, decoded_path
)
return AdminMCPPermissions(tools=allowed, action_allowed=action_allowed)

View file

@ -110,14 +110,7 @@ _TOKEN_COUNTING_ACTION: Final = "countTokens"
class RouteChecks:
@staticmethod
def should_call_route(
route: str,
valid_token: UserAPIKeyAuth,
request: Request | None = None,
):
"""
Check if management route is disabled and raise exception
"""
def check_route_enabled(route: str) -> None:
try:
from litellm_enterprise.proxy.auth.route_checks import EnterpriseRouteChecks
@ -127,6 +120,16 @@ class RouteChecks:
except Exception:
pass
@staticmethod
def should_call_route(
route: str,
valid_token: UserAPIKeyAuth,
request: Request | None = None,
):
"""
Check if management route is disabled and raise exception
"""
RouteChecks.check_route_enabled(route)
# Check if Virtual Key is allowed to call the route - Applies to all Roles
RouteChecks.is_virtual_key_allowed_to_call_route(route=route, valid_token=valid_token, request=request)
return True

View file

@ -577,34 +577,138 @@ async def test_oauth2_proxy_auth_preserves_native_identity_and_peer_trust(
assert "list_keys" in {tool["name"] for tool in response.json()["result"]["tools"]}
@pytest.fixture
def permissions_request() -> Request:
return Request({"type": "http", "method": "GET", "path": "/user/info", "headers": [], "app": proxy_server.app})
@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+")
@pytest.mark.parametrize(
"routes,session,can_write",
[(None, False, True), ([], False, True), (["management_routes"], False, True),
(["info_routes"], False, False), (["llm_api_routes"], False, False), (None, True, True), (["info_routes"], True, False)],
[
(None, False, True),
([], False, True),
(["management_routes"], False, True),
(["info_routes"], False, False),
(["llm_api_routes"], False, False),
(None, True, True),
(["info_routes"], True, False),
],
)
def test_admin_mcp_uses_credential_routes_without_removing_full_access(
routes: list[str] | None, session: bool, can_write: bool
routes: list[str] | None, session: bool, can_write: bool, permissions_request: Request
) -> None:
auth: Final = UserAPIKeyAuth(
user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=routes, is_session_token=session,
user_id="admin",
user_role=LitellmUserRoles.PROXY_ADMIN,
allowed_routes=routes,
is_session_token=session,
)
request: Final = Request({"type": "http", "method": "GET", "path": "/user/info", "headers": []})
permissions: Final = get_admin_mcp_permissions(auth, request, "create_key", "/key/generate")
permissions: Final = get_admin_mcp_permissions(auth, permissions_request, "create_key", "/key/generate")
assert permissions.action_allowed is can_write
assert ("create_key" in permissions.tools) is can_write
@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+")
@pytest.mark.parametrize("grant", ["/team/team-a/callback", "/team/team-a/*"])
def test_admin_mcp_checks_the_concrete_resource_even_when_the_tool_is_visible(grant: str) -> None:
def test_admin_mcp_checks_the_concrete_resource_even_when_the_tool_is_visible(
grant: str, permissions_request: Request
) -> None:
auth: Final = UserAPIKeyAuth(
user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", grant],
user_id="admin",
user_role=LitellmUserRoles.PROXY_ADMIN,
allowed_routes=["/user/info", grant],
metadata={"is_session_token": True, "user_role": "proxy_admin"},
)
request: Final = Request({"type": "http", "method": "GET", "path": "/user/info", "headers": []})
own: Final = get_admin_mcp_permissions(auth, request, "get_team_callbacks", "/team/team-a/callback")
other: Final = get_admin_mcp_permissions(auth, request, "get_team_callbacks", "/team/team-b/callback")
wrong_route: Final = get_admin_mcp_permissions(auth, request, "get_team_callbacks", "/key/generate")
own: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/team/team-a/callback")
other: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/team/team-b/callback")
wrong_route: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/key/generate")
assert "get_team_callbacks" in own.tools
assert own.action_allowed is True
assert other.action_allowed is False
assert wrong_route.action_allowed is False
@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+")
@pytest.mark.parametrize("grant", ["/team/org/team-a/callback", "/team/org/team-a/*", "/team/org/team-a/call*"])
def test_admin_mcp_authorizes_slashes_using_the_registered_route(grant: str, permissions_request: Request) -> None:
auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", grant])
own: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/team/org/team-a/callback")
other: Final = get_admin_mcp_permissions(
auth, permissions_request, "get_team_callbacks", "/team/org/team-b/callback"
)
assert "get_team_callbacks" in own.tools
assert own.action_allowed is True
assert other.action_allowed is False
@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+")
@pytest.mark.parametrize(
"grant,path",
[
("/team/team a/callback", "/team/team%20a/callback"),
("/team/org/team-a/callback", "/team/org%2Fteam-a/callback"),
("/team/team%2Fa/callback", "/team/team%252Fa/callback"),
],
)
def test_admin_mcp_decodes_the_action_path_once(grant: str, path: str, permissions_request: Request) -> None:
auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", grant])
own: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", path)
other: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/team/other/callback")
assert own.action_allowed is True
assert other.action_allowed is False
@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+")
@pytest.mark.parametrize("grant", ["/te?m/*", "/[t]eam/*", "/te*m/*"])
def test_admin_mcp_does_not_invent_glob_permissions(grant: str, permissions_request: Request) -> None:
auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", grant])
permissions: Final = get_admin_mcp_permissions(
auth, permissions_request, "get_team_callbacks", "/team/team-a/callback"
)
assert "get_team_callbacks" not in permissions.tools
assert permissions.action_allowed is False
@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+")
def test_admin_mcp_discovery_respects_disabled_management_routes(
permissions_request: Request, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(proxy_server, "premium_user", True)
monkeypatch.setenv("DISABLE_ADMIN_ENDPOINTS", "true")
auth: Final = UserAPIKeyAuth(
user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", "/key/key-a/reset_spend"]
)
permissions: Final = get_admin_mcp_permissions(
auth, permissions_request, "reset_key_spend", "/key/key-a/reset_spend"
)
assert permissions.tools == ()
assert permissions.action_allowed is False
@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+")
def test_admin_mcp_preserves_http_prefix_grants(permissions_request: Request) -> None:
auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", "/key/list"])
own: Final = get_admin_mcp_permissions(auth, permissions_request, "reset_key_spend", "/key/list/reset_spend")
other: Final = get_admin_mcp_permissions(auth, permissions_request, "reset_key_spend", "/key/other/reset_spend")
assert "reset_key_spend" in own.tools
assert own.action_allowed is True
assert other.action_allowed is False
@pytest.mark.asyncio
async def test_user_info_explains_missing_admin_mcp_dependency(
permissions_request: Request, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setitem(sys.modules, "litellm_admin_mcp.catalog", None)
auth: Final = UserAPIKeyAuth(user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN)
with pytest.raises(ProxyException, match="admin-mcp dependency group") as exc:
await internal_user_endpoints.user_info(
request=permissions_request,
user_id=None,
user_api_key_dict=auth,
admin_mcp=True,
mcp_tool=None,
mcp_path=None,
)
assert exc.value.code == "503"