Merge remote-tracking branch 'origin/litellm_agent365_mcp_guardrail' into litellm_agent365_agent_identity
Some checks failed
LiteLLM Rust / rust-lint (push) Has been cancelled
LiteLLM Rust / rust-test (push) Has been cancelled
Terraform Modules / fmt, validate, test (aws) (push) Has been cancelled
Terraform Modules / fmt, validate, test (gcp) (push) Has been cancelled
Terraform Provider / gofmt, vet, build, test (push) Has been cancelled
Terraform Provider / Provider endpoints vs proxy OpenAPI schema (push) Has been cancelled

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

# Conflicts:
#	litellm/proxy/guardrails/guardrail_hooks/agent_365/agent_365.py
This commit is contained in:
yucheng 2026-09-11 03:19:44 +00:00
commit 01c9465dd8
7 changed files with 157 additions and 55 deletions

View file

@ -5,13 +5,14 @@ import secrets
import time
from collections.abc import Callable, Mapping
from datetime import datetime, timezone
from typing import TYPE_CHECKING, Any, Final, Literal, Optional
from typing import TYPE_CHECKING, Any, Final, Literal, Optional, TypedDict
from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
import httpx
from fastapi import APIRouter, Depends, Form, HTTPException, Request
from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse, Response
from pydantic import BaseModel, ConfigDict, Field, SecretStr, ValidationError
from typing_extensions import ReadOnly
from litellm._logging import verbose_logger
from litellm.caching.in_memory_cache import InMemoryCache
@ -81,7 +82,10 @@ from litellm.proxy.common_utils.encrypt_decrypt_utils import (
encrypt_value_helper,
)
from litellm.proxy.common_utils.http_parsing_utils import _read_request_body
from litellm.proxy.guardrails.guardrail_hooks.agent_365.agent_365 import agent_365_authorization_servers
from litellm.proxy.guardrails.guardrail_hooks.agent_365.agent_365 import (
agent_365_authorization_servers,
agent_365_scopes_supported,
)
from litellm.types.mcp import MCPAuth, MCPCredentials
from litellm.types.mcp_server.mcp_server_manager import MCPServer, MCPTokenEndpointAuthMethod
@ -2375,7 +2379,7 @@ async def _build_oauth_protected_resource_response(
request: Request,
mcp_server_name: str | None,
use_standard_pattern: bool,
) -> dict:
) -> Mapping[str, object]:
"""
Build OAuth protected resource response with the appropriate URL pattern.
@ -2481,11 +2485,12 @@ async def _build_oauth_protected_resource_response(
agent_365_issuers: Final = agent_365_authorization_servers(mcp_server, None) if mcp_server else ()
if mcp_server is not None and agent_365_issuers:
return {
"authorization_servers": list(agent_365_issuers),
agent_365_metadata: Final[_ProtectedResourceMetadata] = {
"authorization_servers": agent_365_issuers,
"resource": resource_url,
"scopes_supported": list(mcp_server.scopes or ()),
"scopes_supported": agent_365_scopes_supported(mcp_server, None),
}
return agent_365_metadata
if explicitly_named and mcp_server is not None and mcp_server.advertises_gateway_authorization_server:
return {
@ -2506,6 +2511,12 @@ async def _build_oauth_protected_resource_response(
}
class _ProtectedResourceMetadata(TypedDict):
authorization_servers: ReadOnly[tuple[str, ...]]
resource: ReadOnly[str]
scopes_supported: ReadOnly[tuple[str, ...]]
def _obo_protected_resource_response(mcp_server: MCPServer | None, resource_url: str) -> dict | None:
"""The OBO (token_exchange) PRM, or None when this server is not OBO / no issuer is configured.

View file

