JWT → 虚拟密钥映射

企业版

JWT → 虚拟密钥映射是一项企业版功能。

获取免费试用

将 JWT 令牌映射到 LiteLLM 虚拟密钥 — 这样每个 JWT 客户端都能获得与虚拟密钥相同的精细控制：模型限制、支出限额、速率限制、护栏以及完整的支出追踪。

为何重要： 标准的 JWT 身份验证将 JWT 映射到一个团队。这是一个共享边界 — 同一团队下的所有客户端共享相同的限制。通过 JWT → 虚拟密钥映射，每个单独的 JWT 客户端（由 client_id、azp 或 sub 等声明标识）都会映射到其自己的虚拟密钥。您无需向用户分发 API 密钥即可实现每个客户端的问责制。

常见用例： 您的公司使用 SSO/OIDC。开发人员使用带有身份令牌的 Claude Code。您希望在不向每个人提供 LiteLLM API 密钥的情况下，强制执行针对开发人员个人的模型访问权限和支出限额。

---

工作原理

---

设置

先决条件

请先完成 OIDC JWT 身份验证设置 — 您需要在代理配置中配置 JWT_PUBLIC_KEY_URL 并设置 enable_jwt_auth: True。

第 1 步。配置用于映射的 JWT 声明

将 jwt_client_id_field 添加到您的 litellm_jwtauth 配置中。这是 LiteLLM 用作查找键的 JWT 声明。

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    team_id_jwt_field: "team_id"          # existing team mapping (optional)
    user_id_jwt_field: "sub"
    jwt_client_id_field: "client_id"      # 👈 claim used for key mapping
    unregistered_jwt_client_behavior: "fallback_team_mapping"  # see below

unregistered_jwt_client_behavior 控制当 JWT 没有注册映射时会发生什么

值	行为
fallback_team_mapping	回退到基于团队的 JWT 身份验证（默认 — 向后兼容）
reject	如果未找到映射，则返回 403
auto_register	首次遇到时自动创建虚拟密钥 + 映射

第 2 步。注册 JWT 客户端 → 虚拟密钥映射

选项 A：单次调用（原子地创建密钥 + 映射）

curl -X POST 'http://0.0.0.0:4000/jwt_client/new' \
  -H 'Authorization: Bearer <PROXY_MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jwt_claim_name": "client_id",
    "jwt_claim_value": "dev-alice",
    "models": ["claude-sonnet-4-5", "claude-haiku-4-5"],
    "max_budget": 50.0,
    "budget_duration": "30d",
    "rpm_limit": 100,
    "tpm_limit": 50000,
    "team_id": "engineering"
  }'

响应包含虚拟密钥令牌（仅在创建时显示）

{
  "key": "sk-abc123...",
  "key_id": "key_123",
  "mapping_id": "mapping_456",
  "jwt_claim_name": "client_id",
  "jwt_claim_value": "dev-alice"
}

选项 B：映射现有的虚拟密钥

curl -X POST 'http://0.0.0.0:4000/jwt/key/mapping/new' \
  -H 'Authorization: Bearer <PROXY_MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jwt_claim_name": "client_id",
    "jwt_claim_value": "dev-alice",
    "virtual_key_id": "key_123"
  }'

第 3 步。测试

# Get a JWT from your OIDC provider (must have client_id: dev-alice)
JWT_TOKEN="eyJhbG..."

curl -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

请求现在根据 dev-alice 的虚拟密钥进行追踪 — 支出、速率限制和模型访问权限均按客户端执行。

---

演练：管理员授予精细访问权限，团队使用 Claude Code

这是工程团队使用公司 SSO 运行 Claude Code 的完整流程。

管理员设置

1. 为工程部创建一个团队

curl -X POST 'http://0.0.0.0:4000/team/new' \
  -H 'Authorization: Bearer <MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "team_alias": "engineering",
    "models": ["claude-sonnet-4-5", "claude-haiku-4-5"]
  }'

2. 为每位开发人员注册他们自己的密钥和支出限额

# Alice — senior eng, higher budget
curl -X POST 'http://0.0.0.0:4000/jwt_client/new' \
  -H 'Authorization: Bearer <MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jwt_claim_name": "client_id",
    "jwt_claim_value": "alice@corp.com",
    "team_id": "engineering",
    "models": ["claude-sonnet-4-5", "claude-haiku-4-5"],
    "max_budget": 200.0,
    "budget_duration": "30d",
    "rpm_limit": 200
  }'

