Why Keycloak Roles Silently Fail in Spring Security and How to Fix It

Spring Boot applications secured with Keycloak frequently return 403 errors even when a user holds the correct role, because Spring Security's default JWT converter does not read Keycloak's token structure. Instead of the standard OAuth2 scope claim, Keycloak stores roles under realm_access.roles and resource_access.<client>.roles, which Spring Security ignores entirely. The result is that no GrantedAuthority objects are created, causing all role-based access checks to fail without any error or stack trace. The fix requires a custom converter that extracts roles from both Keycloak claims and maps them to SimpleGrantedAuthority objects with the required ROLE_ prefix. To avoid rewriting this boilerplate across multiple services, the author packaged the solution into an open-source library called spring-keycloak-toolkit, which also adds RFC 7807-compliant error bodies to replace Spring Security's default empty 401 and 403 responses.