@ -1779,7 +1779,7 @@ class MCPServerManager:
"gmail_send_email": "zapier_mcp_server",
}
"""
self._listed_tools_by_server_id: dict[str, dict[str, MCPTool]] = {}
self._listed_tools_by_server_id: dict[str, Mapping[str, MCPTool]] = {} # mutable-ok: refreshed per tools/list
self._upstream_initialize_instructions_by_server_id: dict[str, str] = {}
# Per-server monotonic timestamp of last upstream prefetch attempt (success,
# empty result, or failure). Used to throttle re-probes for servers that do
@ -4244,7 +4244,7 @@ class MCPServerManager:
# time producing "test_petstore-test_petstore-getinventory".
prefix: Final = get_server_prefix(server)
sep: Final = MCP_TOOL_PREFIX_SEPARATOR
bare_tools: Final = [
bare_tools: Final = [ # mutable-ok: returned through the list[MCPTool] listing contract
(
t.model_copy(update={"name": t.name[len(prefix) + len(sep) :]})
if t.name.startswith(f"{prefix}{sep}")
@ -4252,7 +4252,7 @@ class MCPServerManager:
)
for t in tools
]
self._listed_tools_by_server_id[server.server_id] = {t.name: t for t in bare_tools}
self._listed_tools_by_server_id[server.server_id] = MappingProxyType({t.name: t for t in bare_tools})
return tools if add_prefix else bare_tools
else:
tools = await self._fetch_tools_with_timeout(client, server.name)
@ -5134,7 +5134,7 @@ class MCPServerManager:
for spelling in iter_known_tool_name_spellings(original_name, server):
self.tool_name_to_mcp_server_name_mapping[spelling] = prefix
self._listed_tools_by_server_id[server.server_id] = {tool.name: tool for tool in tools}
self._listed_tools_by_server_id[server.server_id] = MappingProxyType({tool.name: tool for tool in tools})
verbose_logger.info("Successfully fetched %s tools from server %s", len(prefixed_tools), server.name)
return prefixed_tools

View file

@ -61,6 +61,10 @@ ENTRA_ISSUER_TEMPLATE: Final = "https://login.microsoftonline.com/{tenant_id}/v2
EVALUATE_PATH: Final = "/agents/tool-evaluation/evaluate"
MCP_SESSION_ID_HEADER: Final = "mcp-session-id"
DEFENDER_STATUS_EVALUATED: Final = "Evaluated"
GATEWAY_SCOPE_TEMPLATE: Final = "api://{client_id}/access_as_user"
_GATEWAY_OWNED_TOKEN_ERRORS: Final = frozenset(
{"invalid_client", "unauthorized_client", "invalid_scope", "invalid_resource"}
)
_MCP_CALL_TYPES: Final[tuple[str, ...]] = ("mcp_call", "call_mcp_tool")
_TOOL_INPUT_SCHEMA_ADAPTER: Final = TypeAdapter(dict[str, object])
_OBO_CACHE_MAX_ENTRIES: Final = 1000
@ -228,6 +232,15 @@ class Agent365Guardrail(CustomGuardrail):
tool_name=tool_name,
reason=f"the Entra agent identity token request was rejected ({exc.error_code}: {exc.description})",
)
if exc.error_code in _GATEWAY_OWNED_TOKEN_ERRORS:
return self._handle_unavailable(
data=data,
tool_name=tool_name,
reason=(
f"Entra rejected the gateway's own Agent 365 credentials ({exc.error_code}); "
"check the guardrail's client_id, client_secret and resource_app_id"
),
)
self._handle_caller_fault(
data=data,
tool_name=tool_name,
@ -730,24 +743,43 @@ def _applies_to_caller(guardrail: Agent365Guardrail, user_api_key_auth: "UserAPI
return guardrail.should_run_guardrail(data=probe, event_type=GuardrailEventHooks.pre_mcp_call)
def agent_365_authorization_servers(server: MCPServer, user_api_key_auth: "UserAPIKeyAuth | None") -> tuple[str, ...]:
"""Entra issuers an MCP client signs in with before calling ``server`` through an Agent 365 guardrail.
Empty unless the admin advertised the server's ``scopes`` (the audience the client requests), the gateway
would otherwise own sign-in for the server, and an On-Behalf-Of Agent 365 guardrail applies: every registered
one for the anonymous discovery fetch, otherwise those the caller's key, team, or policies select. Agent
identity guardrails never read the caller's bearer, so they neither advertise nor challenge.
"""
if not server.scopes or server.auth_type == MCPAuth.oauth2 or not server.advertises_gateway_authorization_server:
def _applicable_guardrails(
server: MCPServer, user_api_key_auth: "UserAPIKeyAuth | None"
) -> tuple[Agent365Guardrail, ...]:
"""On-Behalf-Of Agent 365 guardrails that gate ``server`` for this caller: every registered one for the
anonymous discovery fetch, otherwise those the caller's key, team, or policies select. Empty when the
gateway does not own sign-in for the server. Agent identity guardrails never read the caller's bearer, so
they neither advertise nor challenge."""
if server.auth_type == MCPAuth.oauth2 or not server.advertises_gateway_authorization_server:
return ()
registered: Final = tuple(
callback
for callback in litellm.logging_callback_manager.get_custom_loggers_for_type(Agent365Guardrail)
if isinstance(callback, Agent365Guardrail) and callback.agent_identity is None
)
applicable: Final = (
registered
if user_api_key_auth is None
else tuple(g for g in registered if _applies_to_caller(g, user_api_key_auth))
if user_api_key_auth is None:
return registered
return tuple(g for g in registered if _applies_to_caller(g, user_api_key_auth))
def agent_365_authorization_servers(server: MCPServer, user_api_key_auth: "UserAPIKeyAuth | None") -> tuple[str, ...]:
"""Entra issuers an MCP client signs in with before calling ``server`` through an Agent 365 guardrail."""
return tuple(
dict.fromkeys(
ENTRA_ISSUER_TEMPLATE.format(tenant_id=g.tenant_id)
for g in _applicable_guardrails(server, user_api_key_auth)
)
)
def agent_365_scopes_supported(server: MCPServer, user_api_key_auth: "UserAPIKeyAuth | None") -> tuple[str, ...]:
"""Scopes the client requests from Entra for ``server``: the admin's ``scopes`` when set, otherwise the
``access_as_user`` scope of each gating guardrail's gateway app registration (``api://<client_id>``)."""
if server.scopes:
return tuple(server.scopes)
return tuple(
dict.fromkeys(
GATEWAY_SCOPE_TEMPLATE.format(client_id=g.client_id)
for g in _applicable_guardrails(server, user_api_key_auth)
)
)
return tuple(dict.fromkeys(ENTRA_ISSUER_TEMPLATE.format(tenant_id=g.tenant_id) for g in applicable))

