Configuring Keycloak

An overview of the server configuration

This guide describes underlying core concepts of Keycloak configuration. It includes configuration guidelines for optimizing Keycloak for faster startup and low memory footprint.

Server options

You can view the server options by adding the help option for individual commands:

Listing build options
bin/kc.[sh|bat] build --help
Listing configuration options
bin/kc.[sh|bat] start --help

Alternatively, you can see the server options at All configuration .

Server options are loaded from different sources in a specific order and they use different formats. If an option is defined in different sources, the order of resolution is the order in the following table:

Source Format

CLI

--db-url-host=<value>

Environment Variable

KC_DB_URL_HOST

conf/keycloak.conf

db-url-host=<value>

Given the db-url-host option as an example, you would set this property as follows:

Command-line argument
bin/kc.[sh|bat] start --db-url-host=mykeycloakdb
Environment variable
export KC_DB_URL_HOST=mykeycloakdb
conf/keycloak.conf
db-url-host=mykeycloakdb

The configuration source and the corresponding format you should use is use-case specific. That decision depends on the platform where the server is deployed and the runtime optimizations you are seeking. For instance, if you deploy the server into Kubernetes, you would probably rely on environment variables to configure the server. However, you are not limited to a single configuration source or format.

Configuration commands and stages

The server options are narrowed to a specific command or configuration stage. The goal is to perform a series of optimizations in a specific order to achieve optimal startup and runtime performance. This configuration occurs in two stages:

First stage

Configuration performed before starting the server in order to build an optimized server image for use at runtime

Second stage

Configuration performed as part of starting the server

First stage: Build an optimized Keycloak image

The first stage involves running the build command and setting any build option available from this command to configure the server.

The configuration options at All configuration include options that are marked with a tool icon. This icon indicates they are build options. Build options take effect only when you apply them to the build command.

You can also check which options require a build by looking at the help message of the build command:

bin/kc.[sh|bat] build --help

The build command can produce an immutable and optimized server image, which is similar to building a container image. In addition to persisting build options, this command also performs optimizations for the best startup and runtime performance. The result is that much processing for starting and running the server is performed before starting Keycloak, so Keycloak is able to start up and run faster later on.

The following are some optimizations performed by the build command:

  • Closed-world assumption about installed providers, which means that no need exists to re-create the registry at every startup

  • Configuration files are pre-parsed to reduce I/O when starting the server

  • Database specific resources are configured and prepared to run against a certain database vendor

  • By persisting build options into the server image, the server does not perform any additional step to interpret configuration options and (re)configure itself

Run the build command to set the database to PostgreSQL before startup:
bin/kc.[sh|bat] build --db=postgres

Once you run the build command, you do not need to set the same build options when you start the server.

Second stage: Starting Keycloak

The second stage involves starting the server by using the start command and including configuration options with the appropriate values.

Run the start command to start the server while setting various database options
bin/kc.[sh|bat] start --db-url-host=keycloak-postgres --db-username=keycloak --db-password=change_me --hostname mykeycloak.acme.com

Note that if you invoke commands containing special shell characters such as ; using the CLI, you need to escape those characters. In that situation, you might choose to use the keycloak.conf file to set configuration options instead.

Optimization by using a configuration file

Most optimizations to startup and memory footprint can be achieved by using the build command. Additionally, you can use the conf/keycloak.conf file to set configuration options. Using this file avoids some necessary parsing steps when providing configuration options using the CLI or environment variables.

Set any build option
bin/kc.[sh|bat] build --db=postgres
Set any configuration option to conf/keycloak.conf
db-url-host=keycloak-postgres
db-username=keycloak
db-password=change_me
hostname=mykeycloak.acme.com
Start the server
bin/kc.[sh|bat] start

By using the keycloak.conf file, the server can omit some steps at startup. As a result, the server starts faster.

The auto-build option: automatic detection when the server needs a build

Under certain circumstances, you might prefer to allow a longer startup time in favor of updating the values of build options when starting the server. Using the auto-build option, you can perform the two configuration stages by using a single command. Note that using auto-build is very likely to double the startup time for Keycloak. For most environments, this approach is not optimal.

You start the server by entering the following command:

Using the auto-build option
bin/kc.[sh|bat] start --auto-build --db postgres --db-url-host keycloak-postgres --db-username keycloak --db-password change_me --hostname mykeycloak.acme.com

By including the auto-build option, the server calculates the build options that have changed and runs the build command, if necessary, before starting the server.

Configuring the server by using configuration files

By default, the server always fetches configuration options from the conf/keycloak.conf file. For a new installation, this file holds only the recommended settings for running in production and those settings are commented out.

You can also specify a different configuration file by using the `[-cf|--config-file] option by entering the following command:

Running the build command using a custom configuration file
bin/kc.[sh|bat] -cf myconfig.conf build
Running the start command using a custom configuration file
bin/kc.[sh|bat] -cf myconfig.conf start

Changes to any build option defined in the keycloak.conf file that is targeted for the build command are ignored if the value differs from the value for the last build command. In this case, make sure you run the build command again so that any build option is updated accordingly.

Development versus production mode

The server supports the following operating modes:

Development mode

This mode is activated every time you run the start-dev command. In this mode, some key configuration options are set to make it possible to start the server for development purposes without the burden of having to define additional settings that are mandatory for production.

Production mode

This mode is activated when you run the build or start command. Use this mode to set any configuration option that is needed for deploying Keycloak in production.

By default, the configuration options for the production mode are commented out in the conf/keycloak.conf. These examples are meant to give you an idea about the main settings to consider when running in production.

Setup of the initial admin user

The initial admin user can be added manually using the web frontend when accessed from localhost or automatically using environment variables.

To add the initial admin user using environment variables, set KEYCLOAK_ADMIN for the initial admin username and KEYCLOAK_ADMIN_PASSWORD for the initial admin password. Keycloak uses them at the first startup to create an initial user with administration rights. Once the first user with administrative rights exists, you can use the UI or the command line tool kcadm.[sh|bat] to create additional users.

Using placeholders

You are able to use placeholders to resolve the configuration option value from environment variables.

Using a placeholder to resolve the host from an environment variable
db-url-host=${MY_DB_HOST}

You are also able to default to a specific value if the environment variable can not be resolved:

Setting a default value
db-url-host=${MY_DB_HOST:mydb}

Unsupported server options

In most cases, the available options from the server configuration should suffice to configure the server. However, you might need to use properties directly from Quarkus to enable a specific behavior or capability that is missing in the keycloak configuration.

As much as possible, avoid using properties directly from Quarkus. If your need is essential, consider opening an issue first and help us to improve the server configuration.

If that’s not possible for you, you can configure the server using Quarkus properties, perform the following steps:

  1. Create a conf/quarkus.properties file and define any property you need.

For a complete list of Quarkus properties, see the Quarkus documentation .

When a raw quarkus property is a runtime property, it is also handled as runtime property for keycloak. When a quarkus property is a build time property, you have to invoke a new keycloak build first for the property to apply.

Note that some quarkus properties are mapped to internally by the Keycloak configuration, for example quarkus.http.port and similar properties that are needed to configure Keycloak. If the property is used by Keycloak, and you define the same property key in the quarkus.properties file, the keycloak configuration value takes precedence over the raw quarkus configuration value, so the value you set in quarkus.properties will be ignored when there is a value in the actual Keycloak configuration.

On this page