fix(admin-mcp): expose and enforce credential route permissions

This commit is contained in:
Tin 2026-10-23 15:10:53 -04:00
parent 82a4ef4095
commit a298cb0512
9 changed files with 162 additions and 15 deletions

View file

@ -3169,11 +3169,18 @@ from litellm.types.proxy.auth.user_api_key_auth import (
)
class AdminMCPPermissions(LiteLLMPydanticObjectBase):
model_config = ConfigDict(frozen=True)
tools: tuple[str, ...]
action_allowed: bool | None = None
class UserInfoResponse(LiteLLMPydanticObjectBase):
user_id: str | None
user_info: dict | BaseModel | None
keys: list
teams: list
admin_mcp_permissions: AdminMCPPermissions | None = None
class UserInfoV2Response(LiteLLMPydanticObjectBase):

View file

@ -3,18 +3,19 @@ import re
from collections.abc import AsyncGenerator, Mapping
from contextlib import asynccontextmanager
from contextvars import ContextVar
from fnmatch import fnmatchcase
from typing import Final
from urllib.parse import urlsplit
from fastapi import FastAPI
from fastapi import FastAPI, HTTPException, Request
from pydantic import TypeAdapter
from starlette.datastructures import Headers
from starlette.requests import Request
from starlette.routing import Mount
from starlette.types import ASGIApp, Receive, Scope, Send
from litellm.constants import STANDARD_CUSTOMER_ID_HEADERS
from litellm.proxy._types import SpecialHeaders
from litellm.proxy._types import AdminMCPPermissions, SpecialHeaders, UserAPIKeyAuth
from litellm.proxy.auth.route_checks import RouteChecks
from litellm.proxy.middleware.admission_control_middleware import ADMISSION_LEASE_SCOPE_KEY
_REQUEST_HEADERS: Final = frozenset(
@ -58,6 +59,62 @@ _RESERVED_KEY_HEADERS: Final = (
_SETTINGS: Final = TypeAdapter(Mapping[str, object])
_IDENTITY_MAPPINGS: Final = TypeAdapter(tuple[dict[str, object], ...] | dict[str, object] | None)
_OAUTH_MAPPINGS: Final = TypeAdapter(dict[str, str])
_ROUTE_GRANTS: Final = TypeAdapter(tuple[str, ...])
def _admin_route_allowed(auth: UserAPIKeyAuth, request: Request, method: str, path: str) -> bool:
target: Final = Request({**request.scope, "method": method, "path": path, "raw_path": path.encode()})
try:
RouteChecks.should_call_route(route=path, valid_token=auth, request=target)
except HTTPException:
return False
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("}"):
continue
if not fnmatchcase(segment, allowed):
return False
return len(grant_parts) <= len(template_parts)
def _admin_tool_visible(auth: UserAPIKeyAuth, request: Request, method: str, path: str) -> bool:
if _admin_route_allowed(auth, request, method, 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("/"))
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,
)
allowed: Final = tuple(
operation.name
for operation in OPERATIONS
if _admin_tool_visible(auth, request, operation.method, operation.path)
)
if tool is None:
return AdminMCPPermissions(tools=allowed)
operation: Final = BY_NAME.get(tool)
if operation is None or tool not in allowed:
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
)
return AdminMCPPermissions(tools=allowed, action_allowed=action_allowed)
def _configured_key_header() -> bytes | None:

View file

