Reasons Your API Returns 403 With a Valid Token — and How to Fix Missing Role Mapping

// build.gradle (or pom.xml equivalent)
// implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")
// implementation("org.springframework.boot:spring-boot-starter-security")

package com.example.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.authorization.AuthorityAuthorizationManager;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.web.SecurityFilterChain;

import java.util.;
import java.util.stream.Collectors;

@Configuration
@EnableMethodSecurity // enables @PreAuthorize
public class SecurityConfig {

    @Bean
    SecurityFilterChain api(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(HttpMethod.GET, "/actuator/health").permitAll()
                // Example: require ADMIN role for admin APIs
                .requestMatchers("/admin/").access(AuthorityAuthorizationManager.hasRole("ADMIN"))
                // Example: require 'read' scope for reads
                .requestMatchers(HttpMethod.GET, "/api/").hasAuthority("SCOPE_read")
                // Everything else requires authentication
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth -> oauth
                .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthenticationConverter()))
            );
        return http.build();
    }

    /**
      Converts JWT -> Authentication with properly mapped authorities.
      Supports:
       - realm_access.roles (Keycloak realm roles)
       - resource_access.{client}.roles (Keycloak client roles)
       - roles (generic array)
       - scope/scp (OAuth scopes)
     /
    @Bean
    JwtAuthenticationConverter jwtAuthenticationConverter() {
        var converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(this::extractAuthorities);
        return converter;
    }

    private Collection<grantedauthority> extractAuthorities(Jwt jwt) {
        Set<string> roleNames = new LinkedHashSet<>();

        // 1) Keycloak realm roles: { "realm_access": { "roles": ["admin","user"] } }
        Map<string, object=""> realmAccess = jwt.getClaim("realm_access");
        if (realmAccess instanceof Map<!--?, ?--> ra) {
            Object roles = ra.get("roles");
            if (roles instanceof Collection<!--?--> c) {
                c.stream().map(Object::toString).forEach(roleNames::add);
            }
        }

        // 2) Keycloak client roles: { "resource_access": { "<clientid>": { "roles": [...] } } }
        Map<string, object=""> resourceAccess = jwt.getClaim("resourceaccess");
        if (resourceAccess instanceof Map<!--?, ?--> res) {
            res.values().forEach(v -> {
                if (v instanceof Map<!--?, ?--> clientObj) {
                    Object roles = clientObj.get("roles");
                    if (roles instanceof Collection<!--?--> c) {
                        c.stream().map(Object::toString).forEach(roleNames::add);
                    }
                }
            });
        }

        // 3) Generic roles array: { "roles": ["manager"] }
        Object rolesClaim = jwt.getClaim("roles");
        if (rolesClaim instanceof Collection<!--?--> c) {
            c.stream().map(Object::toString).forEach(roleNames::add);
        }

        // 4) Scopes: "scope": "read write" or "scp": ["read","write"]
        String scope = jwt.getClaimAsString("scope");
        if (scope != null) {
            Arrays.stream(scope.split("\s+")).forEach(s -> roleNames.add("SCOPE" + s));
        }
        Object scp = jwt.getClaim("scp");
        if (scp instanceof Collection<!--?--> c) {
            c.stream().map(Object::toString).forEach(s -> roleNames.add("SCOPE" + s));
        }

        // Normalize to ROLE* when the claim looks like a role
        Set<string> normalized = roleNames.stream()
                .flatMap(name -> {
                    if (name.startsWith("SCOPE")) return Set.of(name).stream();
                    String n = name.toUpperCase(Locale.ROOT);
                    return Set.of(n.startsWith("ROLE") ? n : "ROLE_" + n).stream();
                })
                .collect(Collectors.toCollection(LinkedHashSet::new));

        // Optional: fallback for authenticated-but-roleless users
        if (normalized.isEmpty()) {
            // Give them a minimal identity authority if you want to distinguish later
            normalized.add("ROLE_AUTHENTICATED");
        }

        return normalized.stream().map(SimpleGrantedAuthority::new).collect(Collectors.toList());
    }
}

// Example controller
package com.example.api;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/admin")
public class AdminController {

    @GetMapping("/whoami")
    @PreAuthorize("hasRole('ADMIN')")
    public String whoAmI() {
        return "You are an ADMIN, welcome to the control room.";
    }
}

@RestController
@RequestMapping("/api")
class ApiController {
    @GetMapping("/docs")
    @PreAuthorize("hasAuthority('SCOPE_read')")
    public String docs() {
        return "Readable content for tokens with 'read' scope.";
    }
}

package com.example.security;

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
class AccessDeniedAdvice {

    @ExceptionHandler(AccessDeniedException.class)
    ResponseEntity<string> onDenied(HttpServletRequest req, AccessDeniedException ex) {
        // In production, keep this terse; avoid leaking internals.
        String msg = "Access denied for " + req.getMethod() + " " + req.getRequestURI()
                + ". Your token is valid but lacks required authorities.";
        return ResponseEntity.status(403).body(msg);
    }
}

Read more at : Reasons Your API Returns 403 With a Valid Token — and How to Fix Missing Role Mapping