Introduction

For Spring Boot 3, the old Keycloak Spring adapter is not the path you should build on. Spring Boot 3 is aligned with modern Spring Security, and the practical integration model is OpenID Connect or OAuth2 support through Spring Security rather than the legacy Keycloak adapter layer. So the correct answer to "use Keycloak Spring adapter with Spring Boot 3" is usually: do not rely on the old adapter, use standard Spring Security OAuth2 configuration instead.

Why the Old Adapter Is the Wrong Direction

Historically, Keycloak provided Spring-specific adapters that wrapped security integration for older Spring stacks. In current Spring Boot 3 style applications, the preferred approach is standards-based integration through:

• 'spring-boot-starter-oauth2-client for login flows'
• 'spring-boot-starter-oauth2-resource-server for JWT-protected APIs'

This matters because Spring Boot 3 moved to Jakarta namespaces and a newer Spring Security model, while the old adapter style is not the long-term integration path.

Resource Server Example

If your Spring Boot 3 application is a backend API protected by Keycloak-issued JWTs, configure it as an OAuth2 resource server.

Dependencies in pom.xml:

1<dependencies>
2  <dependency>
3    <groupId>org.springframework.boot</groupId>
4    <artifactId>spring-boot-starter-security</artifactId>
5  </dependency>
6  <dependency>
7    <groupId>org.springframework.boot</groupId>
8    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
9  </dependency>
10</dependencies>

application.yml:

1spring:
2  security:
3    oauth2:
4      resourceserver:
5        jwt:
6          issuer-uri: http://localhost:8080/realms/myrealm

Security configuration:

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.security.config.Customizer;
4import org.springframework.security.config.annotation.web.builders.HttpSecurity;
5import org.springframework.security.web.SecurityFilterChain;
6
7@Configuration
8public class SecurityConfig {
9
10    @Bean
11    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
12        http
13            .authorizeHttpRequests(auth -> auth
14                .requestMatchers("/public/**").permitAll()
15                .anyRequest().authenticated()
16            )
17            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
18
19        return http.build();
20    }
21}

That is the standard Spring Boot 3 style for a protected API.

Login Client Example

If the application is a browser-based web app that redirects users to Keycloak for login, use OAuth2 client support instead.

Dependencies:

1<dependency>
2  <groupId>org.springframework.boot</groupId>
3  <artifactId>spring-boot-starter-oauth2-client</artifactId>
4</dependency>

Then configure a client registration and use normal Spring Security login integration. The important point is that Keycloak acts as the OIDC provider, while Spring Security handles the client-side integration.

Mapping Keycloak Roles to Spring Authorities

One place where teams miss the old adapter is authority mapping. Keycloak roles often arrive in token claims that need to be translated into Spring authorities.

A common pattern is to add a custom JWT converter.

1import org.springframework.context.annotation.Bean;
2import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
3
4@Bean
5JwtAuthenticationConverter jwtAuthenticationConverter() {
6    return new JwtAuthenticationConverter();
7}

In a real application, you often customize the converter so realm or resource roles become authorities that Spring authorization rules can use. That replaces some of the convenience older adapters used to hide.

What to Configure in Keycloak

On the Keycloak side, the essentials are still familiar:

• create a realm
• create a client
• configure redirect URIs for login-based apps
• define roles and, if needed, protocol mappers
• use the realm issuer URL in Spring configuration

The main difference is that Spring Boot 3 consumes Keycloak as a standards-based identity provider rather than through a Keycloak-specific Spring adapter abstraction.

Common Pitfalls

A common mistake is searching for a drop-in Spring Boot 3 version of the old Keycloak adapter setup and trying to force it into the new stack.

Another mistake is using Spring Security's resource-server support but forgetting that Keycloak role claims may need custom authority mapping.

People also often confuse login-client configuration with resource-server configuration. They solve different application types.

Finally, do not hardcode old /auth-style realm URLs from outdated examples without checking the actual issuer URL exposed by your Keycloak deployment.

Summary

• For Spring Boot 3, the practical integration path is Spring Security OAuth2 or OIDC support, not the legacy Keycloak Spring adapter model
• Use oauth2-resource-server for JWT-protected APIs and oauth2-client for browser login flows
• Configure the Keycloak realm issuer URI in Spring Boot
• Expect to map Keycloak roles into Spring authorities explicitly when needed
• Treat Keycloak as an OpenID Connect or OAuth2 provider rather than relying on older adapter-specific integration patterns
• When modernizing, migrate the security model, not just the dependency coordinates