Custom Role Claim Support in Zilla JWT Validation

[JVaghela-Fintech]

Feature Request

Zilla’s JWT authorization only validates the scope claim (e.g., scope: "openid profile email") for permissions, ignoring custom RBAC claims like:

{
  "role": "Admin",         // Ignored
  "groups": ["Viewer"],    // Ignored
  "scope": "read:data"     // Only this is used
}

Requested Change

Extend Zilla’s JWT validator to:

• Support custom RBAC claims (e.g., role, groups, realm_access.roles)
• Configurable claim names (to support standards like Keycloak, Auth0, or custom IdPs).
• Override scope-only validation
• Allow role/groups to work alongside or replace scope checks.

Backward Compatibility

• Retain scope support for legacy use cases.
• Make custom claims opt-in (no breaking changes).

[jfallows]

Thanks @JVaghela-Fintech this makes complete sense.

Based on the example from our JWT Guard reference...

guards:
  my_jwt_guard:
    type: jwt
    options:
      issuer: https://auth.example.com
      audience: https://api.example.com

...we would most likely add an option for guarded that defaults to the scope claim, but can be overridden to a different claim.

guards:
  my_jwt_guard:
    type: jwt
    options:
      issuer: https://auth.example.com
      audience: https://api.example.com
      roles: realm_access.roles

In general, the claim used for guarded routes could be type string with space separated values (like scope) or type array of string with individual values in the array.

We would support either type, making the scope default non-special even though it is not an array like the standard claims for roles, groups and entitlements.

As illustrated above, the guarded route claim could be at arbitrary depth, such as realm_access.roles used by Keycloak.

{
  "exp": 1676996589,
  "iat": 1676996289,
  "jti": "30737091-fd28-4278-b87b-3e450ee85504",
  "iss": "http://localhost:8180/realms/backend",
  "aud": "account",
  "sub": "b9ec5e66-f4e0-440a-9b1b-56e9213300d0",
  "typ": "Bearer",
  "azp": "rest-api",
  "session_state": "48845725-6cbd-4c76-b9e7-7ce1f729171f",
  "acr": "1",
  "realm_access": {
    "roles": [
      "default-roles-backend",
      "offline_access",
      "uma_authorization"
    ]
  },
  ...
  "scope": "openid email profile",
  "sid": "48845725-6cbd-4c76-b9e7-7ce1f729171f",
  "email_verified": true,
  "preferred_username": "admin",
  "given_name": "",
  "family_name": ""
}

Please let us know if this would fully address the requirement.

[JVaghela-Fintech]

Yes, this serves the purpose. Thank you very much for the quick response