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

docs/my-website/docs/proxy/oauth2.md

@@ -83,5 +83,7 @@ general_settings:
         path: "oauth2"
 ```
 
-For full `routing_overrides` behavior and list-based selectors, see [`/proxy/token_auth`](./token_auth.md#route-jwt-shaped-machine-tokens-to-oauth2).
+Overrides may also include optional `scope` and shell-style wildcards (`*`, `?`) on selectors; wildcard matching is case-sensitive, and space-delimited `scope` strings are handled as documented there.
+
+For full `routing_overrides` behavior, wildcards, `scope`, and list-based selectors, see [`/proxy/token_auth`](./token_auth.md#route-jwt-shaped-machine-tokens-to-oauth2).
 

docs/my-website/docs/proxy/token_auth.md

@@ -814,10 +814,26 @@ general_settings:
 
 ### Matching behavior
 
-- A rule matches when all configured selectors match token claims
-- Supported selectors: `iss` (required), `client_id` (optional), `aud` (optional)
-- Selector values support both string and list forms
-- If no rule matches, LiteLLM continues with standard JWT validation
+- A rule matches when **all** configured selectors match the corresponding token claims (AND semantics).
+- Supported selectors: `iss` (required), `client_id` (optional), `scope` (optional), `aud` (optional).
+- Selector values can be a single string or a list of strings (the claim must match at least one entry, using the rules below).
+- **Wildcards:** selectors may use shell-style `*` and `?`. Matching is **case-sensitive**—use the same casing your IdP emits in JWT claims.
+- **`scope` claim as a space-delimited string:** OAuth/OIDC often sends `scope` as one string (e.g. `openid profile App:LiteLLM`). LiteLLM splits that string **only when matching the `scope` selector**, so a configured value like `App:LiteLLM` can match. **`iss`, `aud`, and `client_id` are never split on spaces**; the full claim string is used (routing uses unverified claims only for path selection; final auth still validates the token).
+- If no rule matches, LiteLLM continues with standard JWT validation.
+
+### Example: `scope` and wildcard `client_id`
+
+```yaml title="config.yaml"
+general_settings:
+  enable_jwt_auth: true
+  enable_oauth2_auth: false
+  litellm_jwtauth:
+    routing_overrides:
+      - iss: "machine-issuer.example.com"
+        scope: "App:LiteLLM"
+        client_id: "*MID_LITELLM"
+        path: "oauth2"
+```
 
 ### List-based override example
 

litellm/proxy/_types.py

@@ -4152,10 +4152,16 @@ class JWTRoutingOverride(BaseModel):
 
     A rule matches when all provided selectors match token claims.
     If matched, request is routed to the configured auth path.
+
+    Wildcard selectors use shell-style patterns (* and ?) and are matched with
+    case-sensitive semantics; use the same casing your IdP emits in JWT claims.
+    Space-delimited tokenization applies only to the ``scope`` claim (OAuth/OIDC
+    scope strings), not to ``iss``, ``aud``, or ``client_id``.
     """
 
     iss: Union[str, List[str]]
     client_id: Optional[Union[str, List[str]]] = None
+    scope: Optional[Union[str, List[str]]] = None
     aud: Optional[Union[str, List[str]]] = None
     path: Literal["oauth2"] = "oauth2"
 

litellm/proxy/auth/user_api_key_auth.py

@@ -8,6 +8,7 @@
 """
 
 import asyncio
+import fnmatch
 import re
 import secrets
 from datetime import datetime, timezone
@@ -140,22 +141,49 @@ def _get_bearer_token_or_received_api_key(api_key: str) -> str:
 
 
 def _routing_selector_matches_claim(
-    selector_value: Optional[Any], claim_value: Optional[Any]
+    selector_value: Optional[Any],
+    claim_value: Optional[Any],
+    *,
+    split_space_delimited: bool = False,
 ) -> bool:
     if selector_value is None:
         return True
 
-    selector_list = (
+    selector_list: List[str] = (
         [str(v) for v in selector_value]
         if isinstance(selector_value, list)
         else [str(selector_value)]
     )
 
+    if claim_value is None:
+        return False
+
     if isinstance(claim_value, list):
         claim_list = [str(v) for v in claim_value]
-        return any(v in claim_list for v in selector_list)
-
-    return str(claim_value) in selector_list if claim_value is not None else False
+    elif (
+        split_space_delimited
+        and isinstance(claim_value, str)
+        and " " in claim_value.strip()
+    ):
+        # OAuth/OIDC often sends scope as a single space-delimited string. Only split
+        # for the scope selector: iss/aud/client_id must stay exact full-string match
+        # on unverified claims (see routing override security review).
+        split_values = [v for v in claim_value.strip().split(" ") if v]
+        claim_list = split_values if len(split_values) > 1 else [claim_value]
+    else:
+        claim_list = [str(claim_value)]
+
+    def _selector_matches_claim(selector: str, claim: str) -> bool:
+        # NOTE: wildcard matching is case-sensitive (fnmatch.fnmatchcase).
+        if "*" in selector or "?" in selector:
+            return fnmatch.fnmatchcase(claim, selector)
+        return selector == claim
+
+    return any(
+        _selector_matches_claim(selector=s, claim=c)
+        for s in selector_list
+        for c in claim_list
+    )
 
 
 def _matches_routing_override(
@@ -166,6 +194,11 @@ def _matches_routing_override(
         and _routing_selector_matches_claim(
             override.client_id, token_claims.get("client_id")
         )
+        and _routing_selector_matches_claim(
+            override.scope,
+            token_claims.get("scope"),
+            split_space_delimited=True,
+        )
         and _routing_selector_matches_claim(override.aud, token_claims.get("aud"))
     )