[Enhancement] Support path-based principal_field for nested JWT claims

[gmintoco]

[Enhancement] Support path-based principal_field for nested JWT claims

Use case

AWS outbound federation (GetWebIdentityToken) puts the IAM role ARN in the JWT sub claim. ARNs contain colons, which StarRocks rejects in usernames. The usable identity is nested under a URI-namespaced claim:

{
  "sub": "arn:aws:iam::123456789012:role/DataProcessingRole",
  "https://sts.amazonaws.com/": {
    "request_tags": { "starrocks_user": "data-eng" }
  }
}

principal_field can't reach starrocks_user — it only does flat top-level lookups.

Root cause

OpenIdConnectVerifier.java calls claims.getStringClaim(principalField), which is a single-level key lookup. URI-namespaced claims (standard per RFC 7519) have JSON objects as values, so getStringClaim returns null.

Prior art

Projects that already support nested JWT claim resolution:

• HashiCorp Vault — user_claim_json_pointer flag enables RFC 6901 JSON Pointer syntax (e.g. "/groups/primary"). Applies to user_claim, groups_claim, bound_claims, and claim_mappings. Docs
• OpenSearch — dot-notation paths for subject_key (e.g. "attributes.sub"). Merged in v3.2.0. PR #5467
• Grafana — JMESPath expressions for username_attribute_path (e.g. "user.username"). Docs
• Envoy Gateway — dot-notation nested claim references in JWT authorization policies. Docs

Proposal

If principal_field contains a path separator, resolve it by walking the nested claim structure. Try flat lookup first for backward compatibility.

Vault's JSON Pointer approach is the most robust (handles URI keys with ~1 escaping). Dot notation is simpler and covers most cases.

[gmintoco]

Submitted a PR for this: #71749

Uses Jackson's built-in JsonPointer (RFC 6901) when principal_field starts with /, flat lookup otherwise. Tested with unit tests and against a live cluster using AWS STS outbound identity federation tokens with deeply nested claims.