Integrating Keycloak with Spring Security: A Simple Guide

So you’re diving into the world of Spring Boot apps and want to make them super secure with a tight authentication system, huh? You’ve landed in the right place! Let’s talk about how you can pull off a seamless integration with Keycloak. It’s all about making your app both secure and easy to manage. Here’s the lowdown.

Introducing Keycloak

Let’s start with the basics. Keycloak is an open-source Identity and Access Management (IAM) tool developed by Red Hat. Think of it as an all-in-one solution for identity management. It brings single sign-on (SSO), user federation, strong authentication, and user management to the table. And it’s not stopping there. Keycloak supports OAuth 2.0, OpenID Connect (OIDC), and SAML protocols, making it pretty flexible for various use cases.

Setting Up Keycloak

First things first, you’ve got to set it up. If you’re into Docker (who isn’t these days?), you can run Keycloak in a Docker container. Check out this simple Docker command:

docker pull keycloak/keycloak:17.0.0
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password keycloak/keycloak:17.0.0 start-dev

Done? Great! Now you can hit up the admin console by navigating to http://localhost:8080. This is where the magic happens. You’ll be creating a new realm and adding clients.

Creating a Realm and Client in Keycloak

Realms are like isolated environments. Go ahead and create a new realm, name it “External” or whatever suits your fancy. Within this realm, you’ll set up a client. Let’s call it “external-client”. You’ll need to configure it just right:

• Client ID: external-client
• Enabled: On
• Client Protocol: openid-connect
• Access Type: Confidential
• Standard Flow Enabled: On
• Direct Access Grants Enabled: On
• Valid Redirect URIs: http://localhost:8081/*

Don’t forget to grab that client secret. You’ll need it later when putting things together in your Spring Boot application.

Spring Boot & Keycloak – A Match Made in Heaven

Now, let’s integrate Keycloak with your Spring Boot application. This is where you get into the nitty-gritty. Start by adding the relevant dependencies in your pom.xml:

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

Then, let’s tweak the application.properties to include the Keycloak settings:

server.port=8081
spring.application.name=Spring 3 and Keycloak

logging.level.org.springframework.security=INFO
logging.pattern.console=%d{dd-MM-yyyy HH:mm:ss} %magenta([%thread]) %highlight(%-5level) %logger.%M - %msg%n

spring.security.oauth2.client.provider.external.issuer-uri=http://localhost:8080/realms/external
spring.security.oauth2.client.registration.external.provider=external
spring.security.oauth2.client.registration.external.client-name=external-client
spring.security.oauth2.client.registration.external.client-id=external-client
spring.security.oauth2.client.registration.external.client-secret=your-client-secret
spring.security.oauth2.client.registration.external.scope=openid,offline_access,profile
spring.security.oauth2.client.registration.external.authorization-grant-type=authorization_code

Hooking Up Your Security Config

The real magic happens when you configure Spring Security to recognize Keycloak. Since the old Keycloak adapters are deprecated, you should roll with Spring Security’s built-in support for OAuth2 and OIDC. Here’s a sample configuration:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .anyRequest().authenticated()
                .and()
                .oauth2Login();
        return http.build();
    }
}

Giving It a Test Run

With everything set up, it’s time to test your app. Start your Spring Boot application and try accessing any endpoint. You should see the Keycloak login page. If everything is configured correctly, it’ll work like a charm. Tools like Postman are great for testing, but you can also just use your browser.

Understanding OAuth2 Flows

Keycloak supports a bunch of OAuth2 flows. Let’s break down a couple of them:

• Authorization Code Flow: Perfect for web apps. It’s a two-step process where the user gets redirected to Keycloak, logs in, and gets sent back with an authorization code, which your application exchanges for an access token.
• PKCE Authorization Code Flow: Good for mobile and JavaScript-based apps. This builds on the Authorization Code Flow but adds extra security with a code verifier and challenge.
• Client Credentials Flow: Ideal for server-to-server communication. No user interaction needed here. Your app requests an access token straight from Keycloak using the client ID and secret.

Wrapping It Up

To sum it up, integrating Keycloak with Spring Security is a fantastic way to add robust identity management and security to your applications. By following these steps, you get a centralized system for user management and authentication, making your app more secure and easy to manage. So give it a try and see how it transforms your security game!