Configuring Keycloak

This guide explains the configuration methods for Keycloak and how to start and apply the preferred configuration. It includes configuration guidelines for optimizing Keycloak for faster startup and low memory footprint.

Configuration Sources for Keycloak

Keycloak loads the configuration from four different configuration sources:

command-line parameters
environment variables
user-created .conf file
keycloak.conf file located in the conf directory.

Configuration sources have a descending ordinal: command-line parameters take precedence over environment variables. Environment variables take precedence over options set by using a specific configuration file. Options from a specific config file take precedence over options defined in conf/keycloak.conf. When the same configuration key is found in multiple configuration sources, the applied value is taken from the configuration source with the highest ordinal.

Example: Configuring the db-url-host parameter.

Source	Format
CLI	--db-url=cliValue
Environment Variable	KC_DB_URL=envVarValue
Configuration file	db-url=confFileValue

Source

Format

CLI

--db-url=cliValue

Environment Variable

KC_DB_URL=envVarValue

Configuration file

db-url=confFileValue

In the example above, the db-url value is set in all three configuration sources. The actual value that is used at startup would be the cliValue. If --db-url=cliValue is not used, the used value would be KC_DB_URL=envVarValue, and last but not least the db-url=confFileValue would be used when no environment variable with the same Key is present. When this value is specified in a user defined configuration file and in conf/keycloak.conf, the value from the user defined configuration file takes precedence.

Configuration Format

The configuration follows a "unified-per-source" format, that is easily translatable from one configuration source to another:

Command-line parameter format

Values for the command-line are following the --<key-with-dashes>=<value> format. For some values, there’s also a -<abbreviation>=value shorthand.

Environment variable format

Values for environment variables are following the uppercased KC_<key_with_underscores>=<value> format.

Configuration file format

Values that go into the configuration file are following the <key-with-dashes>=<value> format.

You can easily translate a Key/Value pair from one configuration source to the other.

You will find the relevant configuration options for a specific guide in all three formats on the table at the bottom of each guide. You can find all available options at the All configuration guide.

The configuration source and the corresponding format you should use is use-case specific.

Example - Configure `db-url-host` on different configuration sources:

The following example shows how the configuration for the db url host looks for all three configuration sources:

command-line parameter

bin/kc.[sh|bat] start --db-url-host=mykeycloakdb

environment variable

export KC_DB_URL_HOST=mykeycloakdb

conf/keycloak.conf

db-url-host=mykeycloakdb

Using environment variables for configuration values

It is possible to use placeholders to resolve an environment specific value from environment variables inside the keycloak.conf file by using the ${ENV_VAR} syntax:

db-url-host=${MY_DB_HOST}

To specify a fallback value in case the environment variable can not be resolved, use a ::

db-url-host=${MY_DB_HOST:mydb}

Configuring the server using a specific configuration file

By default, the server always fetches configuration options from the conf/keycloak.conf file. For a new installation, this file holds only commented settings as an idea of what you want to set when running in production.

You can also specify an explicit configuration file location using the [-cf|--config-file] option by invoking the following command:

bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start

Using the command-line help

Keycloak is packed with a CLI that helps you to configure Keycloak. To find out about the available configuration, invoke the following command:

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

Alternatively, you can find all server options at the All configuration guide.

Using raw Quarkus properties

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

If possible, avoid using properties directly from Quarkus. These are considered unsupported by Keycloak. If your need is essential, consider opening an enhancement request first and help us to improve Keycloak’s configuration to fit your needs.

If that’s not possible, you can configure the server using raw Quarkus properties:

Create a quarkus.properties file in the conf directory and define any property you need.

For a complete list of Quarkus properties, see the Quarkus documentation. Be aware that Keycloak uses a subset of quarkus extensions, so not all properties will be available.

When a quarkus property is a runtime property (no lock icon shown in the quarkus guide), it is also handled as runtime property for Keycloak. When a quarkus property is a build time property, you have to invoke a build for the property to be applied. See the sections below for further information around the build command.

Note that some quarkus properties are mapped 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, defining the same underlying property key in quarkus.properties will have no effect, as the keycloak configuration value takes precedence over the quarkus property value.

Starting Keycloak

Keycloak can be started in two operating modes, development mode and production mode. Both modes offer a different set of defaults for the environment they are intended to be used.

Starting Keycloak in development mode

The development mode is targeted for people trying out Keycloak the first time and get it up and running quickly. It also offers convenient defaults for developers, for example to develop a new Keycloak theme.

The development mode is started by invoking the following command:

bin/kc.[sh|bat] start-dev

Defaults

The development mode sets the following default configuration:

