🕷️ Crawler Inspector

[](https://www.keycloak.org/) [](https://github.com/keycloak/keycloak) - [Guides](https://www.keycloak.org/guides) - [Docs](https://www.keycloak.org/documentation) - [Downloads](https://www.keycloak.org/downloads) - [Community](https://www.keycloak.org/community) - [Blog](https://www.keycloak.org/blog) [](https://github.com/keycloak/keycloak) 1. [Guides](https://www.keycloak.org/guides) 2. [Server](https://www.keycloak.org/guides#server) 3. Configuring Keycloak # Configuring Keycloak Configure and start 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. ## Configuring sources for Keycloak Keycloak loads the configuration from four sources, which are listed here in order of application. 1. Command-line parameters 2. Environment variables 3. Options defined in the `conf/keycloak.conf` file, or in a user-created configuration file. 4. Sensitive options defined in a user-created Java KeyStore file. When an option is set in more than one source, the one that comes first in the list determines the value for that option. For example, the value for an option set by a command-line parameter has a higher priority than an environment variable for the same option. ### Example: Configuring the db-url-host parameter The following example shows how the `db-url` value is set in four configuration sources: | Source | Format | |---|---| | Command line parameters | `--db-url=cliValue` | | Environment variable | `KC_DB_URL=envVarValue` | | Configuration file | `db-url=confFileValue` | | Java KeyStore file | `kc.db-url=keystoreValue` | Based on the priority of application, the value that is used at startup is `cliValue`, because the command line is the highest priority. If `--db-url=cliValue` had not been used, the applied value would be `KC_DB_URL=envVarValue`. If the value were not applied by either the command line or an environment variable, `db-url=confFileValue` would be used. If none of the previous values were applied, the value `kc.db-url=keystoreValue` would be used due to the lowest priority among the available configuration sources. Keycloak configuration options often map to lower-level Quarkus or spi options. We refer to these as first-class and second-class configuration respectively. There are startup warnings to indicate if you are using a second-class option. For example if you try to directly use `quarkus.http.port`, you will be warned to use `kc.http-port` instead. ## Formats for configuration The configuration uses a *unified-per-source* format, which simplifies translation of a key/value pair from one configuration source to another. Note that these formats apply to spi options as well. Command-line parameter format Values for the command-line use the `--<key-with-dashes>=<value>` format. For some values, an `-<abbreviation>=<value>` shorthand also exists. Environment variable format Values for environment variables use the uppercased `KC_<key_with_underscores>=<value>` format. Alternatively, the `KCRAW_` prefix can be used instead of `KC_` to preserve values containing `$` characters — see [Preserving literal values with the KCRAW\_ prefix](https://www.keycloak.org/server/configuration#kcraw-prefix). Configuration file format Values that go into the configuration file use the `<key-with-dashes>=<value>` format. KeyStore configuration file format Values that go into the KeyStore configuration file use the `kc.<key-with-dashes>` format. `<value>` is then a password stored in the KeyStore. At the end of each configuration guide, look for the *Relevant options* heading, which defines the applicable configuration formats. For all configuration options, see [All configuration](https://www.keycloak.org/server/all-config). Choose the configuration source and format that applies to your use case. ### Example - Alternative formats based on configuration source The following example shows the configuration format for `db-url-host` for 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 ``` ### Formats for command-line parameters Keycloak is packed with many command line parameters for configuration. To see the available configuration formats, enter the following command: ``` bin/kc.[sh|bat] start --help ``` Alternatively, see [All configuration](https://www.keycloak.org/server/all-config) for all server options. ### Format for referencing environment variables You can 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} ``` In case the environment variable cannot be resolved, you can specify a fallback value. Use a `:` (colon) as shown here before `mydb`: ``` db-url-host=${MY_DB_HOST:mydb} ``` ### Format to include 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 entering the following command: ``` bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start ``` Setting that option makes Keycloak read configuration from the specified file instead of `conf/keycloak.conf`. ### Setting sensitive options using a Java KeyStore file Thanks to Keystore Configuration Source you can directly load properties from a Java KeyStore using the `[--config-keystore]` and `[--config-keystore-password]` options. Optionally, you can specify the KeyStore type using the `[--config-keystore-type]` option. By default, the KeyStore type is `PKCS12`. The secrets in a KeyStore need to be stored using the `PBE` (password-based encryption) key algorithm, where a key is derived from a KeyStore password. You can generate such a KeyStore using the following `keytool` command: ``` keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v ``` After executing the command, you will be prompted to **Enter the password to be stored**, which represents a value of the `kc.db-password` property above. When the KeyStore is created, you can start the server using the following parameters: ``` bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=keystorepass --config-keystore-type=PKCS12 ``` ### Format for raw Quarkus properties In most cases, the available configuration options should suffice to configure the server. However, for a specific behavior or capability that is missing in the Keycloak configuration, you can use properties from the underlying Quarkus framework. If possible, avoid using properties directly from Quarkus, because they are unsupported by Keycloak. If your need is essential, consider opening an [enhancement request](https://github.com/keycloak/keycloak/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.yml) first. This approach helps us improve the configuration of Keycloak to fit your needs. If an enhancement request is not possible, you can configure the server using raw Quarkus properties: 1. Create a `quarkus.properties` file in the `conf` directory. 2. Define the required properties in that file. You can use only a [subset](https://github.com/keycloak/keycloak/blob/main/quarkus/runtime/pom.xml#L17) of the Quarkus extensions that are defined in the [Quarkus documentation](https://quarkus.io/guides/all-config). Also, note these differences for Quarkus properties: - A lock icon for a Quarkus property in the [Quarkus documentation](https://quarkus.io/guides/all-config) indicates a build time property. You run the `build` command to apply this property. For details about the build command, see the subsequent sections on optimizing Keycloak. - No lock icon for a property in the Quarkus guide indicates a runtime property for Quarkus and Keycloak. You can also store Quarkus properties in a Java KeyStore. ### Using special characters in values Keycloak depends upon Quarkus and MicroProfile for processing configuration values. Be aware that value expressions are supported. For example, `${some_key}` evaluates to the value of `some_key`. To disable expression evaluation, the `\` character functions as an escape character. In particular, it must be used to escape the usage of `$` characters when they appear to define an expression or are repeated. For example, if you want the configuration value `my$$password`, use `my\$\$password` instead. Note that the `\` character requires additional escaping or quoting when using most unix shells, or when it appears in properties files. For example, bash single quotes preserve the single backslash `--db-password='my\$\$password'`. Also, with bash double quotes, you need an additional backslash `--db-password="my\\$\\$password"`. Similarly in a properties file, backslash characters must also be escaped: `kc.db-password=my\\$\\$password` Windows-specific considerations When specifying Windows file paths in configuration values, backslashes must also be escaped. For example, if you want to specify the path `C:\path\to\file`, you should write it as `C:\\path\\to\\file`. Alternatively, you can use forward slashes which don’t need escaping: `C:/path/to/file`. When using PowerShell and your values contain special characters like commas, use single quotes around double quotes: ``` .\kc.bat start --log-level='"INFO,org.hibernate:debug"' ``` PowerShell handles quotes differently. It interprets the quoted string before passing it to the `kc.bat` script, removing the outer quote characters. Therefore, an extra layer of quotes is needed to preserve the value structure. Otherwise, the comma would be interpreted as a delimiter. In Windows CMD, you can use double quotes directly. When manual escaping is not feasible (like when a password is injected by a secrets manager and you cannot control the value), use the `KCRAW_` prefix described in the next section. ### Preserving literal values with the KCRAW\_ prefix When setting configuration values, Keycloak (via SmallRye Config) evaluates expressions such as `${some_key}` and collapses `$$` to `$`. This means passwords or secrets containing `$` characters may be silently modified. While the `\` escaping described above works for values you control directly, it is not always practical - for example, when a secrets manager or orchestration tool injects the value and you cannot add escape characters. In these cases, use the `KCRAW_` prefix instead of `KC_` for any environment variable whose value must be preserved exactly as written. Keycloak automatically escapes `$` characters in `KCRAW_` values so that expression evaluation preserves the original value. Example: Setting a database password containing special characters ``` # Standard prefix — the value will be modified by expression evaluation: export KC_DB_PASSWORD='my$$pa$\{vault}word' # Result: "$$" is collapsed to "$" and "$\{vault}" is evaluated as an # expression, producing "my$paword" or an error # Raw prefix — the value is preserved exactly as written: export KCRAW_DB_PASSWORD='my$$pa$\{vault}word' # Result: the password is used as-is: my$$pa$\{vault}word ``` | | | |---|---| | | The `KCRAW_` prefix applies only to environment variables, where shell quoting rules make escaping of `$` unreliable. Other configuration sources are subject to their own format escaping mechanisms and their values are still treated as expressions. You cannot set both `KC_<KEY>` and `KCRAW_<KEY>` for the same configuration key. If both are present, Keycloak will fail to start and report a configuration error. Apart from escaping `$` characters, `KCRAW_` variables behave identically to their `KC_` counterparts: the same key mapping and priority rules apply. | ### Formats for environment variable keys with special characters Non-alphanumeric characters in your configuration key must be converted to `_` in the corresponding environment variable key. Environment variables are converted back to normal option keys by lower-casing the name and replacing `_` with `-`. Logging wildcards are the exception as `_` in the category is replaced with `.` instead. Logging categories are commonly class / package names, which are more likely to use `.` rather than `-`. | | | |---|---| | | Automatic mapping of the environment variable key to option key may not preserve the intended key | For example `kc.log-level-package.class_name` will become the environment variable key `KC_LOG_LEVEL_PACKAGE_CLASS_NAME`. That will automatically be mapped to `kc.log-level-package.class.name` because `_` in the logging category will be replaced by `.`. Unfortunately this does not match the intent of `kc.log-level-package.class_name`. You have a couple of options in this case: - create an entry in your `keycloak.conf` file that references an environment variable of your choosing. e.g. `kc.log-level-package.class_name=${CLASS_NAME_LEVEL}`. See more on referencing environment variables in [Format for referencing environment variables](https://www.keycloak.org/server/configuration#_format_for_referencing_environment_variables). - or in situations where modifying the `keycloak.conf` may not be easy, you can use a pair of environment variables `KC_UNIQUEIFIER=value` and `KCKEY_UNIQUEIFIER=key`, e.g. `KC_MYKEY=debug` and `KCKEY_MYKEY=log-level-package.class_name`, or `KC_LOG_LEVEL_PACKAGE_CLASS_NAME=debug` and `KCKEY_LOG_LEVEL_PACKAGE_CLASS_NAME=log-level-package.class_name` ## Starting Keycloak You can start Keycloak in `development mode` or `production mode`. Each mode offers different defaults for the intended environment. ### Starting Keycloak in development mode Use development mode to try out Keycloak for the first time to get it up and running quickly. This mode offers convenient defaults for developers, such as for developing a new Keycloak theme. | | | |---|---| | | By default, when you start Keycloak in development mode on Windows Subsystem For Linux, the server binds to all network addresses (`0.0.0.0`). This means your instance may be accessible from other machines on your network. | To start in development mode, enter the following command: ``` bin/kc.[sh|bat] start-dev ``` Defaults 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-caching and template-caching is disabled ### Starting Keycloak in production mode Use production mode for deployments of Keycloak in production environments. This mode follows a *secure by default* principle. To start in production mode, enter the following command: ``` bin/kc.[sh|bat] start ``` Without further configuration, this command will not start Keycloak and show you an error instead. This response is done on purpose, because Keycloak follows a *secure by default* principle. Production mode expects a hostname to be set up and an HTTPS/TLS setup to be available when started. Defaults 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 Before deploying Keycloak in a production environment, make sure to follow the steps outlined in [Configuring Keycloak for production](https://www.keycloak.org/server/configuration-production). By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These options give you an idea about the main configuration to consider when running Keycloak in production. ## Creating the initial admin user You can create the initial admin user by using the web frontend, which you access using a local connection (localhost). You can instead create this user by using environment variables. Set `KC_BOOTSTRAP_ADMIN_USERNAME=<username>` for the initial admin username and `KC_BOOTSTRAP_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 Console 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 We recommend optimizing Keycloak to provide faster startup and better memory consumption before deploying Keycloak in a production environment. This section describes how to apply Keycloak optimizations for the best performance and runtime behavior. ### Creating an optimized Keycloak build By default, when you use the `start` or `start-dev` command, Keycloak runs a `build` command under the covers for convenience reasons. This `build` command performs a set of optimizations for the startup and runtime behavior. The build process can take a few seconds. Especially when running Keycloak in containerized environments such as Kubernetes or OpenShift, startup time is important. To avoid losing that time, run a `build` explicitly before starting up, such as a separate step in a CI/CD pipeline. #### First step: Run a build explicitly To run a `build`, enter the following command: ``` bin/kc.[sh|bat] build <build-options> ``` This command shows `build options` that you enter. Keycloak distinguishes between **build options**, that are usable when running 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. However, if you run a build before the startup, only a subset of options is available to the build command. The restriction is due to the build options getting persisted into an optimized Keycloak image. For example, configuration for credentials such as `db-password` (which is a configuration option) must not get persisted for security reasons. | | | |---|---| | | All build options are persisted in a plain text. Do not store any sensitive data as the build options. This applies across all the available configuration sources, including the KeyStore Config Source. Hence, we also do not recommend to store any build options in a Java keystore. Also, when it comes to the configuration options, we recommend to use the KeyStore Config Source primarily for storing sensitive data. For non-sensitive data you can use the remaining configuration sources. | Build options are marked in [All configuration](https://www.keycloak.org/server/all-config) with a tool icon. To find available build options, see [All configuration page with build options selected](https://www.keycloak.org/server/all-config?f=build) or enter the following command: ``` bin/kc.[sh|bat] build --help ``` Example: Run a `build` 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 entering 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, which saves time. You can enter all configuration options at startup; these options are the ones in [All configuration](https://www.keycloak.org/server/all-config) that are **not** marked with a tool icon. - If a build option is found at startup with a value that is equal to the value used when entering the `build`, that option gets silently ignored when you use the `--optimized` parameter. - If that option has a different value than the value used when a build was entered, an error occurs. For this value to take effect, run a new `build` before starting. Create an optimized build The following example shows the creation of an optimized build followed by the use of the `--optimized` parameter when starting Keycloak. 1. Set the build option for the PostgreSQL database vendor using the build command ``` bin/kc.[sh|bat] build --db=postgres ``` 2. Set the runtime configuration options for postgres in the `conf/keycloak.conf` file. ``` db-url-host=keycloak-postgres db-username=keycloak db-password=change_me hostname=mykeycloak.acme.com https-certificate-file ``` 3. Start the server with the optimized parameter ``` bin/kc.[sh|bat] start --optimized ``` ## Using system variables in the realm configuration Some of the realm capabilities allow administrators to reference system variables such as environment variables and system properties when configuring the realm and its components. By default, Keycloak disallow using system variables but only those explicitly specified through the `spi-admin--allowed-system-variables` configuration option. This option allows you to specify a comma-separated list of keys that will eventually resolve to values from system variables with the same key. 1. Start the server and expose a set of system variables to the server runtime ``` bin/kc.[sh|bat] start --spi-admin--allowed-system-variables=FOO,BAR ``` In future releases, this capability will be removed in favor of preventing any usage of system variables in the realm configuration. ## Underlying concepts This section gives an overview of the underlying concepts Keycloak uses, especially when it comes to optimizing the startup. Keycloak uses the Quarkus framework and a re-augmentation/mutable-jar approach under the covers. This process is started when a `build` command is run. 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](https://quarkus.io/guides/reaugmentation) On this page [Edit this guide](https://github.com/keycloak/keycloak/tree/main/docs/guides/server/configuration.adoc) Keycloak is a Cloud Native Computing Foundation incubation project  © Keycloak Authors 2026. © 2026 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our [Trademark Usage page](https://www.linuxfoundation.org/trademark-usage).

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. ## Configuring sources for Keycloak Keycloak loads the configuration from four sources, which are listed here in order of application. 1. Command-line parameters 2. Environment variables 3. Options defined in the `conf/keycloak.conf` file, or in a user-created configuration file. 4. Sensitive options defined in a user-created Java KeyStore file. When an option is set in more than one source, the one that comes first in the list determines the value for that option. For example, the value for an option set by a command-line parameter has a higher priority than an environment variable for the same option. ### Example: Configuring the db-url-host parameter The following example shows how the `db-url` value is set in four configuration sources: | Source | Format | |---|---| | Command line parameters | `--db-url=cliValue` | | Environment variable | `KC_DB_URL=envVarValue` | | Configuration file | `db-url=confFileValue` | | Java KeyStore file | `kc.db-url=keystoreValue` | Based on the priority of application, the value that is used at startup is `cliValue`, because the command line is the highest priority. If `--db-url=cliValue` had not been used, the applied value would be `KC_DB_URL=envVarValue`. If the value were not applied by either the command line or an environment variable, `db-url=confFileValue` would be used. If none of the previous values were applied, the value `kc.db-url=keystoreValue` would be used due to the lowest priority among the available configuration sources. Keycloak configuration options often map to lower-level Quarkus or spi options. We refer to these as first-class and second-class configuration respectively. There are startup warnings to indicate if you are using a second-class option. For example if you try to directly use `quarkus.http.port`, you will be warned to use `kc.http-port` instead. ## Formats for configuration The configuration uses a *unified-per-source* format, which simplifies translation of a key/value pair from one configuration source to another. Note that these formats apply to spi options as well. Command-line parameter format Values for the command-line use the `--<key-with-dashes>=<value>` format. For some values, an `-<abbreviation>=<value>` shorthand also exists. Environment variable format Values for environment variables use the uppercased `KC_<key_with_underscores>=<value>` format. Alternatively, the `KCRAW_` prefix can be used instead of `KC_` to preserve values containing `$` characters — see [Preserving literal values with the KCRAW\_ prefix](https://www.keycloak.org/server/configuration#kcraw-prefix). Configuration file format Values that go into the configuration file use the `<key-with-dashes>=<value>` format. KeyStore configuration file format Values that go into the KeyStore configuration file use the `kc.<key-with-dashes>` format. `<value>` is then a password stored in the KeyStore. At the end of each configuration guide, look for the *Relevant options* heading, which defines the applicable configuration formats. For all configuration options, see [All configuration](https://www.keycloak.org/server/all-config). Choose the configuration source and format that applies to your use case. ### Example - Alternative formats based on configuration source The following example shows the configuration format for `db-url-host` for 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 ``` ### Formats for command-line parameters Keycloak is packed with many command line parameters for configuration. To see the available configuration formats, enter the following command: ``` bin/kc.[sh|bat] start --help ``` ### Format for referencing environment variables You can 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} ``` In case the environment variable cannot be resolved, you can specify a fallback value. Use a `:` (colon) as shown here before `mydb`: ``` db-url-host=${MY_DB_HOST:mydb} ``` ### Format to include 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 entering the following command: ``` bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start ``` Setting that option makes Keycloak read configuration from the specified file instead of `conf/keycloak.conf`. ### Setting sensitive options using a Java KeyStore file Thanks to Keystore Configuration Source you can directly load properties from a Java KeyStore using the `[--config-keystore]` and `[--config-keystore-password]` options. Optionally, you can specify the KeyStore type using the `[--config-keystore-type]` option. By default, the KeyStore type is `PKCS12`. The secrets in a KeyStore need to be stored using the `PBE` (password-based encryption) key algorithm, where a key is derived from a KeyStore password. You can generate such a KeyStore using the following `keytool` command: ``` keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v ``` After executing the command, you will be prompted to **Enter the password to be stored**, which represents a value of the `kc.db-password` property above. When the KeyStore is created, you can start the server using the following parameters: ``` bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=keystorepass --config-keystore-type=PKCS12 ``` ### Format for raw Quarkus properties In most cases, the available configuration options should suffice to configure the server. However, for a specific behavior or capability that is missing in the Keycloak configuration, you can use properties from the underlying Quarkus framework. If possible, avoid using properties directly from Quarkus, because they are unsupported by Keycloak. If your need is essential, consider opening an [enhancement request](https://github.com/keycloak/keycloak/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.yml) first. This approach helps us improve the configuration of Keycloak to fit your needs. If an enhancement request is not possible, you can configure the server using raw Quarkus properties: 1. Create a `quarkus.properties` file in the `conf` directory. 2. Define the required properties in that file. You can use only a [subset](https://github.com/keycloak/keycloak/blob/main/quarkus/runtime/pom.xml#L17) of the Quarkus extensions that are defined in the [Quarkus documentation](https://quarkus.io/guides/all-config). Also, note these differences for Quarkus properties: - A lock icon for a Quarkus property in the [Quarkus documentation](https://quarkus.io/guides/all-config) indicates a build time property. You run the `build` command to apply this property. For details about the build command, see the subsequent sections on optimizing Keycloak. - No lock icon for a property in the Quarkus guide indicates a runtime property for Quarkus and Keycloak. You can also store Quarkus properties in a Java KeyStore. ### Using special characters in values Keycloak depends upon Quarkus and MicroProfile for processing configuration values. Be aware that value expressions are supported. For example, `${some_key}` evaluates to the value of `some_key`. To disable expression evaluation, the `\` character functions as an escape character. In particular, it must be used to escape the usage of `$` characters when they appear to define an expression or are repeated. For example, if you want the configuration value `my$$password`, use `my\$\$password` instead. Note that the `\` character requires additional escaping or quoting when using most unix shells, or when it appears in properties files. For example, bash single quotes preserve the single backslash `--db-password='my\$\$password'`. Also, with bash double quotes, you need an additional backslash `--db-password="my\\$\\$password"`. Similarly in a properties file, backslash characters must also be escaped: `kc.db-password=my\\$\\$password` Windows-specific considerations When specifying Windows file paths in configuration values, backslashes must also be escaped. For example, if you want to specify the path `C:\path\to\file`, you should write it as `C:\\path\\to\\file`. Alternatively, you can use forward slashes which don’t need escaping: `C:/path/to/file`. When using PowerShell and your values contain special characters like commas, use single quotes around double quotes: ``` .\kc.bat start --log-level='"INFO,org.hibernate:debug"' ``` PowerShell handles quotes differently. It interprets the quoted string before passing it to the `kc.bat` script, removing the outer quote characters. Therefore, an extra layer of quotes is needed to preserve the value structure. Otherwise, the comma would be interpreted as a delimiter. In Windows CMD, you can use double quotes directly. When manual escaping is not feasible (like when a password is injected by a secrets manager and you cannot control the value), use the `KCRAW_` prefix described in the next section. ### Preserving literal values with the KCRAW\_ prefix When setting configuration values, Keycloak (via SmallRye Config) evaluates expressions such as `${some_key}` and collapses `$$` to `$`. This means passwords or secrets containing `$` characters may be silently modified. While the `\` escaping described above works for values you control directly, it is not always practical - for example, when a secrets manager or orchestration tool injects the value and you cannot add escape characters. In these cases, use the `KCRAW_` prefix instead of `KC_` for any environment variable whose value must be preserved exactly as written. Keycloak automatically escapes `$` characters in `KCRAW_` values so that expression evaluation preserves the original value. Example: Setting a database password containing special characters ``` # Standard prefix — the value will be modified by expression evaluation: export KC_DB_PASSWORD='my$$pa$\{vault}word' # Result: "$$" is collapsed to "$" and "$\{vault}" is evaluated as an # expression, producing "my$paword" or an error # Raw prefix — the value is preserved exactly as written: export KCRAW_DB_PASSWORD='my$$pa$\{vault}word' # Result: the password is used as-is: my$$pa$\{vault}word ``` | | | |---|---| | | The `KCRAW_` prefix applies only to environment variables, where shell quoting rules make escaping of `$` unreliable. Other configuration sources are subject to their own format escaping mechanisms and their values are still treated as expressions. You cannot set both `KC_<KEY>` and `KCRAW_<KEY>` for the same configuration key. If both are present, Keycloak will fail to start and report a configuration error. Apart from escaping `$` characters, `KCRAW_` variables behave identically to their `KC_` counterparts: the same key mapping and priority rules apply. | ### Formats for environment variable keys with special characters Non-alphanumeric characters in your configuration key must be converted to `_` in the corresponding environment variable key. Environment variables are converted back to normal option keys by lower-casing the name and replacing `_` with `-`. Logging wildcards are the exception as `_` in the category is replaced with `.` instead. Logging categories are commonly class / package names, which are more likely to use `.` rather than `-`. | | | |---|---| | | Automatic mapping of the environment variable key to option key may not preserve the intended key | For example `kc.log-level-package.class_name` will become the environment variable key `KC_LOG_LEVEL_PACKAGE_CLASS_NAME`. That will automatically be mapped to `kc.log-level-package.class.name` because `_` in the logging category will be replaced by `.`. Unfortunately this does not match the intent of `kc.log-level-package.class_name`. You have a couple of options in this case: - create an entry in your `keycloak.conf` file that references an environment variable of your choosing. e.g. `kc.log-level-package.class_name=${CLASS_NAME_LEVEL}`. See more on referencing environment variables in [Format for referencing environment variables](https://www.keycloak.org/server/configuration#_format_for_referencing_environment_variables). - or in situations where modifying the `keycloak.conf` may not be easy, you can use a pair of environment variables `KC_UNIQUEIFIER=value` and `KCKEY_UNIQUEIFIER=key`, e.g. `KC_MYKEY=debug` and `KCKEY_MYKEY=log-level-package.class_name`, or `KC_LOG_LEVEL_PACKAGE_CLASS_NAME=debug` and `KCKEY_LOG_LEVEL_PACKAGE_CLASS_NAME=log-level-package.class_name` ## Starting Keycloak You can start Keycloak in `development mode` or `production mode`. Each mode offers different defaults for the intended environment. ### Starting Keycloak in development mode Use development mode to try out Keycloak for the first time to get it up and running quickly. This mode offers convenient defaults for developers, such as for developing a new Keycloak theme. | | | |---|---| | | By default, when you start Keycloak in development mode on Windows Subsystem For Linux, the server binds to all network addresses (`0.0.0.0`). This means your instance may be accessible from other machines on your network. | To start in development mode, enter the following command: ``` bin/kc.[sh|bat] start-dev ``` Defaults 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-caching and template-caching is disabled ### Starting Keycloak in production mode Use production mode for deployments of Keycloak in production environments. This mode follows a *secure by default* principle. To start in production mode, enter the following command: ``` bin/kc.[sh|bat] start ``` Without further configuration, this command will not start Keycloak and show you an error instead. This response is done on purpose, because Keycloak follows a *secure by default* principle. Production mode expects a hostname to be set up and an HTTPS/TLS setup to be available when started. Defaults 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 By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These options give you an idea about the main configuration to consider when running Keycloak in production. ## Creating the initial admin user You can create the initial admin user by using the web frontend, which you access using a local connection (localhost). You can instead create this user by using environment variables. Set `KC_BOOTSTRAP_ADMIN_USERNAME=<username>` for the initial admin username and `KC_BOOTSTRAP_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 Console 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 We recommend optimizing Keycloak to provide faster startup and better memory consumption before deploying Keycloak in a production environment. This section describes how to apply Keycloak optimizations for the best performance and runtime behavior. ### Creating an optimized Keycloak build By default, when you use the `start` or `start-dev` command, Keycloak runs a `build` command under the covers for convenience reasons. This `build` command performs a set of optimizations for the startup and runtime behavior. The build process can take a few seconds. Especially when running Keycloak in containerized environments such as Kubernetes or OpenShift, startup time is important. To avoid losing that time, run a `build` explicitly before starting up, such as a separate step in a CI/CD pipeline. #### First step: Run a build explicitly To run a `build`, enter the following command: ``` bin/kc.[sh|bat] build <build-options> ``` This command shows `build options` that you enter. Keycloak distinguishes between **build options**, that are usable when running 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. However, if you run a build before the startup, only a subset of options is available to the build command. The restriction is due to the build options getting persisted into an optimized Keycloak image. For example, configuration for credentials such as `db-password` (which is a configuration option) must not get persisted for security reasons. | | | |---|---| | | All build options are persisted in a plain text. Do not store any sensitive data as the build options. This applies across all the available configuration sources, including the KeyStore Config Source. Hence, we also do not recommend to store any build options in a Java keystore. Also, when it comes to the configuration options, we recommend to use the KeyStore Config Source primarily for storing sensitive data. For non-sensitive data you can use the remaining configuration sources. | ``` bin/kc.[sh|bat] build --help ``` Example: Run a `build` 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 entering 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, which saves time. You can enter all configuration options at startup; these options are the ones in [All configuration](https://www.keycloak.org/server/all-config) that are **not** marked with a tool icon. - If a build option is found at startup with a value that is equal to the value used when entering the `build`, that option gets silently ignored when you use the `--optimized` parameter. - If that option has a different value than the value used when a build was entered, an error occurs. For this value to take effect, run a new `build` before starting. Create an optimized build The following example shows the creation of an optimized build followed by the use of the `--optimized` parameter when starting Keycloak. 1. Set the build option for the PostgreSQL database vendor using the build command ``` bin/kc.[sh|bat] build --db=postgres ``` 2. Set the runtime configuration options for postgres in the `conf/keycloak.conf` file. ``` db-url-host=keycloak-postgres db-username=keycloak db-password=change_me hostname=mykeycloak.acme.com https-certificate-file ``` 3. Start the server with the optimized parameter ``` bin/kc.[sh|bat] start --optimized ``` ## Using system variables in the realm configuration Some of the realm capabilities allow administrators to reference system variables such as environment variables and system properties when configuring the realm and its components. By default, Keycloak disallow using system variables but only those explicitly specified through the `spi-admin--allowed-system-variables` configuration option. This option allows you to specify a comma-separated list of keys that will eventually resolve to values from system variables with the same key. 1. Start the server and expose a set of system variables to the server runtime ``` bin/kc.[sh|bat] start --spi-admin--allowed-system-variables=FOO,BAR ``` In future releases, this capability will be removed in favor of preventing any usage of system variables in the realm configuration. ## Underlying concepts This section gives an overview of the underlying concepts Keycloak uses, especially when it comes to optimizing the startup. Keycloak uses the Quarkus framework and a re-augmentation/mutable-jar approach under the covers. This process is started when a `build` command is run. 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.