From cbb84b6650c523c48c1c6fd97a46b358833985bf Mon Sep 17 00:00:00 2001 From: Ishaan Jaffer Date: Tue, 31 Mar 2026 16:33:27 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20add=20mermaid=20sequence=20diagram=20fo?= =?UTF-8?q?r=20JWT=20=E2=86=92=20key=20resolution=20flow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/my-website/docs/proxy/jwt_key_mapping.md | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/my-website/docs/proxy/jwt_key_mapping.md b/docs/my-website/docs/proxy/jwt_key_mapping.md index 3e8672ed052..452bf821016 100644 --- a/docs/my-website/docs/proxy/jwt_key_mapping.md +++ b/docs/my-website/docs/proxy/jwt_key_mapping.md @@ -18,21 +18,34 @@ Map JWT tokens to LiteLLM virtual keys — so every JWT client gets the same gra ## How It Works -When a JWT arrives at the proxy: +```mermaid +sequenceDiagram + participant Client as Client (Claude Code / API) + participant Proxy as LiteLLM Proxy + participant OIDC as OIDC Provider + participant DB as Mapping Table -1. LiteLLM validates the JWT signature against your OIDC provider. -2. It extracts a configurable claim (e.g. `client_id`) from the token. -3. It looks up that claim value in the JWT key mapping table. -4. If a mapping exists, the request proceeds under that virtual key — same permission checks, spend tracking, and rate limiting as if the user had sent `Authorization: Bearer sk-...`. + Client->>Proxy: POST /v1/chat/completions
Authorization: Bearer -``` -JWT Token LiteLLM Proxy Virtual Key -───────────────────── ────────────────────── ────────────────────── -{ 1. Validate signature sk-abc123 - "client_id": "dev-alice", 2. Extract client_id ────▶ models: ["claude-*"] - "sub": "alice@corp.com", 3. Look up mapping max_budget: $50/month - ... 4. Apply virtual key rpm_limit: 100 -} permissions + Proxy->>OIDC: Verify JWT signature + OIDC-->>Proxy: Valid ✓ + + Proxy->>Proxy: Extract claim
(e.g. client_id = "alice@corp.com") + + Proxy->>DB: Look up (claim_name, claim_value) + alt Mapping found + DB-->>Proxy: virtual_key_id = sk-abc123 + Proxy->>Proxy: Apply virtual key permissions
(models, budget, rate limits) + Proxy-->>Client: 200 OK + else No mapping — fallback_team_mapping + Proxy->>Proxy: Fall through to team JWT auth + Proxy-->>Client: 200 OK + else No mapping — reject + Proxy-->>Client: 403 Forbidden + else No mapping — auto_register + Proxy->>DB: Create new virtual key + mapping + Proxy-->>Client: 200 OK + end ``` ---