閘道驗證參考
LiteLLM 提供兩個閘道介面，兩者共用大多數驗證與授權原語，但在幾個重要地方有所不同。本頁為並排參考：各個標頭的作用、兩個介面相同之處，以及不同之處。每個章節都會連結至專屬頁面以提供完整細節。
| 介面 | 端點 | 專屬文件 |
|---|---|---|
| MCP Gateway | /mcp, /{server}/mcp, /toolset/{name}/mcp, /sse, /v1/mcp/..., /mcp-rest/... | MCP 總覽 |
| A2A Agent Gateway | /a2a/{agent_id}, /a2a/{agent_id}/message/send, /v1/agents/... | A2A 總覽 |
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: Bearer sk-... | 建議使用的 LiteLLM Virtual Key 標頭。當傳入的 Authorization 標頭可能帶有不同的 token（OAuth passthrough、OBO、A2A per-user forwarding）時，請一律使用。 | ✓ | ✓ |
Authorization: Bearer sk-... | 標準備援。查找前會先去除 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 | 端使用者識別。在 key 之上疊加每位端使用者的預算、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 | 以逗號分隔的標籤，用於 spend-log 標記與以標籤為基礎的路由。要求主體欄位 tags 具有優先權。 | —（MCP ASGI 上不會解析） | ✓ |
x-litellm-mcp-debug: true | 回傳遮罩後的診斷回應標頭（x-mcp-debug-*）。請參閱 MCP OAuth — 偵錯。 | ✓ | — |
x-mcp-servers | 將請求範圍限定到特定 MCP 伺服器（以逗號分隔）。 | ✓ | — |
2. LiteLLM → 後端（驗證閘道對代理程式或 MCP 伺服器的身份）
這是 MCP 與 A2A 差異最大的區域。MCP 在每個伺服器註冊上都有第一類的 auth_type 欄位。A2A 完全沒有 auth_type 欄位；傳出驗證模式是根據 litellm_params 中的內容推斷。
MCP：auth_type 列舉
MCP 伺服器的傳出 Authorization 標頭（或每個請求的 SigV4 簽章）由 auth_type 決定。完整表格請參閱 MCP 總覽：新增 HTTP MCP 伺服器。
auth_type | 機制 | 專屬文件 |
|---|---|---|
none | 不加入驗證標頭 | — |
api_key / bearer_token / basic / authorization / token | 靜態標頭，每次呼叫都會原樣傳送 | MCP 總覽 |
oauth2 | PKCE（互動式）或 M2M client_credentials。由 oauth2_flow 區分。 | MCP OAuth |
oauth2_token_exchange | RFC 8693 On-Behalf-Of（OBO）— 將呼叫者的 bearer token 交換為具範圍限制的 MCP token | MCP OBO 驗證 |
oauth2_id_jag | 身分斷言授權授權類型：將使用者的身分 token（傳入或在 SSO 登入時擷取）進行雙段交換，以取得 MCP access token | MCP ID-JAG 驗證 |
true_passthrough | 不經 LiteLLM 受理。用戶端自己的 Authorization 會原樣轉送至上游 | MCP OAuth Passthrough |
oauth_delegate | LiteLLM 先以 x-litellm-api-key 接受呼叫者，然後轉送用戶端在 Authorization 中送出的另一個上游 bearer。受理 key 絕不會被轉送 | MCP OAuth Passthrough |
aws_sigv4 | 使用專用的 MCP 端憑證鏈，對每個請求進行 SigV4 簽章 | MCP AWS SigV4 |
A2A：從 litellm_params 推斷的驗證模式
代理程式上沒有 auth_type 欄位。提供者處理常式會從 litellm_params 的內容中挑選驗證機制：
| 模式 | 觸發時機 | 傳送至後端 |
|---|---|---|
| Bearer / JWT | 已設定 litellm_params.api_key | Authorization: Bearer <api_key> |
| 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 與 SigV4 的雙模式是 AgentCore 專屬。其他 A2A 提供者（Vertex、LangGraph、Azure Foundry）使用提供者自身的憑證慣例。請參閱 Providers 下相關的提供者頁面。
零信任附加元件（僅限 MCP）
如果 MCP 伺服器需要以密碼學方式驗證請求確實經由 LiteLLM，請在上層套用 MCP JWT Signer 防護欄。它會使用短效 RS256 JWT 為每個傳出的工具呼叫簽章，並公開 MCP 伺服器可驗證的 JWKS 端點。這是防護欄（guardrail: mcp_jwt_signer, mode: pre_mcp_call），而不是 auth_type，且可與任何 auth_type 組合使用。
3. 每位使用者的標頭透傳
兩個介面都允許用戶端轉送要送往特定後端伺服器/代理程式的憑證，而不需要管理員預先設定。其慣例看起來對稱，但解析方式不同，因此複製貼上時請務必精確。
| 介面 | 前綴 | 解析規則 | 比對對象 | 範例 |
|---|---|---|---|---|
| MCP | x-mcp- | 格式：x-mcp-{server_alias}-{header_name} | 先比對伺服器的 alias，再比對 server_name（不區分大小寫） | x-mcp-github-authorization: Bearer ghp_... → 伺服器 github，標頭 Authorization |
| A2A | x-a2a- | 格式：x-a2a-{agent_name_or_id}-{header_name}；與代理程式的 UUID 與可讀名稱比對（兩者都會嘗試） | 代理程式的 UUID 以及 可讀名稱（兩者都會嘗試） | x-a2a-my-agent-x-api-key: secret → 代理程式 my-agent，標頭 x-api-key |
兩個介面也都支援與使用者 passthrough 可組合的管理員控制替代方案：
| 機制 | MCP | A2A | 備註 |
|---|---|---|---|
static_headers: {K: V} | ✓ | ✓ | 一律傳送。若 key 衝突，優先於使用者 passthrough。 |
extra_headers: [name, name, ...] | ✓ | ✓ | 管理員允許清單中可原樣轉送的用戶端標頭名稱。 |
x-<surface>-<id>-<header> 慣例 | ✓ (x-mcp-) | ✓ (x-a2a-) | 由用戶端驅動，不需要管理員設定。 |
完整機制請參閱 MCP 總覽：轉送自訂標頭 與 A2A Agent Authentication Headers。
4. 授權：RBAC 與存取群組
兩個介面都使用 object_permission 模型與交集式解析，但目前深度不同。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 | 相同 | 相同（優先繼承：如果 key 沒有清單，則繼承 team 的） |
| End user | 相同（透過 x-litellm-end-user-id） | — 今日尚未解析 |
| Agent | 相同（透過 x-litellm-agent-id） | — 不適用（agent 本身就是目標） |
| Internal user | 相同（請求經驗證為其的那位人類）；與執行中的結果取交集，因此只能縮小範圍 | — 今日尚未解析 |
| Org | 相同 — 作為上限 | — 今日尚未解析 |
| 關注項目 | MCP | A2A |
|---|---|---|
| 每個 server / 每個 agent 的允許清單 | object_permission.mcp_servers | object_permission.agents |
| 存取群組（以標籤為基礎的授權） | object_permission.mcp_access_groups | object_permission.agent_access_groups |
| 每個 server 的工具層級允許清單 | object_permission.mcp_tool_permissions: {server_id: [tool, ...]} | n/a（工具位於 agent 內） |
| server 註冊允許清單（admin-static） | MCP server 上的 allowed_tools / disallowed_tools | n/a |
| 參數層級允許清單 | MCP server 上的 allowed_params: {tool_name: [param, ...]} | n/a |
| 拒絕行為 | list_tools 會過濾掉隱藏的 server；call_tool 會回傳錯誤 | GET /v1/agents 會過濾；POST /a2a/{agent_id} 會回傳 HTTP 403 |
5. Trace ID 與身分傳遞
x-litellm-trace-id 會在每次請求中接受，並在兩個介面上隨記錄傳遞。A2A 還有幾個特定額外項目：
| 設定 | 範圍 | 行為 |
|---|---|---|
require_trace_id_on_calls_to_agent: true | 每個 agent，位於 agent 的 litellm_params 上 | 拒絕缺少 x-litellm-trace-id（或 x-litellm-session-id fallback）的進站 /a2a/{agent_id} 呼叫，並回傳 HTTP 400。請參閱 A2A Overview — Trace ID enforcement。 |
require_trace_id_on_calls_by_agent: true | 每個 agent，位於 agent 的 litellm_params 上 | 反向方向 — 當由該 agent 擁有的 key 發出出站呼叫時，要求該些呼叫帶有 trace ID。 |
子 agent 身分傳遞。 當 LiteLLM 在 A2A 呼叫的一部分中向下游發出請求時，會轉送 X-LiteLLM-Trace-Id 和 X-LiteLLM-Agent-Id，以維持追蹤連續性與支出歸屬。原始虛擬 key 與 end-user 身分不會自動轉送。請使用 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 | 標準聊天完成防護欄會套用到 agent 所發出的底層 LLM 呼叫 |
| 請求中介入 | mode: during_mcp_call | — |
| 零信任 JWT 簽章 | mcp_jwt_signer 防護欄 | —（目前不適用於 A2A） |
| 文件 | MCP Guardrails、MCP Zero Trust | 標準 guardrails 文件 會透過 agent 的底層模型呼叫套用 |
7. 備忘表：各標頭的作用
為了方便複製貼上，以下是兩個介面中高頻使用的請求標頭：
# Always (LiteLLM-side auth and identification)
x-litellm-api-key: Bearer sk-...
# or
Authorization: Bearer sk-...
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 ghp_<user-token> # user passthrough to github_mcp
x-litellm-mcp-debug: true # diagnostic response headers
# A2A — per-user passthrough
x-a2a-my-agent-authorization: Bearer <user-token> # caller's token to my-agent
x-a2a-my-agent-x-api-key: <user-key> # additional per-agent header
若要深入了解，請沿著上方的交叉連結前往專屬頁面。
