Integrating Keycloak with Spring Boot — A Practical Guide

After understanding the core concepts of SSO, it’s time to see a **real implementation**. In this post, we integrate **Keycloak** with a Spring Boot application, showing login flows, adapters, and configuration.

---

What is Keycloak?

Keycloak is an open-source Identity and Access Management (IAM) solution that supports:

• Single Sign-On (SSO)
• OAuth2 and OpenID Connect
• LDAP / Active Directory integration
• User federation, roles, and fine-grained authorization

It acts as the **Identity Provider (IdP)**, while your Spring Boot app acts as the **Service Provider (SP)**.

---

Step 1: Set up Keycloak

1. Download and run Keycloak (standalone or container):

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

2. Log in to Keycloak admin console: http://localhost:8080/ 3. Create a realm (e.g., springboot-sso) 4. Create a client (e.g., my-app) 5. Configure access type as confidential and set redirect URIs (e.g., http://localhost:8081/*)

---

Step 2: Add Keycloak dependencies to Spring Boot

Add these Maven dependencies:

  org.keycloak

  keycloak-spring-boot-starter

  22.0.1





  org.keycloak

  keycloak-spring-security-adapter

  22.0.1

> Versions may vary; check the latest Keycloak Spring Boot adapters.

---

Step 3: Configure application.properties

Add Keycloak configuration:

keycloak.realm=springboot-sso

keycloak.auth-server-url=http://localhost:8080/

keycloak.resource=my-app

keycloak.credentials.secret=YOUR_CLIENT_SECRET

keycloak.ssl-required=external

keycloak.public-client=false

keycloak.bearer-only=false

---

Step 4: Configure Spring Security Adapter

Create a security configuration class:

import org.keycloak.adapters.springsecurity.KeycloakSecurityComponents;

import org.keycloak.adapters.springsecurity.config.KeycloakWebSecurityConfigurerAdapter;

import org.springframework.context.annotation.Configuration;

import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;

import org.springframework.security.config.annotation.web.builders.HttpSecurity;

@Configuration

public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {

    @Override

    protected void configure(HttpSecurity http) throws Exception {

        super.configure(http);

        http.authorizeRequests()

            .antMatchers("/public/**").permitAll()

            .anyRequest().authenticated();

    }

    @Autowired

    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {

        auth.authenticationProvider(keycloakAuthenticationProvider());

    }

}

This configuration ensures that:

• Public endpoints are accessible without login
• All other endpoints require authentication via Keycloak
• Keycloak authentication provider is used for Spring Security

---

Step 5: Running the application

1. Start your Spring Boot app (`localhost:8081`) 2. Try accessing a protected endpoint: http://localhost:8081/secure 3. You’ll be redirected to Keycloak login page 4. After successful login, you’ll return to the Spring Boot app with a valid session

---

Step 6: Roles and Authorization

In Keycloak, you can define roles per client or realm. Then in Spring Security, you can restrict access:

http.authorizeRequests()

    .antMatchers("/admin/**").hasRole("ADMIN")

    .antMatchers("/user/**").hasRole("USER");

> Important: Keycloak roles are mapped to Spring Security authorities. > Always check how your Keycloak claims are converted.

---

Common issues

• Redirect loop — often due to incorrect redirect URI or public vs confidential client
• 403 Forbidden — token valid but roles not mapped correctly
• Token expiration — default Keycloak token lasts 5 minutes; adjust if needed
• WebFlux vs MVC differences — reactive apps need special configuration

---

Next steps

The next post will show **how to debug SSO authentication issues**, including:

• Token expiration
• Roles not applied correctly
• Redirect loops and filter chain problems

This builds naturally on the Keycloak + Spring Boot integration we just set up.

Part of the Spring Boot SSO Series

❤️ Support This Blog

---

If this post helped you, you can support my writing with a small donation. Thank you for reading.

---

Coffee ☕ Thanks 🙏 Extra Support ❤️