Keycloak Extension Playground
Simple project environment for developing custom Keycloak extensions.
This example uses the in-process KeycloakServer from the keycloak-testsuite-utils project to ease development.
Note that you might need to build the keycloak project locally with the version referenced in this pom.xml
since the required library keycloak-testsuite-utils is not distributed to maven central.
Building Keycloak
To build the Keycloak Project simply clone it into a directory like
# The Keycloak version referenced in the pom.xml
KC_VERSION=19.0.2
git clone https://github.com/keycloak/keycloak
git fetch origin --tags
git checkout $KC_VERSION
mvn clean install -DskipTests
Note that the current Keycloak release also needs the new keycloak-admin-ui dependency. If this dependency cannot be resolved, then you need to build the admin ui keycloak-theme first.
IDE Setup
Create a new launch configuration and configure com.github.thomasdarimont.keycloak.server.KeycloakPlaygroundServer as the main class.
Additionally configure keycloak-playground-server as the working directory.
Note, that you can configure Keycloak to use an h2 or PostgreSQL database, depending on your needs.
The following set of JVM options configure Keycloak with:
- h2 or PostgreSQL as database
- listen on all local interfaces on port
8081 - Keycloak Admin User
adminwith passwordadmin previewProfile features enabled
You can access the local Keycloak instance via the URL: http://localhost:8081/auth
Developing with a local h2 database
-Dkeycloak.bind.address=0.0.0.0
-Djava.net.preferIPv4Stack=true
-Dkeycloak.connectionsJpa.url=jdbc:h2:file:./data/keycloak_17_0_0_0000_master;DB_CLOSE_ON_EXIT=FALSE
-Dkeycloak.connectionsJpa.driver=org.h2.Driver
-Dkeycloak.connectionsJpa.driverDialect=org.hibernate.dialect.H2Dialect
-Dkeycloak.connectionsJpa.user=sa
-Dkeycloak.connectionsJpa.password=
-Dkeycloak.connectionsJpa.showSql=false
-Dkeycloak.connectionsJpa.formatSql=true
-Dprofile=COMMUNITY
-Dproduct.default-profile=COMMUNITY
-Dkeycloak.password.blacklists.path=./data/blacklists/
-Dcom.sun.net.ssl.checkRevocation=false
-Dkeycloak.truststore.disabled=true
-Dkeycloak.profile=COMMUNITY
-Dkeycloak.product.name=keycloak
-Dproduct.name=keycloak
-Dkeycloak.profile=preview
-Dkeycloak.hostname.frontendUrl=http://localhost:8081/auth
-Dkeycloak.profile.feature.account2=enabled
-Dkeycloak.profile.feature.account_api=enabled
-Dkeycloak.profile.feature.scripts=enabled
-Dkeycloak.profile.feature.device_activity=enabled
-Dkeycloak.profile.feature.tokenexchange=enabled
-Dkeycloak.profile.feature.ciba=enabled
-Dkeycloak.profile.feature.client_policies=enabled
-Dkeycloak.profile.feature.map_storage=disabled
-Dkeycloak.ciba-auth-channel.ciba-http-auth-channel.httpAuthenticationChannelUri=http://localhost:7777/ciba/auth
-Dkeycloak.theme.welcomeTheme=keycloak
-Dkeycloak.theme.dir=../simple-theme/
-Dresources=../simple-theme/
Developing with a PostgreSQL database
-Dkeycloak.bind.address=127.0.0.1
-Djava.net.preferIPv4Stack=true
-Dkeycloak.connectionsJpa.url=jdbc:postgresql://localhost:5432/keycloak_playground
-Dkeycloak.connectionsJpa.driver=org.postgresql.Driver
-Dkeycloak.connectionsJpa.driverDialect=org.hibernate.dialect.PostgreSQLDialect
-Dkeycloak.connectionsJpa.user=keycloak
-Dkeycloak.connectionsJpa.password=keycloak
-Dkeycloak.connectionsJpa.showSql=true
-Dkeycloak.connectionsJpa.formatSql=true
-Dprofile=COMMUNITY
-Dproduct.default-profile=COMMUNITY
-Dkeycloak.password.blacklists.path=/home/tom/dev/tmp/blacklists/
-Dcom.sun.net.ssl.checkRevocation=false
-Dkeycloak.truststore.disabled=true
-Dkeycloak.profile=COMMUNITY
-Dkeycloak.product.name=keycloak
-Dproduct.name=keycloak
-Dkeycloak.profile=preview
-Dkeycloak.profile.feature.account2=enabled
-Dkeycloak.profile.feature.account_api=enabled
-Dkeycloak.profile.feature.scripts=enabled
-Dkeycloak.profile.feature.device_activity=enabled
-Dkeycloak.profile.feature.tokenexchange=enabled
-Dkeycloak.profile.feature.ciba=enabled
-Dkeycloak.profile.feature.client_policies=enabled
-Dkeycloak.profile.feature.map_storage=disabled
-Dkeycloak.theme.welcomeTheme=keycloak
-Dkeycloak.theme.dir=../simple-theme/
-Dresources=../simple-theme/
Developing a Keycloak extension
To develop your extension, simply create a new maven module, e.g. simple-auth-extension in the keycloak-extension-playground.
Then add the module as a dependency to the keycloak-playground-server project.
The Server Development part of the Keycloak reference documentation contains additional resources and examples for developing custom Keycloak extensions.
Examples
The Keycloak project on github provides a useful set of examples for Keycloak extensions.
Simple Auth Extension
The simple-auth-extension project provides an example project that can be used as a starting point.
Simple Themes
The simple-themes example project demonstrates how to use custom themes with keycloak.