게이트웨이 인증 레퍼런스

게이트웨이 인증 레퍼런스 (Gateway Auth Reference)

LiteLLM은 대부분의 인증·권한 부여 프리미티브를 공유하지만 몇몇 중요한 곳에서 갈라지는 두 개의 게이트웨이 표면을 노출해요. 이 페이지는 나란히 비교한 레퍼런스입니다: 어떤 헤더가 어떤 일을 하는지, 두 표면이 어디서 대칭이고 어디서 아닌지. 각 섹션은 전체 상세를 담은 전용 페이지로 연결됩니다.

표면 엔드포인트 전용 문서
MCP Gateway /mcp, /{server}/mcp, /toolset/{name}/mcp, /sse, /v1/mcp/..., /mcp-rest/... MCP Overview
A2A Agent Gateway /a2a/{agent_id}, /a2a/{agent_id}/message/send, /v1/agents/... A2A Overview

1. 클라이언트 → LiteLLM (호출자 인증)

두 표면 모두 같은 LiteLLM Virtual Key 헤더와 같은 식별 헤더를 받아요. 갈라지는 한 곳: MCP ASGI 라우트(/mcp, /{name}/mcp, /toolset/{name}/mcp, /sse의 스트리머블 MCP 엔드포인트)는 표준 FastAPI 인증 의존성을 우회하고, 벤더별 인증 별칭(API-Key, x-api-key, x-goog-api-key, Ocp-Apim-Subscription-Key)이나 x-litellm-tags를 파싱하지 않아요. MCP REST/관리 라우트(/v1/mcp/..., /mcp-rest/...)와 모든 A2A 라우트는 전체 헤더 세트를 받습니다.

헤더 용도 MCP ASGI MCP REST + A2A
x-litellm-api-key: *** sk-... 선호되는 LiteLLM Virtual Key 헤더. 인바운드 Authorization 헤더가 다른 토큰(OAuth passthrough, OBO, A2A 사용자별 전달)을 담을 수 있을 때 사용 ✓ ✓
Authorization: Bearer *** 표준 폴백. 조회 전에 Bearer 접두사 제거 ✓ ✓
API-Key, x-api-key, x-goog-api-key, Ocp-Apim-Subscription-Key 벤더별 별칭 (Azure, Anthropic, Google AI Studio, Azure APIM) — ✓
x-litellm-end-user-id 최종 사용자 식별. 키 위에 사용자별 예산, MCP 접근 교차, 감사 로그 항목을 얹음. x-litellm-customer-id 는 수용되는 별칭 ✓ ✓
x-litellm-trace-id 요청 간 상관관계 ID. x-litellm-session-id 또는 일치하는 x-<vendor>-session-id 헤더로 폴백 ✓ ✓
x-litellm-session-id 세션 그룹핑. trace-id와 같은 파싱 경로, 낮은 우선순위 ✓ ✓
x-litellm-tags 지출 로그 라벨링과 태그 기반 라우팅을 위한 쉼표 구분 태그. body 필드 tags 가 우선 — (MCP ASGI에서 파싱 안 됨) ✓
x-litellm-mcp-debug: true 마스킹된 진단 응답 헤더(x-mcp-debug-*) 반환. MCP OAuth — Debugging 참고 ✓ —
x-mcp-servers 요청을 특정 MCP 서버로 한정 (쉼표 구분) ✓ —

2. LiteLLM → 백엔드 (에이전트 또는 MCP 서버에 게이트웨이 인증)

여기가 MCP와 A2A가 가장 많이 갈라지는 섹션이에요. MCP는 각 서버 등록에 일급 auth_type 필드가 있습니다. A2A에는 auth_type 필드가 전혀 없으며, 아웃바운드 인증 모드는 litellm_params에 무엇이 있는지로 추론됩니다.

MCP: auth_type enum

아홉 가지 값. MCP 서버의 아웃바운드 Authorization 헤더(또는 요청별 SigV4 서명)는 auth_type 으로 결정됩니다. 전체 표는 MCP Overview: Add HTTP MCP Server 참고.

