JWT Auth Policy - Claim & Scope Matching Refactor

[renuka-fernando]

1. Background

Two problems in the current jwt-auth policy:

1. Array claims silently fail. requiredClaims only handles string-valued claims. A token with an array claim such as "group": ["foo","bar"] never matches — even when the expected value is present in the array — so the request is wrongly rejected. (Confirmed by direct test.)

2. requiredScopes uses the wrong logic.

   • Currently requires all listed scopes to be present (AND).
   • Natural semantic for scopes is any one is sufficient (OR) — this is the bug to fix.
   • After the fix: claims stay AND, scopes become OR — different logic per field, which is intended but must be made explicit so it isn't mistaken for a bug.

We also want richer matching (any-of, all-of, exclusion) for both claims and scopes, expressed consistently.

---

2. New field set (overview)

Field	Applies to	Logic	Replaces	Status
anyOfClaims	claims	OR across claims	part of requiredClaims	New
allOfClaims	claims	AND across claims	requiredClaims	New
noneOfClaims	claims	exclusion	—	New
claimsExpression	claims	arbitrary boolean (CEL)	—	New (see §6)
anyOfScopes	scopes	OR	requiredScopes	New
allOfScopes	scopes	AND	requiredScopes	New
noneOfScopes	scopes	exclusion	—	New
scopesExpression	scopes	arbitrary boolean (CEL)	—	New (see §6)
requiredClaims	claims	AND	—	Deprecated
requiredScopes	scopes	AND	—	Deprecated

Naming decisions: noneOfClaims / noneOfScopes; claimsExpression / scopesExpression for the advanced form.

---

3. Simple matchers — anyOfClaims structure

Recommended: Option 2 (array of objects). Both forms are shown below; they are functionally equivalent for the simple case, but Option 2 is the recommendation — it is the proven UI-rendering shape and natively supports the "contains all" case (see the pros/cons for each option below).

Option 1 — Map (claim → values)

anyOfClaims:
  department: [platform, engineering]
  team: [devops, platform]

