OIDC Authentication for Spring Boot Apps with KeyCloak

Spring Boot provides a perfect out-of-the-box Spring Security auto configuration for OpendID Connect based user authentication. Since KeyCloak is a certified OpenID Provider, Spring Boot and KeyCloak integrates pritty well with no special configurations.

[KeyCloak version: 6.0.1, Spring Boot version: 2.1.7.Release]

KeyCloak configurations

Starting KeyCloak with port offset

Since the Spring Boot application too starts with port 8080, in this tutorial KeyCloak is started with port 8081 using an offset.

sh standalone.sh -Djboss.socket.binding.port-offset=1

Realm and user creation

Create a realm with name “spring-boot-demo” and add a sample user. No special configurations are required for this tutotial. Refer documentation for additional help on creating a realm and a user.

Client creation

Create a client in KeyCloak with the following configurations. Refer the registering and creationg a client in KeyCloak documentation for additional help.

• client id: spring-boot-client
• client protocol: openid-connect
• access type: confidential
• enabled, consent required, standard flow enabled: true
• base Url: http://localhost:8080/
• redirect Url: http://localhost:8080/login/oauth2/code/oidcclient
• exclude session state from authentication response: true
• scope → full scope allowed: false
• client scopes: email, profile

Spring Boot Application

The complete source code for the project can be found here source code: https://github.com/sureshatt/spring-security-projects/tree/master/spring-boot-oidc-login. Project structure is as given bellow:

spring-boot-oidc-login
|-- src
|---- main
|------ java
|-------- com.sureshatt.springsecurity.oidc
|---------- HomeController.java
|---------- OidcLoginApplication.java
|------ resources
|-------- templates
|---------- home.html
|------ application.yml
|-- pom.xml

Spring Seurity configuration

With Spring Security auto configuration, there is no need to write a single line of Java code to configure OIDC authentication. It is only required to provide the required configration in the properties file.

spring.security.oauth2.client.registration.oidcclient.client-id=spring-boot-client
spring.security.oauth2.client.registration.oidcclient.client-secret={copy-paste-client-secret-here}
spring.security.oauth2.client.registration.oidcclient.client-name=OIDC-Client
spring.security.oauth2.client.registration.oidcclient.provider=keycloak
spring.security.oauth2.client.registration.oidcclient.scope=openid
spring.security.oauth2.client.provider.keycloak.issuer-uri=http://localhost:8081/auth/realms/spring-boot-demo

With the above configuration, Spring Security will trigger OIDC authentication flow with KeyCloak for any unauthenticated resouce access of the applcation.

The View, Model and the Controller

The controller is mapped to the root “/” over Http GET. Therefore when an authenticated user access the root, the Spring Boot framework will make sure to pass the authenticated in user information to the controller as the Principle object. This information is then passed to the view over the mode, hence the sub claim of Id Token is displayed as the username in the view.

@Controller
public class HomeController {
@GetMapping(“/”)
    public String homeView(Model model, Principal principal) {
        model.addAttribute(“sub”, principal.getName());
        return “home”;
    }
}

Result