feat: configurable claim mapping for the JWT identity plugin

[araujof]

Summary

Adds claim mapping in the JWT identity plugin as configuration. It was fixed in StandardClaimMap, and claim_mapper accepted only "standard", so an operator whose IdP nests roles under realm_access.roles or namespaces them behind a URL had to patch the crate and rebuild.

Closes: #27

Two ways to configure it, mutually exclusive:

claim_mapper: keycloak        # a shipped preset: standard, keycloak, auth0, cognito

claim_map:                    # or write the map
  subject:
    id: sub
    roles:
      paths: [realm_access.roles, resource_access.my-api.roles]
      merge: union            # first_match (default) or union
    permissions:
      paths: [{path: permissions, array_only: true}, {path: scope, string_only: true}]
      split: whitespace
      on_missing: deny        # ignore (default) or deny

claims:                       # applies to a preset or a map
  include: [iss]

Paths use dots for nesting. \. escapes a literal dot, so a claim named https://my-app.example.com/roles is reachable. Colons are literals and need no escaping.

Compatibility

A config that does not change produces the identity it produced before. StandardClaimMap is untouched and the tests use it as the reference:

• Token shapes from Keycloak, Auth0, Cognito, SPIRE and Kubernetes docs, asserted against the old mapper before the new engine existed.
• Comprehensive test cases: every mapped claim against every JSON shape it can hold, and every shape pair across each fallback chain.

Both fail if a preset candidate is changed. Review found two places where the preset and the old mapper disagreed, an array-valued scope and a non-string client_id. The sweep exists because the hand-written corpus missed both.

Breaking changes

• Unknown keys in config: and in a trusted_issuers entry are rejected. Both structs default every field, so a misspelling took effect silently. A misspelled audiences was the worst case, because an empty audience list turns audience checking off.
• claims is a top-level field, not part of claim_map.
• A workload trust_domain is no longer mappable. It is the SPIFFE ID's authority, so it is derived from the identity.

New capability

claims: {include: [iss]} makes the issuing IdP readable from a policy. Subject claims are the only route from a JWT claim to a policy and registered claims were always dropped, so a deployment with several trusted issuers could not gate on which one signed the token.

Presets

Each preset declares a candidate only where the provider mints the claim, and its description records what it leaves out:

Preset	Not mapped	Reason
keycloak	teams	its groups claim holds realm roles
auth0	roles, teams	Auth0 forbids these as bare claim names, so they are per deployment
cognito	roles	cognito:roles holds IAM role ARNs

Tests assert those fields stay empty, so adding a candidate later cannot pass quietly.

Errors

Misconfiguration fails when the plugin is built, not on the first request: both mapper fields set, an unknown preset name, a malformed path (named with its field), a map with no section for its role, a flag on a field where it has no meaning. A section with no path for its anchor logs a warning at startup, since it would deny every token.

At runtime a field whose paths all miss stays empty and logs one debug event naming the paths tried. on_missing: deny turns that into auth.mapping_failed, the existing code. The spiffe:// check on workload identities has no config surface that disables it.

[praxis-bot]

Review: configurable claim mapping for the JWT identity plugin

Thorough review of all 20 changed files (~6,500 lines added). The design is sound: hand-rolled config parsing over serde_json::Value produces targeted error messages that name the field and path, the compilation step catches every misconfiguration at startup, and the standard-preset equivalence suite with its corpus and shape sweep is an unusually strong compatibility guarantee.

Severity	Count
Critical	0
Large	0
Medium	2

No blocking issues found. Two observations below.

[terylt]

Overall, nice work!

Here are some comments:

Four findings follow, ordered by how much they matter.

1. merge: union does not dedupe, and it shows up on client fields

builtins/plugins/identity-jwt/src/configured_mapper.rs:142

resolve_collection concatenates the values from each path under merge: union without deduplicating. For subject fields this is invisible because they land in HashSets downstream. ClientExtension.roles, .permissions, .teams, .authorized_scopes and .authorized_audiences are Vec<String>, so the duplicates survive.

The union example documented in this PR is enough to trigger it. With realm_access.roles unioned against resource_access.<api>.roles, and a role name present in both (common in Keycloak), client.roles comes out as ["admin", "viewer", "admin"].

Policy evaluation is not affected, since the APL bag re-collects into a HashSet. What is affected is anything reading ClientExtension directly: audit logs, serialized output, other plugins. The other awkward part is that the same config behaves differently depending on role, deduped for user, not deduped for client.

Dedupe in resolve_collection while preserving first-seen order.

