feat: As a user, I want to select a Consumer (and its Consumer Group) from a JWT claim in openid-connect on a single route.

[PiyushMishra318]

Description

Feature Description

Add a consumer_selector capability to the openid-connect plugin so a single route can select a Consumer (and Consumer Group) from a JWT claim (for example, iss) before OIDC validation.

This enables deterministic multi-realm authentication on one route by mapping token claim values to Consumer identities, then applying the selected Consumer Group’s openid-connect configuration (realm-specific discovery/JWKS/introspection settings).

Motivation

Today, Consumer Group plugin configs are applied only after a Consumer is resolved.
Without a pre-auth resolver like key-auth, route-level openid-connect cannot dynamically switch realms by Consumer Group.

This forces users to:

• duplicate routes per realm, or
• use unsupported workaround patterns with extra auth plugins.

Proposed Behavior

Add new optional attributes in openid-connect:

• consumer_selector.enabled (boolean)
• consumer_selector.claim (string, default iss)
• consumer_selector.map (object: claim_value -> consumer_name)
• consumer_selector.strict (boolean, default true)

Request flow with selector enabled:

1. Extract bearer token.
2. Decode JWT payload to read selector claim.
3. Resolve mapped Consumer by consumer_name.
4. Attach Consumer to request context.
5. Load selected Consumer Group’s openid-connect config.
6. Continue normal OIDC validation and header injection (X-Userinfo, etc.) using selected config.

Compatibility / Risk Notes

• Feature is opt-in (consumer_selector.enabled=false by default).
• Existing openid-connect behavior is unchanged when selector is not enabled.
• This introduces a new control path and should be reviewed for:
  • claim spoofing risks before signature verification,
  • config mismatch/fallback behavior,
  • interaction with existing plugin execution order.

Example Config

"openid-connect": {
  "client_id": "dummy",
  "client_secret": "dummy",
  "discovery": "https://idp.example/.well-known/openid-configuration",
  "bearer_only": true,
  "consumer_selector": {
    "enabled": true,
    "claim": "iss",
    "strict": true,
    "map": {
      "https://idp.example/realms/realm-a": "realm-a-consumer",
      "https://idp.example/realms/realm-b": "realm-b-consumer"
    }
  }
}

If this design direction is acceptable, I can split this into smaller PRs (schema/docs first, runtime behavior second) if preferred.

[Baoyuantop]

The use case you describe is real — multi-realm OIDC on a single route is a recurring ask. However, I have concerns about the proposed approach that I think are worth discussing before moving toward implementation.

Security: routing on an unverified claim

The core issue is that consumer_selector.claim is read from the JWT payload before signature verification. While the selected realm's JWKS will eventually reject a forged token, the selector decision itself happens on attacker-controlled data. This opens the door to resource exhaustion by enumerating mapped iss values and triggering OIDC discovery/introspection requests, and potentially leaking internal realm mapping information through error response differences. The proposal notes this risk but doesn't propose a mitigation, which I'd consider a blocker for merging.

Architectural conflict

In APISIX, the contract for all auth plugins is: verify credentials → write ctx.consumer. The Consumer Group merge happens afterward in a single place in init.lua, via plugin.merge_consumer_route() and the rewrite_in_consumer phase. The proposed design would have openid-connect perform its own consumer resolution and Consumer Group config lookup internally, creating a second code path for logic that is intentionally centralized. This makes future maintenance significantly harder and could cause subtle conflicts with the standard merge flow.

Complexity vs. benefit

The multi-route workaround does have real cost (duplicated config), but it also gives complete isolation between realms, which is easier to reason about from a security and debugging perspective. The proposed feature adds a two-phase JWT decode, an embedded consumer resolver, a non-trivial schema extension, and a new execution path — all scoped to a single plugin. That's a high complexity budget for the benefit gained.

A more composable alternative

If this is important enough to solve at the framework level, I'd suggest considering a traffic-splitting approach at the routing layer: use APISIX's vars matching or a dedicated routing condition to inspect the raw Authorization header and dispatch to realm-specific routes before any auth plugin runs. This keeps the concern of "which realm does this token belong to" separate from "is this token valid for this realm", and avoids coupling the selector logic into openid-connect itself.