Add configurable scope list aggregation and wildcard pattern source for OAuth2 scope matching

[cmmoran]

Preflight checklist

• I agree to follow this project's Code of Conduct.
• I have read and am following this repository's Contribution Guidelines."
• I have discussed this feature request with the community.

Describe the background of your feature request

Heimdall currently supports configurable scope matching strategies such as exact, hierarchic, and wildcard, but two distinct authorization concerns are currently coupled or unavailable:

1. Scope list aggregation: some routes require all configured scope values, while others should allow access when any one configured scope value matches.
2. Wildcard pattern source: the current wildcard strategy follows grant-style semantics, where wildcard patterns are expected in the token’s granted scopes. Resource-server or gateway policies often need the opposite: configured required scopes
   contain wildcard patterns, while issued tokens carry concrete scopes.

Example use case:

A service issues concrete runtime scopes:

documents.read
reports.write

A gateway policy wants to allow a route when the token has any scope under a configured namespace:

scopes:
  matching_strategy: wildcard
  pattern_source: required
  match: any
  values:
    - documents.*
    - reports.*

This should allow documents.read without requiring tokens to contain broad wildcard scopes such as documents.*.

Describe your idea

Proposed behavior:

• Add match to control list aggregation:

  • all default: every configured value must match.
  • any: at least one configured value must match.

• Add pattern_source for wildcard matching:

  • granted default: preserve existing behavior, where token/granted scopes may contain wildcard patterns.
  • required: configured required scopes may contain wildcard patterns matched against concrete token scopes.

• Restrict pattern_source to matching_strategy: wildcard in both runtime config decoding and JSON Schema validation.

• Preserve all existing behavior by default.

This enables gateway/resource-server scope policies without changing existing wildcard semantics or requiring access tokens to carry wildcard scopes.

Are there any workarounds or alternatives?

A workaround is to enumerate every concrete scope in the Heimdall rule configuration and keep that list synchronized with the authorization server’s scope catalog. For example, instead of configuring documents.*, a service could configure
documents.read, documents.write, documents.delete, etc.

That works for small, stable scope sets, but it becomes brittle when scopes are added over time and does not express the intended policy as clearly as a namespace pattern.

Another alternative is to mint wildcard scopes such as documents.* into runtime access tokens, matching the existing grant-side wildcard behavior. That is not ideal for deployments where access tokens are expected to contain concrete granted
scopes and resource-server policy is responsible for expressing broader accepted patterns.

Version

v0.17.17

Additional Context

No response