auth_type 메커니즘 전용 문서
none 인증 헤더 추가 없음 —
api_key / bearer_token / basic / authorization / token 정적 헤더, 호출마다 그대로 전송 MCP Overview
oauth2 PKCE(대화형) 또는 M2M client_credentials. oauth2_flow 로 구분 MCP OAuth
oauth2_token_exchange RFC 8693 On-Behalf-Of (OBO) — 호출자의 bearer 토큰을 범위 있는 MCP 토큰으로 교환 MCP OBO Auth
oauth2_id_jag Identity Assertion Authorization Grant: 사용자 신원 토큰(인바운드 또는 SSO 로그인에서 캡처)의 two-leg 교환으로 MCP 액세스 토큰 MCP ID-JAG Auth
aws_sigv4 전용 MCP 측 자격 증명 체인을 사용한 요청별 SigV4 서명 MCP AWS SigV4

A2A: litellm_params에서 추론된 인증 모드

에이전트에는 auth_type 필드가 없어요. 프로바이더 핸들러가 litellm_params 의 내용에서 인증 메커니즘을 고릅니다:

모드 언제 발동 백엔드로 전송
Bearer / JWT litellm_params.api_key 설정됨 Authorization: Bearer ***
SigV4 (AgentCore 전용) litellm_params.api_key 설정 안 됨 전체 AWS 자격 증명 체인을 통한 요청별 SigV4. Bedrock AgentCore — A2A Gateway Authentication 참고
프로바이더 네이티브 litellm_params.custom_llm_provider가 비-Bedrock 프로바이더(Vertex AI Agent Engine, LangGraph, Azure AI Foundry, Pydantic AI)와 일치 프로바이더의 일반 인증 경로

JWT vs SigV4 이중 모드는 AgentCore 전용이에요. 다른 A2A 프로바이더(Vertex, LangGraph, Azure Foundry)는 프로바이더 자체 자격 증명 규칙을 사용합니다. Providers 아래의 해당 프로바이더 페이지 참고.

제로 트러스트 추가 기능 (MCP 전용)

MCP 서버가 요청이 LiteLLM을 통해 왔다는 것을 암호학적으로 검증해야 한다면, MCP JWT Signer 가드레일을 그 위에 얹으세요. 모든 아웃바운드 도구 호출에 단기 RS256 JWT로 서명하고 MCP 서버가 검증할 수 있는 JWKS 엔드포인트를 게시합니다. 이것은 auth_type 이 아니라 가드레일(guardrail: mcp_jwt_signer, mode: pre_mcp_call)이며 어떤 auth_type 과도 결합됩니다.

3. 사용자별 헤더 패스스루

두 표면 모두 관리자 사전 설정 없이 클라이언트가 특정 백엔드 서버/에이전트로 향하는 자격 증명을 전달하게 해줘요. 관례는 대칭으로 보이지만 파싱이 다르므로, 복사-붙여넣기할 때 정확해야 합니다.

표면 접두사 파싱 규칙 매칭 대상 예시
MCP x-mcp- 형식: x-mcp-{server_alias}-{header_name} 서버의 alias, 그다음 server_name (대소문자 무시) x-mcp-github-authorization: Bearer *** → 서버 github, 헤더 Authorization
A2A x-a2a- 형식: x-a2a-{agent_name_or_id}-{header_name} 에이전트의 UUID와 사람이 읽을 수 있는 이름 (둘 다 시도) x-a2a-my-agent-x-api-key: *** → 에이전트 my-agent, 헤더 x-api-key

두 표면 모두 사용자 패스스루와 결합되는 관리자 제어 대안도 지원합니다:

메커니즘 MCP A2A 비고
static_headers: {K: V} ✓ ✓ 항상 전송. 키 충돌 시 사용자 패스스루를 이김
extra_headers: [name, ...] ✓ ✓ 전달할 클라이언트 헤더 이름의 관리자 allowlist
x-<surface>-<id>-<header> 관례 ✓ (x-mcp-) ✓ (x-a2a-) 클라이언트 주도, 관리자 config 불필요

전체 메커니즘은 MCP Overview: Forwarding Custom Headers와 A2A Agent Authentication Headers 참고.

4. 권한 부여: RBAC *** 접근 그룹

두 표면 모두 object_permission 모델을 교차(intersection) 방식 해석으로 사용하지만, 오늘날 깊이가 달라요. MCP는 여섯 수준으로 해석하고 A2A는 두 수준으로 해석합니다. 상세 플로차트와 표는 전용 페이지에 있습니다:

