This post has been featured in the 7th anniversary edition of This Week in Spring – January 2n, 2018.
Important updates on March 22nd, 2018: Thanks to valid feedback from friends and colleagues Stéphane and Jochen and in the light of the high interested in this post, I have updated the demo. I basically removed all the boilerplate. With Spring Boot 2 final and Spring Security 5 final, you can use OAuth2 login from within a Boot-application agains Keycloak without the need of a key cloak starker or any boilerplate code. All you need is a sane configuration. Due to the nesting of the needed properties, I switched to YAML.
Here’s a short post how to authenticate against Keycloak from within a Spring Boot 2 application. For Spring Boot 1.5.x there’s a community adapter from the Keycloak-team that takes the burden from you, but this adapter is not yet ready for Spring Boot 2 and Spring Security 5.
I had the following requirements for the setup I am gonna present:
- Manage users outside one application (i.e. be ready for a bunch of services): Realized with Keycloak
- Full integration with Spring Security, especially method security
- Funktional with server side rendered Thymeleaf or other template systems supported by Spring Boot
Here is the fully functional demo project: keycloakdemo. I am not replicating some comments from the sources in the following paragraphs.
With Spring Boot 2 comes Spring Security 5 and the first class support for OAuth Login: New feature OAuth2-Login. That means one doesn’t need separate modules anymore. But to make this work, it’s not enough to have
spring-boot-starter-security on the class path, you’ll need two more dependencies:
I’ll spare you the details on how to setup Keycloak and how to create a realm and what a realm is. Keycloak has an excellent documentation about that and the screenshots from the one existing tutorial on how to use the Spring Boot adapter have been copied around anyway, along with that post. The realm I used in the demo is part of the repo: test-realm.json. It’s easy to import into Keycloak.
Next step, prepare your application as usual, that is: Annotate your Main-class with
@SpringBootApplication. Then configure your client registration together with Keycloak as the provider for the client as described in there in the documentation:
The first two properties are reused in the registration below so that I don’t have to copy them all over the place. This configuration creates a client registration for you. If you need more control, the documentation is there to help you: About client registration.
And now you’re ready to configure your security as usual with the added, new option
The following controller together with a simple Thymeleaf template is just for demoing purposes:
Assuming you have a Keycloak server running on port 8080, you can checkout the above linked project, build it with Java 9 and run it on port 8082. Open http://localhost:8082, hit login and you should be redirected to your Keycloak instance and back after a successful login.
Needless to say that this setup works well with other OAuth 2 providers.