Add spaceDelimitedClaims field to RequestAuthentication API

[fjglira]

Related Issues
#56873

Following a change in Istio 1.21, JWT claims other than scope and permissions are treated as exact string values. This created an issue for users with custom, space-delimited claims (for example: a roles claim with the value "editor admin"), as they could no longer match individual values like editor or admin in their Authorization Policies.

This PR introduces a new field, spaceDelimitedClaims, to the RequestAuthentication API. This field allows users to explicitly specify a list of custom claims that Istio should parse as space-delimited strings. This restores the previous, more flexible behavior for users who depend on it, without changing the new default for other claims.

API Changes

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
spec:
  jwtRules:
  - issuer: "https://example.com"
    jwksUri: "https://example.com/.well-known/jwks.json"
    spaceDelimitedClaims:
    - "custom_scope"
    - "provider.login.scope"
    - "roles"

This change is fully backward compatible. The default behavior for the standard scope and permissions claims remains unchanged; they will always be treated as space-delimited lists, regardless of whether they are included in the new field.

[istio-policy-bot]

😊 Welcome @fjglira! This is either your first contribution to the Istio api repo, or it's been
a while since you've been here.

You can learn more about the Istio working groups, Code of Conduct, and contribution guidelines
by referring to Contributing to Istio.

Thanks for contributing!

Courtesy of your friendly welcome wagon.

[louiscryan]

Do we know if space is the only delimiter we care about ? Would we be better off with something a little more long-term flexible

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
spec:
  jwtRules:
  - issuer: "https://example.com"
    jwksUri: "https://example.com/.well-known/jwks.json"
    formattedClaims:
       - format: SPACE_DELIMITED
         claims:
            - "custom_scope"
            - "provider.login.scope"
            - "roles"

where 'format' likely starts with just SPACE_DELIMITED and CSV as the available options but can evolve without requiring schema change over time to handle more cases ?

[fjglira]

Do we know if space is the only delimiter we care about ? Would we be better off with something a little more long-term flexible

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
spec:
  jwtRules:
  - issuer: "https://example.com"
    jwksUri: "https://example.com/.well-known/jwks.json"
    formattedClaims:
       - format: SPACE_DELIMITED
         claims:
            - "custom_scope"
            - "provider.login.scope"
            - "roles"

where 'format' likely starts with just SPACE_DELIMITED and CSV as the available options but can evolve without requiring schema change over time to handle more cases ?

Hi @louiscryan, that's a great point about ensuring long-term flexibility.

The primary motivation for this feature is to handle custom claims that adopt the same format as the standard scope claim. For instance, the original issue highlights the need to parse a space-delimited string from a custom claim like provider.oauth.scope used by Oracle OAuth.

As defined in RFC 6749, Section 3.3, the scope value is explicitly a space-delimited list of strings. Given that this is the standardized and most prevalent format for this kind of value, I opted for a solution that applies this same parsing logic to other claims that follow this convention.

I agree that your proposed formattedClaims structure is more extensible, and we can certainly adopt it if we find concrete use cases for other delimiters (like CSV) in the future. For now, would you be comfortable merging this targeted solution to solve the immediate issue, and we can iterate with a more generic approach later if we need to?

[louiscryan]

Im.fine with this as the schema evolution to handle other cases seems trivial either way

[louiscryan]

lgtm