Litellm jwt mapping virtualkeys

[shivamrawat1]

Cherry picked #25570
Resolves LIT-2008

Relevant issues

unregistered_jwt_client_behavior (reject / fallback_team_mapping / auto_register) was documented but never implemented.
_resolve_jwt_to_virtual_key had a single unconditional return None on no-match, so there was no way to enforce access control on
unmapped JWT clients — they always fell through to team auth. Separately, the doc still referenced the renamed field
jwt_client_id_field which LiteLLM_JWTAuth.init now rejects with a ValueError.

🐛 Bug Fix
📖 Documentation
✅ Test

Changes

• Added UnregisteredJWTClientBehavior enum and unregistered_jwt_client_behavior field to LiteLLM_JWTAuth (default:
  fallback_team_mapping — fully backward-compatible)
• reject: raises HTTP 403 on both fresh DB miss and cached NO_MAPPING sentinel
• auto_register: creates a new virtual key + mapping row on first encounter, proceeds as mapped
• Added backward-compat alias: jwt_client_id_field silently maps to virtual_key_claim_field so existing configs don't break
• Fixed doc to use virtual_key_claim_field with a deprecation note
• 5 new unit tests covering all three branches + the alias

Fix:
enabled autumatic key creation:

Created a jwt token scoped to a team and user and used it to make a call to a endpoint.

Key mapping is created automatically:

Confirmation the key was mapped

[greptile-apps]

Greptile Summary

This PR implements the long-documented but previously unimplemented unregistered_jwt_client_behavior field for JWT-to-virtual-key mapping, adding REJECT, AUTO_REGISTER, and FALLBACK_TEAM_MAPPING options to LiteLLM_JWTAuth. It also fixes a security gap where a JWT omitting the configured virtual_key_claim_field could bypass the REJECT policy, and adds a backward-compatibility alias for the renamed jwt_client_id_field.

• _resolve_jwt_to_virtual_key now honours the configured behavior at every exit point (missing claim, cached __NO_MAPPING__ sentinel, and fresh DB miss), with _PendingAutoRegister deferring key creation until after JWTAuthManager.auth_builder has enforced RBAC/scope/email-domain policy.
• _auto_register_jwt_mapping handles the race condition via unique-constraint detection, orphan cleanup, and a 503 raise when the winner's mapping disappears — addressing all four issues raised in previous review threads.
• 13 new unit tests cover all three behavior branches, the stale-sentinel eviction path, race recovery, prisma_client=None semantics, the proxy-admin sentinel optimization, and the jwt_client_id_field alias.

Confidence Score: 5/5

Safe to merge — all previously flagged security and logic gaps in the JWT mapping auth path have been addressed.

All four issues raised in prior review threads (REJECT bypass via missing claim, table_name='key' for key creation, orphaned-key accumulation, and inconsistent sentinel/fresh-path behavior for AUTO_REGISTER) are resolved and covered by new unit tests. The one remaining observation is a style-only concern about direct Prisma writes bypassing the helper-function layer; it does not affect correctness or security.

No files require special attention — the auth path changes in user_api_key_auth.py are well-tested and the logic is sound.

Important Files Changed

Filename	Overview
litellm/proxy/_types.py	Adds UnregisteredJWTClientBehavior enum (FALLBACK_TEAM_MAPPING/REJECT/AUTO_REGISTER) and wires it into LiteLLM_JWTAuth; adds backward-compat alias for jwt_client_id_field → virtual_key_claim_field.
litellm/proxy/auth/user_api_key_auth.py	Implements the three behavior branches in _resolve_jwt_to_virtual_key and introduces _auto_register_jwt_mapping and _PendingAutoRegister; the new helper makes direct Prisma writes (create + delete) inside the auth critical path, bypassing the team's helper-function pattern.
tests/proxy_unit_tests/test_jwt_key_mapping.py	Adds 13 new unit tests covering REJECT (DB miss, cached sentinel, missing claim), AUTO_REGISTER (pending signal, helper invocation, race, prisma=None, proxy-admin sentinel), and backward-compat alias; all tests use mocks with no real network calls.

_{Reviews (7): Last reviewed commit: "fix(jwt): cache proxy-admin AUTO_REGISTE..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 62.58993% with 52 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/auth/user_api_key_auth.py	58.73%	52 Missing ⚠️

📢 Thoughts on this report? Let us know!

[shivamrawat1]

@greptile review again with new commit that resolves the p1 and p2 issue

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 3 · PR risk: 0/10

[shivamrawat1]

@greptile review again

[shivamrawat1]

@greptile review again with new commit that resolves all remaining issues

[shivamrawat1]

@greptile review again with new PR

[shivamrawat1]

@greptile review again

[shivamrawat1]

@greptile review again with the new commit that resolves the issues regarding db lookup

[mateo-berri]

LGTM; thanks!