@ -930,6 +930,11 @@ async def user_info(
request: Request,
user_id: str | None = fastapi.Query(default=None, description="User ID in the request parameters"),
user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
admin_mcp: bool = fastapi.Query(
default=False, description="Include the caller's current admin MCP route permissions"
),
mcp_tool: str | None = fastapi.Query(default=None, description="Admin MCP tool to authorize for this caller"),
mcp_path: str | None = fastapi.Query(default=None, description="Concrete management route used by the MCP tool"),
):
"""
[10/07/2024]
@ -950,12 +955,23 @@ async def user_info(
user_id = _normalize_user_info_user_id(request=request, user_id=user_id)
_enforce_user_info_access(user_id=user_id, user_api_key_dict=user_api_key_dict)
from litellm.proxy.admin_mcp import get_admin_mcp_permissions
mcp_permissions: Final = (
get_admin_mcp_permissions(user_api_key_dict, request, mcp_tool, mcp_path) if admin_mcp is True else None
)
if prisma_client is None:
raise Exception(
"Database not connected. Connect a database to your proxy - https://docs.litellm.ai/docs/simple_proxy#managing-auth---virtual-keys"
)
if user_id is None and user_api_key_has_admin_view(user_api_key_dict):
return await _get_user_info_for_proxy_admin(user_api_key_dict=user_api_key_dict)
admin_response: Final = await _get_user_info_for_proxy_admin(user_api_key_dict=user_api_key_dict)
return (
admin_response.model_copy(update={"admin_mcp_permissions": mcp_permissions})
if mcp_permissions is not None
else admin_response
)
elif user_id is None:
user_id = user_api_key_dict.user_id
## GET USER ROW ##
@ -994,7 +1010,11 @@ async def user_info(
),
)
return response_data
return (
response_data.model_copy(update={"admin_mcp_permissions": mcp_permissions})
if mcp_permissions is not None
else response_data
)
except Exception as e:
verbose_proxy_logger.exception("litellm.proxy.proxy_server.user_info(): Exception occured - %s", e)
raise handle_exception_on_proxy(e)

View file

@ -247,7 +247,7 @@ e2e-dev = [
"mcp>=2.3.0,<3",
]
admin-mcp = [
"litellm-admin-mcp @ https://github.com/BerriAI/liteadmin-mcp/archive/d35ec9c19c117d4c50cc1eccf6ce1296aac25a1a.tar.gz#sha256=86b930f6706fb2da10d53d1798ee7fd14e44fb0afdef0da122cf0e6bb88fa2c3 ; python_version >= '3.12'",
"litellm-admin-mcp @ https://github.com/BerriAI/liteadmin-mcp/archive/31fb096904ae05684c0779110a93b135b5601182.tar.gz#sha256=5803a20a00a18177f4591706956f31be311879543049b8b38143ad90bb1cb0a6 ; python_version >= '3.12'",
]
proxy-dev = [
{ include-group = "admin-mcp" },

View file

@ -12,8 +12,8 @@ from starlette.testclient import TestClient
from litellm.constants import STANDARD_CUSTOMER_ID_HEADERS
from litellm.proxy import proxy_server
from litellm.proxy._types import LiteLLM_UserTable, ProxyException, SpecialHeaders
from litellm.proxy.admin_mcp import admin_mcp_lifespan
from litellm.proxy._types import LiteLLM_UserTable, LitellmUserRoles, ProxyException, SpecialHeaders, UserAPIKeyAuth
from litellm.proxy.admin_mcp import admin_mcp_lifespan, get_admin_mcp_permissions
from litellm.proxy.auth.user_api_key_auth import get_api_key, get_api_key_from_custom_header
from litellm.proxy.common_utils.user_api_key_cache import UserApiKeyCache
from litellm.proxy.management_endpoints import internal_user_endpoints
@ -66,12 +66,22 @@ def management_app(monkeypatch: pytest.MonkeyPatch) -> FastAPI:
if credential not in {"admin-a", "admin-b", "admin-b-limited", "member", "viewer"}:
raise HTTPException(status_code=401)
user_id: Final = "admin-b" if credential == "admin-b-limited" else credential
role: Final = {"member": LitellmUserRoles.INTERNAL_USER, "viewer": LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY}.get(
user_id, LitellmUserRoles.PROXY_ADMIN
)
auth: Final = UserAPIKeyAuth(
user_id=user_id, user_role=role,
allowed_routes=["/user/info"] if credential == "admin-b-limited" else None,
)
return {
"user_id": user_id,
"user_info": {
"user_id": user_id,
"user_role": {"member": "internal_user", "viewer": "proxy_admin_viewer"}.get(user_id, "proxy_admin"),
"user_role": role.value,
},
"admin_mcp_permissions": get_admin_mcp_permissions(
auth, request, request.query_params.get("mcp_tool"), request.query_params.get("mcp_path")
).model_dump(mode="json"),
}
@app.get("/key/list", operation_id="list_keys_key_list_get")
@ -565,3 +575,36 @@ async def test_oauth2_proxy_auth_preserves_native_identity_and_peer_trust(
assert response.status_code == status, response.text
if status == 200:
assert "list_keys" in {tool["name"] for tool in response.json()["result"]["tools"]}
@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)],
)
def test_admin_mcp_uses_credential_routes_without_removing_full_access(
routes: list[str] | None, session: bool, can_write: bool
) -> None:
auth: Final = UserAPIKeyAuth(
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")
assert permissions.action_allowed is can_write
assert ("create_key" in permissions.tools) is can_write
@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:
auth: Final = UserAPIKeyAuth(
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")
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

View file

@ -452,7 +452,10 @@ def test_admin_mcp_survives_only_management_component_lifespans(
@application.get("/user/info")
async def user_info() -> dict[str, object]:
return {"user_id": "admin", "user_info": {"user_id": "admin", "user_role": "proxy_admin"}}
return {
"user_id": "admin", "user_info": {"user_id": "admin", "user_role": "proxy_admin"},
"admin_mcp_permissions": {"tools": ["list_teams"], "action_allowed": True},
}
if component_lifespan is not None:
application.router.lifespan_context = partial(component_lifespan, lifespan=application.router.lifespan_context)

View file

@ -144,7 +144,10 @@ async def test_proxy_shutdown_drains_active_admin_tool_before_closing_connector(
@admin_mcp_proxy.get("/user/info")
async def user_info() -> dict[str, object]:
return {"user_id": "admin", "user_info": {"user_id": "admin", "user_role": "proxy_admin"}}
return {
"user_id": "admin", "user_info": {"user_id": "admin", "user_role": "proxy_admin"},
"admin_mcp_permissions": {"tools": ["list_teams"], "action_allowed": True},
}
@admin_mcp_proxy.get("/team/list", operation_id="list_team_team_list_get")
async def list_teams() -> dict[str, object]:

View file

@ -25658,6 +25658,13 @@ export interface components {
*/
source: "admin";
};
/** AdminMCPPermissions */
AdminMCPPermissions: {
/** Action Allowed */
action_allowed?: boolean | null;
/** Tools */
tools: string[];
};
/**
* AgentCapabilities
* @description Defines optional capabilities supported by an agent.
@ -49693,6 +49700,7 @@ export interface components {
};
/** UserInfoResponse */
UserInfoResponse: {
admin_mcp_permissions?: components["schemas"]["AdminMCPPermissions"] | null;
/** Keys */
keys: unknown[];
/** Teams */
@ -76210,6 +76218,12 @@ export interface operations {
query?: {
/** @description User ID in the request parameters */
user_id?: string | null;
/** @description Include the caller's current admin MCP route permissions */
admin_mcp?: boolean;
/** @description Admin MCP tool to authorize for this caller */
mcp_tool?: string | null;
/** @description Concrete management route used by the MCP tool */
mcp_path?: string | null;
};
header?: never;
path?: never;

8
uv.lock generated
View file

@ -4981,7 +4981,7 @@ requires-dist = [
provides-extras = ["proxy", "cli", "extra-proxy", "utils", "caching", "mcp", "saml", "semantic-router", "mlflow", "grpc", "stt-vertex-chirp", "stt-nvidia-riva", "google", "bedrock-realtime", "proxy-runtime"]
[package.metadata.requires-dev]
admin-mcp = [{ name = "litellm-admin-mcp", marker = "python_full_version >= '3.12'", url = "https://github.com/BerriAI/liteadmin-mcp/archive/d35ec9c19c117d4c50cc1eccf6ce1296aac25a1a.tar.gz" }]
admin-mcp = [{ name = "litellm-admin-mcp", marker = "python_full_version >= '3.12'", url = "https://github.com/BerriAI/liteadmin-mcp/archive/31fb096904ae05684c0779110a93b135b5601182.tar.gz" }]
benchmarks = [
{ name = "a2a-sdk", specifier = "==1.1.0" },
{ name = "mcp", specifier = ">=2.3.0,<3" },
@ -5077,7 +5077,7 @@ proxy-dev = [
{ name = "azure-identity", specifier = "==1.25.2" },
{ name = "backports-zstd", marker = "python_full_version < '3.14'", specifier = "==1.8.0" },
{ name = "hypercorn", specifier = "==0.17.3" },
{ name = "litellm-admin-mcp", marker = "python_full_version >= '3.12'", url = "https://github.com/BerriAI/liteadmin-mcp/archive/d35ec9c19c117d4c50cc1eccf6ce1296aac25a1a.tar.gz" },
{ name = "litellm-admin-mcp", marker = "python_full_version >= '3.12'", url = "https://github.com/BerriAI/liteadmin-mcp/archive/31fb096904ae05684c0779110a93b135b5601182.tar.gz" },
{ name = "opentelemetry-api", specifier = "==1.33.1" },
{ name = "opentelemetry-exporter-otlp", specifier = "==1.33.1" },
{ name = "opentelemetry-instrumentation-fastapi", specifier = "==0.54b1" },
@ -5090,14 +5090,14 @@ proxy-dev = [
[[package]]
name = "litellm-admin-mcp"
version = "0.1.0"
source = { url = "https://github.com/BerriAI/liteadmin-mcp/archive/d35ec9c19c117d4c50cc1eccf6ce1296aac25a1a.tar.gz" }
source = { url = "https://github.com/BerriAI/liteadmin-mcp/archive/31fb096904ae05684c0779110a93b135b5601182.tar.gz" }
dependencies = [
{ name = "httpx2" },
{ name = "jsonschema" },
{ name = "mcp" },
{ name = "uvicorn" },
]
sdist = { hash = "sha256:86b930f6706fb2da10d53d1798ee7fd14e44fb0afdef0da122cf0e6bb88fa2c3" }
sdist = { hash = "sha256:5803a20a00a18177f4591706956f31be311879543049b8b38143ad90bb1cb0a6" }
[package.metadata]
requires-dist = [