Spring JWT authority mapping: convert a trusted claim into one deliberate namespace

Signature before authority

A receipt token has a claims field named permissions containing receipt.read and receipt.issue. The resource server must validate signature, issuer, audience and time before using those values. JWT validation establishes token trust; the converter turns a trusted claim into application authorities. If a controller checks SCOPE_receipt.issue while the converter emits PERM_receipt.issue, access is denied. If the converter maps an untrusted header or request parameter, the check becomes meaningless.

Keep the namespace explicit

Configure JwtGrantedAuthoritiesConverter for the exact claim name and prefix. Put that converter inside JwtAuthenticationConverter and attach it to the resource-server chain. Avoid silently accepting several claim names or treating arbitrary token strings as roles. Role and authority prefixes are string conventions, so document the issuer contract and test the final Authentication rather than only the decoded token. Tenant ownership remains a separate database decision from a permission string.

Test absent and malformed claims

Use signed test tokens or a trusted decoder fixture. Verify one permission grants its intended action, an absent permissions claim grants none, and a similarly named permission fails. Test both the HTTP matcher and method guard if they enforce the same action. Do not assume a role change takes effect on already-issued self-contained tokens; token lifetime and revocation policy set that delay.

Implementation contract

JwtGrantedAuthoritiesConverter grants = new JwtGrantedAuthoritiesConverter();
grants.setAuthoritiesClaimName("permissions");
grants.setAuthorityPrefix("PERM_");
JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
converter.setJwtGrantedAuthoritiesConverter(grants);
http.oauth2ResourceServer(oauth -> oauth.jwt(jwt -> jwt.jwtAuthenticationConverter(converter)));

Cost and verification

Authority conversion is linear in the number of claim values. Verification of a signed JWT usually dominates the local cost; oversized permission arrays increase token size on every call.

Common Mistakes

• Do not authorize from a claim before token validation.
• Do not mix role and scope prefixes without an explicit mapping contract.
• Do not let a broad permission replace a tenant-specific ownership check.

Read next

Spring Security JWT resource server: validate trust before checking scope, Spring Security roles and authorities: check the actual granted string, Spring resource server JWT: validate both issuer and intended audience, Spring Security scope versus tenant ownership: two separate decisions, Spring method authorization: test the proxied service boundary.