fix(auth): gate MCP EdDSA legacy acceptance on FIPS mode — stored signing_alg and guardrail JWKS

Defect 1: _stored_client_assertion_signing_alg unconditionally coerced a stored
client_assertion_signing_alg=EdDSA to RS256, but the stored key is Ed25519 which
cannot sign RS256, so every token exchange for that server failed (CredError
misconfigured) with LITELLM_FIPS_MODE unset. Gate the coercion on is_fips_mode():
outside FIPS return the stored EdDSA unchanged with a deprecation warning
(read-side grace mirroring handle_jwt); inside FIPS keep the RS256 fallback +
rotate-key warning so the exchange fails loudly. Widen the two read-side type
surfaces (MCPServer.client_assertion_signing_alg, PrivateKeyJwtAuth.signing_alg)
to StoredJwtAlgorithm via LEGACY_JWT_ALGORITHMS; write-side New/Update request
validators stay approved-only and still 422 EdDSA.

Defect 2: the guardrail JWKS filter used the raw approved list
(jwks_keys_for(jwks_keys, APPROVED_JWT_ALGORITHMS)), dropping OKP/Ed25519 keys
so every guarded MCP call 401'd outside FIPS (mixed JWKS even misreported a kid
mismatch). Mirror handle_jwt: jwks_keys_for(jwks_keys,
allowed_jwt_algorithms(is_fips_mode())); EdDSA keys verify outside FIPS with the
standard once-per-process deprecation notice, and are still dropped inside FIPS.
This commit is contained in:
yucheng-berri 2026-10-14 17:42:21 -07:00
parent 1c05d98791
commit ff348d1be4
8 changed files with 216 additions and 36 deletions

View file

