Wednesday, 21 September 2016

Keycloak 2.2.1.Final Released

Keycloak 2.2.1.Final has just been released. This release fixes an issue in the JavaScript adapter that was introduced in 2.2.0.Final, for more details see KEYCLOAK-3586.

To download the release go to the Keycloak homepage.

Tuesday, 20 September 2016

keycloak-server.json, RIP

All Keycloak Configuration in One Place

We have moved configuration of the Keycloak server from keycloak-server.json to standalone.xml, standalone-ha.xml, or domain.xml.  Which xml file you use will depend on how you run your server.  I'll reference standalone.xml from here on out, but configuration is the same for each file.

As of version 2.2.0, keycloak-server.json will no longer be shipped with Keycloak.  We do provide a conversion tool to help you make the switch.

So now, you can configure the entire server from a single xml file.  Keycloak server configuration is done in the same file where you configure data sources, socket bindings, logging, and clustering.

But there are other advantages...

Managing Keycloak with the Command Line Interface (CLI)

While you can still edit standalone.xml by hand just like you did with keycloak-server.json, you can now manage your configuration with the jboss-cli tool.  Whether you are managing a single Keycloak server or an entire domain of servers, you can use jboss-cli to configure Keycloak remotely.

But the best part about jboss-cli is scripting.  CLI commands can be run as a script for common configuration tasks.  This is all explained in the Keycloak documentation, complete with examples and recipes.

It's Clearer and Safer in XML

I don't want to start a flame war about config files in json vs. xml.  But for Keycloak configuration, XML is definitely a step forward.

First, your XML is validated via XML Schema along with a custom parser that understands exactly what Keycloak is expecting.  Keycloak won't boot if you have specified an invalid tag or value.  This was much less true when we used keycloak-server.json.  More bad data could get past the initial boot and cause problems later.

Second, our XML layout is much easier to understand than the old json.  Consider the old declaration for the realmCache provider:

Until I started on the "convert to standalone.xml" project, I didn't really know what the json fully meant.  From just looking at keycloak-server.json, it was hard to tell.

So here is what the json above actually means.  realmCache is the name of an SPI type.  Inside the realmCache declaration, you can specify a value for provider.  But that really means, "default provider name".  After that you can make zero or more provider declarations.  In this case, default is the name of a provider.  Inside the provider declaration, you can always specify if the provider is enabled.  At the same level as the enabled flag, you can also add other properties that only that particular provider understands.

Now consider the same declaration in its new XML format:
I think you'll agree, this is easier to understand.  It really doesn't need much explanation does it?


So like I said, all this is fully explained with lots of examples in the latest documentation.  And as always, feedback is much appreciated.

So long, and thanks for all the fish.


Thursday, 15 September 2016

Keycloak 2.2.0.Final Released

Keycloak 2.2.0.Final has just been released.

For the list of resolved issues check out JIRA and to download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide

Friday, 9 September 2016

Keycloak 2.2.0.CR1 Released

Keycloak 2.2.0.CR1 has just been released. The final release will follow next week if no major issues are reported. Few highlights of this release:

  • OpenID Connect certification - We've continued to work on our OpenID Connect implementation and we're now passing the basic, implicit, hybrid and config profiles. We'll get the dynamic profile sorted in the 2.3 release.
  • Server config moved to standalone/domain.xml - In the past some server configuration was done in keycloak-server.json and some in standalone/domain.xml. We've now moved all config to standalone/domain.xml and keycloak-server.json is now deprecated. This brings the option to use jboss-cli including offline scripts to automate configuration.
  • Manual DB migration - We've had automatic migration of the database for a long time, but we now have an option to have Keycloak write a SQL migration file instead of applying the changes directly.
  • Fuse adapter download - There is now a Fuse adapter download that makes it possible to install Keycloak support in Fuse without access to external Maven repository.
  • Hot deployment of providers - It's now possible to hot deploy custom providers from within a JEE deployment. We've not had the chance to write documentation around this yet and it could do with a bit more testing so consider it a preview feature. Take a look at the user-storage-jpa provider example though, it's great stuff!
  • Identity Provider Authenticator - In the past redirecting to identity providers was hardcoded in the Keycloak code, we've now refactored this into a new authenticator.
  • Norwegian, Japanese and Lituanian translations - Keycloak now comes with 11 translations. 10 of them contributed and maintained by our excellent community.

For the full list of issues resolved check out JIRA and to download the release go to the Keycloak homepage.

Wednesday, 10 August 2016

Keycloak 2.1.0.Final released

Keycloak 2.1.0.Final has just been released. This release only contains one fix related to Authorization services since 2.1.0.CR1 release.

For the list of resolved issues check out JIRA and to download the release go to the Keycloak homepage. Before you upgrade refer to the migration guide

Wednesday, 3 August 2016

Keycloak 2.1.0.CR1 released

Keycloak 2.1.0.CR1 has just been released. The final release will follow next week if no major issues are reported. Few highlights of this release:

  • Password Policy SPI - Now it's possible to plug your own implementation of password policy. This is useful if available builtin policies are not sufficient for you.
  • Jetty 9.3 adapter - Allow you to secure your applications deployed on Jetty 9.3 server.
  • Authorization fixes & improvements - There are lots of fixes and improvements in authorization services, which were recently added in 2.0 release. It really worth to check this out and eventually provide us some feedback.
  • Better OpenID Connect interoperability - There are lots of minor fixes related to OpenID Connect support.

