feat(spring): add opt-in Keycloak role mapping to VaadinSecurityConfigurer

[totally-not-ai]

Summary

Keycloak sends user roles in the access token, so Vaadin's role-based access control does not see them. This change adds VaadinSecurityConfigurer.keycloakRoleMapping(), which turns Keycloak realm and client roles into Spring Security role authorities for one security filter chain.

What changed

• KeycloakOidcUserMapper (new, ported from SSO Kit): decodes the access token and maps the realm_access roles and the resource_access roles of the current client id to prefixed role authorities. Roles that belong to other clients are ignored. Access-token scopes become SCOPE_ authorities.
• VaadinSecurityConfigurer.keycloakRoleMapping() (new): opts in to the mapper. It only works together with oauth2LoginPage(...); without a login page the configurer logs a warning and does nothing. If the application shares its own OidcUserService through HttpSecurity, that instance is reused instead of a new one.
• KeycloakRoleMapping (new, package-private): holds the wiring to OidcUserService. spring-security-oauth2-client is an optional dependency, and the JVM verifies a class as a whole when it loads it, so naming those types inside VaadinSecurityConfigurer would break every application that does not have the dependency. Keeping them in a separate class means it is only loaded when the application asks for Keycloak role mapping.

Differences from the SSO Kit version:

• The JWT decoder of a client registration is created once and reused, instead of being built on every login.
• The role prefix comes from VaadinRolePrefixHolder instead of a hardcoded ROLE_, and is resolved when a user is mapped, because the prefix of the filter chain is only known after configure() has run.
• An access token that is not a decodable JWT maps a user without roles instead of failing the login.
• The OidcUserInfo is always kept on the resulting user, so userinfo claims are not lost when the client registration sets a user-name attribute.

Use case

An application logs users in with Keycloak, and admins are marked by a Keycloak realm role called admin. The developer wants @RolesAllowed("admin") on a view to just work, without writing a custom OidcUserService.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http.with(VaadinSecurityConfigurer.vaadin(),
                configurer -> configurer
                        .oauth2LoginPage("/oauth2/authorization/keycloak")
                        .keycloakRoleMapping())
                .build();
    }
}

@Route("admin")
@RolesAllowed("admin") // matches the Keycloak realm role "admin"
public class AdminView extends VerticalLayout {
}

API Changes

com.vaadin.flow.spring.security.KeycloakOidcUserMapper

// Added
public class KeycloakOidcUserMapper implements Converter<OidcUserSource, OidcUser>
public KeycloakOidcUserMapper() // prefixes roles with ROLE_
public KeycloakOidcUserMapper(String rolePrefix) // null means ROLE_
public OidcUser convert(OidcUserSource userSource)

com.vaadin.flow.spring.security.VaadinSecurityConfigurer

// Added
public VaadinSecurityConfigurer keycloakRoleMapping() // opt in to Keycloak role mapping, needs oauth2LoginPage(...)

Test summary

#	Status	What the test verifies	Why it matters
1	✅	Realm roles and the current client's roles become prefixed role authorities, scopes become SCOPE_ authorities, and an OidcUserAuthority is still present	This is the whole point of the feature
2	✅	Roles that resource_access grants for other clients produce no role authority	Leaking another client's roles would grant access the user should not have
3	✅	A custom role prefix is applied to roles but not to scopes	A wrong prefix silently breaks every @RolesAllowed check
4	✅	An access token that is not a decodable JWT maps a user without roles instead of throwing	A non-Keycloak or opaque token must not break the login
5	✅	With a user-name attribute configured, the user keeps its OidcUserInfo and userinfo claims, and getName() resolves	Dropping userinfo lost all claims and failed the login when the name is only in the userinfo response
6	✅	The JWT decoder is created once per client registration and reused across logins	Building a decoder per login fetches the JWK set every time
7	✅	keycloakRoleMapping() with an OAuth2 login page installs the mapper into the chain's OidcUserService	Without this the opt-in does nothing
8	✅	keycloakRoleMapping() without an OAuth2 login page configures no OidcUserService	Must not half-configure a chain that has no OIDC login
9	✅	An OidcUserService shared on HttpSecurity is reused, not replaced	An application's own customized service must survive
10	✅	The mapper picks up the filter chain's role prefix set after the chain is built	The prefix is unknown at configure time; resolving too early yields ROLE_
11	✅	VaadinSecurityConfigurer loads and verifies through a class loader that hides spring-security-oauth2-client	Any reference to the optional dependency crashes apps that do not use OAuth2

• KeycloakOidcUserMapperTest.convert_realmAndClientRolesAndScopesMapped — 1
• KeycloakOidcUserMapperTest.convert_otherClientRolesAndMissingClaimsIgnored — 2
• KeycloakOidcUserMapperTest.convert_customRolePrefixAppliedToRolesOnly — 3
• KeycloakOidcUserMapperTest.convert_accessTokenNotAJwt_mappedWithoutRoles — 4
• KeycloakOidcUserMapperTest.convert_userNameAttributeUsedAsName_userInfoRetained — 5
• KeycloakOidcUserMapperTest.convert_decoderCreatedOncePerClientRegistration — 6
• VaadinSecurityConfigurerTest.keycloakRoleMapping_withOAuth2LoginPage_oidcUserServiceMapsRoles — 7
• VaadinSecurityConfigurerTest.keycloakRoleMapping_withoutOAuth2LoginPage_notConfigured — 8
• VaadinSecurityConfigurerTest.keycloakRoleMapping_sharedOidcUserService_isReused — 9
• VaadinSecurityConfigurerTest.keycloakRoleMapping_rolePrefixOfChain_isUsedForRoles — 10
• VaadinSecurityConfigurerTest.withoutOAuth2ClientOnClasspath_configurerStillLinks — 11

Deliberately untested: the real NimbusJwtDecoder built from a client registration (it needs a live JWK set endpoint, so the tests inject a decoder factory), the warning log text when no login page is configured, and an end-to-end login against a real Keycloak server.

[Artur-]

This file should not change in this PR

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
87.1% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

Test Results

 1 441 files  + 1   1 525 suites  +1   1h 40m 37s ⏱️ + 2m 41s
12 062 tests +11  11 994 ✅ +11  68 💤 ±0  0 ❌ ±0 
12 380 runs  +11  12 312 ✅ +11  68 💤 ±0  0 ❌ ±0 

Results for commit dab7a97. ± Comparison against base commit bbfb634.