@ -201,6 +201,7 @@ from litellm.proxy._types import (
from litellm.proxy.agent_endpoints.auth.managed_authorization import managed_agent_policy
from litellm.proxy.auth.ip_address_utils import IPAddressUtils
from litellm.proxy.common_utils.encrypt_decrypt_utils import decrypt_value_helper
from litellm.proxy.common_utils.fips import is_fips_mode
from litellm.proxy.common_utils.user_api_key_cache import get_management_object_ttl
from litellm.proxy.management_endpoints.sso.id_jag_assertion_capture import (
id_jag_assertion_capture_gap_at_startup,
@ -228,7 +229,7 @@ from litellm.types.mcp_server.mcp_server_manager import (
from litellm.types.proxy.auth.jwt_algorithms import (
APPROVED_JWT_ALGORITHMS,
LEGACY_JWT_ALGORITHMS,
ApprovedJwtAlgorithm,
StoredJwtAlgorithm,
)
from litellm.types.utils import CallTypes
@ -439,7 +440,7 @@ class MCPServerConfig(TypedDict, total=False):
id_jag_resource: str
client_private_key: str
client_private_key_id: str
client_assertion_signing_alg: ApprovedJwtAlgorithm
client_assertion_signing_alg: StoredJwtAlgorithm
timeout: float
max_concurrent_requests: int
rpm: ReadOnly[int | None]
@ -1607,26 +1608,38 @@ def warn_on_shared_identifier_prefixes(servers: Iterable[MCPServer]) -> None:
)
def _stored_client_assertion_signing_alg(value: object, server_name: str) -> ApprovedJwtAlgorithm:
def _stored_client_assertion_signing_alg(value: object, server_name: str) -> StoredJwtAlgorithm:
if value in APPROVED_JWT_ALGORITHMS:
return value
if isinstance(value, str) and value in LEGACY_JWT_ALGORITHMS:
# The FIPS flag decides whether legacy crypto may run, mirroring the main JWT entrance
# (handle_jwt): outside FIPS the stored EdDSA keeps signing its Ed25519 key (a coerced
# RS256 cannot be produced by that key, so coercion bricks the server on upgrade);
# inside FIPS nothing non-approved may run, so the RS256 fallback stands and the
# exchange fails loudly until the key is rotated.
if not is_fips_mode():
verbose_logger.warning(
"MCP server %s: client_assertion_signing_alg %r is legacy and not FIPS 140-3 approved; "
"accepted outside FIPS mode, so the stored Ed25519 key keeps signing; rotate to an approved "
"RSA/EC key (see APPROVED_JWT_ALGORITHMS) — EdDSA support ends in the next major release",
server_name,
value,
)
return value
verbose_logger.warning(
"MCP server %s: client_assertion_signing_alg %r is legacy and not approved for signing; the "
"stored client_private_key cannot sign the RS256 fallback, so token exchange will fail until "
"the key is rotated to RSA or EC (see APPROVED_JWT_ALGORITHMS)",
server_name,
value,
)
return "RS256"
if value is not None:
if value in LEGACY_JWT_ALGORITHMS:
# An Ed25519 key cannot produce the RS256 fallback, so this server's token exchange
# fails until the stored key is rotated; do not imply the fallback "just works".
verbose_logger.warning(
"MCP server %s: client_assertion_signing_alg %r is legacy and not approved for signing; the "
"stored client_private_key cannot sign the RS256 fallback, so token exchange will fail until "
"the key is rotated to RSA or EC (see APPROVED_JWT_ALGORITHMS)",
server_name,
value,
)
else:
verbose_logger.warning(
"MCP server %s: client_assertion_signing_alg %r is not an approved algorithm, using RS256",
server_name,
value,
)
verbose_logger.warning(
"MCP server %s: client_assertion_signing_alg %r is not an approved algorithm, using RS256",
server_name,
value,
)
return "RS256"

View file

@ -46,7 +46,7 @@ from litellm.types.mcp import (
DEFAULT_SUBJECT_TOKEN_TYPE,
normalize_upstream_header_name,
)
from litellm.types.proxy.auth.jwt_algorithms import ApprovedJwtAlgorithm
from litellm.types.proxy.auth.jwt_algorithms import StoredJwtAlgorithm
class AuthResolution(str, Enum):
@ -328,7 +328,9 @@ class PrivateKeyJwtAuth(LiteLLMBaseModel):
source: Literal["private_key_jwt"] = "private_key_jwt"
private_key: SecretStr
key_id: str | None = None
signing_alg: ApprovedJwtAlgorithm = "RS256"
# Read-side surface: carries a stored legacy EdDSA value under FIPS-gated grace; the
# write-side request validators stay approved-only.
signing_alg: StoredJwtAlgorithm = "RS256"
class ClientSecretAuth(LiteLLMBaseModel):

View file

@ -74,6 +74,7 @@ import os
import re
import time
from collections.abc import Mapping, Sequence
from functools import lru_cache
from typing import TYPE_CHECKING, Any, Final, Optional
import httpx
@ -90,10 +91,10 @@ from litellm.integrations.custom_guardrail import (
log_guardrail_information,
)
from litellm.proxy._types import UserAPIKeyAuth
from litellm.proxy.auth.jwt_algorithms import jwks_keys_for
from litellm.proxy.auth.jwt_algorithms import allowed_jwt_algorithms, jwks_keys_for
from litellm.proxy.common_utils.fips import is_fips_mode
from litellm.types.guardrail_base_init import GuardrailBaseInitKwargs
from litellm.types.guardrails import GuardrailEventHooks
from litellm.types.proxy.auth.jwt_algorithms import APPROVED_JWT_ALGORITHMS
from litellm.types.utils import CallTypesLiteral
if TYPE_CHECKING:
@ -134,6 +135,17 @@ _jwks_cache: Final[dict[str, tuple[Sequence[Mapping[str, object]], float]]] = {}
_JWKS_CACHE_TTL: Final = 3600 # 1 hour
@lru_cache(maxsize=1)
def _log_eddsa_deprecation() -> None:
"""The branch-standard once-per-process EdDSA deprecation notice (handle_jwt emits the
same text at its entrance); this guardrail accepts EdDSA keys only outside FIPS mode."""
verbose_proxy_logger.warning(
"JWT Auth: accepted a token signed with EdDSA, which is deprecated and not FIPS 140-3 approved; "
"it is rejected when LITELLM_FIPS_MODE=true. Move the IdP signing key to RS256, PS256 or ES256; "
"EdDSA support will be removed in the next major release"
)
def get_mcp_jwt_signer() -> Optional["MCPJWTSigner"]:
"""Return the active MCPJWTSigner singleton, or None if not initialized."""
return _mcp_jwt_signer_instance
@ -454,7 +466,10 @@ class MCPJWTSigner(CustomGuardrail):
unverified_header: Final = jwt.get_unverified_header(raw_token)
kid: Final = unverified_header.get("kid")
approved_keys: Final = jwks_keys_for(jwks_keys, APPROVED_JWT_ALGORITHMS)
# Mirror the main JWT entrance (handle_jwt): outside FIPS mode the legacy EdDSA keys
# stay usable so an OKP/Ed25519 IdP keeps verifying; inside FIPS only approved
# algorithms pass and the clear error below fires.
approved_keys: Final = jwks_keys_for(jwks_keys, allowed_jwt_algorithms(is_fips_mode()))
if not approved_keys:
raise jwt.exceptions.PyJWKSetError(f"No JWKS key at {jwks_uri!r} uses an approved signing algorithm")
@ -480,6 +495,10 @@ class MCPJWTSigner(CustomGuardrail):
# PyJWT populates algorithm_name from the key's `alg` field; when absent
# it infers from the key type (RSAPublicKey → RS256).
alg: Final = getattr(signing_jwk, "algorithm_name", None) or "RS256"
if alg == "EdDSA":
# Only reachable outside FIPS mode (inside it the filter above drops EdDSA keys);
# same once-per-process deprecation notice the main JWT entrance emits.
_log_eddsa_deprecation()
decode_options: Final[Options] = {"verify_exp": True}
decode_kwargs: Final[_JWTDecodeKwargs] = {

View file

@ -16,7 +16,7 @@ from litellm.types.mcp import (
normalize_upstream_header_name,
validate_mcp_protocol_transport,
)
from litellm.types.proxy.auth.jwt_algorithms import ApprovedJwtAlgorithm
from litellm.types.proxy.auth.jwt_algorithms import StoredJwtAlgorithm
# MCPInfo now allows arbitrary additional fields for custom metadata
@ -182,7 +182,10 @@ class MCPServer(LiteLLMBaseModel):
id_jag_resource: str | None = None
client_private_key: str | None = None
client_private_key_id: str | None = None
client_assertion_signing_alg: ApprovedJwtAlgorithm = "RS256"
# Read-side surface: a stored legacy EdDSA value flows through (FIPS-gated grace in
# mcp_server_manager._stored_client_assertion_signing_alg); write-side requests stay
# approved-only and 422 it.
client_assertion_signing_alg: StoredJwtAlgorithm = "RS256"
# Wire dialect: "rfc8693" (standard token-exchange grant) or "entra_obo" (Microsoft Entra
# On-Behalf-Of, the RFC 7523 jwt-bearer grant + requested_token_use extension)
token_exchange_profile: str = "rfc8693"

View file

@ -16,4 +16,10 @@ APPROVED_JWT_ALGORITHMS: Final[tuple[ApprovedJwtAlgorithm, ...]] = (
"ES512",
)
LEGACY_JWT_ALGORITHMS: Final = ("EdDSA",)
LegacyJwtAlgorithm: TypeAlias = Literal["EdDSA"]
LEGACY_JWT_ALGORITHMS: Final[tuple[LegacyJwtAlgorithm, ...]] = ("EdDSA",)
StoredJwtAlgorithm: TypeAlias = ApprovedJwtAlgorithm | LegacyJwtAlgorithm
"""A value read back from stored/declared config: approved, or legacy EdDSA carried under
read-side grace outside FIPS mode (write-side validation stays approved-only)."""

View file

@ -16,7 +16,7 @@ import jwt
import litellm
import pytest
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec, rsa
from cryptography.hazmat.primitives.asymmetric import ec, ed25519, rsa
from litellm.proxy._experimental.mcp_server.outbound_credentials.result import (
Error,
@ -67,6 +67,20 @@ _PUBLIC_PEM = (
)
.decode()
)
_ED25519_KEY = ed25519.Ed25519PrivateKey.generate()
_ED25519_PRIVATE_PEM = _ED25519_KEY.private_bytes(
serialization.Encoding.PEM,
serialization.PrivateFormat.PKCS8,
serialization.NoEncryption(),
).decode()
_ED25519_PUBLIC_PEM = (
_ED25519_KEY.public_key()
.public_bytes(
serialization.Encoding.PEM,
serialization.PublicFormat.SubjectPublicKeyInfo,
)
.decode()
)
def _resp(token="access", expires_in=3600):
@ -139,6 +153,38 @@ async def test_fetch_private_key_jwt_client_assertion():
assert jwt.get_unverified_header(data["client_assertion"])["kid"] == "kid-1"
@pytest.mark.asyncio
async def test_fetch_signs_eddsa_client_assertion_for_ed25519_key():
"""The widened read-side signing_alg admits legacy EdDSA so a stored Ed25519 key keeps
working outside FIPS mode; the minted assertion is a real EdDSA token signed by that key."""
client = _client(_resp())
with patch(_PATCH_TARGET, return_value=client):
await TokenEndpointClient().fetch(
_ENDPOINT,
_CLIENT_ID,
{"grant_type": "g"},
PrivateKeyJwtAuth(
private_key=SecretStr(_ED25519_PRIVATE_PEM),
key_id="ed-kid",
signing_alg="EdDSA",
),
)
data = _posted_data(client)
assert data["client_assertion_type"] == CLIENT_ASSERTION_TYPE
header = jwt.get_unverified_header(data["client_assertion"])
assert header["alg"] == "EdDSA"
assert header["kid"] == "ed-kid"
decoded = jwt.decode(
data["client_assertion"],
_ED25519_PUBLIC_PEM,
algorithms=["EdDSA"],
audience=_ENDPOINT,
)
assert decoded["iss"] == _CLIENT_ID
assert decoded["sub"] == _CLIENT_ID
@pytest.mark.asyncio
async def test_fetch_http_error_maps_to_upstream_unavailable_with_status():
error_resp = MagicMock()
@ -195,8 +241,9 @@ async def test_fetch_network_error_maps_to_upstream_unavailable(raised):
[
PrivateKeyJwtAuth(private_key=SecretStr("not-a-pem-key"), signing_alg="RS256"),
PrivateKeyJwtAuth(private_key=SecretStr(_EC_PRIVATE_PEM), signing_alg="RS256"),
PrivateKeyJwtAuth(private_key=SecretStr(_ED25519_PRIVATE_PEM), signing_alg="RS256"),
],
ids=["garbage-key", "key-alg-mismatch"],
ids=["garbage-key", "key-alg-mismatch", "ed25519-key-rs256-alg"],
)
async def test_fetch_unsignable_client_assertion_is_misconfigured_not_a_crash(auth):
client = AsyncMock()

View file

@ -17829,9 +17829,11 @@ def test_stored_client_assertion_signing_alg_falls_back_to_rs256_for_non_approve
assert "client_assertion_signing_alg" in caplog.text and "HS256" in caplog.text and "srv" in caplog.text
def test_stored_client_assertion_signing_alg_warns_eddsa_key_cannot_sign_fallback(caplog):
"""A stored EdDSA server kept booting pre-allowlist; the fallback warning must say its
Ed25519 key cannot produce the RS256 fallback, so exchanges fail until the key is rotated."""
def test_stored_client_assertion_signing_alg_warns_eddsa_key_cannot_sign_fallback(monkeypatch, caplog):
"""FIPS on: a stored EdDSA server keeps today's behavior — coerced to the RS256 fallback with
the rotate-your-key warning, since its Ed25519 key cannot produce RS256, so the exchange fails
loudly instead of silently running a non-approved algorithm."""
monkeypatch.setenv("LITELLM_FIPS_MODE", "true")
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
_stored_client_assertion_signing_alg,
)
@ -17843,6 +17845,22 @@ def test_stored_client_assertion_signing_alg_warns_eddsa_key_cannot_sign_fallbac
assert "rotated" in caplog.text
def test_stored_client_assertion_signing_alg_keeps_eddsa_outside_fips_mode(monkeypatch, caplog):
"""FIPS off: a stored EdDSA value passes through verbatim (read-side grace, mirroring
handle_jwt's legacy-accepted-with-deprecation rule), so the server's Ed25519 key keeps
signing instead of bricking on upgrade against an unsignable RS256 fallback."""
monkeypatch.delenv("LITELLM_FIPS_MODE", raising=False)
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
_stored_client_assertion_signing_alg,
)
with caplog.at_level(logging.WARNING, logger="LiteLLM"):
assert _stored_client_assertion_signing_alg("EdDSA", "srv") == "EdDSA"
assert "EdDSA" in caplog.text and "srv" in caplog.text
assert "legacy" in caplog.text.lower()
assert "rotate" in caplog.text.lower()
def test_stored_client_assertion_signing_alg_passes_through_approved(caplog):
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
_stored_client_assertion_signing_alg,
@ -17855,6 +17873,9 @@ def test_stored_client_assertion_signing_alg_passes_through_approved(caplog):
def test_mcp_server_model_rejects_non_approved_client_assertion_signing_alg():
"""The runtime (read-side) model still refuses non-legacy garbage; the legacy EdDSA value is
admitted read-side (widened via LEGACY_JWT_ALGORITHMS) while the write-side request
validators in litellm.proxy._types stay strict and 422 it (see test__types.py)."""
from pydantic import ValidationError
with pytest.raises(ValidationError) as exc:
@ -17862,10 +17883,18 @@ def test_mcp_server_model_rejects_non_approved_client_assertion_signing_alg():
server_id="srv",
name="srv",
transport="http",
client_assertion_signing_alg="EdDSA",
client_assertion_signing_alg="HS256",
)
assert "client_assertion_signing_alg" in str(exc.value)
server = MCPServer(
server_id="srv",
name="srv",
transport="http",
client_assertion_signing_alg="EdDSA",
)
assert server.client_assertion_signing_alg == "EdDSA"
@pytest.mark.asyncio
@pytest.mark.parametrize(

View file

@ -1334,10 +1334,22 @@ def _oct_idp_key_and_token(now: int):
@pytest.mark.asyncio
@pytest.mark.parametrize(
"key_and_token", (_oct_idp_key_and_token, _okp_idp_key_and_token), ids=("oct-HS256", "OKP-EdDSA")
"key_and_token,fips",
[
(_oct_idp_key_and_token, None),
(_okp_idp_key_and_token, "true"),
],
ids=("oct-HS256", "OKP-EdDSA-fips-on"),
)
async def test_verify_incoming_jwt_rejects_jwks_without_approved_algorithms(key_and_token):
"""A JWKS whose only keys use non-approved algorithms can never verify the incoming token."""
async def test_verify_incoming_jwt_rejects_jwks_without_approved_algorithms(monkeypatch, key_and_token, fips):
"""A JWKS whose only keys use non-approved algorithms can never verify the incoming token.
HS256 is never allowed; EdDSA is legacy — refused under FIPS mode, accepted (with a
deprecation warning) outside it, mirroring the main JWT entrance in handle_jwt."""
if fips is None:
monkeypatch.delenv("LITELLM_FIPS_MODE", raising=False)
else:
monkeypatch.setenv("LITELLM_FIPS_MODE", fips)
jwks_key, incoming_token = key_and_token(int(time.time()))
signer = _make_signer(
access_token_discovery_uri="https://idp.example.com/.well-known/openid-configuration",
@ -1357,6 +1369,55 @@ async def test_verify_incoming_jwt_rejects_jwks_without_approved_algorithms(key_
await signer._verify_incoming_jwt(incoming_token)
@pytest.mark.asyncio
async def test_verify_incoming_jwt_accepts_okp_eddsa_outside_fips_mode(monkeypatch):
"""Flag-off legacy grace, mirroring handle_jwt: an IdP whose JWKS only carries OKP/Ed25519
keys still verifies its tokens; the approved-only filter must not 401 it outside FIPS."""
monkeypatch.delenv("LITELLM_FIPS_MODE", raising=False)
jwks_key, incoming_token = _okp_idp_key_and_token(int(time.time()))
signer = _make_signer(
access_token_discovery_uri="https://idp.example.com/.well-known/openid-configuration",
)
with patch.object(
signer,
"_get_oidc_discovery",
new_callable=AsyncMock,
return_value={"jwks_uri": "https://idp.example.com/jwks"},
):
with patch(
"litellm.proxy.guardrails.guardrail_hooks.mcp_jwt_signer.mcp_jwt_signer._fetch_jwks",
new_callable=AsyncMock,
return_value=[jwks_key],
):
payload = await signer._verify_incoming_jwt(incoming_token)
assert payload["sub"] == "idp-user"
@pytest.mark.asyncio
async def test_verify_incoming_jwt_matches_okp_kid_in_mixed_jwks_outside_fips_mode(monkeypatch):
"""A mixed JWKS (approved RSA keys plus one OKP/Ed25519 key) resolves the OKP kid outside
FIPS mode instead of dropping the key and dying on a misleading kid-mismatch error."""
monkeypatch.delenv("LITELLM_FIPS_MODE", raising=False)
okp_jwk, incoming_token = _okp_idp_key_and_token(int(time.time()))
signer = _make_signer(
access_token_discovery_uri="https://idp.example.com/.well-known/openid-configuration",
)
jwks = [*signer.get_jwks()["keys"], okp_jwk]
with patch.object(
signer,
"_get_oidc_discovery",
new_callable=AsyncMock,
return_value={"jwks_uri": "https://idp.example.com/jwks"},
):
with patch(
"litellm.proxy.guardrails.guardrail_hooks.mcp_jwt_signer.mcp_jwt_signer._fetch_jwks",
new_callable=AsyncMock,
return_value=jwks,
):
payload = await signer._verify_incoming_jwt(incoming_token)
assert payload["sub"] == "idp-user"
@pytest.mark.asyncio
async def test_verify_incoming_jwt_ignores_filtered_keys_sharing_kid():
"""An approved RS256 key still verifies when the JWKS also carries a non-approved key with the same kid."""