# Bob — contractor, tighter limits
curl -X POST 'http://0.0.0.0:4000/jwt_client/new' \
  -H 'Authorization: Bearer <MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jwt_claim_name": "client_id",
    "jwt_claim_value": "bob@contractor.com",
    "team_id": "engineering",
    "models": ["claude-haiku-4-5"],
    "max_budget": 20.0,
    "budget_duration": "30d",
    "rpm_limit": 30
  }'

3. 配置 Claude Code 以使用代理

在团队的 Claude Code 配置中将代理设置为 API 基地址

# Point Claude Code at the LiteLLM proxy instead of Anthropic directly.
# ANTHROPIC_API_KEY here is the bearer token sent to the proxy — set it to
# the user's SSO/OIDC JWT token (obtained from your IdP at login).
export ANTHROPIC_API_KEY="<user-sso-jwt-token>"
export ANTHROPIC_BASE_URL="http://your-litellm-proxy:4000"

或在 ~/.claude/settings.json 中设置

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://your-litellm-proxy:4000"
  }
}

4. 开发人员像往常一样通过 SSO 进行身份验证

当 Alice 运行 Claude Code 时，她的 JWT（由您的 IdP 颁发，包含 client_id: alice@corp.com）会发送到代理。LiteLLM 查找映射，找到她的虚拟密钥，并执行她特定的限制 — 每月 200 美元的预算、200 RPM 上限，且仅能访问 Sonnet 和 Haiku 模型。

Bob 的令牌映射到他自己的密钥 — 每月 20 美元，仅限 Haiku，30 RPM。

无需分发 API 密钥。没有共享限制。在 LiteLLM 仪表板中提供完整的按开发人员计费视图。

---

管理映射

查看映射及其密钥设置

curl 'http://0.0.0.0:4000/jwt/key/mapping/info?jwt_claim_name=client_id&jwt_claim_value=alice@corp.com' \
  -H 'Authorization: Bearer <MASTER_KEY>'

响应包含关联密钥的 models、max_budget、spend、rpm_limit、expires 等信息。

更新映射

curl -X POST 'http://0.0.0.0:4000/jwt_client/update' \
  -H 'Authorization: Bearer <MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jwt_claim_name": "client_id",
    "jwt_claim_value": "alice@corp.com",
    "max_budget": 300.0
  }'

删除映射

curl -X DELETE 'http://0.0.0.0:4000/jwt/key/mapping/delete' \
  -H 'Authorization: Bearer <MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jwt_claim_name": "client_id",
    "jwt_claim_value": "alice@corp.com"
  }'

---

安全性

JWT 绑定密钥受到严格锁定

• 非管理员用户无法对 JWT 绑定密钥调用 /key/update、/key/delete 或 /key/regenerate。这些操作将返回 403。
• JWT 绑定密钥自动限制为 llm_api_routes — 它们可以进行 LLM 调用，但不能管理其他密钥或管理资源。
• 只有代理管理员可以创建、更新或删除映射。

---

多 IdP 支持

如果您有来自多个身份提供商的用户，且它们共享相同的声明值（例如，两个服务都具有来自不同颁发者的 sub: user-123），请在创建映射时设置 issuer。

curl -X POST 'http://0.0.0.0:4000/jwt_client/new' \
  -H 'Authorization: Bearer <MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jwt_claim_name": "sub",
    "jwt_claim_value": "user-123",
    "issuer": "https://idp-a.corp.com",
    "models": ["claude-sonnet-4-5"],
    "max_budget": 50.0
  }'

映射对于每个 (claim_name, claim_value, issuer) 都是唯一的 — 因此来自 IdP A 的 user-123 和来自 IdP B 的 user-123 将解析为不同的虚拟密钥。

---

JWT 客户端与虚拟密钥的功能对比

功能	虚拟密钥	JWT → 密钥映射
按客户端模型访问	✅	✅
按客户端支出预算	✅	✅
按客户端 RPM/TPM 限制	✅	✅
团队成员资格	✅	✅
仪表板支出追踪	✅	✅
护栏	✅	✅
密钥轮换	✅	✅ (仅限管理员)
密钥过期	✅	✅
无需分发 API 密钥	❌	✅
兼容现有 SSO/OIDC	❌	✅

---

相关内容

• OIDC JWT 身份验证 — 使用此功能前需要基础 JWT 身份验证设置
• 虚拟密钥 — 完整的虚拟密钥文档
• 访问控制 — 模型和团队访问控制