• Pros: concise, easy to read/write by hand, familiar (mirrors today's requiredClaims); duplicate claim keys are impossible by construction (prevents a config mistake).
• Cons: harder to extend with per-claim options later (e.g. matchType: regex); cannot express the array "contains all" case (see below). UI-rendering risk: every map param in shipped policies resolves to claim → string — no shipped policy uses a map whose values are lists, so this shape is un-exercised in the workspace UI (a front-end we don't own).

Option 2 — Array of objects (Recommended)

anyOfClaims:
  - claim: department
    values: [platform, engineering]
  - claim: team
    values: [devops, platform]

• Pros: extensible (per-entry options), explicit structure, same shape as claimsExpression leaves. Allows the same claim more than once, which unlocks the array "contains all" case without the advanced form (see below). Proven UI-rendering shape: repeatable structured rows are the dominant pattern across shipped policies (set-headers, request-rewrite, mcp-authz, token-based-ratelimit, …); mcp-authz is direct precedent — an array of objects where each item has a name plus a nested list, i.e. the same {claim, values} structure.
• Cons: more verbose; claim:/values: boilerplate on every entry.

Array "contains all" — only possible with Option 2. Because entries can repeat a claim, allOfClaims (AND across entries) can require an array claim to contain multiple values:

allOfClaims:
  - claim: group
    values: [admin]      # group array must contain admin
  - claim: group
    values: [auditor]    # AND group array must contain auditor

Option 1 (map) cannot express this — keys are unique, so group can't be listed twice. With Option 1, this case requires claimsExpression (§6).

Note: with auto-detection of array vs scalar claims (see §5), the main reason for per-claim options (a type field) goes away — but the duplicate-claim capability above remains a genuine advantage of Option 2.

allOfClaims and noneOfClaims use the same structure as whichever option is chosen for anyOfClaims.

UI rendering — side-by-side comparison

---

4. Two-level any/all semantics (documenting for clarity)

Each simple field has two levels of logic:

• Within a single claim — the value list is always OR. A claim "matches" if the token's value is any of the listed values.
• Across claims — governed by the field name:
  • anyOfClaims → OR (at least one claim matches)
  • allOfClaims → AND (every claim matches)
  • noneOfClaims → NONE (no claim matches)

Examples

allOfClaims — every claim must match:

allOfClaims:
  department: [platform, engineering]   # dept is platform OR engineering
  team: [devops]                        # AND team is devops

Passes when: (department ∈ {platform, engineering}) AND (team == devops).

anyOfClaims — at least one claim must match:

anyOfClaims:
  department: [platform, engineering]   # dept is platform OR engineering
  team: [devops]                        # OR team is devops

Passes when: (department ∈ {platform, engineering}) OR (team == devops).

noneOfClaims — no claim may match (exclusion):

noneOfClaims:
  department: [finance]                 # dept must NOT be finance
  team: [hr, legal]                     # AND team must NOT be hr or legal

Passes when: (department ∉ {finance}) AND (team ∉ {hr, legal}).

Array claims: if the token claim is itself an array (e.g. "group": ["a","b"]), "matches" means the array contains any of the listed values (membership).

Known limitation (Option 1 only): with the map form, the simple fields cannot express "an array claim must contain all of these values" (within-claim is always OR, and keys are unique). That case then requires claimsExpression (§6). With Option 2 (array form), it is expressible by repeating the claim under allOfClaims — see §3.

---

5. Array-claim handling (bug fix, no config needed)

Value matching auto-detects the claim shape at runtime:

• Scalar claim ("role": "admin") → exact equality.
• Array claim ("group": ["foo","bar"]) → membership check.

Example — scalar claim

Token: "role": "admin"

allOfClaims:
  role: [admin]        # exact match → passes

Example — array claim (membership)

Token: "group": ["foo","bar"]

allOfClaims:
  group: [foo]         # array contains "foo" → passes

The same policy works whether the identity provider sends group as a single string or as an array — no config change needed.

This fixes the array bug from §1 transparently for all fields. No type: string|array|auto param is needed — auto-detection is always correct, and its cost is negligible next to signature verification / JWKS fetch.

---

6. Advanced conditions — CEL expression

For arbitrary boolean logic for example:

A user must belong to both the admin and security-auditor groups, where groups is a JSON array claim:

"groups": ["admin", "security-auditor", "developers"]

The simple form can't express "contains all of [admin, security-auditor]" — this needs the advanced form.

Option A — Recursive expression tree

and/or take a list of sub-expressions; not takes one; leaves are {claim, anyOf|allOf}. Sibling entries under and/or combine per the parent operator.

Rule: siblings under and are AND-ed; siblings under or are OR-ed. and/or/not are the only operators.

claimsExpression:
  or:
    - and:
        - { claim: department, anyOf: [engineering] }
        - { claim: team,       anyOf: [devops] }
    - and:
        - { claim: role, anyOf: [admin] }
        - not: { claim: department, anyOf: [finance] }

Array "contains all" via allOf at the leaf:

claimsExpression:
  and:
    - { claim: groups, allOf: [admin, security-auditor] }   # array must contain BOTH

• Pros: native YAML; can express any boolean formula; leaf anyOf/allOf covers the array cases; claim names are statically inspectable.
• Cons: verbose and error-prone to hand-write; non-trivial parser + validation + test surface to build from scratch; un-exercised shape — no shipped policy nests and/or/not recursively, and it renders poorly as a form (deeply nested group widgets).

Option B — CEL expression (Recommended)

A single CEL string:

claimsExpression: >
  (department == "engineering" && "devops" in team) ||
  (role == "admin" && department != "finance")

Array "contains all":

claimsExpression: >
  "admin" in groups && "security-auditor" in groups

• Pros: extremely compact and expressive; well-known, standardized; handles arrays, string ops, comparisons natively; battle-tested in Envoy/Kubernetes. Already in this codebase — cel-go is a direct dependency, advanced-ratelimit ships a reusable CEL evaluator, and its policy-definition.yaml already surfaces a CEL expression field in the workspace UI. Nothing new to build or render.
• Cons: API developers must learn CEL; free-text field is harder to statically lint for claim names and gives less policy-specific error messages (inherent to any expression language — already the accepted trade-off in advanced-ratelimit).

Comparison

Dimension	Option A (tree)	Option B (CEL)
Learning curve	Low (just YAML)	Medium (learn CEL)
Expressiveness	Boolean over claim membership	Full expression language
Hand-writing ergonomics	Verbose	Compact
Dependency	Must build a bespoke engine	Already shipped (cel-go, reused from advanced-ratelimit)
UI rendering	Un-proven (recursive nested groups)	Proven (CEL expression field already ships)
Static validation / linting	Easier	Harder
Array "contains all"	allOf leaf	in operator

---

7. Field interaction

When multiple fields are set, all present fields are AND-ed together. The request passes only if every specified block passes.

Example — a policy combining four fields:

anyOfClaims:                    # (1) at least one of these claims matches
  - claim: department
    values: [platform, engineering]
noneOfClaims:                   # (2) none of these claims may match
  - claim: status
    values: [suspended]
allOfScopes:                    # (3) all of these scopes must be present
  - api:read
anyOfScopes:                    # (4) at least one of these scopes must be present
  - api:write
  - api:admin

The request passes only when all four hold:

(department ∈ {platform, engineering})        # anyOfClaims
  AND status ∉ {suspended}                     # noneOfClaims
  AND (api:read present)                        # allOfScopes
  AND (api:write OR api:admin present)          # anyOfScopes

If any one block fails, the request is rejected.

---

8. Deprecations

• requiredClaims → use allOfClaims. Kept for backward compatibility; still string-only + AND.
• requiredScopes → use anyOfScopes (OR) or allOfScopes (AND) depending on intent. Note the AND→OR shift in default expectation — needs a migration note.

Precedence rule (recommended): new fields override the deprecated one — they do not stack.

• If any new claim field (anyOfClaims / allOfClaims / noneOfClaims / claimsExpression) is set, requiredClaims is ignored entirely. Same for scopes: any new scope field supersedes requiredScopes.
• Precedence is per-concept (claims vs scopes), not per-individual-field.
• Why override, not stack: clear mental model ("new wins, old is legacy") and a safe migration — copying requiredClaims → allOfClaims just works. Stacking would silently make a policy stricter if a user forgot to delete the old field — a subtle over-restriction that's hard to debug.
• When a deprecated field is ignored because a new one is present, log a deprecation warning so the user knows to remove it.

Examples

Only the deprecated field set → it still applies (backward compatible):

requiredClaims:            # honored — no new claim field present
  role: admin

Both set → new field wins, deprecated one is ignored + warning logged:

requiredClaims:            # IGNORED (superseded by allOfClaims) → deprecation warning
  role: admin
allOfClaims:               # this is what actually applies
  - claim: role
    values: [admin, superuser]

Effective check: role ∈ {admin, superuser}. The requiredClaims: {role: admin} block has no effect.

Precedence is per-concept — claims and scopes are independent:

requiredClaims:            # IGNORED — a new claim field (anyOfClaims) is present
  role: admin
anyOfClaims:               # applies (claims concept)
  - claim: department
    values: [platform, engineering]
requiredScopes:            # STILL APPLIES — no new scope field is set
  - api:read

Here the new claim field supersedes requiredClaims, but requiredScopes is untouched because no new scope field was provided.

---

9. Open questions for the team

1. Map vs array for the simple claim fields (§3)? — Recommendation: Option 2 (array of objects). Ratify?

2. Advanced form (§6) — Recommendation: adopt CEL (Option B) now, reusing the advanced-ratelimit evaluator; not deferred. Ratify?

3. Deprecated + new field both set (§8) — Recommendation: precedence (new overrides old, per-concept); do not stack. Ratify?

4. Deprecation warnings — log at startup, per-request, or silent (§8)?

5. Namespacing — worth grouping under claims: / scopes: objects instead of the ...OfClaims/...OfScopes suffixes? Cleaner, but a bigger structural change and must not collide with existing param names.

   Flat (current proposal):

   anyOfClaims:
     - claim: department
       values: [platform, engineering]
   noneOfClaims:
     - claim: status
       values: [suspended]
   allOfScopes: [api:read]
   scopesExpression: '"api:write" in scopes || "api:admin" in scopes'

   Namespaced (alternative):

   claims:
     anyOf:
       - claim: department
         values: [platform, engineering]
     noneOf:
       - claim: status
         values: [suspended]
   scopes:
     allOf: [api:read]
     expression: '"api:write" in scopes || "api:admin" in scopes'