2. Dotted paths in claims.exclude / claims.include are accepted and match nothing

builtins/plugins/identity-jwt/src/claim_map_config.rs:305

ClaimsOverrides::validate only checks that exclude and include do not overlap. The entries themselves are never validated as plain top-level claim names.

Every other path-shaped field in this config uses dotted syntax, so an operator writing claims: {exclude: [realm_access.roles]} to keep a sensitive nested claim out of the policy-visible bag is a plausible mistake rather than a contrived one. I confirmed it: the config loads without complaint, the entry matches nothing, and the entire realm_access object stays in subject.claims.

Rejecting an entry that contains an unescaped ., or at minimum warning at load time, matches the stance this PR already takes elsewhere. deny_unknown_fields and the undeclared-anchor warning both exist to stop misconfiguration from going quiet, and this is the same class of problem.

3. claims overrides are silently ignored for role: workload

builtins/plugins/identity-jwt/src/resolver.rs:257

with_claims attaches the overrides regardless of the configured role, but WorkloadIdentity has no claims bag, so claims_bag is never called on that path. A config with role: workload and claims: {include: [iss]} builds without error and does nothing at all.

The construction-time warn! a few lines below for a missing anchor is the precedent. Same treatment fits here.

4. Diagnostic strings are built before the level check

builtins/plugins/identity-jwt/src/configured_mapper.rs:275

Diagnostics::emit, and record / record_scalar_miss feeding paths_tried at :234 and :253, render their strings unconditionally. The comment says the escaping cost never lands on a resolving request, which assumes a miss is rare, but a miss is the common case.

A plain {sub, email} token under the default standard preset misses roles, permissions and teams. That is 5 ClaimPath::to_string() renderings into paths_tried, 3 Vec<String>, and 3 more format! plus join strings in emit, all thrown away when the subscriber sits at info. Every request pays it.

Gate on tracing::enabled!(Level::DEBUG), or defer the rendering into a lazily formatted field. I have not benchmarked this, so the size of the win is unmeasured, but the allocations are unconditional either way.

[araujof]

Overall, nice work!

Here are some comments:

Four findings follow, ordered by how much they matter.
...

Addressed! Thanks!

[terylt]

Re-reviewed. All comments addressed. A couple of small comments below but I will approve!

All four fixes are correct. Notes on each, then two small things that are not blocking.

Union dedupe

resolve_collection dedupes under merge: union with first-seen order kept. Confirmed the Keycloak case reaches client.roles as ["admin", "viewer", "auditor"], and confirmed first_match still carries a claim's own duplicates through unchanged.

Worth recording why this is safe for the parity story: no shipped preset uses merge: union, and the default is first_match, so nothing on the standard-preset path can reach the new code. The 14 equivalence tests still pass, which is consistent with that.

Claims override names

This went further than the finding asked for, and in a good direction. A dotted entry is refused at load, and \. now unescapes, so a claim whose name genuinely holds dots stays reachable. I checked an Auth0 style https://my-app\.example\.com/roles through both include and exclude and it matches the right key in the bag.

The overlap check now runs on the unescaped names, so a conflict written two different ways is still caught. That is a small improvement over what was there before.

Workload warning

Gated on exactly the right role. I confirmed by reading the mapper that map_subject and map_client both call claims_bag and map_workload does not, so caller_workload is the only role where the setting is inert.

Diagnostics gating

Safe. denied, which is what declined() reads, is deliberately left ungated, and missed and empty only ever reach emit. I verified a field with on_missing: deny still declines the token in a test binary with no subscriber installed at all, which is the regression this change could plausibly have caused.

One caveat I did not chase far: tracing::enabled! is evaluated at the Diagnostics::new callsite while the events fire in emit with fields attached. A field-directed filter could in principle disagree between the two. It takes an unusual filter to hit and the failure is a missing debug line, so it is noted rather than raised.

Two small things

configured_mapper.rs:162. A single-candidate union now dedupes the claim's own array, so ["a", "b", "a"] becomes ["a", "b"], while the same claim under first_match keeps the duplicate. The new comment covers the first_match case but not this one. It reads as defensible under the changelog's "each value once" wording, so this is a request for a clause in the comment rather than a behaviour change.

claim_map_config.rs:317. The doc on compile still says it reports "All of them at once, so fixing one does not uncover the next on the following startup", but name parsing short-circuits on the first bad entry. Verified: two dotted entries report only the first, and a name error preempts the overlap report entirely. Either collect the name errors the way the overlap check does, or soften the doc.

[terylt]

LGTM