Chapter 1. Configuring Red Hat build of Keycloak
Chapter 1. Configuring Red Hat build of Keycloak This chapter explains the configuration methods for Red Hat build of Keycloak and how to start and apply the preferred configuration. It includes configuration guidelines for optimizing Red Hat build of Keycloak for faster startup and low memory footprint. 1.1. Configuring sources for Red Hat build of Keycloak Red Hat build of Keycloak loads the configuration from five sources, which are listed here in order of application. Command-line parameters Environment variables Options defined in a user-created configuration file. Options defined in the conf/keycloak.conf file. 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. 1.1.1. 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. However, if this value had been set in a user defined configuration file, that value would take precedence over the conf/keycloak.conf file. If none of the values were applied, the value kc.db-url=confFileValue would be used due to the lowest priority among the available configuration sources. 1.2. 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. 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. 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 chapter, look for the Relevant options heading, which defines the applicable configuration formats. For all configuration options, see All configuration . Choose the configuration source and format that applies to your use case. 1.2.1. 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 conf/keycloak.conf 1.2.2. Formats for command-line parameters Red Hat build of 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 for all server options. 1.2.3. Formats for environment variables You can use placeholders to resolve an environment specific value from environment variables inside the keycloak.conf file by using the USD{ENV_VAR} syntax: 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=USD{MY_DB_HOST:mydb} 1.2.4. 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 1.2.5. 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=storepass --config-keystore-type=PKCS12 1.2.6. 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 Red Hat build of Keycloak configuration, you can use properties from the underlying Quarkus framework. If possible, avoid using properties directly from Quarkus, because they are unsupported by Red Hat build of Keycloak. If your need is essential, consider opening an enhancement request first. This approach helps us improve the configuration of Red Hat build of Keycloak to fit your needs. If an enhancement request is not possible, you can configure the server using raw Quarkus properties: Create a quarkus.properties file in the conf directory. Define the required properties in that file. You can use only a subset of the Quarkus extensions that are defined in the Quarkus documentation . Also, note these differences for Quarkus properties: A lock icon for a Quarkus property in the Quarkus documentation 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 Red Hat build of Keycloak. No lock icon for a property in the Quarkus guide indicates a runtime property for Quarkus and Red Hat build of Keycloak. Use the [-cf|--config-file] command line parameter to include that file. Similarly, you can also store Quarkus properies in a Java KeyStore. Note that some Quarkus properties are already mapped in the Red Hat build of Keycloak configuration, such as quarkus.http.port and similar essential properties. If the property is used by Keycloak, defining that property key in quarkus.properties has no effect. The Keycloak configuration value takes precedence over the Quarkus property value. 1.3. Starting Red Hat build of Keycloak You can start Red Hat build of Keycloak in development mode or production mode . Each mode offers different defaults for the intended environment. 1.3.1. Starting Red Hat build of Keycloak in development mode Use development mode to try out Red Hat build of 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 Red Hat build of Keycloak theme. 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 1.3.2. Starting Red Hat build of Keycloak in production mode Use production mode for deployments of Red Hat build 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 Red Hat build of Keycloak and show you an error instead. This response is done on purpose, because Red Hat build of 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 Red Hat build of Keycloak in a production environment, make sure to follow the steps outlined in Configuring Red Hat build of Keycloak for 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 Red Hat build of Keycloak in production. 1.4. 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 KEYCLOAK_ADMIN= <username> for the initial admin username and KEYCLOAK_ADMIN_PASSWORD= <password> for the initial admin password. Red Hat build of 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. Red Hat build of Keycloak ignores the values and starts up correctly. 1.5. Optimize the Red Hat build of Keycloak startup We recommend optimizing Red Hat build of Keycloak to provide faster startup and better memory consumption before deploying Red Hat build of Keycloak in a production environment. This section describes how to apply Red Hat build of Keycloak optimizations for the best performance and runtime behavior. 1.5.1. Creating an optimized Red Hat build of Keycloak build By default, when you use the start or start-dev command, Red Hat build of 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 Red Hat build of Keycloak in containerized environments such as Kubernetes or OpenShift, startup time is important. To avoid losing that time, run a build explicity before starting up, such as a separate step in a CI/CD pipeline. 1.5.1.1. 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. Red Hat build of 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 Red Hat build 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 Red Hat build of Keycloak image. For example, configuration for credentials such as db-password (which is a configuration option) must not get persisted for security reasons. Warning 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 with a tool icon. To find available build options, 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 1.5.1.2. Second step: Start Red Hat build of Keycloak using --optimized After a successful build, you can start Red Hat build of 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 Red Hat build of Keycloak to assume a pre-built, already optimized Red Hat build of Keycloak image is used. As a result, Red Hat build of 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 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, a warning appears in the logs and the previously built value is used. 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 Red Hat build of Keycloak. Set the build option for the PostgreSQL database vendor using the build command bin/kc.[sh|bat] build --db=postgres Set the runtime configuration options for postgres in the conf/keycloak.conf file. Start the server with the optimized parameter bin/kc.[sh|bat] start --optimized You can achieve most optimizations to startup and runtime behavior by using the build command. Also, by using the keycloak.conf file as a configuration source, you avoid some steps at startup that would otherwise require command line parameters, such as initializing the CLI itself. As a result, the server starts up even faster. 1.6. Underlying concepts This section gives an overview of the underlying concepts Red Hat build of Keycloak uses, especially when it comes to optimizing the startup. Red Hat build of 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 Red Hat build of 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
bin/kc.[sh|bat] start --db-url-host=mykeycloakdb export KC_DB_URL_HOST=mykeycloakdb db-url-host=mykeycloakdb bin/kc.[sh|bat] start --help db-url-host=USD{MY_DB_HOST} db-url-host=USD{MY_DB_HOST:mydb} bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=storepass --config-keystore-type=PKCS12 bin/kc.[sh|bat] start-dev bin/kc.[sh|bat] start bin/kc.[sh|bat] build <build-options> bin/kc.[sh|bat] build --help bin/kc.[sh|bat] build --db=postgres bin/kc.[sh|bat] start --optimized <configuration-options> bin/kc.[sh|bat] build --db=postgres db-url-host=keycloak-postgres db-username=keycloak db-password=change_me hostname=mykeycloak.acme.com https-certificate-file bin/kc.[sh|bat] start --optimized