Migrating from Legacy Keycloak Spring Boot Adapters

Introduction

Keycloak previously provided dedicated Spring Boot and Spring Security adapters to simplify client-side OpenID Connect (OIDC) integration for Spring-based applications. These adapters were widely used to secure applications with minimal configuration.

However, these legacy adapters have since been deprecated and ultimately removed as part of Keycloak’s move toward standards-based OAuth2 and OIDC integration.

The older keycloak-spring-boot-adapter and keycloak-spring-security-adapter are no longer supported in recent Keycloak versions and are incompatible with Spring Boot 3.x.

These adapters depended on WebSecurityConfigurerAdapter, which was completely removed in Spring Security 6, the security foundation used by Spring Boot 3.

The link lists the adaptors deprecation details.

What is recommended to use instead?

• Native Spring Security OAuth2/OIDC

Spring Security now has first-class OAuth2 and OIDC support built into its core libraries (spring-security-oauth2-client, spring-security-oauth2-resource-server). These replace the Keycloak adapters for both:

• OAuth2 Login (Authorization Code flow)
• OIDC Authentication
• Resource Server (JWT token validation)

And they work natively with Spring Boot 3 / Spring Security 6.

They integrate seamlessly with Spring Boot 3 and Spring Security 6, and are the officially recommended approach when using Keycloak 25+

This article suggests helpful hints to migrate Keycloak Spring Boot adaptor.

Helpful hints

If your existing codebase is large with many security customizations around adapters, starting a fresh Spring Boot 3 project with native Spring Security config might be easier than hacking around old patterns.

Otherwise, incremental migration (remove adapter refs, add new config) works too.

Java and Spring Boot Version Changes

Java Requirements

• Spring Boot 3 requires Java 17 or higher (17+ supported, many use Java 21).
• Older apps on Java 8/11 must be updated.
  -> So expect a Java upgrade step: Java 17 minimum.

Spring Security Changes

• WebSecurityConfigurerAdapter has been removed
• Configuration now uses lambda-style DSL with SecurityFilterChain
• antMatchers() has been replaced by requestMatchers()

These changes are central to migrating legacy security configurations.

Migration Steps – Higher-Level Guidance

1.Remove Old Adapter Dependencies

Remove any of the following dependencies from your project:

<dependency>
  <groupId>org.keycloak</groupId>
  <artifactId>keycloak-spring-boot-adapter</artifactId>
</dependency>
<dependency>
  <groupId>org.keycloak</groupId>
  <artifactId>keycloak-spring-security-adapter</artifactId>
</dependency>

These adapters are no longer supported and should not be used with Spring Boot 3 or Keycloak 25+.

2. Add Native Spring Security OAuth2 Dependencies
At minimum:

For OAuth2 Login (web app)

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

For Resource Server (REST API validating JWT access tokens)

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

3. Update Spring Security Configuration

Instead of extending WebSecurityConfigurerAdapter, now define a SecurityFilterChain:

• oauth2Login() (The Client Role):
  Used when a human user interacts with your app via a browser. Your app acts as an OAuth2 Client, redirecting the user to an Identity Provider (in our case Keycloak) to log in and receive an Authorization Code.
• oauth2ResourceServer() (The Resource Server Role):
  Used when a programmatic client (like a mobile app, a CLI tool, or another microservice) sends a request to your API. These clients don’t “log in” via a browser; they simply attach a Bearer Token (JWT) to the Authorization header.

Hybrid Approach (UI + API in the Same Application)

In some applications, you may want:

• Browser-based login for UI pages (Thymeleaf, JS)
• Strict JWT authentication for /api/** endpoints

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    // Chain 1: Protects the REST API only
    @Bean
    @Order(1)
    public SecurityFilterChain apiSecurityFilterChain(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/api/**")
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
            .build();
    }

    // Chain 2: Default for everything else (Browser Login)
    @Bean
    @Order(2)
    public SecurityFilterChain uiSecurityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .oauth2Login(Customizer.withDefaults())
            .build();
    }
}

Note: The above code is just for illustration. You may validate it further.

Important Note
Combining oauth2Login() and oauth2ResourceServer() is only required in hybrid applications. Pure UI or pure API applications typically need only one of these configurations.

application.yml Configuration

spring:
  security:
    oauth2:
      # Browser-based login (Authorization Code flow)
      client:
        registration:
          keycloak:
            client-id: your-client-id
            client-secret: your-client-secret
            scope: openid, profile, email
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          keycloak:
            issuer-uri: https://your-skycloak-hostname/realms/your-realm-name

      # REST API (JWT validation)
      resourceserver:
        jwt:
          issuer-uri: https://your-skycloak-hostname/realms/your-realm-name

Using issuer-uri allows Spring Security to automatically discover Keycloak’s authorization, token, and JWKS endpoints.

You may find this article helpful while doing the migration.

Summary

In this article, we explored how to migrate applications from legacy Keycloak Spring Boot adapters to the native Spring Security OAuth2/OIDC approach required for Keycloak 25+ and Spring Boot 3.

By adopting Spring Security’s built-in OAuth2 Client and Resource Server capabilities, applications gain:

• Standards-compliant OAuth2/OIDC integration
• Compatibility with modern Spring and Java versions
• Long-term maintainability without vendor-specific adapters

About Skycloak

If you’re new to Skycloak, visit the Skycloak Getting Started Guide to learn more and securing your Keycloak deployments.

Skycloak is a fully managed Keycloak platform hosted in the cloud. It enables organizations to leverage the power of open-source Keycloak IAM without the operational overhead of installing, maintaining, and scaling production-grade Keycloak environments—delivered securely and cost-effectively.