feat(auth): add scope and wildcard support for JWT routing overrides

[milan-berri]

Enhancement request for JWT routing_overrides to:

• support optional scope selector matching (same optional behavior as client_id)
• support wildcard matching for selectors (not full regex), with iss still required

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Type

🆕 New Feature
✅ Test

Changes

• Added scope to JWTRoutingOverride schema:
  • scope: Optional[Union[str, List[str]]] = None
• Extended routing override claim matching:
  • wildcard support with fnmatch (* and ?)
  • list-aware selector and claim matching
  • space-delimited string claim handling (notably for scope)
• Updated override evaluation to include scope:
  • _matches_routing_override(...) now checks iss, optional client_id, optional scope, optional aud
• Added/refined tests in tests/test_litellm/proxy/auth/test_user_api_key_auth.py:
  • parametrized matcher tests for exact/list/wildcard/scope tokenization semantics
  • parametrized override tests for combined selector behavior (AND semantics)
  • focused async routing tests for OAuth2 path vs JWT fallback behavior
• Kept route-scope behavior unchanged:
  • JWT override to OAuth2 remains restricted to LLM + info routes (no expansion to management routes)

---

Note

Medium Risk
Changes JWT routing-override matching used to decide whether JWT-shaped bearer tokens are routed to OAuth2 introspection, so misconfiguration or matcher edge cases could affect authentication behavior.

Overview
Adds a new optional scope selector to JWTRoutingOverride and documents matching semantics (case-sensitive shell wildcards, and space-delimited parsing only for scope).

Updates JWT routing-override evaluation to support wildcard selectors (*, ?) across iss/client_id/aud and to AND in scope matching (including splitting OAuth/OIDC scope strings). Expands unit/integration tests to cover exact/list/wildcard behavior, scope tokenization, and OAuth2-routing vs JWT-fallback flows.

^{Reviewed by Cursor Bugbot for commit c3758db. Bugbot is set up for automated code reviews on this repo. Configure here.}

[veria-ai]

JWT routing override selectors extended

This PR adds scope matching and case-sensitive wildcard support to JWT routing overrides. I checked the selector matching path, the auth-path handoff, and the configuration model; the unverified claims are still only used to select the validator, with final token validation left to the selected OAuth2/JWT auth flow.

---

Status: 0 open
Risk: 2/10

[greptile-apps]

Greptile Summary

This PR extends JWTRoutingOverride with an optional scope selector and adds shell-style wildcard matching (*/? via fnmatch.fnmatchcase) to all routing-override selectors. The implementation is clean: scope is space-tokenized only when explicitly requested via split_space_delimited=True, keeping iss/aud/client_id as full-string or wildcard matches without splitting, and backward compatibility is preserved since the new field is optional.

Confidence Score: 5/5

Safe to merge — all new fields are optional, routing still operates on unverified claims only for path selection, and final auth validation is unchanged.

No P0 or P1 findings. Previously flagged items (bracket-expression edge case in fnmatch, unreachable else branch) have been resolved or acknowledged. Tests are mock-only, comprehensive, and correctly reflect the documented semantics.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/_types.py	Adds scope: Optional[Union[str, List[str]]] field to JWTRoutingOverride and extends the class docstring to document wildcard semantics and space-delimited tokenization. Change is backward-compatible (field is Optional).
litellm/proxy/auth/user_api_key_auth.py	Extends _routing_selector_matches_claim with split_space_delimited flag and fnmatch-based wildcard matching; wires scope into _matches_routing_override with the flag enabled. Logic is correct and the iss injection-via-space edge case is handled by the False-when-no-split guard.
tests/test_litellm/proxy/auth/test_user_api_key_auth.py	Adds comprehensive parametrized unit tests for the new matching logic and three async integration tests that verify the OAuth2 routing path is taken or skipped correctly; JWT token payloads are consistent with the configured overrides and no real network calls are made.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Bearer token received"] --> B["_should_route_jwt_to_oauth2_override()"]
    B --> C{"routing_overrides configured?"}
    C -- No --> D["JWT auth path"]
    C -- Yes --> E["get_unverified_claims(token)"]
    E --> F{"For each override: _matches_routing_override()"}
    F --> G["_routing_selector_matches_claim(iss, ...)"]
    G --> H["_routing_selector_matches_claim(client_id, ...)"]
    H --> I["_routing_selector_matches_claim(scope, split_space_delimited=True)"]
    I --> J["_routing_selector_matches_claim(aud, ...)"]
    J --> K{All selectors match?}
    K -- No, next override --> F
    K -- No overrides left --> D
    K -- Yes --> L["OAuth2 auth path (Oauth2Handler.check_oauth2_token)"]

Loading

_{Reviews (3): Last reviewed commit: "refactor(auth): drop dead fallback in sc..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c3758db. Configure here.}

[cursor]

Undocumented fnmatch bracket patterns silently active in wildcards

Low Severity

The wildcard gate (if "*" in selector or "?" in selector) only checks for * and ?, but fnmatch.fnmatchcase also interprets [seq] and [!seq] bracket patterns. A selector like "*[v2]" would treat [v2] as a character class (matching v or 2), not as the literal string [v2]. The docstring similarly documents only * and ? as supported. This creates inconsistent behavior: [seq] in a selector is literal when alone but interpreted as a pattern when * or ? is also present.

Additional Locations (1)

• litellm/proxy/_types.py#L4337-L4339

 

^{Reviewed by Cursor Bugbot for commit c3758db. Configure here.}

[oss-pr-review-agent-shin]

🤖 litellm-agent: Squash-merged into staging branch shin_agent_oss_staging_05_07_2026. Staging PR: #27422

---

Triage Summary
Extends JWT routing override matching to support a new scope claim selector and shell-style wildcard patterns (* and ?) for all selectors. Adds space-delimited tokenization for the OAuth/OIDC scope claim so multi-scope strings are matched token-by-token. Changes are confined to litellm/proxy/_types.py (adds scope field to JWTRoutingOverride), litellm/proxy/auth/user_api_key_auth.py (rewrites _routing_selector_matches_claim with fnmatch support and scope splitting), and a substantially expanded test suite in tests/test_litellm/proxy/auth/test_user_api_key_auth.py.

Merge Confidence: 5/5 ✅ READY
⚠️ 11 checks failing: ci/circleci: litellm_assistants_api_testing, ci/circleci: langfuse_logging_unit_tests, ci/circleci: batches_testing (+8 more)
Ready to ship.

Greptile 5/5, no blocking pattern findings, CircleCI passed. 11 checks failing but unrelated to this diff: ci/circleci: litellm_assistants_api_testing, ci/circleci: langfuse_logging_unit_tests, ci/circleci: batches_testing (+8 more). 10 unrelated CI failures unique to this PR (ci/circleci: litellm_assistants_api_testing, ci/circleci: langfuse_logging_unit_tests, ci/circleci: batches_testing (+7 more)) — not related to this diff but worth a glance. 1 check also red on neighboring PRs (ci/circleci: realtime_translation_testing) — infra-wide noise, no penalty.