수준 MCP 필드 A2A 필드
Key object_permission.mcp_servers, object_permission.mcp_access_groups, object_permission.mcp_tool_permissions object_permission.agents, object_permission.agent_access_groups
Team 동일 동일 (상속 우선: 키에 목록이 없으면 팀의 것을 상속)
End user 동일 (x-litellm-end-user-id 경유) — (오늘날 해석 안 됨)
Agent 동일 (x-litellm-agent-id 경유) — (적용 불가: 에이전트가 대상)
Internal user 동일 (요청을 인증한 사람); 실행 결과와 교차되어 좁힐 수만 있음 — (오늘날 해석 안 됨)
Org 동일 — 상한(ceiling)으로 작용 — (오늘날 해석 안 됨)
관심사 MCP A2A
서버/에이전트별 allowlist object_permission.mcp_servers object_permission.agents
접근 그룹 (태그 기반 부여) object_permission.mcp_access_groups object_permission.agent_access_groups
서버별 도구 수준 allowlist object_permission.mcp_tool_permissions: {server_id: [tool, ...]} n/a (도구는 에이전트 안에 있음)
서버 등록 allowlist (관리자 정적) MCP 서버의 allowed_tools / disallowed_tools n/a
파라미터 수준 allowlist MCP 서버의 allowed_params: {tool_name: [param, ...]} n/a
거부 동작 list_tools 는 숨긴 서버를 걸러내고, call_tool은 오류 반환 GET /v1/agents 필터링; POST /a2a/{agent_id} 가 HTTP 403 반환

5. 트레이스 ID와 신원 전파

x-litellm-trace-id 는 모든 요청에서 수용되고 두 표면 모두에서 로깅을 통해 이어집니다. 몇 가지 A2A 전용 추가 사항:

설정 범위 동작
require_trace_id_on_calls_to_agent: true 에이전트별, 에이전트의 litellm_params x-litellm-trace-id(또는 x-litellm-session-id 폴백)이 없는 인바운드 /a2a/{agent_id} 호출을 HTTP 400으로 거부. A2A Overview — Trace ID enforcement 참고
require_trace_id_on_calls_by_agent: true 에이전트별, 에이전트의 litellm_params 반대 방향 — 그 에이전트가 소유한 키가 아웃바운드 호출을 할 때 trace ID를 요구

하위 에이전트 신원 전파. LiteLLM이 A2A 호출의 일부로 다운스트림 호출을 파견할 때, 추적 연속성과 지출 귀속을 위해 X-LiteLLM-Trace-Id 와 X-LiteLLM-Agent-Id 를 전달합니다. 원래 가상 키와 최종 사용자 신원은 자동 전달되지 않아요. 신원을 명시적으로 이어가려면 extra_headers 또는 x-a2a-{agent_name_or_id}-{header} 관례를 사용하세요. A2A Overview: Sub-agent identity propagation 참고.

6. 게이트웨이 경로의 가드레일

관심사 MCP A2A
사전 호출 입력 가드레일 (Presidio, Bedrock, Lakera, Aporia 등) mode: pre_mcp_call 표준 채팅 컴플리션 가드레일이 에이전트가 만드는 기반 LLM 호출에 적용
호출 중 개입 mode: during_mcp_call —
제로 트러스트 JWT 서명 mcp_jwt_signer 가드레일 — (오늘날 A2A에 적용 안 됨)
문서 MCP Guardrails, MCP Zero Trust 표준 가드레일 문서가 에이전트의 기반 모델 호출을 통해 적용

7. 치트시트: 어떤 헤더가 무슨 역할을 하나

복사-붙여넣기를 위한 두 표면에 걸친 고빈도 요청 헤더:

# Always (LiteLLM-side auth and identification)
x-litellm-api-key: *** sk-...
# or
Authorization: Bearer ***

x-litellm-end-user-id: user-42
x-litellm-trace-id: 8f4a-2b1c-d3e5-...

# MCP — server scoping / per-user passthrough
x-mcp-servers: github,zapier
x-mcp-github-authorization: Bearer ***     # user passthrough to github_mcp
x-litellm-mcp-debug: true                                # diagnostic response headers

# A2A — per-user passthrough
x-a2a-my-agent-authorization: Bearer ***        # caller's token to my-agent
x-a2a-my-agent-x-api-key: ***                     # additional per-agent header

심층 분석은 위의 교차 링크를 따라 전용 페이지로 이동하세요.

출처: 문서

더 알아보기 (Learn more)