December 16 2020 by Keycloak Team
The world is changing fast and IT has been an important part of the engine. As companies start moving their infrastructure to the cloud, security becomes a key factor to make this journey a success.
We are proud to announce that Keycloak is now running on top of Quarkus, a Kubernetes and Cloud native Stack using the best of breed Java libraries and standards, to give to our users a cloud-friendly distribution with a strong focus on usability, scalability, and optimized for running in the hybrid cloud.
Also known as Keycloak.X, this new distribution format provides:
Reduced startup time
Lower memory footprint
Better Developer Experience
Focus on Usability
Keycloak is basically a Java application, currently running on top of the Wildfly (JEE) Application Server. So far, that is how we have been releasing the Keycloak Server for general use.
While Wildfly is probably the most optimized, easy-to-use, and best performing JEE Application Server, the requirements we have now for running in a more cloud-native fashion push us forward, where Quarkus, being a Java and Container-First stack, provides the more natural path for bringing to Keycloak all the capabilities that make Quarkus the perfect fit for running in the hybrid cloud with a focus on platforms like Kubernetes and Openshift.
For more information on Quarkus, check their web site at https://quarkus.io/.
On Quarkus, Keycloak is a regular Java application with a much simpler stack if compared to the Wildfly distribution.
With the new distribution users should expect a better experience when configuring and starting the server as well as when performing other common operations.
The introduction of a rich Command-Line Interface makes it a lot easier to install and use Keycloak.
The distribution is simpler with only a few directories, and the total size of the distribution is almost half the size of the current WildFly based distribution.
By leveraging Quarkus, Keycloak has significantly reduced server startup time, memory footprint (low RSS), as well as better runtime performance through Vert.x.
All these aspects are important when deploying in the hybrid cloud where resource usage should be optimized to provide the optimal runtime environment as well as reduced costs.
In conjunction with the Keycloak Operator, deploying Keycloak to the hybrid cloud should be easier.
The same goes for spinning up a simple container.
Quarkus provides a rich ecosystem for developers with an impressive number of integrations to different libraries.
Flexibility is probably one of the main characteristics of Keycloak and with Quarkus we expect to provide a much better experience for developers.
Download and extract the Keycloak.X distribution zip or tar.gz file from https://www.keycloak.org/downloads.
bin directory is where all binaries are located, basically the new Keycloak CLI and a few other utilities.
conf directory, as the name suggests, is where configuration files are located. You may be using the
keycloak.properties file within this directory to configure the server or not. More on that you’ll see later when we talk about configuration in more detail.
providers directory is where you should deploy your JAR files with your custom providers or themes jar.
One of the main requirements we have is to improve user experience when using the server for the very first time as well as in the long run when the server is running in production.
Common operations that people usually perform on the server are easier to perform and configuration should be simpler by providing good defaults and requiring the minimal set of options to have a running server.
The Keycloak CLI is a tool that you should now use to start and change configuration of the server. As any other CLI, it is self-descriptive with good documentation around its usage.
You are now able to look at the different actions you can perform, such as starting the server or exporting a realm, as well as go through the different configuration options you can set for each supported command.
We’re always looking for improvements in the CLI. Please, feel free to contact us with any suggestion you think that might help.
As previously mentioned, the default configuration imposes some conditions on how the server can be started.
One of the main conditions to successfully start the server is to configure HTTPS.
However, for development purposes Keycloak can be started in development mode.
For now, this mode is basically a configuration profile that allows you to run the server without HTTPS using local caches.
After executing the command above, the server should be available at http://localhost:8080/.
In the future, this mode will also lax on some configuration policies for realms that otherwise would not be allowed when running in production. For instance, using wildcards as valid redirect URIs for your clients.
Considering how critical an IAM solution is and the impact of misconfiguration on the overall security of the deployment, Keycloak is now distributed with the minimal configuration possible with a secure by default policy in mind.
The idea is to provide the bare minimum configuration options to run the server while imposing some key constraints on how the configuration should be set before running in production.
This is one of the main areas we are improving, and constantly trying to improve, where boilerplate configuration should be avoided through a small set of configuration options or with good defaults.
The different configuration options can now be set using a properties file, environment variables or as arguments through the Keycloak CLI.
You can easily check the available configuration options by running the
For more details about the configuration, check the Configuration Design document.
Configuration options are organized in two categories:
Those that can be set at runtime when starting the server
Those that can only be set when configuring the server through the
As an example, if you want to change the HTTP port to
8180, you may use:
However, for changing the database, you would need to first run the
config command before starting the server:
kc.sh config --db=postgres --db-username=******* --db-password=******* Kc.sh # then start the server
Basically, any configuration option you can set when configuring the server can also be set when starting the server, but the other way around is not true, and the database configuration is an example of that.
help option to check which properties can be set for each available command.
In the real world, you would configure a valid key pair and certificate, but you can use the command below to generate a self-signed certificate to understand how to setup HTTPS.
Just make sure to execute the following command at the root directory of the distribution:
keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore
The command above should create a
server.keystore file inside the
conf directory. By default, Keycloak will load the keys and certificates from this keystore if none was set.
After that, you can run the server as follows:
Database configuration is much simpler. You are able to change the database with only a few simple command-line arguments:
kc.sh config --db=postgres && kc.sh --db-username=**** --db-password=****
For each database we provide good defaults for JDBC URL, driver, database name, and dialect. So you don’t need to provide these options if you are happy with the defaults.
In the example above, the server connects to a PostgreSQL service running on localhost where the database name is
Of course, when running in production you usually need to customize the JDBC URL and other parameters , so you can start the server as follows:
kc.sh --db-url=jdbc:postgresql://<host>/<database> \ --db-username=****** \ --db-password=******
Or still rely on the default JDBC URL and set both host and database as follows:
kc.sh -Dkc.db.url.host=<host> \ -Dkc.db.url.database=<database> --db-username=****** --db-password=******
For the time being we are still using Infinispan and JGroups for clustering and HA deployments.
However, the configuration is now using Infinispan’s native configuration as opposed to using an abstraction as in the Wildfly Infinispan Subsystem. That should give much more flexibility in terms of configuration, support, as well as documentation.
The configuration is also simplified and you should get good defaults for the different platforms where the server is being deployed.
By default, clustering is enabled and you are ready to build a Keycloak cluster using the default configuration.
The default configuration is located in the
conf directory, the file name is
In the same directory, you also have a
cluster-local.xml file which configures all caches as local, no clustering. To use this configuration you run the following command:
You can define your own cache configuration by just creating a file in the
conf directory with the
cluster- prefix, just like
cluster-default files that we ship with the distribution.
We also provide some good defaults for specific platforms such as Kubernetes and EC2. For instance, to run a cluster in Kubernetes you could run the following command:
kc.sh -Djgroups.dns.query=<jgroups-ping-service>.<namespace>.<cluster-domain-suffix> --cluster-stack=kubernetes
The default configuration for these platforms is based on the defaults provided by Infinispan.
In the example above, the default configuration for Kubernetes is going to be based on UDP for node communication and DNS_PING for node discovery. Any parameter you can use to customize the default configuration can be obtained from Infinispan documentation.
The JAR files for custom providers and themes should be placed in the
However, in order to benefit from optimizations when installing custom providers, you should first run the
before starting the server:
kc.sh config kc.sh # then start the server
Basically, SPI implementations are resolved when configuring the server hence saving startup time and memory during startup. Once
you run the
config command to install your custom providers, they would be statically linked into the server.
To run Keycloak using Docker, you can use the following command:
docker run --name keycloak -p 8080:8080 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ quay.io/keycloak/keycloak-x \ start-dev
As expected, the container will run in development mode.
You can run the server in the same manner as when using the Keycloak.X distribution by passing any command-line argument.
To configure the container with any additional configuration that you want to persist into the server image, you can use the
--auto-config option as follows:
docker run --name keycloak -p 8080:8080 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ quay.io/keycloak/keycloak-x \ --auto-config \ --db=postgres -Dkc.db.url.host=$DB_HOST --db-username=keycloak --db-password=change_me --http-enabled=true
The command above should be enough to run a server using a PostgreSQL database listening on a given
DB_HOST. Once the container is created, subsequent restarts will never go through the configuration phase again but just start the server with the configuration previously defined.
The recommendation, however, is to always create your own image based on this image. By doing that, you are able to perform more customizations, such as deploying custom providers or themes, as well as improve the startup time by eliminating the configuration step.
For more details and examples, see https://github.com/keycloak/keycloak-containers/tree/master/server-x.
Here are a few numbers for a very simple comparison between Keycloak running on Quarkus and Wildfly.
Both distributions are running using OpenJDK 11, a PostgreSQL Database, and numbers are the average of 10 consecutive runs for each distribution.
The test scenario involves running the server for the very first time as well as when the database is already initialized.
The numbers should speak by themselves and people should expect these numbers improving on each Keycloak.X release.
However, it is not only about cutting down MBs but how to optimize memory usage. By running both servers using a 64MB heap, you should notice that when running on Wildfly you have a lot of garbage collection that eventually may cause the server to fail to start. While with Keycloak.X using the same heap size you are able to have a running server. Of course, using this heap size is not realistic depending on your use case but it gives a good idea on what you should expect from now on.
Regarding performance, in this first release our main focus was startup time and memory consumption. Runtime performance is a WIP and the results are promising due to the fact that Keycloak.X runs on top of Vert.X.
In general, we are still just on the beginning of the journey. Once Keycloak has the native distribution on Quarkus, we can expect even faster startup times, smaller memory consumption and overaly better performance with less resources.
This is only the beginning of our journey to provide a more cloud friendly experience for those using Keycloak.
Keycloak.X is a preview distribution and we are constantly improving it with the help of our community until it becomes our main distribution. We appreciate any feedback during this journey.
There are a lot of important work being done that complements Keycloak.X distribution such as:
Native Image Support
Improve Developer Experience
We would like to ask for your support and feedback to keep improving your experience on using Keycloak.
This was a result of a combined effort by the community and as such we would like to highlight and thank for all contributions we had.
A special thanks to:
And everybody that helped with the Configuration Design Document.