For the full list of issues resolved check out JIRA and to download the release go to the Keycloak homepage.

Thursday, 14 July 2016

Loading Providers and Themes from Maven Repository

Keycloak has a number of SPIs where you can provide your own providers to hook in custom behavior. The custom providers can be deployed by copying the JAR into the providers directory or it can be deployed as a module which provides greater control of the classpath for the provider.

Keycloak also has the ability to create themes to customize login pages and account management console. These can either be copied to the themes directory or they can also be deployed as modules.

In this post I'll show how you can load custom providers and themes from a Maven repository. This could either be from the local Maven repository or a remove Maven repository.

Loading providers and themes from a Maven repository can be useful for development and also as a distribution mechanism, especially when Keycloak is clustered and you want to make sure all nodes have the same providers and themes.

Before going through these examples make sure you have the Keycloak server installed. If you don't you can get it from We'll refer to the directory where you have the Keycloak server as KEYCLOAK_HOME.

You also need to download the Keycloak examples as we'll use one of the example providers. You can get them from Then extract the archive somewhere. We'll refer to the directory with the examples as EXAMPLES_HOME.

Deploying Provider as a Module

Before we load the example provider from Maven we'll first deploy it as a module. There's two reasons for this. Firstly, we'll make sure that we have everything configured correctly and that the provider is working as expected. Secondly, loading the provider from Maven is actually a feature of the JBoss Modules which is what provides the support for modules in the first place.

To deploy the provider go through the following steps: Stop the Keycloak server, then build and install the example provider with the following steps:

cd $EXAMPLES_HOME/providers/event-listener-sysout
mvn clean install
$KEYCLOAK_HOME/bin/ --command="module add \
 --name=org.keycloak.examples.event-sysout \
 --resources=target/event-listener-sysout-example.jar \
This will create a module for the example provider. Next we need to configure Keycloak to load providers from the. Open $KEYCLOAK_HOME/standalone/configuration/keycloak-server.json in a text editor and update the providers section to:
"providers": [

Once you've done that start the Keycloak server and login to the Keycloak Admin Console. Select Events from the menu, then click on the Config tab. Remove the jboss-logging listener, add sysout and click on Save. The sysout event listener is the custom event listener provider we just deployed as a module.

To check that the provider is working as expected logout, then login again. You should see some events on the standard output from the Keycloak server:

10:52:01,844 INFO  [stdout] (default task-50) EVENT: type=LOGOUT..
10:52:04,792 INFO  [stdout] (default task-54) EVENT: type=LOGIN..
10:52:04,976 INFO  [stdout] (default task-57) EVENT: type=CODE_TO_TOKEN..

Loading Provider from the Local Maven Repository

Loading the provider from the local Maven Repository is very easy. In the previous steps we already built and installed the provider into the local Maven Repository so we just need to make the module use the Maven artifact instead of the JAR directly from the module.

First stop the Keycloak server. Then delete the file modules/org/keycloak/examples/event-sysout/main/event-listener-sysout-example.jar. Next open $KEYCLOAK_HOME/modules/org/keycloak/examples/event-sysout/main/module.xml in a text editor and change it to:

<?xml version="1.0" ?>

<module xmlns="urn:jboss:module:1.1" name="org.keycloak.examples.event-sysout">

        <artifact name="org.keycloak:event-listener-sysout-example:2.0.0.Final"/>

        <module name="org.keycloak.keycloak-core"/>
        <module name="org.keycloak.keycloak-server-spi"/>

Note: if you are not using version 2.0.0.Final of the examples remember to change the version.

You can now start the server again and try login. You'll hopefully see that the events are still being printed to standard out. As you deleted the JAR from the module directory the provider is now being loaded from the local Maven repository.

Loading Provider from a Remote Maven Repository

Let's start by creating a Nexus repository we can use to deploy the provider to. We'll use Docker and the official Sonatype Nexus image. You can obviously use any Maven Repository you want, but for the sake of completeness we'll include steps to setup the repository as well. Make sure you have Docker installed then run: docker run -d -p 8081:8081 sonatype/nexus After a while you'll have a Sonatype Nexus Maven Repository running at http://localhost:8081. You can login to this with username admin and password admin123. Now let's deploy the example provider to this repository. First edit the file .m2/settings.xml in your home directory and add the credentials for the Sonatype Nexus repository:

Then edit $EXAMPLES_HOME/providers/event-listener-sysout/pom.xml. Add a distributionManagement element:
        <name>Local Nexus</name>
Also, you need to enable the deploy plugin as it's been disabled in the parent POM:


Now you can run the following to deploy the provider to the repository:

mvn deploy

Check that it was indeed deployed by opening http://localhost:8081/content/repositories/releases/org/keycloak/event-listener-sysout-example/.

Stop Keycloak. To make sure the provider can indeed be retrieved from the remote Maven repository delete the directory .m2/repository/org/keycloak/event-listener-sysout-example. This will remove the provider from the local Maven repository. You can try to start the Keycloak server again, but you will get a warning. To enable the remote Maven repository start the Keycloak server with:

bin/ \

Keycloak should now start successfully and should download the provider from the remote Maven repository. It'll get cached in the local Maven repository so it won't have to retrieve it every time Keycloak is started.