0Pricing
Spring Security 6 & JWT Authentication · Lesson

Mapping JWT Claims to Spring Authorities

Learn how a resource server converts JWT claims into Spring Security GrantedAuthorities using JwtAuthenticationConverter for fine-grained access control.

Mapping JWT Claims to Spring Authorities is a free Spring Security 6 & JWT Authentication lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Security 6 & JWT Authentication learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

From Claims to Authorities

A resource server validates a JWT, but to enforce access it needs Spring GrantedAuthority objects. The bridge between raw claims and authorities is the JwtAuthenticationConverter.

The Default Scope Mapping

By default Spring reads the scope or scp claim, splits it on spaces, and prefixes each value with SCOPE_. So a scope of read becomes the authority SCOPE_read.

// scope: 'read write'  ->  SCOPE_read, SCOPE_write

Checking Scope Authorities

You can require these authorities in your security config or with annotations.

http.authorizeHttpRequests(auth -> auth
    .requestMatchers('/api/data').hasAuthority('SCOPE_read'));

The Problem with Roles

Many identity providers put roles in a custom claim like roles or realm_access.roles, not in scope. The default converter ignores those, so you must customize it.

Building a Custom Converter

Create a JwtGrantedAuthoritiesConverter and point it at the claim that holds your roles.

JwtGrantedAuthoritiesConverter c = new JwtGrantedAuthoritiesConverter();
c.setAuthoritiesClaimName('roles');
c.setAuthorityPrefix('ROLE_');

Wrapping in JwtAuthenticationConverter

Wrap the authorities converter inside a JwtAuthenticationConverter, which produces the final authentication token.

JwtAuthenticationConverter conv = new JwtAuthenticationConverter();
conv.setJwtGrantedAuthoritiesConverter(c);

Registering the Converter

Tell the resource server to use your converter inside the JWT configuration.

http.oauth2ResourceServer(o -> o
    .jwt(j -> j.jwtAuthenticationConverter(conv)));

Nested Claims

Some providers nest roles, e.g. Keycloak uses realm_access.roles. The simple converter cannot read nested paths, so write a lambda converter that drills into the structure.

Converter<Jwt, Collection<GrantedAuthority>> conv = jwt -> {
    Map<String,Object> realm = jwt.getClaim('realm_access');
    List<String> roles = (List<String>) realm.get('roles');
    return roles.stream()
        .map(r -> new SimpleGrantedAuthority('ROLE_' + r))
        .collect(Collectors.toList());
};

Combining Scopes and Roles

You may want both scope-based and role-based authorities. Merge two converters' results so a single principal carries both SCOPE_ and ROLE_ authorities.

Customizing the Principal Name

By default the principal name is the sub claim. Override setPrincipalClaimName if you prefer to identify users by, say, preferred_username.

conv.setPrincipalClaimName('preferred_username');

Verifying the Mapping

Test with a mock JWT that carries the roles claim and assert the request succeeds only when the expected authority is present.

mockMvc.perform(get('/api/admin')
    .with(jwt().authorities(new SimpleGrantedAuthority('ROLE_admin'))))
    .andExpect(status().isOk());

Quick Check

Test your understanding of claim-to-authority mapping.

Recap

You learned to map JWT claims to Spring authorities:

  • Default mapping turns scope into SCOPE_ authorities
  • Use JwtGrantedAuthoritiesConverter to read custom role claims
  • Write a lambda converter for nested claims like realm_access.roles
  • Register it via jwtAuthenticationConverter

This gives your resource server precise, claim-driven access control.

Frequently asked questions

Is the “Mapping JWT Claims to Spring Authorities” lesson free?

Yes — the full text of “Mapping JWT Claims to Spring Authorities” is free to read here on the web, and the Spring Security 6 & JWT Authentication course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Security 6 & JWT Authentication course, upgrade to CoddyKit PRO.

What will I learn in “Mapping JWT Claims to Spring Authorities”?

Learn how a resource server converts JWT claims into Spring Security GrantedAuthorities using JwtAuthenticationConverter for fine-grained access control. You practise Spring Security 6 & JWT Authentication with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Security 6 & JWT Authentication?

No prior experience is required. Spring Security 6 & JWT Authentication on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Mapping JWT Claims to Spring Authorities” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Security 6 & JWT Authentication lesson?

Yes. Every Spring Security 6 & JWT Authentication lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Resource Server Setup
  2. Decoding and Validating JWTs
  3. Scopes and Claims Enforcement
  4. Mapping JWT Claims to Spring Authorities
← Back to Spring Security 6 & JWT Authentication