Embedded Keycloak Server running in a Spring Boot App
This project provides an embedded Authentication and Authorization Server
based on Keycloak and Spring Boot.
The idea is to have a variant of Keycloak-X but based on
Spring Boot instead of Quarkus.
Keycloak is embedded by hosting it's JAX-RS Application in a Spring-Boot environment.
Modules
embedded-spring-boot-keycloak-server-support
This module contains the necessary bits to embed a Keycloak server in a Spring Boot app.
embedded-spring-boot-keycloak-server-plain
This module contains the raw embed a Keycloak server in a Spring Boot app without additional customizations.
embedded-spring-boot-keycloak-server-custom
This module contains the embed a Keycloak server in a Spring Boot app with additional customizations.
Build
To build the embedded Spring Boot Keycloak Server, run the following command:
Note: we use the install goal to install the artifacts into the local maven repository
in order to be able to consume the artifacts in our customization project.
mvn clean install
Run
To run the plain embedded keycloak server app, you can execute the following command:
java -jar embedded-spring-boot-keycloak-server-plain/target/*.jar
The embedded Keycloak server is now reachable via http://localhost:8080/auth
Configuration
The Keycloak server part can be configured via Spring Boot configuration mechanism.
See embedded-spring-boot-keycloak-server-plain/application.yml for a list of configurable settings.
Customizing
The embedded-spring-boot-keycloak-server-custom example project demonstrates how one can use the
embedded-spring-boot-keycloak-server-support library to create an embedded Keycloak server with additional
customizations like Keycloak extensions and a custom theme.
Clustering
The embedded Keycloak server uses JGroups for Peer-to-Peer cluster communication and Infinispan for
managing distributed caches like SSO-Sessions etc.
JGroups Clustering can be configured via the jgroups.xml configuration file.
Infinispan distributed caches can be configured via the infinispan.xml configuration file.
By default JGroups is configured with TCPPING discovery which requires a list of initial hostnames
to join a cluster. If you want another JGroups discovery mechanism like, e.g. dnsping or kube_ping,
then you just need to adapt the jgroups.xml configuration file. Note that some discovery strategies like
kube_ping need additional jars in the classpath.
Note, that you need to use a centralized database if you want to really leverage a clustered embedded Keycloak.
To see the clustering in action, you can run the following command on two nodes:
Run on Node1:
java -Djgroups.tcpping.initial_hosts='node1[7800],node2[7800]' -jar target/*.jar
Run on Node2:
java -Djgroups.tcpping.initial_hosts='node1[7800],node2[7800]' -jar target/*.jar
If the clustering works you should see messages like:
2020-04-19 11:29:16.665 INFO 17055 --- [PN,neumann-3283] org.infinispan.CLUSTER : ISPN000094: Received new cluster view for channel ISPN: [neumann-3283|1] (2) [neumann-3283, gauss-45273]
2020-04-19 11:29:16.668 INFO 17055 --- [PN,neumann-3283] org.infinispan.CLUSTER : ISPN100000: Node gauss-45273 joined the cluster
2020-04-19 11:29:17.005 INFO 17055 --- [e-thread--p2-t2] org.infinispan.CLUSTER : [Context=org.infinispan.CONFIG] ISPN100002: Starting rebalance with members [neumann-3283, gauss-45273], phase READ_OLD_WRITE_ALL, topology id 2
...