View file

@ -10,6 +10,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from fastapi import HTTPException
from fastapi.encoders import jsonable_encoder
from litellm.types.mcp import MCPAuth
@ -7148,7 +7149,7 @@ async def _agent_365_gated_prm(scopes):
@pytest.mark.asyncio
async def test_agent_365_gated_server_prm_names_the_entra_tenant(agent_365_guardrail):
response = await _agent_365_gated_prm(scopes=["api://gateway-app/access_as_user"])
assert response == {
assert jsonable_encoder(response) == {
"authorization_servers": ["https://login.microsoftonline.com/tenant-abc/v2.0"],
"resource": "https://litellm.example.com/mcp/tools",
"scopes_supported": ["api://gateway-app/access_as_user"],
@ -7156,9 +7157,13 @@ async def test_agent_365_gated_server_prm_names_the_entra_tenant(agent_365_guard
@pytest.mark.asyncio
async def test_agent_365_prm_falls_back_to_gateway_without_scopes(agent_365_guardrail):
async def test_agent_365_prm_defaults_scopeless_server_to_the_gateway_app_scope(agent_365_guardrail):
response = await _agent_365_gated_prm(scopes=None)
assert response["authorization_servers"] == ["https://litellm.example.com/mcp"]
assert jsonable_encoder(response) == {
"authorization_servers": ["https://login.microsoftonline.com/tenant-abc/v2.0"],
"resource": "https://litellm.example.com/mcp/tools",
"scopes_supported": ["api://client-xyz/access_as_user"],
}
def _token_request(headers):

View file

@ -8867,7 +8867,7 @@ class TestAgent365ChallengeAtConnect:
litellm.callbacks, guardrail, require_self=False
)
async def _connect(self, server: MCPServer, oauth2_headers: dict[str, str] | None) -> None:
async def _connect(self, server: MCPServer, oauth2_headers: dict[str, str] | None) -> HTTPException | None:
from litellm.proxy._experimental.mcp_server import server as server_module
with (
@ -8878,36 +8878,43 @@ class TestAgent365ChallengeAtConnect:
server_module, "_get_allowed_mcp_servers", AsyncMock(return_value=[])
),
):
await server_module._raise_preemptive_401_for_unauthenticated_servers(
scope={"type": "http", "method": "POST", "path": "/mcp/tools", "headers": []},
mcp_servers=["tools"],
oauth2_headers=oauth2_headers,
mcp_server_auth_headers=None,
user_api_key_auth=UserAPIKeyAuth(api_key="sk-litellm-virtual-key", user_id="u-1"),
client_ip=None,
)
try:
await server_module._raise_preemptive_401_for_unauthenticated_servers(
scope={"type": "http", "method": "POST", "path": "/mcp/tools", "headers": []},
mcp_servers=["tools"],
oauth2_headers=oauth2_headers,
mcp_server_auth_headers=None,
user_api_key_auth=UserAPIKeyAuth(api_key="sk-litellm-virtual-key", user_id="u-1"),
client_ip=None,
)
except HTTPException as challenge:
return challenge
return None
@pytest.mark.asyncio
async def test_no_bearer_gets_the_discovery_challenge(self, agent_365_guardrail):
with pytest.raises(HTTPException) as exc:
await self._connect(self._server([self.GATEWAY_SCOPE]), None)
challenge = await self._connect(self._server([self.GATEWAY_SCOPE]), None)
assert exc.value.status_code == 401
www_authenticate = (exc.value.headers or {}).get("WWW-Authenticate", "")
assert challenge is not None and challenge.status_code == 401
www_authenticate = (challenge.headers or {}).get("WWW-Authenticate", "")
assert 'error="invalid_token"' in www_authenticate
assert 'resource_metadata="/.well-known/oauth-protected-resource/mcp/tools"' in www_authenticate
@pytest.mark.asyncio
async def test_bearer_present_connects(self, agent_365_guardrail):
await self._connect(self._server([self.GATEWAY_SCOPE]), {"Authorization": "Bearer entra-user-token"})
bearer = {"Authorization": "Bearer entra-user-token"}
assert await self._connect(self._server([self.GATEWAY_SCOPE]), bearer) is None
@pytest.mark.asyncio
async def test_server_without_advertised_scopes_is_not_challenged(self, agent_365_guardrail):
await self._connect(self._server(None), None)
async def test_scopeless_server_is_still_challenged(self, agent_365_guardrail):
challenge = await self._connect(self._server(None), None)
assert challenge is not None and challenge.status_code == 401
assert 'error="invalid_token"' in (challenge.headers or {}).get("WWW-Authenticate", "")
@pytest.mark.asyncio
async def test_no_registered_guardrail_means_no_challenge(self):
await self._connect(self._server([self.GATEWAY_SCOPE]), None)
assert await self._connect(self._server([self.GATEWAY_SCOPE]), None) is None
def _make_obo_server(alias: str) -> MCPServer:

View file

@ -6508,7 +6508,6 @@ class TestMCPServerManager:
@pytest.mark.parametrize("add_prefix", [True, False])
async def test_openapi_listing_records_tool_metadata_for_pre_call_hooks(self, add_prefix):
from litellm.proxy._experimental.mcp_server.tool_registry import global_mcp_tool_registry
from litellm.types.mcp_server.tool_registry import MCPTool as RegistryTool
server = MCPServer(
server_id="petstore-id",
@ -6519,14 +6518,15 @@ class TestMCPServerManager:
spec_path="https://example.com/petstore.yaml",
)
schema = {"type": "object", "properties": {"petId": {"type": "integer"}}}
registered = RegistryTool(
name="petstore-get_pet", description="Fetch a pet", input_schema=schema, handler=lambda: None
)
manager = MCPServerManager()
manager._create_mcp_client = AsyncMock(return_value=AsyncMock())
with patch.dict(global_mcp_tool_registry.tools, {"petstore-get_pet": registered}, clear=True):
global_mcp_tool_registry.register_tool(
name="petstore-get_pet", description="Fetch a pet", input_schema=schema, handler=lambda: None
)
try:
listed = await manager._get_tools_from_server(server=server, add_prefix=add_prefix)
finally:
global_mcp_tool_registry.unregister_tools_with_prefix("petstore-")
assert [t.name for t in listed] == ["petstore-get_pet" if add_prefix else "get_pet"]
for spelling in ("get_pet", "petstore-get_pet"):

View file

@ -22,7 +22,10 @@ from litellm.proxy.guardrails.guardrail_hooks.agent_365 import (
guardrail_initializer_registry,
initialize_guardrail,
)
from litellm.proxy.guardrails.guardrail_hooks.agent_365.agent_365 import agent_365_authorization_servers
from litellm.proxy.guardrails.guardrail_hooks.agent_365.agent_365 import (
agent_365_authorization_servers,
agent_365_scopes_supported,
)
from litellm.types.guardrails import (
GuardrailEventHooks,
LitellmParams,
@ -654,6 +657,40 @@ class TestUnreachableFallback:
assert exc_info.value.status_code == 401
assert "invalid_grant" in exc_info.value.detail["message"]
@pytest.mark.asyncio
@pytest.mark.parametrize(
"error_code", ["invalid_client", "unauthorized_client", "invalid_scope", "invalid_resource"]
)
async def test_gateway_credential_rejection_is_unavailable_not_a_caller_401(self, error_code: str):
handler: Final = FakeHandler(
[_response(401, {"error": error_code, "error_description": "AADSTS7000215: invalid client secret"})]
)
guardrail: Final = _make_guardrail(handler)
data: Final = _mcp_data()
with pytest.raises(HTTPException) as exc_info:
await _run(guardrail, data)
assert exc_info.value.status_code == 503
assert exc_info.value.headers is None or "WWW-Authenticate" not in exc_info.value.headers
info: Final = _guardrail_info(data)
assert info["guardrail_status"] == "guardrail_failed_to_respond"
assert info["guardrail_response"]["verdict"] == "Unavailable"
assert error_code in info["guardrail_response"]["reason"]
assert "client_secret" in info["guardrail_response"]["reason"]
@pytest.mark.asyncio
async def test_gateway_credential_rejection_follows_fail_open(self):
handler: Final = FakeHandler(
[_response(401, {"error": "invalid_client", "error_description": "AADSTS7000215: invalid client secret"})]
)
guardrail: Final = _make_guardrail(handler, unreachable_fallback="fail_open")
data: Final = _mcp_data()
result: Final = await _run(guardrail, data)
assert result is data
info: Final = _guardrail_info(data)
assert info["guardrail_status"] == "guardrail_failed_to_respond"
assert info["guardrail_response"]["verdict"] == "Unscanned"
assert "invalid_client" in info["guardrail_response"]["reason"]
@pytest.mark.asyncio
async def test_obo_endpoint_5xx_fail_open(self):
handler: Final = FakeHandler([_response(503, text="entra down")])
@ -1190,9 +1227,17 @@ class TestAgent365AuthorizationServers:
_mcp_server(MCPAuth.api_key, scopes=[GATEWAY_SCOPE], auth_value="k"), None
) == (ENTRA_ISSUER,)
def test_silent_without_advertised_scopes(self, registered_guardrail):
assert agent_365_authorization_servers(_mcp_server(scopes=None), None) == ()
assert agent_365_authorization_servers(_mcp_server(scopes=[]), None) == ()
@pytest.mark.parametrize("scopes", [None, []], ids=["unset", "empty"])
def test_scopeless_server_signs_in_with_the_gateway_app_scope(self, registered_guardrail, scopes):
server: Final = _mcp_server(scopes=scopes)
assert agent_365_authorization_servers(server, None) == (ENTRA_ISSUER,)
assert agent_365_scopes_supported(server, None) == ("api://client-xyz/access_as_user",)
def test_admin_scopes_override_the_default_gateway_scope(self, registered_guardrail):
assert agent_365_scopes_supported(_mcp_server(scopes=[GATEWAY_SCOPE]), None) == (GATEWAY_SCOPE,)
def test_no_default_scope_when_no_guardrail_gates_the_server(self):
assert agent_365_scopes_supported(_mcp_server(scopes=None), None) == ()
def test_silent_when_no_guardrail_is_registered(self):
assert agent_365_authorization_servers(_mcp_server(scopes=[GATEWAY_SCOPE]), None) == ()
@ -1246,7 +1291,9 @@ class TestAgent365AuthorizationServers:
api_key="sk-guarded", user_id="u-2", metadata={"guardrails": ["agent-365-guard"]}
)
try:
with patch("litellm.proxy.proxy_server.premium_user", True):
with patch( # test-quality-ok: key-selected guardrails read the proxy server premium global, no injection seam
"litellm.proxy.proxy_server.premium_user", True
):
assert agent_365_authorization_servers(server, plain_key) == ()
assert agent_365_authorization_servers(server, guarded_key) == (ENTRA_ISSUER,)
assert agent_365_authorization_servers(server, None) == (ENTRA_ISSUER,)