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

[totally-not-ai]

Summary

Keycloak sends a user's roles in the access token, so Vaadin applications never saw them and role-based access control did not work. This adds an opt-in switch, VaadinSecurityConfigurer.keycloakRoleMapping(), that reads those roles and turns them into Spring Security authorities.

What changed

Fully backward compatible. Nothing changes unless an application calls the new keycloakRoleMapping() method. It is off by default.

• New public class KeycloakOidcUserMapper, ported from SSO Kit. It decodes the access token and adds the realm roles (realm_access), the client roles granted to the current client id (resource_access), and the token scopes as SCOPE_ authorities. Roles that resource_access grants to other clients are ignored.
• New VaadinSecurityConfigurer.keycloakRoleMapping() opts one security filter chain in. It only works together with oauth2LoginPage(...); if no OAuth2 login page is configured, the configurer logs a warning and does nothing.
• When enabled, the configurer creates an OidcUserService and shares it as a shared object, so it can be inspected or replaced. An application that owns its own OidcUserService should leave the switch off and set the mapper with setOidcUserConverter(...) instead.
• Differences from the SSO Kit version: the JWT decoder of a client registration is built once and reused instead of on every login, the role prefix comes from VaadinRolePrefixHolder (resolved when a user is mapped, so a prefix defined by the filter chain itself is picked up) instead of a hardcoded ROLE_, and a login is never failed when the access token cannot be decoded — the user is simply mapped without role authorities.
• The wiring lives in a separate package-private class so that VaadinSecurityConfigurer still loads for applications without the optional spring-security-oauth2-client dependency.

Use case

An application uses Keycloak for login and protects its admin views with @RolesAllowed("admin"). Today those views stay blocked even for users who have the admin realm role, because the role never reaches Spring Security. Adding one call fixes it.

@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") // now matches the "admin" realm role in Keycloak
public class AdminView extends VerticalLayout {
}

An application that builds its own OidcUserService can use the mapper directly instead:

var oidcUserService = new OidcUserService();
oidcUserService.setOidcUserConverter(new KeycloakOidcUserMapper());

API Changes

com.vaadin.flow.spring.security.KeycloakOidcUserMapper

// Added
public class KeycloakOidcUserMapper implements Converter<OidcUserSource, OidcUser>
public KeycloakOidcUserMapper() // uses the ROLE_ prefix
public KeycloakOidcUserMapper(String rolePrefix) // null means ROLE_
public OidcUser convert(OidcUserSource userSource)

com.vaadin.flow.spring.security.VaadinSecurityConfigurer

// Added
public VaadinSecurityConfigurer keycloakRoleMapping() // opts in to Keycloak role mapping, off by default

Test summary

• Realm roles, client roles for the current client, and token scopes become authorities; roles belonging to other clients are left out.
• The role prefix is configurable, applies to roles only (not scopes), and a prefix set by the security filter chain is picked up even though it is known only after the chain is built.
• The authenticated user keeps its userinfo claims and can take its name from a userinfo attribute that is missing from the ID token.
• Login still succeeds without role authorities when the access token is not a decodable JWT, or when the client registration has no JWK set URI or no issuer URI.
• The JWT decoder is built only once per client registration.
• The opt-in only takes effect together with an OAuth2 login page, and VaadinSecurityConfigurer still loads when the optional spring-security-oauth2-client dependency is absent.

[Artur-]

This file should not change in this PR

[github-actions]

Test Results

 1 456 files  + 1   1 540 suites  +1   1h 33m 55s ⏱️ + 7m 46s
11 951 tests +12  11 883 ✅ +12  68 💤 ±0  0 ❌ ±0 
12 269 runs  +12  12 201 ✅ +12  68 💤 ±0  0 ❌ ±0 

Results for commit 3757644. ± Comparison against base commit ffe584b.

♻️ This comment has been updated with latest results.

[heruan]

Suggestions to simplify the port, nothing blocking.

[mshabarov]

@totally-not-ai resolve conflicts with main and revert changes in package-lock files that are unrelevant.

[totally-not-ai]

@mshabarov Both done.

Merged main in and resolved the one conflict, in VaadinSecurityConfigurerTest — main and this branch had each appended tests at the end of the class. Both sets are kept: the new anonymous sub-resource and document request tests from main, and the classpath test from here, with its class loader moved down next to the other test helpers. The module's tests pass after the merge.

On the lock files: there are none left in the diff. What the merge did drag in was a copyright-year rewrite across the 123 freshly imported flow-tests/vaadin-cdi-tests sources, applied by the formatter on commit. Those are restored to their main content, so the diff is back to the six vaadin-spring files this PR is actually about.

[Artur-]

merge main

[totally-not-ai]

@Artur- Merged. main is now an ancestor of this branch, so the conflicts are gone.

Three conflicts, all in VaadinSecurityConfigurerTest, all of the "both sides appended at the same spot" kind: two imports and a block of test methods. Both sides are kept in each case — the new session-concurrency and expired-session tests from main, and the classpath test from here. The session management work that came in with main merged cleanly into the configurer itself, and both its VaadinExpiredSessionStrategy entry and the two entries from this PR are present in SpringClassesSerializableTest.

vaadin-spring passes after the merge, and the diff is still only the six files this PR adds to.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[heruan]

Re-approving after the merges from main. The six vaadin-spring files are unchanged since the last review, the conflict resolution in VaadinSecurityConfigurerTest kept both sides, and the diff no longer touches any lock file.

[github-actions]

Pull request created: #6110

Generated by Documentation Bot · agent · 96.3 AIC · ⌖ 6.84 AIC · ⊞ 11.7K

[github-actions]

Documentation Bot: Draft documentation pull request for this change: #aw_docspr

Files updated:

• articles/flow/integrations/spring/oauth2.adoc
• articles/flow/security/vaadin-security-configurer.adoc

It was written from the state of this pull request as you see it now. Please review it and mark it ready for review.

Generated by Documentation Bot for #25627 · agent · 96.3 AIC · ⌖ 6.84 AIC · ⊞ 11.7K · ◷