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.



  1. Management of Keycloak will be easier now. Thank you!!

  2. Beauty is in the eye of the beholder I guess... I find the non-xml version to be more understandable :-)

    1. True, but you have to deal with the XML config file in either case and at least now there's a single place ;)

  3. Hi,

    " We do provide a conversion tool to help you make the switch."

    Where is this tool and how do we use it?

    1. The migration guide explains this:

  4. {
    "spi": {
    "realmCache": {
    "default-provider": "default",
    "provider": {
    "default": {
    "enabled": true,
    "properties": {
    "propName": "propValue"

    It really was the change in structure that made it more readable, not the change from JSON to XML.

  5. This was an unfortunate decision. First off, I love everything about Keycloak, except for JBoss. JBoss is *not* easy configure from my perspective. I'd rather have a WAR I can drop into any servlet container. Now, it appears I won't have that luxury. Also consider now you have a dichotomy between client config (keycloak.json) and server config (standalone.xml).


Please only add comments directly associated with the post. For general questions use the Keycloak user mailing list.