Red Hat
Sep 20, 2016
by Stan Silvert

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.

Original Post