HTTP is enabled
Strict hostname resolution is disabled
Cache is set to local (No distributed cache mechanism used for high availability)
Theme- and Template-caching is disabled

Starting Keycloak in production mode

The production mode is targeted for deployments of Keycloak into production environments and follows a "secure by default" principle.

The production mode is started by invoking the following command:

bin/kc.[sh|bat] start

Without further configuration, this command will not start Keycloak and show you an error instead. This is done on purpose, because Keycloak follows a "secure by default" principle in this mode and expects to have a hostname setup and a HTTPS/TLS setup available when started in production mode.

Defaults

The production mode sets the following defaults:

HTTP is disabled as transport layer security (HTTPS) is essential
Hostname configuration is expected
HTTPS/TLS configuration is expected

Make sure to follow the steps outlined in the Configuring Keycloak for production guide before deploying Keycloak to production environments.

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

Setup of the initial admin user

The initial admin user can be added manually using the web frontend. It needs to be accessed using a local connection (localhost) or using environment variables:

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

If the initial administrator already exists and the environment variables are still present at startup, an error message stating the failed creation of the initial administrator is shown in the logs. Keycloak ignores the values and starts up correctly.

Optimize the Keycloak startup

It is highly recommended to optimize Keycloak for better startup times and memory consumption before deploying into production environments. This section shows you how to apply a set of optimizations for Keycloak to get the best performance and runtime behavior possible.

Create an optimized Keycloak build

By default, when the start or start-dev commands are used, Keycloak runs a build command under the covers for convenience reasons. This build command performs a set of optimizations to achieve an optimized startup- and runtime-behavior. The build process can take some time, usually a few seconds. Especially when running Keycloak in containerized environments like Kubernetes or OpenShift, startup time is important. So in order to avoid the time that gets lost when running a build as part of Keycloaks first startup, it is possible and recommended to invoke a build explicitly before starting up, for example as a separate step in a CI/CD pipeline.

First step: Run a build explicitly

To run a build, invoke the following command:

bin/kc.[sh|bat] build <build-options>

As you may notice, the command above shows build options that should be invoked. Keycloak distinguishes between build options, that are usable when invoking the build command, and configuration options, that are usable when starting up the server.

For a non-optimized startup of Keycloak, this distinction has no effect, but when a build is invoked beforehand, there’s only a subset of Options available to the build command. The reason is, that build options get persisted into Keycloaks classpath, so configuration for e.g. credentials like db-password must not get persisted for security reasons.

Build options are marked in the All configuration guide with a tool icon. Find available build options either by looking at the All configuration page with build options selected or by invoking the following command:

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

Example: Run the build command to set the database to PostgreSQL before startup:

bin/kc.[sh|bat] build --db=postgres

Second step: Start Keycloak using `--optimized`

After a successful build, you can start Keycloak and turn off the default startup behavior by invoking the following command:

bin/kc.[sh|bat] start --optimized <configuration-options>

The --optimized parameter tells Keycloak to assume a pre-built, already optimized Keycloak image is used. As a result, Keycloak avoids checking for and running a build directly at startup to save the time to walk through this process.

You can invoke all configuration options at startup - these are all options in the All configuration guide that are not marked with a tool icon.

If a build option is found at startup with an equal value to the value used when invoking the build, it gets silently ignored when using the --optimized flag. If it has a different value than the value used when a build was invoked, a warning is shown in the logs and the previously built value is used. In order for this value to take effect, you have to run a new build before starting.

The following example shows how to create an optimized build, then start Keycloak using the --optimized parameter:

Create an optimized build

Set build option for the postgresql database vendor using the build command

bin/kc.[sh|bat] build --db=postgres

Set the runtime configuration options to keycloak.conf

Set configuration options for postgres inside conf/keycloak.conf

db-url-host=keycloak-postgres
db-username=keycloak
db-password=change_me
hostname=mykeycloak.acme.com
https-certificate-file

Start the server with the optimized parameter

bin/kc.[sh|bat] start --optimized

Most optimizations to startup and runtime behavior can be achieved by using the build command. By using the keycloak.conf file as a source for configuration options, Keycloak avoids some steps at startup that are needed when invoking the configuration using the command line, for example initialising the CLI itself. As a result, the server starts up even faster.

Underlying concepts

This section gives an overview around the underlying concepts Keycloak uses, especially when it comes to optimizing the startup.

Keycloak uses the Quarkus framework and it’s re-augmentation/mutable-jar approach under the covers. This process is started when a build is invoked.

The following are some optimizations performed by the build command:

A new closed-world assumption about installed providers is created, meaning that no need exists to re-create the registry and initialize the factories at every Keycloak 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

You can read more at the specific Quarkus guide