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 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.
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.
It is possible to use placeholders to resolve an environment specific value from environment variables inside the keycloak.conf file by using the `${r"++${ENV_VAR}++"}` syntax:
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.
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 https://github.com/keycloak/keycloak/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.yml[enhancement request] first and help us
to improve Keycloak's configuration to fit your needs.
For a complete list of Quarkus properties, see the https://quarkus.io/guides/all-config[Quarkus documentation]. Be aware that Keycloak uses a https://github.com/keycloak/keycloak/blob/main/quarkus/runtime/pom.xml#L17[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.
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.
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.
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.
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.
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.
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.
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.
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.
Find available build options either by looking at the https://www.keycloak.org/server/all-config?f=build[All configuration page with build options selected] or by invoking the following command:
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 options are the ones in <@links.server id="all-config"/> 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.
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.
* 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
