Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Server Configuration Guide

Red Hat build of Keycloak 26.4

Red Hat Customer Content Services

Abstract

This guide consists of information for administrators to configure Red Hat build of Keycloak 26.4.

Chapter 1. Configuring Red Hat build of Keycloak
Copy link

Configure and start 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.

Red Hat build of 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.

The following example shows how the db-url value is set in four configuration sources:

Expand
SourceFormat

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.

1.2. Formats for configuration
Copy link

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.
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.

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
Copy to Clipboard Toggle word wrap

environment variable

export KC_DB_URL_HOST=mykeycloakdb
Copy to Clipboard Toggle word wrap

conf/keycloak.conf

db-url-host=mykeycloakdb
Copy to Clipboard Toggle word wrap

1.2.2. Formats for command-line parameters
Copy link

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
Copy to Clipboard Toggle word wrap

Alternatively, see All configuration for all server options.

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}
Copy to Clipboard Toggle word wrap

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}
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

Setting that option makes Red Hat build of Keycloak read configuration from the specified file instead of conf/keycloak.conf.

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
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

1.2.6. Format for raw Quarkus properties
Copy link

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:

  1. Create a quarkus.properties file in the conf directory.

  2. 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.

You can also store Quarkus properties 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 Red Hat build of Keycloak, defining that property key in quarkus.properties has no effect. The Red Hat build of Keycloak configuration value takes precedence over the Quarkus property value.

1.2.7. Using special characters in values
Copy link

Red Hat build of 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"'
Copy to Clipboard Toggle word wrap

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.

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 -.

Warning

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 Section 1.2.3, “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

1.3. Starting Red Hat build of Keycloak
Copy link

You can start Red Hat build of Keycloak in development mode or production mode. Each mode offers different defaults for the intended environment.

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
Copy to Clipboard Toggle word wrap

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

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
Copy to Clipboard Toggle word wrap

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
Copy link

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.

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.

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.

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 explicitly before starting up, such as a separate step in a CI/CD pipeline.

1.5.1.1. First step: Run a build explicitly
Copy link

To run a build, enter the following command: 

bin/kc.[sh|bat] build <build-options>
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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

bin/kc.[sh|bat] build --db=postgres
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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.

  1. Set the build option for the PostgreSQL database vendor using the build command 

    bin/kc.[sh|bat] build --db=postgres
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  3. Start the server with the optimized parameter 

    bin/kc.[sh|bat] start --optimized
    Copy to Clipboard Toggle word wrap

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.

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, Red Hat build of 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
    Copy to Clipboard Toggle word wrap

In future releases, this capability will be removed in favor of preventing any usage of system variables in the realm configuration.

1.7. Underlying concepts
Copy link

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

Prepare Red Hat build of Keycloak for use in production.

A Red Hat build of Keycloak production environment provides secure authentication and authorization for deployments that range from on-premise deployments that support a few thousand users to deployments that serve millions of users.

This chapter describes the general areas of configuration required for a production ready Red Hat build of Keycloak environment. This information focuses on the general concepts instead of the actual implementation, which depends on your environment. The key aspects covered in this chapter apply to all environments, whether it is containerized, on-premise, GitOps, or Ansible.

2.1. TLS for secure communication
Copy link

Red Hat build of Keycloak continually exchanges sensitive data, which means that all communication to and from Red Hat build of Keycloak requires a secure communication channel. To prevent several attack vectors, you enable HTTP over TLS, or HTTPS, for that channel.

To configure secure communication channels for Red Hat build of Keycloak, see Configuring TLS and Configuring outgoing HTTP requests.

To secure the cache communication for Red Hat build of Keycloak, see Configuring distributed caches.

2.2. The hostname for Red Hat build of Keycloak
Copy link

In a production environment, Red Hat build of Keycloak instances usually run in a private network, but Red Hat build of Keycloak needs to expose certain public facing endpoints to communicate with the applications to be secured.

For details on the endpoint categories and instructions on how to configure the public hostname for them, see Configuring the hostname (v2).

It is considered a best practice to expose the Red Hat build of Keycloak Administration REST API and Console on a different hostname or context-path than the one used for the public frontend URLs that are used e.g. by login flows. This separation ensures that the Administration interfaces are not exposed to the public internet, which reduces the attack surface.

Warning

Access to REST APIs needs to be blocked on the reverse proxy level, if they are not intended to be publicly exposed.

For details, see Configuring the hostname (v2).

2.3. Reverse proxy in a distributed environment
Copy link

Apart from Configuring the hostname (v2), production environments usually include a reverse proxy / load balancer component. It separates and unifies access to the network used by your company or organization. For a Red Hat build of Keycloak production environment, this component is recommended.

For details on configuring proxy communication modes in Red Hat build of Keycloak, see Configuring a reverse proxy. That chapter also recommends which paths should be hidden from public access and which paths should be exposed so that Red Hat build of Keycloak can secure your applications.

2.4. Limit the number of queued requests
Copy link

A production environment should protect itself from an overload situation, so that it responds to as many valid requests as possible, and to continue regular operations once the situation returns to normal again. One way of doing this is rejecting additional requests once a certain threshold is reached.

Load shedding should be implemented on all levels, including the load balancers in your environment. In addition to that, there is a feature in Red Hat build of Keycloak to limit the number of requests that can’t be processed right away and need to be queued. By default, there is no limit set. Set the option http-max-queued-requests to limit the number of queued requests to a given threshold matching your environment. Any request that exceeds this limit would return with an immediate 503 Server not Available response.

2.5. Production grade database
Copy link

The database used by Red Hat build of Keycloak is crucial for the overall performance, availability, reliability and integrity of Red Hat build of Keycloak. For details on how to configure a supported database, see Configuring the database.

To ensure that users can continue to log in when a Red Hat build of Keycloak instance goes down, a typical production environment contains two or more Red Hat build of Keycloak instances.

Red Hat build of Keycloak runs on top of JGroups and Infinispan, which provide a reliable, high-availability stack for a clustered scenario. In the default setup, communication between the nodes is encrypted using TLS.

To find out more about using multiple nodes, the different caches and an appropriate stack for your environment, see Configuring distributed caches.

2.6.1. Configure Firewall ports
Copy link

A set of network ports must be open to allow a healthy network communication between Red Hat build of Keycloak servers. See Configuring distributed caches. It describes what ports need to be open and their usage.

The system properties java.net.preferIPv4Stack and java.net.preferIPv6Addresses are used to configure the JVM for use with IPv4 or IPv6 addresses.

By default, Red Hat build of Keycloak is accessible via IPv4 and IPv6 addresses at the same time. In order to run only with IPv4 addresses, you need to specify the property java.net.preferIPv4Stack=true. The latter ensures that any hostname to IP address conversions always return IPv4 address variants.

These system properties are conveniently set by the JAVA_OPTS_APPEND environment variable. For example, to change the IP stack preference to IPv4, set an environment variable as follows: 

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=true"
Copy to Clipboard Toggle word wrap

To set up the server for IPv6 only, set an environment variable as follows for the distributed caches to form a cluster: 

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true"
Copy to Clipboard Toggle word wrap

See Configuring distributed caches for more details.

Bootstrap Red Hat build of Keycloak and recover access by creating a temporary admin account.

3.1. A temporary admin account
Copy link

A user or service admin account created using one of the methods described below is temporary. This means the account should exist only for the duration necessary to perform operations needed to gain permanent and more secure admin access. After that, the account needs to be removed manually. Various UI/UX elements, such as the Administration Console warning banner, labels, and log messages, will indicate to a Red Hat build of Keycloak administrator that the account is temporary.

Red Hat build of Keycloak start and start-dev commands support options for bootstrapping both temporary admin users and admin service accounts. These options are standard configuration options, so they can be specified in any of the configuration sources such as environment variables or CLI parameters. For instance, the following examples demonstrate how to use the start and start-dev commands with CLI parameters to bootstrap a temporary admin user and an admin service account, respectively: 

bin/kc.[sh|bat] start --bootstrap-admin-username tmpadm --bootstrap-admin-password pass
Copy to Clipboard Toggle word wrap 
bin/kc.[sh|bat] start-dev --bootstrap-admin-client-id tmpadm --bootstrap-admin-client-secret secret
Copy to Clipboard Toggle word wrap

The username or client ID values can be omitted; see the Section 3.5, “Default values” section below for more information.

The purpose of these options is solely for bootstrapping temporary admin accounts. These accounts will be created only during the initial start of the Red Hat build of Keycloak server when the master realm doesn’t exist yet. The accounts are always created in the master realm. For recovering lost admin access, use the dedicated command described in the sections below.

The bootstrap-admin command can be executed even before the first-ever start of Red Hat build of Keycloak. Bear in mind that all the Red Hat build of Keycloak nodes need to be stopped prior to using this command. Its execution will trigger the creation of the initial master realm, and as a result, the startup options to bootstrap the admin user and service account will be ignored later when the server is started for the first time.

Additionally, it is strongly recommended to use the dedicated command with the same options that the Red Hat build of Keycloak server is started with (e.g., db options).

If you have built an optimized version of Red Hat build of Keycloak with the build command as outlined in Configuring Red Hat build of Keycloak, use the command line option --optimized to have Red Hat build of Keycloak skip the build check for a faster startup time. When doing this, remove the build time options from the command line and keep only the runtime options.

Note

if you do not use --optimized keep in mind that an bootstrap-admin command may implicitly create or update an optimized build for you - if you are running the command from the same machine as a server instance, this may impact the next start of your server.

3.3.1. Create an admin user
Copy link

To create a temporary admin user, execute the following command: 

bin/kc.[sh|bat] bootstrap-admin user
Copy to Clipboard Toggle word wrap

If no other parameters are specified and/or no corresponding environment variables are set, the user is prompted to enter the required information. The username value can be omitted to use the default values. For more information, see the Section 3.5, “Default values” and Section 3.7, “Environment variables” sections below.

Alternatively, the parameters can be directly specified in the command: 

bin/kc.[sh|bat] bootstrap-admin user --username tmpadm --password:env PASS_VAR
Copy to Clipboard Toggle word wrap

This command creates a temporary admin user with the username tmpadm and the password retrieved from the environment variable.

3.3.2. Create a service account
Copy link

In automated scenarios, a temporary admin service account can be a more suitable alternative to a temporary admin user.

To create a temporary admin service account, execute the following command: 

bin/kc.[sh|bat] bootstrap-admin service
Copy to Clipboard Toggle word wrap

Similarly, if no corresponding environment variables or additional parameters are set, the user will be prompted to enter the required information. The client ID value can be omitted to use the default values. For more information, see the Section 3.5, “Default values” and Section 3.7, “Environment variables” sections below.

Alternatively, the parameters can be directly specified in the command: 

bin/kc.[sh|bat] bootstrap-admin service --client-id tmpclient --client-secret:env=SECRET_VAR
Copy to Clipboard Toggle word wrap

This command creates a temporary admin service account with the client ID tmpclient and the secret retrieved from the environment variable.

Passwordless, OTP, or other advanced authentication methods can be enforced for a realm with lost admin access. In such a case, the admin service account needs to be created to recover lost admin access to the realm. After the service account is created, authentication against the Red Hat build of Keycloak instance is required to perform all necessary operations: 

bin/kcadm.[sh|bat] config credentials --server http://localhost:8080 --realm master --client <service_account_client_name> --secret <service_account_secret>
Copy to Clipboard Toggle word wrap

Next, retrieve the credentialId. For this example, the OTP credential is the relevant one. Use the following command to get an array of CredentialRepresentation objects and find the one with type set to otp: 

bin/kcadm.[sh|bat] get users/{userId}/credentials -r {realm-name}
Copy to Clipboard Toggle word wrap

Finally, the retrieved ID can be used to remove the advanced authentication method (in our case, OTP): 

bin/kcadm.[sh|bat] delete users/{userId}/credentials/{credentialId} -r {realm-name}
Copy to Clipboard Toggle word wrap

3.5. Default values
Copy link

For both the startup and dedicated command scenarios, the username and client ID are optional and default to temp-admin for both the user and service account, respectively.

3.6. Disable the parameters prompt
Copy link

To disable the prompt for the parameters, the --no-prompt parameter can be used. For example: 

bin/kc.[sh|bat] bootstrap-admin user --username tmpadm --no-prompt
Copy to Clipboard Toggle word wrap

If no corresponding environment variable is set, the command will fail with an error message indicating that the required password parameter is missing.

The --no-prompt parameter can be useful if the username or client ID should be omitted. For example: 

bin/kc.[sh|bat] bootstrap-admin user --password:env PASS_VAR --no-prompt
Copy to Clipboard Toggle word wrap

This creates a temporary admin user with the default username without prompting for confirmation. For more information, see the Section 3.5, “Default values” section above.

3.7. Environment variables
Copy link

For the bootstrap-admin user command, both username and password can be optionally set as environment variables: 

bin/kc.[sh|bat] bootstrap-admin user --username:env <YourUsernameEnv> --password:env <YourPassEnv>
Copy to Clipboard Toggle word wrap

For the bootstrap-admin service command, the client ID is optional and defaults to temp-admin, while the client secret is required to be set as an environment variable: 

bin/kc.[sh|bat] bootstrap-admin service --client-id:env <YourClientIdEnv> --client-secret:env <YourSecretEnv>
Copy to Clipboard Toggle word wrap

Chapter 4. Directory Structure
Copy link

Understand the purpose of the directories under the installation root.

4.1. Installation Locations
Copy link

If you are installing from a zip file then by default there will be an install root directory of rhbk-26.4.2, which can be created anywhere you choose on your filesystem.

/opt/keycloak is the root install location for the server in all containerized usage shown for Red Hat build of Keycloak.

Note

In the rest of the documentation, relative paths are understood to be relative to the install root - for example, conf/file.xml means <install root>/conf/file.xml

4.2. Directory Structure
Copy link

Under the Red Hat build of Keycloak install root there exists a number of folders:

  • bin/ - contains all the shell scripts for the server, including kc.sh|bat, kcadm.sh|bat, and kcreg.sh|bat

    • client/ - used internally

  • conf/ - directory used for configuration files, including keycloak.conf - see Configuring Red Hat build of Keycloak. Many options for specifying a configuration file expect paths relative to this directory.

  • data/ - directory for the server to store runtime information, such as transaction logs

  • lib/ - used internally
  • providers/ - directory for user provided dependencies - see Configuring providers for extending the server and Configuring the database for an example of adding a JDBC driver.
  • themes/ - directory for customizations to the Admin Console - see Developing Themes

Run Red Hat build of Keycloak from a container image.

This chapter describes how to optimize and run the Red Hat build of Keycloak container image to provide the best experience running a container.

Warning

This chapter applies only for building an image that you run in a OpenShift environment. Only an OpenShift environment is supported for this image. It is not supported if you run it in other Kubernetes distributions.

The default Red Hat build of Keycloak container image ships ready to be configured and optimized.

For the best start up of your Red Hat build of Keycloak container, build an image by running the build step during the container build. This step will save time in every subsequent start phase of the container image.

The following Containerfile creates a pre-configured Red Hat build of Keycloak image that enables the health and metrics endpoints, enables the token exchange feature, and uses a PostgreSQL database.

Containerfile:

FROM registry.redhat.io/rhbk/keycloak-rhel9:26.4 AS builder

# Enable health and metrics support
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true

# Configure a database vendor
ENV KC_DB=postgres

WORKDIR /opt/keycloak
# for demonstration purposes only, please make sure to use proper certificates in production instead
RUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore
RUN /opt/keycloak/bin/kc.sh build

FROM registry.redhat.io/rhbk/keycloak-rhel9:26.4
COPY --from=builder /opt/keycloak/ /opt/keycloak/

# change these values to point to a running postgres instance
ENV KC_DB=postgres
ENV KC_DB_URL=<DBURL>
ENV KC_DB_USERNAME=<DBUSERNAME>
ENV KC_DB_PASSWORD=<DBPASSWORD>
ENV KC_HOSTNAME=localhost
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
Copy to Clipboard Toggle word wrap

The build process includes multiple stages:

  • Run the build command to set server build options to create an optimized image.
  • The files generated by the build stage are copied into a new image.
  • In the final image, additional configuration options for the hostname and database are set so that you don’t need to set them again when running the container.
  • In the entrypoint, the kc.sh enables access to all the distribution sub-commands.

To install custom providers, you just need to define a step to include the JAR file(s) into the /opt/keycloak/providers directory. This step must be placed before the line that RUNs the build command, as below: 

# A example build step that downloads a JAR file from a URL and adds it to the providers directory
FROM registry.redhat.io/rhbk/keycloak-rhel9:26.4 as builder

...

# Add the provider JAR file to the providers directory
ADD --chown=keycloak:keycloak --chmod=644 <MY_PROVIDER_JAR_URL> /opt/keycloak/providers/myprovider.jar

...

# Context: RUN the build command
RUN /opt/keycloak/bin/kc.sh build
Copy to Clipboard Toggle word wrap

5.1.2. Installing additional RPM packages
Copy link

If you try to install new software in a stage FROM registry.redhat.io/rhbk/keycloak-rhel9, you will notice that microdnf, dnf, and even rpm are not installed. Also, very few packages are available, only enough for a bash shell, and to run Red Hat build of Keycloak itself. This is due to security hardening measures, which reduce the attack surface of the Red Hat build of Keycloak container.

First, consider if your use case can be implemented in a different way, and so avoid installing new RPMs into the final container:

  • A RUN curl instruction in your Containerfile can be replaced with ADD, since that instruction natively supports remote URLs.
  • Some common CLI tools can be replaced by creative use of the Linux filesystem. For example, ip addr show tap0 becomes cat /sys/class/net/tap0/address
  • Tasks that need RPMs can be moved to a former stage of an image build, and the results copied across instead.

Here is an example. Running update-ca-trust in a former build stage, then copying the result forward: 

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
COPY mycertificate.crt /etc/pki/ca-trust/source/anchors/mycertificate.crt
RUN update-ca-trust

FROM registry.redhat.io/rhbk/keycloak-rhel9
COPY --from=ubi-micro-build /etc/pki /etc/pki
Copy to Clipboard Toggle word wrap

It is possible to install new RPMs if absolutely required, following this two-stage pattern established by ubi-micro: 

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build
RUN mkdir -p /mnt/rootfs
RUN dnf install --installroot /mnt/rootfs <package names go here> --releasever 9 --setopt install_weak_deps=false --nodocs -y && \
    dnf --installroot /mnt/rootfs clean all && \
    rpm --root /mnt/rootfs -e --nodeps setup

FROM registry.redhat.io/rhbk/keycloak-rhel9
COPY --from=ubi-micro-build /mnt/rootfs /
Copy to Clipboard Toggle word wrap

This approach uses a chroot, /mnt/rootfs, so that only the packages you specify and their dependencies are installed, and so can be easily copied into the second stage without guesswork.

Warning

Some packages have a large tree of dependencies. By installing new RPMs you may unintentionally increase the container’s attack surface. Check the list of installed packages carefully.

5.1.3. Custom ENTRYPOINT shell scripts
Copy link

If you use a custom entry point script, start Red Hat build of Keycloak with exec so it can receive termination signals that are essential for a graceful shutdown.

Correct approach for an ENTRYPOINT shell script

#!/bin/bash

# (add your custom logic here)

# Run the 'exec' command as the last step of the script.
# As it replaces the current shell process, no additional shell commands will run after the 'exec' command.
exec /opt/keycloak/bin/kc.sh start "$@"
Copy to Clipboard Toggle word wrap

Warning

Without exec, the shell script remains PID 1 in the container and blocks signals like SIGTERM from reaching Red Hat build of Keycloak. This prevents a graceful shutdown and can lead to cache inconsistencies or data loss.

5.1.4. Building the container image
Copy link

To build the actual container image, run the following command from the directory containing your Containerfile: 

podman build . -t mykeycloak -f Containerfile
Copy to Clipboard Toggle word wrap
Note

Podman can be used only for creating or customizing images. Podman is not supported for running Red Hat build of Keycloak in production environments.

To start the image, run: 

podman run --name mykeycloak -p 8443:8443 -p 9000:9000 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized --hostname=localhost
Copy to Clipboard Toggle word wrap

Red Hat build of Keycloak starts in production mode, using only secured HTTPS communication, and is available on https://localhost:8443.

Health check endpoints are available at https://localhost:9000/health, https://localhost:9000/health/ready and https://localhost:9000/health/live.

Opening up https://localhost:9000/metrics leads to a page containing operational metrics that could be used by your monitoring solution.

5.1.6. Known issues with Docker
Copy link

  • If a RUN dnf install command seems to be taking an excessive amount of time, then likely your Docker systemd service has the file limit setting LimitNOFILE configured incorrectly. Either update the service configuration to use a better value, such as 1024000, or directly use ulimit in the RUN command: 
...
RUN ulimit -n 1024000 && dnf install --installroot ...
...
Copy to Clipboard Toggle word wrap
  • If you are including provider JARs and your container fails a start --optimized with a notification that a provider JAR has changed, this is due to Docker truncating or otherwise modifying file modification timestamps from what the build command recorded to what is seen at runtime. In this case you will need to force the image to use a known timestamp of your choosing with a touch command prior to running a build: 
...
# ADD or copy one or more provider jars
ADD --chown=keycloak:keycloak --chmod=644 some-jar.jar /opt/keycloak/providers/
...
RUN touch -m --date=@1743465600 /opt/keycloak/providers/*
RUN /opt/keycloak/bin/kc.sh build
...
Copy to Clipboard Toggle word wrap

5.2. Exposing the container to a different port
Copy link

By default, the server is listening for http and https requests using the ports 8080 and 8443, respectively.

If you want to expose the container using a different port, you need to set the hostname accordingly:

  1. Exposing the container using a port other than the default ports 
podman run --name mykeycloak -p 3000:8443 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized --hostname=https://localhost:3000
Copy to Clipboard Toggle word wrap

By setting the hostname option to a full url you can now access the server at https://localhost:3000.

The easiest way to try Red Hat build of Keycloak from a container for development or testing purposes is to use the Development mode. You use the start-dev command: 

podman run --name mykeycloak -p 127.0.0.1:8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        registry.redhat.io/rhbk/keycloak-rhel9:26.4 \
        start-dev
Copy to Clipboard Toggle word wrap

Invoking this command starts the Red Hat build of Keycloak server in development mode.

This mode should be strictly avoided in production environments because it has insecure defaults. For more information about running Red Hat build of Keycloak in production, see Configuring Red Hat build of Keycloak for production.

In keeping with concepts such as immutable infrastructure, containers need to be re-provisioned routinely. In these environments, you need containers that start fast, therefore you need to create an optimized image as described in the preceding section. However, if your environment has different requirements, you can run a standard Red Hat build of Keycloak image by just running the start command. For example: 

podman run --name mykeycloak -p 127.0.0.1:8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        registry.redhat.io/rhbk/keycloak-rhel9:26.4 \
        start \
        --hostname=localhost --http-enabled=true
        --db=postgres --features=token-exchange \
        --db-url=<JDBC-URL> --db-username=<DB-USER> --db-password=<DB-PASSWORD> \
        --https-key-store-file=<file> --https-key-store-password=<password>
Copy to Clipboard Toggle word wrap

Running this command starts a Red Hat build of Keycloak server that detects and applies the build options first. In the example, the line --db=postgres --features=token-exchange sets the database vendor to PostgreSQL and enables the token exchange feature.

Red Hat build of Keycloak then starts up and applies the configuration for the specific environment. This approach significantly increases startup time and creates an image that is mutable, which is not the best practice.

Red Hat build of Keycloak only allows to create the initial admin user from a local network connection. This is not the case when running in a container, so you have to provide the following environment variables when you run the image: 

# setting the admin username
-e KC_BOOTSTRAP_ADMIN_USERNAME=<admin-user-name>

# setting the initial password
-e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me
Copy to Clipboard Toggle word wrap

5.6. Importing A Realm On Startup
Copy link

The Red Hat build of Keycloak containers have a directory /opt/keycloak/data/import. If you put one or more import files in that directory via a volume mount or other means and add the startup argument --import-realm, the Red Hat build of Keycloak container will import that data on startup! This may only make sense to do in Dev mode. 

podman run --name keycloak_unoptimized -p 127.0.0.1:8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        -v /path/to/realm/data:/opt/keycloak/data/import \
        registry.redhat.io/rhbk/keycloak-rhel9:26.4 \
        start-dev --import-realm
Copy to Clipboard Toggle word wrap

Feel free to join the open GitHub Discussion around enhancements of the admin bootstrapping process.

5.7. Specifying different memory settings
Copy link

The Red Hat build of Keycloak container, instead of specifying hardcoded values for the initial and maximum heap size, uses relative values to the total memory of a container. This behavior is achieved by JVM options -XX:MaxRAMPercentage=70, and -XX:InitialRAMPercentage=50.

The -XX:MaxRAMPercentage option represents the maximum heap size as 70% of the total container memory. The -XX:InitialRAMPercentage option represents the initial heap size as 50% of the total container memory. These values were chosen based on a deeper analysis of Red Hat build of Keycloak memory management.

As the heap size is dynamically calculated based on the total container memory, you should always set the memory limit for the container. Previously, the maximum heap size was set to 512 MB, and in order to approach similar values, you should set the memory limit to at least 750 MB. For smaller production-ready deployments, the recommended memory limit is 2 GB.

The JVM options related to the heap might be overridden by setting the environment variable JAVA_OPTS_KC_HEAP. You can find the default values of the JAVA_OPTS_KC_HEAP in the source code of the kc.sh, or kc.bat script.

For example, you can specify the environment variable and memory limit as follows: 

podman run --name mykeycloak -p 127.0.0.1:8080:8080 -m 1g \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        -e JAVA_OPTS_KC_HEAP="-XX:MaxHeapFreeRatio=30 -XX:MaxRAMPercentage=65" \
        registry.redhat.io/rhbk/keycloak-rhel9:26.4 \
        start-dev
Copy to Clipboard Toggle word wrap
Warning

If the memory limit is not set, the memory consumption rapidly increases as the heap size can grow up to 70% of the total container memory. Once the JVM allocates the memory, it is returned to the OS reluctantly with the current Red Hat build of Keycloak GC settings.

5.8. Relevant options
Copy link

Expand
 Value

db 🛠

The database vendor.

In production mode the default value of dev-file is deprecated, you should explicitly specify the db instead.

Named key: db-kind-<datasource> 🛠

CLI: --db
Env: KC_DB

dev-file (default), dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb

db-password

The password of the database user.

Named key: db-password-<datasource>

CLI: --db-password
Env: KC_DB_PASSWORD

 

db-url

The full database JDBC URL.

If not provided, a default URL is set based on the selected database vendor. For instance, if using postgres, the default JDBC URL would be jdbc:postgresql://localhost/keycloak.

Named key: db-url-full-<datasource>

CLI: --db-url
Env: KC_DB_URL

 

db-username

The username of the database user.

Named key: db-username-<datasource>

CLI: --db-username
Env: KC_DB_USERNAME

 

features 🛠

Enables a set of one or more features.

CLI: --features
Env: KC_FEATURES

account-api[:v1], account[:v3], admin-api[:v1], admin-fine-grained-authz[:v1,v2], admin[:v2], authorization[:v1], ciba[:v1], client-auth-federated[:v1], client-policies[:v1], client-secret-rotation[:v1], client-types[:v1], clusterless[:v1], db-tidb[:v1], declarative-ui[:v1], device-flow[:v1], docker[:v1], dpop[:v1], dynamic-scopes[:v1], fips[:v1], hostname[:v2], impersonation[:v1], instagram-broker[:v1], ipa-tuura-federation[:v1], kerberos[:v1], kubernetes-service-accounts[:v1], log-mdc[:v1], login[:v2,v1], logout-all-sessions[:v1], multi-site[:v1], oid4vc-vci[:v1], opentelemetry[:v1], organization[:v1], par[:v1], passkeys-conditional-ui-authenticator[:v1], passkeys[:v1], persistent-user-sessions[:v1], preview, quick-theme[:v1], recovery-codes[:v1], rolling-updates[:v1,v2], scripts[:v1], spiffe[:v1], step-up-authentication[:v1], token-exchange-external-internal[:v2], token-exchange-standard[:v2], token-exchange[:v1], transient-users[:v1], update-email[:v1], user-event-metrics[:v1], web-authn[:v1], workflows[:v1]

hostname

Address at which is the server exposed.

Can be a full URL, or just a hostname. When only hostname is provided, scheme, port and context path are resolved from the request.

CLI: --hostname
Env: KC_HOSTNAME

Available only when hostname:v2 feature is enabled

 

https-key-store-file

The key store which holds the certificate information instead of specifying separate files.

CLI: --https-key-store-file
Env: KC_HTTPS_KEY_STORE_FILE

 

https-key-store-password

The password of the key store file.

CLI: --https-key-store-password
Env: KC_HTTPS_KEY_STORE_PASSWORD

password (default)

health-enabled 🛠

If the server should expose health check endpoints.

If enabled, health checks are available at the /health, /health/ready and /health/live endpoints.

CLI: --health-enabled
Env: KC_HEALTH_ENABLED

true, false (default)

metrics-enabled 🛠

If the server should expose metrics.

If enabled, metrics are available at the /metrics endpoint.

CLI: --metrics-enabled
Env: KC_METRICS_ENABLED

true, false (default)

Chapter 6. Configuring TLS
Copy link

Configure Red Hat build of Keycloak’s https certificates for ingoing and outgoing requests.

Transport Layer Security (short: TLS) is crucial to exchange data over a secured channel. For production environments, you should never expose Red Hat build of Keycloak endpoints through HTTP, as sensitive data is at the core of what Red Hat build of Keycloak exchanges with other applications. In this chapter, you will learn how to configure Red Hat build of Keycloak to use HTTPS/TLS.

Red Hat build of Keycloak can be configured to load the required certificate infrastructure using files in PEM format or from a Java Keystore. When both alternatives are configured, the PEM files takes precedence over the Java Keystores.

6.1. Providing certificates in PEM format
Copy link

When you use a pair of matching certificate and private key files in PEM format, you configure Red Hat build of Keycloak to use them by running the following command: 

bin/kc.[sh|bat] start --https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pem
Copy to Clipboard Toggle word wrap

Red Hat build of Keycloak creates a keystore out of these files in memory and uses this keystore afterwards.

6.2. Providing a Keystore
Copy link

When no keystore file is explicitly configured, but http-enabled is set to false, Red Hat build of Keycloak looks for a conf/server.keystore file.

As an alternative, you can use an existing keystore by running the following command: 

bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-file
Copy to Clipboard Toggle word wrap

Recognized file extensions for a keystore:

  • .p12, .pkcs12, and .pfx for a pkcs12 file
  • .jks, and .keystore for a jks file
  • .key, .crt, and .pem for a pem file

If your keystore does not have an extension matching its file type, you will also need to set the https-key-store-type option.

6.2.1. Setting the Keystore password
Copy link

You can set a secure password for your keystore using the https-key-store-password option: 

bin/kc.[sh|bat] start --https-key-store-password=<value>
Copy to Clipboard Toggle word wrap

If no password is set, the default password password is used.

6.2.1.1. Securing credentials
Copy link

Avoid setting a password in plaintext by using the CLI or adding it to conf/keycloak.conf file. Instead use good practices such as using a vault / mounted secret. For more detail, see Using a vault and Configuring Red Hat build of Keycloak for production.

6.3. Configuring TLS protocols
Copy link

By default, Red Hat build of Keycloak does not enable deprecated TLS protocols. If your client supports only deprecated protocols, consider upgrading the client. However, as a temporary work-around, you can enable deprecated protocols by running the following command: 

bin/kc.[sh|bat] start --https-protocols=<protocol>[,<protocol>]
Copy to Clipboard Toggle word wrap

For example to only enable TLSv1.3, use a command such as the following: kc.sh start --https-protocols=TLSv1.3.

6.4. Switching the HTTPS port
Copy link

Red Hat build of Keycloak listens for HTTPS traffic on port 8443. To change this port, use the following command: 

bin/kc.[sh|bat] start --https-port=<port>
Copy to Clipboard Toggle word wrap

6.5. Certificate and Key Reloading
Copy link

By default Red Hat build of Keycloak will reload the certificates, keys, and keystores specified in https-* options every hour. For environments where your server keys may need frequent rotation, this allows that to happen without a server restart. You may override the default via the https-certificates-reload-period option. Interval on which to reload key store, trust store, and certificate files referenced by https-* options. The value may be a java.time.Duration value, an integer number of seconds, or an integer followed by one of the time units [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable.

6.6. Relevant options
Copy link

Expand
 Value

http-enabled

Enables the HTTP listener.

Enabled by default in development mode. Typically not enabled in production unless the server is fronted by a TLS termination proxy.

CLI: --http-enabled
Env: KC_HTTP_ENABLED

true, false (default)

https-certificate-file

The file path to a server certificate or certificate chain in PEM format.

CLI: --https-certificate-file
Env: KC_HTTPS_CERTIFICATE_FILE

 

https-certificate-key-file

The file path to a private key in PEM format.

CLI: --https-certificate-key-file
Env: KC_HTTPS_CERTIFICATE_KEY_FILE

 

https-certificates-reload-period

Interval on which to reload key store, trust store, and certificate files referenced by https-* options.

May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable.

CLI: --https-certificates-reload-period
Env: KC_HTTPS_CERTIFICATES_RELOAD_PERIOD

1h (default)

https-cipher-suites

The cipher suites to use.

If none is given, a reasonable default is selected.

CLI: --https-cipher-suites
Env: KC_HTTPS_CIPHER_SUITES

 

https-key-store-file

The key store which holds the certificate information instead of specifying separate files.

CLI: --https-key-store-file
Env: KC_HTTPS_KEY_STORE_FILE

 

https-key-store-password

The password of the key store file.

CLI: --https-key-store-password
Env: KC_HTTPS_KEY_STORE_PASSWORD

password (default)

https-key-store-type

The type of the key store file.

If not given, the type is automatically detected based on the file extension. If fips-mode is set to strict and no value is set, it defaults to BCFKS.

CLI: --https-key-store-type
Env: KC_HTTPS_KEY_STORE_TYPE

 

https-port

The used HTTPS port.

CLI: --https-port
Env: KC_HTTPS_PORT

8443 (default)

https-protocols

The list of protocols to explicitly enable.

If a value is not supported by the JRE / security configuration, it will be silently ignored.

CLI: --https-protocols
Env: KC_HTTPS_PROTOCOLS

TLSv1.3, TLSv1.2, or any

6.6.1. Management server
Copy link

Expand
 Value

https-management-certificate-file

The file path to a server certificate or certificate chain in PEM format for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificate-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_FILE

Available only when http-management-scheme is inherited

 

https-management-certificate-key-file

The file path to a private key in PEM format for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificate-key-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_KEY_FILE

Available only when http-management-scheme is inherited

 

https-management-certificates-reload-period

Interval on which to reload key store, trust store, and certificate files referenced by https-management-* options for the management server.

May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificates-reload-period
Env: KC_HTTPS_MANAGEMENT_CERTIFICATES_RELOAD_PERIOD

Available only when http-management-scheme is inherited

1h (default)

https-management-key-store-file

The key store which holds the certificate information instead of specifying separate files for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-key-store-file
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_FILE

Available only when http-management-scheme is inherited

 

https-management-key-store-password

The password of the key store file for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-key-store-password
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_PASSWORD

Available only when http-management-scheme is inherited

password (default)

Chapter 7. Configuring the hostname (v2)
Copy link

Configure the frontend and backchannel endpoints exposed by Red Hat build of Keycloak.

7.1. The importance of setting the hostname option
Copy link

By default, Red Hat build of Keycloak mandates the configuration of the hostname option and does not dynamically resolve URLs. This is a security measure.

Red Hat build of Keycloak freely discloses its own URLs, for instance through the OIDC Discovery endpoint, or as part of the password reset link in an email. If the hostname was dynamically interpreted from a hostname header, it could provide a potential attacker with an opportunity to manipulate a URL in the email, redirect a user to the attacker’s fake domain, and steal sensitive data such as action tokens, passwords, etc.

By explicitly setting the hostname option, we avoid a situation where tokens could be issued by a fraudulent issuer. The server can be started with an explicit hostname using the following command: 

bin/kc.[sh|bat] start --hostname my.keycloak.org
Copy to Clipboard Toggle word wrap
Note

The examples start the Red Hat build of Keycloak instance in production mode, which requires a public certificate and private key in order to secure communications. For more information, refer to the Configuring Red Hat build of Keycloak for production.

As demonstrated in the previous example, the scheme and port are not explicitly required. In such cases, Red Hat build of Keycloak automatically handles these aspects. For instance, the server would be accessible at https://my.keycloak.org:8443 in the given example. However, a reverse proxy will typically expose Red Hat build of Keycloak at the default ports, e.g. 443. In that case it’s desirable to specify the full URL in the hostname option rather than keeping the parts of the URL dynamic. The server can then be started with: 

bin/kc.[sh|bat] start --hostname https://my.keycloak.org
Copy to Clipboard Toggle word wrap

Similarly, your reverse proxy might expose Red Hat build of Keycloak at a different context path. It is possible to configure Red Hat build of Keycloak to reflect that via the hostname and hostname-admin options. See the following example: 

bin/kc.[sh|bat] start --hostname https://my.keycloak.org:123/auth
Copy to Clipboard Toggle word wrap

Red Hat build of Keycloak has the capability to offer a separate URL for backchannel requests, enabling internal communication while maintaining the use of a public URL for frontchannel requests. Moreover, the backchannel is dynamically resolved based on incoming headers. Consider the following example: 

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic true
Copy to Clipboard Toggle word wrap

In this manner, your applications, referred to as clients, can connect with Red Hat build of Keycloak through your local network, while the server remains publicly accessible at https://my.keycloak.org.

7.4. Using edge TLS termination
Copy link

As you can observe, the HTTPS protocol is the default choice, adhering to Red Hat build of Keycloak’s commitment to security best practices. However, Red Hat build of Keycloak also provides the flexibility for users to opt for HTTP if necessary. This can be achieved simply by specifying the HTTP listener, consult the Configuring TLS for details. With an edge TLS-termination proxy you can start the server as follows: 

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --http-enabled true
Copy to Clipboard Toggle word wrap

The result of this configuration is that you can continue to access Red Hat build of Keycloak at https://my.keycloak.org via HTTPS, while the proxy interacts with the instance using HTTP and port 8080.

7.5. Using a reverse proxy
Copy link

When a proxy is forwarding http or reencrypted TLS requests, the proxy-headers option should be set. Depending on the hostname settings, some or all of the URL, may be dynamically determined.

Warning

If either forwarded or xforwarded is selected, make sure your reverse proxy properly sets and overwrites the Forwarded or X-Forwarded-* headers respectively. To set these headers, consult the documentation for your reverse proxy. Misconfiguration will leave Red Hat build of Keycloak exposed to security vulnerabilities.

7.5.1. Fully dynamic URLs.
Copy link

For example if your reverse proxy correctly sets the Forwarded header, and you don’t want to hardcode the hostname, Red Hat build of Keycloak can accommodate this. You simply need to initiate the server as follows: 

bin/kc.[sh|bat] start --hostname-strict false --proxy-headers forwarded
Copy to Clipboard Toggle word wrap

With this configuration, the server respects the value set by the Forwarded header. This also implies that all endpoints are dynamically resolved.

7.5.2. Partially dynamic URLs
Copy link

The proxy-headers option can be also used to resolve the URL partially dynamically when the hostname option is not specified as a full URL. For example: 

bin/kc.[sh|bat] start --hostname my.keycloak.org --proxy-headers xforwarded
Copy to Clipboard Toggle word wrap

In this case, scheme, and port are resolved dynamically from X-Forwarded-* headers, while hostname is statically defined as my.keycloak.org.

7.5.3. Fixed URLs
Copy link

The proxy-headers is still relevant even when the hostname is set to a full URL as the headers are used to determine the origin of the request. For example: 

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --proxy-headers xforwarded
Copy to Clipboard Toggle word wrap

In this case, while nothing is dynamically resolved from the X-Forwarded-* headers, the X-Forwarded-* headers are used to determine the correct origin of the request.

If you wish to expose the Admin Console on a different host, you can do so with the following command: 

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443
Copy to Clipboard Toggle word wrap

This allows you to access Red Hat build of Keycloak at https://my.keycloak.org and the Admin Console at https://admin.my.keycloak.org:8443, while the backend continues to use https://my.keycloak.org.

Note

Keep in mind that hostname and proxy options do not change the ports on which the server listens. Instead it changes only the ports of static resources like JavaScript and CSS links, OIDC well-known endpoints, redirect URIs, etc. that will be used in front of the proxy. You need to use HTTP configuration options to change the actual ports the server is listening on. Refer to the All configuration for details.

Warning

Using the hostname-admin option does not prevent accessing the Administration REST API endpoints via the frontend URL specified by the hostname option. If you want to restrict access to the Administration REST API, you need to do it on the reverse proxy level. Administration Console implicitly accesses the API using the URL as specified by the hostname-admin option.

7.7. Background - server endpoints
Copy link

Red Hat build of Keycloak exposes several endpoints, each with a different purpose. They are typically used for communication among applications or for managing the server. We recognize 3 main endpoint groups:

  • Frontend
  • Backend
  • Administration

If you want to work with either of these endpoints, you need to set the base URL. The base URL consists of a several parts:

  • a scheme (e.g. https protocol)
  • a hostname (e.g. example.keycloak.org)
  • a port (e.g. 8443)
  • a path (e.g. /auth)

The base URL for each group has an important impact on how tokens are issued and validated, on how links are created for actions that require the user to be redirected to Red Hat build of Keycloak (for example, when resetting password through email links), and, most importantly, how applications will discover these endpoints when fetching the OpenID Connect Discovery Document from realms/{realm-name}/.well-known/openid-configuration.

7.7.1. Frontend
Copy link

Users and applications use the frontend URL to access Red Hat build of Keycloak through a front channel. The front channel is a publicly accessible communication channel. For example browser-based flows (accessing the login page, clicking on the link to reset a password or binding the tokens) can be considered as frontchannel requests.

In order to make Red Hat build of Keycloak accessible via the frontend URL, you need to set the hostname option: 

bin/kc.[sh|bat] start --hostname my.keycloak.org
Copy to Clipboard Toggle word wrap

7.7.2. Backend
Copy link

The backend endpoints are those accessible through a public domain or through a private network. They’re related to direct backend communication between Red Hat build of Keycloak and a client (an application secured by Red Hat build of Keycloak). Such communication might be over a local network, avoiding a reverse proxy. Examples of the endpoints that belong to this group are the authorization endpoint, token and token introspection endpoint, userinfo endpoint, JWKS URI endpoint, etc.

The default value of hostname-backchannel-dynamic option is false, which means that the backchannel URLs are same as the frontchannel URLs. Dynamic resolution of backchannel URLs from incoming request headers can be enabled by setting the following options: 

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic true
Copy to Clipboard Toggle word wrap

Note that hostname option must be set to a URL. For more information, refer to the Section 7.9, “Validations” section below.

7.7.3. Administration
Copy link

Similarly to the base frontend URL, you can also set the base URL for resources and endpoints of the administration console. The server exposes the administration console and static resources using a specific URL. This URL is used for redirect URLs, loading resources (CSS, JS), Administration REST API etc. It can be done by setting the hostname-admin option: 

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443
Copy to Clipboard Toggle word wrap

Again, the hostname option must be set to a URL. For more information, refer to the Section 7.9, “Validations” section below.

7.8. Sources for resolving the URL
Copy link

As indicated in the previous sections, URLs can be resolved in several ways: they can be dynamically generated, hardcoded, or a combination of both:

  • Dynamic from an incoming request:

    • Host header, scheme, server port, context path
    • Proxy-set headers: Forwarded and X-Forwarded-*

  • Hardcoded:

    • Server-wide config (e.g hostname, hostname-admin, etc.)
    • Realm configuration for frontend URL

7.9. Validations
Copy link

  • hostname URL and hostname-admin URL are verified that full URL is used, incl. scheme and hostname. Port is validated only if present, otherwise default port for given protocol is assumed (80 or 443).

  • In production profile (kc.sh|bat start), either --hostname or --hostname-strict false must be explicitly configured.

    • This does not apply for dev profile (kc.sh|bat start-dev) where --hostname-strict false is the default value.

  • If --hostname is not configured:

    • hostname-backchannel-dynamic must be set to false.
    • hostname-strict must be set to false.
  • If hostname-admin is configured, hostname must be set to a URL (not just hostname). Otherwise Red Hat build of Keycloak would not know what is the correct frontend URL (incl. port etc.) when accessing the Admin Console.
  • If hostname-backchannel-dynamic is set to true, hostname must be set to a URL (not just hostname). Otherwise Red Hat build of Keycloak would not know what is the correct frontend URL (incl. port etc.) when being access via the dynamically resolved backchannel.

Additionally if hostname is configured, then hostname-strict is ignored.

7.10. Troubleshooting
Copy link

To troubleshoot the hostname configuration, you can use a dedicated debug tool which can be enabled as:

Red Hat build of Keycloak configuration:

bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-debug=true
Copy to Clipboard Toggle word wrap

After Red Hat build of Keycloak starts properly, open your browser and go to: http://mykeycloak:8080/realms/<your-realm>/hostname-debug

7.11. Relevant options
Copy link

Expand
Table 7.1. By default, this endpoint is disabled (--hostname-debug=false)
 Value

hostname

Address at which is the server exposed.

Can be a full URL, or just a hostname. When only hostname is provided, scheme, port and context path are resolved from the request.

CLI: --hostname
Env: KC_HOSTNAME

Available only when hostname:v2 feature is enabled

 

hostname-admin

Address for accessing the administration console.

Use this option if you are exposing the administration console using a reverse proxy on a different address than specified in the hostname option.

CLI: --hostname-admin
Env: KC_HOSTNAME_ADMIN

Available only when hostname:v2 feature is enabled

 

hostname-backchannel-dynamic

Enables dynamic resolving of backchannel URLs, including hostname, scheme, port and context path.

Set to true if your application accesses Keycloak via a private network. If set to true, hostname option needs to be specified as a full URL.

CLI: --hostname-backchannel-dynamic
Env: KC_HOSTNAME_BACKCHANNEL_DYNAMIC

Available only when hostname:v2 feature is enabled

true, false (default)

hostname-debug

Toggles the hostname debug page that is accessible at /realms/master/hostname-debug.

CLI: --hostname-debug
Env: KC_HOSTNAME_DEBUG

Available only when hostname:v2 feature is enabled

true, false (default)

hostname-strict

Disables dynamically resolving the hostname from request headers.

Should always be set to true in production, unless your reverse proxy overwrites the Host header. If enabled, the hostname option needs to be specified.

CLI: --hostname-strict
Env: KC_HOSTNAME_STRICT

Available only when hostname:v2 feature is enabled

true (default), false

Chapter 8. Configuring a reverse proxy
Copy link

Configure Red Hat build of Keycloak with a reverse proxy, API gateway, or load balancer.

Distributed environments frequently require the use of a reverse proxy. Red Hat build of Keycloak offers several options to securely integrate with such environments.

8.1. Port to be proxied
Copy link

Red Hat build of Keycloak runs on the following ports by default:

  • 8443 (8080 when you enable HTTP explicitly by --http-enabled=true)
  • 9000

The port 8443 (or 8080 if HTTP is enabled) is used for the Admin UI, Account Console, SAML and OIDC endpoints and the Admin REST API as described in the Configuring the hostname (v2) chapter.

The port 9000 is used for management, which includes endpoints for health checks and metrics as described in the Configuring the Management Interface chapter.

You only need to proxy port 8443 (or 8080) even when you use different host names for frontend/backend and administration as described at Configuring Red Hat build of Keycloak for production. You should not proxy port 9000 as health checks and metrics use those ports directly, and you do not want to expose this information to external callers.

8.2. Configure the reverse proxy headers
Copy link

Red Hat build of Keycloak will parse the reverse proxy headers based on the proxy-headers option which accepts several values:

  • By default if the option is not specified, no reverse proxy headers are parsed. This should be used when no proxy is in use or with https passthrough.
  • forwarded enables parsing of the Forwarded header as per RFC7239.
  • xforwarded enables parsing of non-standard X-Forwarded-* headers, such as X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Port.
Note

If you are using a reverse proxy for anything other than https passthrough and do not set the proxy-headers option, then by default you will see 403 Forbidden responses to requests via the proxy that perform origin checking.

For example: 

bin/kc.[sh|bat] start --proxy-headers forwarded
Copy to Clipboard Toggle word wrap
Warning

If either forwarded or xforwarded is selected, make sure your reverse proxy properly sets and overwrites the Forwarded or X-Forwarded-* headers respectively. To set these headers, consult the documentation for your reverse proxy. Do not use forwarded or xforwarded with https passthrough. Misconfiguration will leave Red Hat build of Keycloak exposed to security vulnerabilities.

Take extra precautions to ensure that the client address is properly set by your reverse proxy via the Forwarded or X-Forwarded-For headers. If this header is incorrectly configured, rogue clients can set this header and trick Red Hat build of Keycloak into thinking the client is connected from a different IP address than the actual address. This precaution can be more critical if you do any deny or allow listing of IP addresses.

Note

When using the xforwarded setting, the X-Forwarded-Port takes precedence over any port included in the X-Forwarded-Host.

Note

If the TLS connection is terminated at the reverse proxy (edge termination), enabling HTTP through the http-enabled setting is required.

8.3. Different context-path on reverse proxy
Copy link

Red Hat build of Keycloak assumes it is exposed through the reverse proxy under the same context path as Red Hat build of Keycloak is configured for. By default Red Hat build of Keycloak is exposed through the root (/), which means it expects to be exposed through the reverse proxy on / as well. You can use a full URL for the hostname option in these cases, for example using --hostname=https://my.keycloak.org/auth if Red Hat build of Keycloak is exposed through the reverse proxy on /auth.

For more details on exposing Red Hat build of Keycloak on different hostname or context-path incl. Administration REST API and Console, see Configuring the hostname (v2).

Alternatively you can also change the context path of Red Hat build of Keycloak itself to match the context path for the reverse proxy using the http-relative-path option, which will change the context-path of Red Hat build of Keycloak itself to match the context path used by the reverse proxy.

8.4. Enable sticky sessions
Copy link

Typical cluster deployment consists of the load balancer (reverse proxy) and 2 or more Red Hat build of Keycloak servers on private network. For performance purposes, it may be useful if load balancer forwards all requests related to particular browser session to the same Red Hat build of Keycloak backend node.

The reason is, that Red Hat build of Keycloak is using Infinispan distributed cache under the covers for save data related to current authentication session and user session. The Infinispan distributed caches are configured with limited number of owners. That means that session related data are stored only in some cluster nodes and the other nodes need to lookup the data remotely if they want to access it.

For example if authentication session with ID 123 is saved in the Infinispan cache on node1, and then node2 needs to lookup this session, it needs to send the request to node1 over the network to return the particular session entity.

It is beneficial if particular session entity is always available locally, which can be done with the help of sticky sessions. The workflow in the cluster environment with the public frontend load balancer and two backend Red Hat build of Keycloak nodes can be like this:

  • User sends initial request to see the Red Hat build of Keycloak login screen
  • This request is served by the frontend load balancer, which forwards it to some random node (eg. node1). Strictly said, the node doesn’t need to be random, but can be chosen according to some other criteria (client IP address etc). It all depends on the implementation and configuration of underlying load balancer (reverse proxy).
  • Red Hat build of Keycloak creates authentication session with random ID (eg. 123) and saves it to the Infinispan cache.
  • Infinispan distributed cache assigns the primary owner of the session based on the hash of session ID. See Infinispan documentation for more details around this. Let’s assume that Infinispan assigned node2 to be the owner of this session.
  • Red Hat build of Keycloak creates the cookie AUTH_SESSION_ID with the format like <session-id>.<owner-node-id> . In our example case, it will be 123.node2 .
  • Response is returned to the user with the Red Hat build of Keycloak login screen and the AUTH_SESSION_ID cookie in the browser

From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID 123 and hence Infinispan can lookup this session locally. After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID 123 .

The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to stick over the AUTH_SESSION_ID cookie. The appropriate procedure to make this change depends on your loadbalancer.

If your proxy supports session affinity without processing cookies from backend nodes, you should set the spi-sticky-session-encoder--infinispan--should-attach-route option to false in order to avoid attaching the node to cookies and just rely on the reverse proxy capabilities. 

bin/kc.[sh|bat] start --spi-sticky-session-encoder--infinispan--should-attach-route=false
Copy to Clipboard Toggle word wrap

By default, the spi-sticky-session-encoder--infinispan--should-attach-route option value is true so that the node name is attached to cookies to indicate to the reverse proxy the node that subsequent requests should be sent to.

8.5. Exposed path recommendations
Copy link

When using a reverse proxy, Red Hat build of Keycloak only requires certain paths to be exposed. The following table shows the recommended paths to expose.

Expand
Red Hat build of Keycloak PathReverse Proxy PathExposedReason

/

-

No

When exposing all paths, admin paths are exposed unnecessarily.

/admin/

-

No

Exposed admin paths lead to an unnecessary attack vector.

/realms/

/realms/

Yes

This path is needed to work correctly, for example, for OIDC endpoints.

/resources/

/resources/

Yes

This path is needed to serve assets correctly. It may be served from a CDN instead of the Red Hat build of Keycloak path.

/.well-known/

/.well-known/

Yes

This path is needed to resolve Authorization Server Metadata and other information via RFC8414.

/metrics

-

No

Exposed metrics lead to an unnecessary attack vector.

/health

-

No

Exposed health checks lead to an unnecessary attack vector.

We assume you run Red Hat build of Keycloak on the root path / on your reverse proxy/gateway’s public API. If not, prefix the path with your desired one.

Note

If you configured a http-relative-path on the server, proceed as follows to use discovery wih RFC8414: Configure a reverse proxy to map the /.well-known/ path without the prefix to the path with the prefix on the server.

8.6. Trusted Proxies
Copy link

To ensure that proxy headers are used only from proxies you trust, set the proxy-trusted-addresses option to a comma separated list of IP addresses (IPv4 or IPv6) or Classless Inter-Domain Routing (CIDR) notations.

For example: 

bin/kc.[sh|bat] start --proxy-headers forwarded --proxy-trusted-addresses=192.168.0.32,127.0.0.0/8
Copy to Clipboard Toggle word wrap

8.7. PROXY Protocol
Copy link

The proxy-protocol-enabled option controls whether the server should use the HA PROXY protocol when serving requests from behind a proxy. When set to true, the remote address returned will be the one from the actual connecting client. The value cannot be true when using the proxy-headers option.

This is useful when running behind a compatible https passthrough proxy because the request headers cannot be manipulated.

For example: 

bin/kc.[sh|bat] start --proxy-protocol-enabled true
Copy to Clipboard Toggle word wrap

8.8. Enabling client certificate lookup
Copy link

When the proxy is configured as a TLS termination proxy the client certificate information can be forwarded to the server through specific HTTP request headers and then used to authenticate clients. You are able to configure how the server is going to retrieve client certificate information depending on the proxy you are using.

Warning

Client certificate lookup via a proxy header for X.509 authentication is considered security-sensitive. If misconfigured, a forged client certificate header can be used for authentication. Extra precautions need to be taken to ensure that the client certificate information can be trusted when passed via a proxy header.

  • Double check your use case needs reencrypt or edge TLS termination which implies using a proxy header for client certificate lookup. TLS passthrough is recommended as a more secure option when X.509 authentication is desired as it does not require passing the certificate via a proxy header. Client certificate lookup from a proxy header is applicable only to reencrypt and edge TLS termination.

  • If passthrough is not an option, implement the following security measures:

    • Configure your network so that Red Hat build of Keycloak is isolated and can accept connections only from the proxy.
    • Make sure that the proxy overwrites the header that is configured in spi-x509cert-lookup--<provider>--ssl-client-cert option.
    • Pay extra attention to the spi-x509cert-lookup--<provider>--trust-proxy-verification setting. Make sure you enable it only if you can trust your proxy to verify the client certificate. Setting spi-x509cert-lookup--<provider>--trust-proxy-verification=true without the proxy verifying the client certificate chain will expose Red Hat build of Keycloak to security vulnerability when a forged client certificate can be used for authentication.

The server supports some of the most commons TLS termination proxies such as:

Expand
ProxyProvider

Apache HTTP Server

apache

HAProxy

haproxy

NGINX

nginx

To configure how client certificates are retrieved from the requests you need to:

Enable the corresponding proxy provider

bin/kc.[sh|bat] build --spi-x509cert-lookup--provider=<provider>
Copy to Clipboard Toggle word wrap

Configure the HTTP headers

bin/kc.[sh|bat] start --spi-x509cert-lookup--<provider>--ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup--<provider>--ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup--<provider>-certificate-chain-length=10
Copy to Clipboard Toggle word wrap

When configuring the HTTP headers, you need to make sure the values you are using correspond to the name of the headers forwarded by the proxy with the client certificate information.

The available options for configuring a provider are:

Expand
OptionDescription

ssl-client-cert

The name of the header holding the client certificate

ssl-cert-chain-prefix

The prefix of the headers holding additional certificates in the chain and used to retrieve individual certificates accordingly to the length of the chain. For instance, a value CERT_CHAIN will tell the server to load additional certificates from headers CERT_CHAIN_0 to CERT_CHAIN_9 if certificate-chain-length is set to 10.

certificate-chain-length

The maximum length of the certificate chain.

trust-proxy-verification

Enable trusting NGINX proxy certificate verification, instead of forwarding the certificate to Red Hat build of Keycloak and verifying it in Red Hat build of Keycloak.

cert-is-url-encoded

Whether the forwarded certificate is url-encoded or not. In NGINX, this corresponds to the $ssl_client_cert and $ssl_client_escaped_cert variables. This can also be used for the Traefik PassTlsClientCert middleware, as it sends the client certficate unencoded.

8.8.1. Configuring the NGINX provider
Copy link

The NGINX SSL/TLS module does not expose the client certificate chain. Red Hat build of Keycloak’s NGINX certificate lookup provider rebuilds it by using the Red Hat build of Keycloak truststore.

If you are using this provider, see Configuring trusted certificates for how to configure a Red Hat build of Keycloak Truststore.

8.9. Relevant options
Copy link

Expand
 Value

hostname

Address at which is the server exposed.

Can be a full URL, or just a hostname. When only hostname is provided, scheme, port and context path are resolved from the request.

CLI: --hostname
Env: KC_HOSTNAME

Available only when hostname:v2 feature is enabled

 

hostname-admin

Address for accessing the administration console.

Use this option if you are exposing the administration console using a reverse proxy on a different address than specified in the hostname option.

CLI: --hostname-admin
Env: KC_HOSTNAME_ADMIN

Available only when hostname:v2 feature is enabled

 

http-relative-path 🛠

Set the path relative to / for serving resources.

The path must start with a /.

CLI: --http-relative-path
Env: KC_HTTP_RELATIVE_PATH

/ (default)

proxy-headers

The proxy headers that should be accepted by the server.

Misconfiguration might leave the server exposed to security vulnerabilities. Takes precedence over the deprecated proxy option.

CLI: --proxy-headers
Env: KC_PROXY_HEADERS

forwarded, xforwarded

proxy-protocol-enabled

Whether the server should use the HA PROXY protocol when serving requests from behind a proxy.

When set to true, the remote address returned will be the one from the actual connecting client. Cannot be enabled when the proxy-headers is used.

CLI: --proxy-protocol-enabled
Env: KC_PROXY_PROTOCOL_ENABLED

true, false (default)

proxy-trusted-addresses

A comma separated list of trusted proxy addresses.

If set, then proxy headers from other addresses will be ignored. By default all addresses are trusted. A trusted proxy address is specified as an IP address (IPv4 or IPv6) or Classless Inter-Domain Routing (CIDR) notation. Available only when proxy-headers is set.

CLI: --proxy-trusted-addresses
Env: KC_PROXY_TRUSTED_ADDRESSES

 

Chapter 9. Configuring the database
Copy link

Configure a relational database for Red Hat build of Keycloak to store user, client, and realm data.

This chapter explains how to configure the Red Hat build of Keycloak server to store data in a relational database.

9.1. Supported databases
Copy link

The server has built-in support for different databases. You can query the available databases by viewing the expected values for the db configuration option. The following table lists the supported databases and their tested versions.

Expand
DatabaseOption valueTested VersionSupported Versions

MariaDB Server

mariadb

11.8

11.8 (LTS), 11.4 (LTS), 10.11 (LTS), 10.6 (LTS)

Microsoft SQL Server

mssql

2022

2022, 2019

MySQL

mysql

8.4

8.4 (LTS), 8.0 (LTS)

Oracle Database

oracle

23.5

23.x (i.e 23.5+), 19c (19.3+) (Note: Oracle RAC is also supported if using the same database engine version, e.g 23.5+, 19.3+)

PostgreSQL

postgres

17

17.x, 16.x, 15.x, 14.x, 13.x

EnterpriseDB Advanced

postgres

17

17

Amazon Aurora PostgreSQL

postgres

17.5

17.x, 16.x, 15.x

Azure SQL Database

mssql

latest

latest

Azure SQL Managed Instance

mssql

latest

latest

Note

It is not a supported configuration if the underlying database specific Hibernate dialect allows the use of a version that differs from those shown.

By default, the server uses the dev-file database. This is the default database that the server will use to persist data and only exists for development use-cases. The dev-file database is not suitable for production use-cases, and must be replaced before deploying to production.

9.2. Installing a database driver
Copy link

Database drivers are shipped as part of Red Hat build of Keycloak except for the Oracle Database and Microsoft SQL Server drivers.

Install the necessary missing driver manually if you want to connect to one of these databases or skip this section if you want to connect to a different database for which the database driver is already included.

Note

Overriding the built-in database drivers or supplying your own drivers is considered unsupported. The only supported exceptions are explicitly documented in this guide, such as the Oracle Database driver.

9.2.1. Installing the Oracle Database driver
Copy link

To install the Oracle Database driver for Red Hat build of Keycloak:

  1. Download the ojdbc17 and orai18n JAR files from one of the following sources:

    1. Zipped JDBC driver and Companion Jars version 23.6.0.24.10 from the Oracle driver download page.
    2. Maven Central via ojdbc17 and orai18n.
    3. Installation media recommended by the database vendor for the specific database in use.
  2. When running the unzipped distribution: Place the ojdbc17 and orai18n JAR files in Red Hat build of Keycloak’s providers folder

  3. When running containers: Build a custom Red Hat build of Keycloak image and add the JARs in the providers folder. When building a custom image for the Operator, those images need to be optimized images with all build-time options of Red Hat build of Keycloak set.

    A minimal Containerfile to build an image which can be used with the Red Hat build of Keycloak Operator and includes Oracle Database JDBC drivers downloaded from Maven Central looks like the following: 

    FROM registry.redhat.io/rhbk/keycloak-rhel9:26.4
ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc17/23.6.0.24.10/ojdbc17-23.6.0.24.10.jar /opt/keycloak/providers/ojdbc17.jar
ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/nls/orai18n/23.6.0.24.10/orai18n-23.6.0.24.10.jar /opt/keycloak/providers/orai18n.jar
# Setting the build parameter for the database:
ENV KC_DB=oracle
# Add all other build parameters needed, for example enable health and metrics:
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
# To be able to use the image with the Red Hat build of Keycloak Operator, it needs to be optimized, which requires Red Hat build of Keycloak's build step:
RUN /opt/keycloak/bin/kc.sh build
    Copy to Clipboard Toggle word wrap

    See the Running Red Hat build of Keycloak in a container chapter for details on how to build optimized images.

Then continue configuring the database as described in the next section.

9.2.2. Installing the Microsoft SQL Server driver
Copy link

To install the Microsoft SQL Server driver for Red Hat build of Keycloak:

  1. Download the mssql-jdbc JAR file from one of the following sources:

    1. Download a version from the Microsoft JDBC Driver for SQL Server page.
    2. Maven Central via mssql-jdbc.
    3. Installation media recommended by the database vendor for the specific database in use.
  2. When running the unzipped distribution: Place the mssql-jdbc in Red Hat build of Keycloak’s providers folder

  3. When running containers: Build a custom Red Hat build of Keycloak image and add the JARs in the providers folder. When building a custom image for the Red Hat build of Keycloak Operator, those images need to be optimized images with all build-time options of Red Hat build of Keycloak set.

    A minimal Containerfile to build an image which can be used with the Red Hat build of Keycloak Operator and includes Microsoft SQL Server JDBC drivers downloaded from Maven Central looks like the following: 

    FROM registry.redhat.io/rhbk/keycloak-rhel9:26.4
ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/13.2.0.jre11/mssql-jdbc-13.2.0.jre11.jar /opt/keycloak/providers/mssql-jdbc.jar
# Setting the build parameter for the database:
ENV KC_DB=mssql
# Add all other build parameters needed, for example enable health and metrics:
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
# To be able to use the image with the Red Hat build of Keycloak Operator, it needs to be optimized, which requires Red Hat build of Keycloak's build step:
RUN /opt/keycloak/bin/kc.sh build
    Copy to Clipboard Toggle word wrap

    See the Running Red Hat build of Keycloak in a container chapter for details on how to build optimized images.

Then continue configuring the database as described in the next section.

9.3. Configuring a database
Copy link

For each supported database, the server provides some opinionated defaults to simplify database configuration. You complete the configuration by providing some key settings such as the database host and credentials.

The configuration can be set during a build command OR a start command:

  1. Using a build command followed by an optimized start command (recommended)

    First, the minimum settings needed to connect to the database can be specified in conf/keycloak.conf: 

    # The database vendor.
db=postgres

# The username of the database user.
db-username=keycloak

# The password of the database user.
db-password=change_me

# Sets the hostname of the default JDBC URL of the chosen vendor
db-url-host=keycloak-postgres
    Copy to Clipboard Toggle word wrap

    Then, the following commands create a new and optimized server image based on the configuration options and start the server. 

    bin/kc.[sh|bat] build
bin/kc.[sh|bat] start --optimized
    Copy to Clipboard Toggle word wrap

  2. Using only a start command (without --optimized) 

    bin/kc.[sh|bat] start --db postgres --db-url-host keycloak-postgres --db-username keycloak --db-password change_me
    Copy to Clipboard Toggle word wrap
Warning

The examples above include the minimum settings needed to connect to the database but it exposes the database password and is not recommended. Use the conf/keycloak.conf as shown above, environment variables, or keystore for at least the password.

The default schema is keycloak, but you can change it by using the db-schema configuration option.

It is also possible to configure the database when Importing and exporting realms or Bootstrapping and recovering an admin account: 

bin/kc.[sh|bat] import --help
bin/kc.[sh|bat] export --help
bin/kc.[sh|bat] bootstrap-admin --help
Copy to Clipboard Toggle word wrap

For more information, see Configuring Red Hat build of Keycloak.

9.4. Overriding default connection settings
Copy link

The server uses JDBC as the underlying technology to communicate with the database. If the default connection settings are insufficient, you can specify a JDBC URL using the db-url configuration option.

The following is a sample command for a PostgreSQL database. 

bin/kc.[sh|bat] start --db postgres --db-url jdbc:postgresql://mypostgres/mydatabase
Copy to Clipboard Toggle word wrap

Be aware that you need to escape characters when invoking commands containing special shell characters such as ; using the CLI, so you might want to set it in the configuration file instead.

9.5. Configuring Unicode support for the database
Copy link

Unicode support for all fields depends on whether the database allows VARCHAR and CHAR fields to use the Unicode character set.

  • If these fields can be set, Unicode is likely to work, usually at the expense of field length.
  • If the database only supports Unicode in the NVARCHAR and NCHAR fields, Unicode support for all text fields is unlikely to work because the server schema uses VARCHAR and CHAR fields extensively.

The database schema provides support for Unicode strings only for the following special fields:

  • Realms: display name, HTML display name, localization texts (keys and values)
  • Federation Providers: display name
  • Users: username, given name, last name, attribute names and values
  • Groups: name, attribute names and values
  • Roles: name
  • Descriptions of objects

Otherwise, characters are limited to those contained in database encoding, which is often 8-bit. However, for some database systems, you can enable UTF-8 encoding of Unicode characters and use the full Unicode character set in all text fields. For a given database, this choice might result in a shorter maximum string length than the maximum string length supported by 8-bit encodings.

Unicode characters are supported in an Oracle database if the database was created with Unicode support in the VARCHAR and CHAR fields. For example, you configured AL32UTF8 as the database character set. In this case, the JDBC driver requires no special settings.

If the database was not created with Unicode support, you need to configure the JDBC driver to support Unicode characters in the special fields. You configure two properties. Note that you can configure these properties as system properties or as connection properties.

  1. Set oracle.jdbc.defaultNChar to true.

  2. Optionally, set oracle.jdbc.convertNcharLiterals to true.

    Note

    For details on these properties and any performance implications, see the Oracle JDBC driver configuration documentation.

Unicode characters are supported only for the special fields for a Microsoft SQL Server database. The database requires no special settings.

The sendStringParametersAsUnicode property of JDBC driver should be set to false to significantly improve performance. Without this parameter, the Microsoft SQL Server might be unable to use indexes.

Unicode characters are supported in a MySQL database if the database was created with Unicode support in the VARCHAR and CHAR fields when using the CREATE DATABASE command.

Note that the utf8mb4 character set is not supported due to different storage requirements for the utf8 character set. See MySQL documentation for details. In that situation, the length restriction on non-special fields does not apply because columns are created to accommodate the number of characters, not bytes. If the database default character set does not allow Unicode storage, only the special fields allow storing Unicode values.

  1. Start MySQL Server.
  2. Under JDBC driver settings, locate the JDBC connection settings.
  3. Add this connection property: characterEncoding=UTF-8

Unicode is supported for a PostgreSQL database when the database character set is UTF8. Unicode characters can be used in any field with no reduction of field length for non-special fields. The JDBC driver requires no special settings. The character set is determined when the PostgreSQL database is created.

  1. Check the default character set for a PostgreSQL cluster by entering the following SQL command. 

    show server_encoding;
    Copy to Clipboard Toggle word wrap

  2. If the default character set is not UTF 8, create the database with the UTF8 as the default character set using a command such as: 

    create database keycloak with encoding 'UTF8';
    Copy to Clipboard Toggle word wrap

9.6. Preparing for PostgreSQL
Copy link

When running PostgreSQL reader and writer instances, Red Hat build of Keycloak needs to always connect to the writer instance to do its work. When using the original PostgreSQL driver, Red Hat build of Keycloak sets the targetServerType property of the PostgreSQL JDBC driver to primary to ensure that it always connects to a writable primary instance and never connects to a secondary reader instance in failover or switchover scenarios.

You can override this behavior by setting your own value for targetServerType in the DB URL or additional properties.

Note

The targetServerType is only applied automatically to the primary datasource, as requirements might be different for additional datasources.

9.7. Preparing for Amazon Aurora PostgreSQL
Copy link

When using Amazon Aurora PostgreSQL, the Amazon Web Services JDBC Driver offers additional features like transfer of database connections when a writer instance changes in a Multi-AZ setup. This driver is not part of the distribution and needs to be installed before it can be used.

To install this driver, apply the following steps:

  1. When running the unzipped distribution: Download the JAR file from the Amazon Web Services JDBC Driver releases page and place it in Red Hat build of Keycloak’s providers folder.

  2. When running containers: Build a custom Red Hat build of Keycloak image and add the JAR in the providers folder.

    A minimal Containerfile to build an image which can be used with the Red Hat build of Keycloak Operator looks like the following: 

    FROM registry.redhat.io/rhbk/keycloak-rhel9:26.4
ADD --chmod=0666 https://github.com/awslabs/aws-advanced-jdbc-wrapper/releases/download/2.5.6/aws-advanced-jdbc-wrapper-2.5.6.jar /opt/keycloak/providers/aws-advanced-jdbc-wrapper.jar
    Copy to Clipboard Toggle word wrap

    See the Running Red Hat build of Keycloak in a container chapter for details on how to build optimized images, and the Using custom Red Hat build of Keycloak images chapter on how to run optimized and non-optimized images with the Red Hat build of Keycloak Operator.

  3. Configure Red Hat build of Keycloak to run with the following parameters:

    db-url
    Insert aws-wrapper to the regular PostgreSQL JDBC URL resulting in a URL like jdbc:aws-wrapper:postgresql://....
    db-driver
    Set to software.amazon.jdbc.Driver to use the AWS JDBC wrapper.
Note

When overriding the wrapperPlugins option of the AWS JDBC Driver, always include the failover or failover2 plugin to ensure that Red Hat build of Keycloak always connects to the writer instance even in failover or switchover scenarios.

9.8. Preparing for MySQL server
Copy link

Beginning with MySQL 8.0.30, MySQL supports generated invisible primary keys for any InnoDB table that is created without an explicit primary key (more information here). If this feature is enabled, the database schema initialization and also migrations will fail with the error message Multiple primary key defined (1068). You then need to disable it by setting the parameter sql_generate_invisible_primary_key to OFF in your MySQL server configuration before installing or upgrading Red Hat build of Keycloak.

Because cluster nodes can boot concurrently, they take extra time for database actions. For example, a booting server instance may perform some database migration, importing, or first time initializations. A database lock prevents start actions from conflicting with each other when cluster nodes boot up concurrently.

The maximum timeout for this lock is 900 seconds. If a node waits on this lock for more than the timeout, the boot fails. The need to change the default value is unlikely, but you can change it by entering this command: 

bin/kc.[sh|bat] start --spi-dblock--jpa--lock-wait-timeout 900
Copy to Clipboard Toggle word wrap

Red Hat build of Keycloak uses non-XA transactions and the appropriate database drivers by default.

If you wish to use the XA transaction support offered by your driver, enter the following command: 

bin/kc.[sh|bat] build --db=<vendor> --transaction-xa-enabled=true
Copy to Clipboard Toggle word wrap

Red Hat build of Keycloak automatically chooses the appropriate JDBC driver for your vendor.

Note

Certain vendors, such as Azure SQL and MariaDB Galera, do not support or rely on the XA transaction mechanism.

XA recovery defaults to enabled and will use the file system location KEYCLOAK_HOME/data/transaction-logs to store transaction logs.

Note

Enabling XA transactions in a containerized environment does not fully support XA recovery unless stable storage is available at that path.

To setup the JPA migrationStrategy (manual/update/validate) you should setup JPA provider as follows:

Setting the migration-strategy for the quarkus provider of the connections-jpa SPI

bin/kc.[sh|bat] start --spi-connections--jpa--quarkus-migration-strategy=manual
Copy to Clipboard Toggle word wrap

If you want to get a SQL file for DB initialization, too, you have to add this additional SPI initializeEmpty (true/false):

Setting the initialize-empty for the quarkus provider of the connections-jpa SPI

bin/kc.[sh|bat] start --spi-connections--jpa--quarkus-initialize-empty=false
Copy to Clipboard Toggle word wrap

In the same way the migrationExport to point to a specific file and location:

Setting the migration-export for the quarkus provider of the connections-jpa SPI

bin/kc.[sh|bat] start --spi-connections--jpa--quarkus-migration-export=<path>/<file.sql>
Copy to Clipboard Toggle word wrap

For more information, check the Migrating the database documentation.

9.12. Configuring the connection pool
Copy link

9.12.1. MySQL and MariaDB
Copy link

In order to prevent 'No operations allowed after connection closed' exceptions from being thrown, it is necessary to ensure that Red Hat build of Keycloak’s connection pool has a connection maximum lifetime that is less than the server’s configured wait_timeout. When using the MySQL and MariaDB database, Red Hat build of Keycloak configures a default max lifetime of 7 hours and 50 minutes, as this is less than the default server value of 8 hours.

If you are explicitly configuring the wait_timeout in your database, it is necessary to ensure that you configure a db-pool-max-lifetime value that is less than the wait_timeout. The recommended best practice, is to define this value to be your wait_timeout minus a few minutes. Failure to correctly configure the db-pool-max-lifetime will result in Red Hat build of Keycloak logging a warning on startup.

9.13. Configure multiple datasources
Copy link

Red Hat build of Keycloak allows you to specify additional datasources in case you need to access another database from your extensions. This is useful when using the main Red Hat build of Keycloak datasource is not a viable option for storing custom data, like users.

You can find more details on how to connect to your own users database in the {developerguide_userstoragespi_name} documentation.

Defining multiple datasources works like defining a single datasource, with one important change - you have to specify a name for each datasource as part of the config option name.

9.13.1. Required configuration
Copy link

In order to enable an additional datasource, you need to set up 2 things - the JPA persistence.xml file and Red Hat build of Keycloak configuration. The persistence.xml file serves to specify persistence units as part of the Jakarta Persistence API standard, and is required for proper configuration propagation to the Hibernate ORM framework. When you complete the part with the persistence.xml file, you need to set up Red Hat build of Keycloak configuration accordingly.

The additional datasource properties might be specified via the standard config sources like CLI, keycloak.conf, or environment variables.

The additional datasources can be configured in a similar way as the main datasource. This is achieved by using analogous names for config options, which additionally include the name of the additional datasource. For example, when the main datasource uses the db-username, the additional one would be db-username-<datasource>. See the Relevant options chapter for the complete list of them.

9.13.1.1. 1. JPA persistence.xml file
Copy link

The persistence.xml provides configuration for Jakarta Persistence API (JPA) such as what entities it should manage, the datasource name, JDBC settings, JPA/Hibernate custom settings, and more. The file needs to be placed in the META-INF/persistence.xml folder of your custom Red Hat build of Keycloak extension.

Note

Be aware that Quarkus provides the ability to set up the JPA persistence unit via Hibernate ORM properties instead of using the persistence.xml file. However, the supported way for Red Hat build of Keycloak is using the persistence.xml file, and if the file is present, the Quarkus properties are ignored.

In Red Hat build of Keycloak, most of the configuration is automatic, and you just need to provide fundamental configuration details - the datasource name and transaction type.

Red Hat build of Keycloak requires setting the transaction type for the additional datasource to JTA. You can set the transaction type and datasource name as follows for this minimal persistence.xml file: 

<persistence xmlns="https://jakarta.ee/xml/ns/persistence"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd"
                         version="3.0">
    <persistence-unit name="user-store-pu" transaction-type="JTA">
        <class>org.your.extension.UserEntity</class>
        <properties>
            <property name="jakarta.persistence.jtaDataSource" value="user-store" />
        </properties>
    </persistence-unit>
</persistence>
Copy to Clipboard Toggle word wrap
Note

To properly set the datasource name, you should set the jakarta.persistence.jtaDataSource property. If it is not set, the persistence unit name will be used as the datasource name instead (so user-store-pu in this case). In the example above, the resulting datasource name is user-store. The datasource name can be the same as the persistence unit name.

In order to use your own JPA entities, you need to provide the <class> properties that mark JPA entities that will be managed by this persistence unit, directed to a specific datasource. In the example above, the org.your.extension.UserEntity JPA entity will be managed by the persistence unit user-store-pu, directed to the user-store datasource.

9.13.1.2. 2. Required properties
Copy link

Once you have set up your persistence.xml, the minimal configuration on the Red Hat build of Keycloak side is the setup of the DB kind/vendor for the specified datasource. You need to specify the build time option db-kind-<name>, where the <name> is the name of your datasource and must be the same as specified in the persistence.xml file.

Therefore, you can enable the additional datasource user-store as follows (postgres as an example): 

bin/kc.[sh|bat] start --db-kind-user-store=postgres
Copy to Clipboard Toggle word wrap

After specifying the db-kind for the datasource, all database-kind–specific defaults (such as the driver and dialect) are automatically applied, just like for the main datasource.

9.13.2. Configuration via environment variables
Copy link

If you do not want to configure the datasource via CLI or keycloak.conf properties, you can use the environment variables.

You can set the DB kind via environment variables (for the user-store datasource) as follows: 

export KC_DB_KIND_USER_STORE=postgres
export KC_DB_USERNAME_USER_STORE=my-username
Copy to Clipboard Toggle word wrap

It maps to the db-kind-user-store and db-username-user-store Red Hat build of Keycloak properties due to the default mapping of the _ (underscore) to the - (dash) for environment variables. However, sometimes, the name of the datasource might contain some special characters like _, $ or .

In order to have it properly configured via the Red Hat build of Keycloak environment variables, you need to explicitly say what the key for the datasource should look like. You can use a pair of unique Red Hat build of Keycloak environment variables with a special case of the KCKEY_.

For instance, for a datasource with the name user_store$marketing, you can set environment variables as follows: 

export KC_USER_STORE_DB_KIND=mariadb
export KCKEY_USER_STORE_DB_KIND=db-kind-user_store$marketing
Copy to Clipboard Toggle word wrap

You can find more information in the guide Configuring Red Hat build of Keycloak, in subsection Formats for environment variable keys with special characters.

In the past, we instructed users to use raw Quarkus properties to configure additional datasources in some places. However, as using Quarkus properties in the conf/quarkus.properties file is considered unsupported, it is strongly recommended to use the dedicated additional datasources options as described above.

Before you are able to migrate to the dedicated options, you can still specify the datasource settings via the Quarkus properties as follows: 

quarkus.datasource.user-store.db-kind=h2
quarkus.datasource.user-store.username=sa
quarkus.datasource.user-store.jdbc.url=jdbc:h2:mem:user-store;DB_CLOSE_DELAY=-1
quarkus.datasource.user-store.jdbc.transactions=xa
Copy to Clipboard Toggle word wrap
Warning

Use Quarkus properties without quotation for the datasource name, as properties with the quoted datasource name clash with the new datasource options mapping. Therefore, use quarkus.datasource.user-store.db-kind=h2, instead of quarkus.datasource."user-store".db-kind=h2 to prevent any issues.

9.14. Relevant options
Copy link

Expand
 Value

db 🛠

The database vendor.

In production mode the default value of dev-file is deprecated, you should explicitly specify the db instead.

Named key: db-kind-<datasource> 🛠

CLI: --db
Env: KC_DB

dev-file (default), dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb

db-debug-jpql

Add JPQL information as comments to SQL statements to debug JPA SQL statement generation.

Named key: db-debug-jpql-<datasource>

CLI: --db-debug-jpql
Env: KC_DB_DEBUG_JPQL

true, false (default)

db-driver 🛠

The fully qualified class name of the JDBC driver.

If not set, a default driver is set accordingly to the chosen database.

Named key: db-driver-<datasource> 🛠

CLI: --db-driver
Env: KC_DB_DRIVER

 

db-log-slow-queries-threshold

Log SQL statements slower than the configured threshold with logger org.

hibernate.SQL_SLOW and log-level info.

Named key: db-log-slow-queries-threshold-<datasource>

CLI: --db-log-slow-queries-threshold
Env: KC_DB_LOG_SLOW_QUERIES_THRESHOLD

10000 (default)

db-password

The password of the database user.

Named key: db-password-<datasource>

CLI: --db-password
Env: KC_DB_PASSWORD

 

db-pool-initial-size

The initial size of the connection pool.

Named key: db-pool-initial-size-<datasource>

CLI: --db-pool-initial-size
Env: KC_DB_POOL_INITIAL_SIZE

 

db-pool-max-lifetime

The maximum time a connection remains in the pool, after which it will be closed upon return and replaced as necessary.

May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d].

CLI: --db-pool-max-lifetime
Env: KC_DB_POOL_MAX_LIFETIME

 

db-pool-max-size

The maximum size of the connection pool.

Named key: db-pool-max-size-<datasource>

CLI: --db-pool-max-size
Env: KC_DB_POOL_MAX_SIZE

100 (default)

db-pool-min-size

The minimal size of the connection pool.

Named key: db-pool-min-size-<datasource>

CLI: --db-pool-min-size
Env: KC_DB_POOL_MIN_SIZE

 

db-schema

The database schema to be used.

Named key: db-schema-<datasource>

CLI: --db-schema
Env: KC_DB_SCHEMA

 

db-url

The full database JDBC URL.

If not provided, a default URL is set based on the selected database vendor. For instance, if using postgres, the default JDBC URL would be jdbc:postgresql://localhost/keycloak.

Named key: db-url-full-<datasource>

CLI: --db-url
Env: KC_DB_URL

 

db-url-database

Sets the database name of the default JDBC URL of the chosen vendor.

If the db-url option is set, this option is ignored.

Named key: db-url-database-<datasource>

CLI: --db-url-database
Env: KC_DB_URL_DATABASE

 

db-url-host

Sets the hostname of the default JDBC URL of the chosen vendor.

If the db-url option is set, this option is ignored.

Named key: db-url-host-<datasource>

CLI: --db-url-host
Env: KC_DB_URL_HOST

 

db-url-port

Sets the port of the default JDBC URL of the chosen vendor.

If the db-url option is set, this option is ignored.

Named key: db-url-port-<datasource>

CLI: --db-url-port
Env: KC_DB_URL_PORT

 

db-url-properties

Sets the properties of the default JDBC URL of the chosen vendor.

Make sure to set the properties accordingly to the format expected by the database vendor, as well as appending the right character at the beginning of this property value. If the db-url option is set, this option is ignored.

Named key: db-url-properties-<datasource>

CLI: --db-url-properties
Env: KC_DB_URL_PROPERTIES

 

db-username

The username of the database user.

Named key: db-username-<datasource>

CLI: --db-username
Env: KC_DB_USERNAME

 

transaction-xa-enabled 🛠

If set to true, XA datasources will be used.

Named key: transaction-xa-enabled-<datasource> 🛠

CLI: --transaction-xa-enabled
Env: KC_TRANSACTION_XA_ENABLED

true, false (default)

9.14.1. Additional datasources options
Copy link

Expand
 Value

db-debug-jpql-<datasource>

Used for named <datasource>.

Add JPQL information as comments to SQL statements to debug JPA SQL statement generation.

CLI: --db-debug-jpql-<datasource>
Env: KC_DB_DEBUG_JPQL_<DATASOURCE>

true, false (default)

db-driver-<datasource> 🛠

Used for named <datasource>.

The fully qualified class name of the JDBC driver. If not set, a default driver is set accordingly to the chosen database.

CLI: --db-driver-<datasource>
Env: KC_DB_DRIVER_<DATASOURCE>

 

db-enabled-<datasource>

If the named datasource <datasource> should be enabled at runtime.

CLI: --db-enabled-<datasource>
Env: KC_DB_ENABLED_<DATASOURCE>

true (default), false

db-kind-<datasource> 🛠

Used for named <datasource>.

The database vendor. In production mode the default value of dev-file is deprecated, you should explicitly specify the db instead.

CLI: --db-kind-<datasource>
Env: KC_DB_KIND_<DATASOURCE>

dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb

db-log-slow-queries-threshold-<datasource>

Used for named <datasource>.

Log SQL statements slower than the configured threshold with logger org.hibernate.SQL_SLOW and log-level info.

CLI: --db-log-slow-queries-threshold-<datasource>
Env: KC_DB_LOG_SLOW_QUERIES_THRESHOLD_<DATASOURCE>

10000 (default)

db-password-<datasource>

Used for named <datasource>.

The password of the database user.

CLI: --db-password-<datasource>
Env: KC_DB_PASSWORD_<DATASOURCE>

 

db-pool-initial-size-<datasource>

Used for named <datasource>.

The initial size of the connection pool.

CLI: --db-pool-initial-size-<datasource>
Env: KC_DB_POOL_INITIAL_SIZE_<DATASOURCE>

 

db-pool-max-size-<datasource>

Used for named <datasource>.

The maximum size of the connection pool.

CLI: --db-pool-max-size-<datasource>
Env: KC_DB_POOL_MAX_SIZE_<DATASOURCE>

100 (default)

db-pool-min-size-<datasource>

Used for named <datasource>.

The minimal size of the connection pool.

CLI: --db-pool-min-size-<datasource>
Env: KC_DB_POOL_MIN_SIZE_<DATASOURCE>

 

db-schema-<datasource>

Used for named <datasource>.

The database schema to be used.

CLI: --db-schema-<datasource>
Env: KC_DB_SCHEMA_<DATASOURCE>

 

db-url-database-<datasource>

Used for named <datasource>.

Sets the database name of the default JDBC URL of the chosen vendor. If the db-url option is set, this option is ignored.

CLI: --db-url-database-<datasource>
Env: KC_DB_URL_DATABASE_<DATASOURCE>

 

db-url-full-<datasource>

Used for named <datasource>.

The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor. For instance, if using postgres, the default JDBC URL would be jdbc:postgresql://localhost/keycloak.

CLI: --db-url-full-<datasource>
Env: KC_DB_URL_FULL_<DATASOURCE>

 

db-url-host-<datasource>

Used for named <datasource>.

Sets the hostname of the default JDBC URL of the chosen vendor. If the db-url option is set, this option is ignored.

CLI: --db-url-host-<datasource>
Env: KC_DB_URL_HOST_<DATASOURCE>

 

db-url-port-<datasource>

Used for named <datasource>.

Sets the port of the default JDBC URL of the chosen vendor. If the db-url option is set, this option is ignored.

CLI: --db-url-port-<datasource>
Env: KC_DB_URL_PORT_<DATASOURCE>

 

db-url-properties-<datasource>

Used for named <datasource>.

Sets the properties of the default JDBC URL of the chosen vendor. Make sure to set the properties accordingly to the format expected by the database vendor, as well as appending the right character at the beginning of this property value. If the db-url option is set, this option is ignored.

CLI: --db-url-properties-<datasource>
Env: KC_DB_URL_PROPERTIES_<DATASOURCE>

 

db-username-<datasource>

Used for named <datasource>.

The username of the database user.

CLI: --db-username-<datasource>
Env: KC_DB_USERNAME_<DATASOURCE>

 

transaction-xa-enabled-<datasource> 🛠

If set to true, XA for <datasource> datasource will be used.

CLI: --transaction-xa-enabled-<datasource>
Env: KC_TRANSACTION_XA_ENABLED_<DATASOURCE>

true (default), false

Chapter 10. Configuring distributed caches
Copy link

Configure the caching layer to cluster multiple Red Hat build of Keycloak instances and to increase performance.

Red Hat build of Keycloak is designed for high availability and multi-node clustered setups. The current distributed cache implementation is built on top of Infinispan, a high-performance, distributable in-memory data grid.

10.1. Enable distributed caching
Copy link

When you start Red Hat build of Keycloak in production mode, by using the start command, caching is enabled and all Red Hat build of Keycloak nodes in your network are discovered.

By default, caches use the jdbc-ping stack which is based upon a TCP transport and uses the configured database to track nodes joining the cluster. Red Hat build of Keycloak allows you to either choose from a set of pre-defined default transport stacks, or to define your own custom stack, as you will see later in this chapter.

To explicitly enable distributed infinispan caching, enter this command: 

bin/kc.[sh|bat] start --cache=ispn
Copy to Clipboard Toggle word wrap

When you start Red Hat build of Keycloak in development mode, by using the start-dev command, Red Hat build of Keycloak uses only local caches and distributed caches are completely disabled by implicitly setting the --cache=local option. The local cache mode is intended only for development and testing purposes.

10.2. Configuring caches
Copy link

Red Hat build of Keycloak provides a regular {infinispan_configuring_docs}[Infinispan configuration file] located at conf/cache-ispn.xml. This file contains the default configuration used for the cache-container and JGroups transport.

The following table gives an overview of the specific caches Red Hat build of Keycloak uses:

Expand
Cache nameCache TypeDescription

realms

Local

Cache persisted realm data

users

Local

Cache persisted user data

authorization

Local

Cache persisted authorization data

keys

Local

Cache external public keys

crl

Local

Cache for X.509 authenticator CRLs

work

Replicated

Propagate invalidation messages across nodes

authenticationSessions

Distributed

Caches authentication sessions, created/destroyed/expired during the authentication process

sessions

Distributed

Cache persisted user session data

clientSessions

Distributed

Cache persisted client session data

offlineSessions

Distributed

Cache persisted offline user session data

offlineClientSessions

Distributed

Cache persisted offline client session data

loginFailures

Distributed

keep track of failed logins, fraud detection

actionTokens

Distributed

Caches action Tokens

10.2.1. Cache types and defaults
Copy link

Local caches

Red Hat build of Keycloak caches persistent data locally to avoid unnecessary round-trips to the database.

The following data is kept local to each node in the cluster using local caches:

  • realms and related data like clients, roles, and groups.
  • users and related data like granted roles and group memberships.
  • authorization and related data like resources, permissions, and policies.
  • keys

Local caches for realms, users, and authorization are configured to hold up to 10,000 entries per default. The local key cache can hold up to 1,000 entries per default and defaults to expire every one hour. Therefore, keys are forced to be periodically downloaded from external clients or identity providers.

In order to achieve an optimal runtime and avoid additional round-trips to the database you should consider looking at the configuration for each cache to make sure the maximum number of entries is aligned with the size of your database. More entries you can cache, less often the server needs to fetch data from the database. You should evaluate the trade-offs between memory utilization and performance.

Invalidation of local caches

Local caching improves performance, but adds a challenge in multi-node setups.

When one Red Hat build of Keycloak node updates data in the shared database, all other nodes need to be aware of it, so they invalidate that data from their caches.

The work cache is a replicated cache and used for sending these invalidation messages. The entries/messages in this cache are very short-lived, and you should not expect this cache growing in size over time.

Authentication sessions

Authentication sessions are created whenever a user tries to authenticate. They are automatically destroyed once the authentication process completes or due to reaching their expiration time.

The authenticationSessions distributed cache is used to store authentication sessions and any other data associated with it during the authentication process.

By relying on a distributable cache, authentication sessions are available to any node in the cluster so that users can be redirected to any node without losing their authentication state. However, production-ready deployments should always consider session affinity and favor redirecting users to the node where their sessions were initially created. By doing that, you are going to avoid unnecessary state transfer between nodes and improve CPU, memory, and network utilization.

User sessions

Once the user is authenticated, a user session is created. The user session tracks your active users and their state so that they can seamlessly authenticate to any application without being asked for their credentials again. For each application, the user authenticates with a client session, so that the server can track the applications the user is authenticated with and their state on a per-application basis.

User and client sessions are automatically destroyed whenever the user performs a logout, the client performs a token revocation, or due to reaching their expiration time.

The session data are stored in the database by default and loaded on-demand to the following caches:

  • sessions
  • clientSessions

By relying on a distributable cache, cached user and client sessions are available to any node in the cluster so that users can be redirected to any node without the need to load session data from the database. However, production-ready deployments should always consider session affinity and favor redirecting users to the node where their sessions were initially created. By doing that, you are going to avoid unnecessary state transfer between nodes and improve CPU, memory, and network utilization.

These in-memory caches for user sessions and client sessions are limited to, by default, 10000 entries per node which reduces the overall memory usage of Red Hat build of Keycloak for larger installations. The internal caches will run with only a single owner for each cache entry.

Offline user sessions

As an OpenID Connect Provider, the server is capable of authenticating users and issuing offline tokens. When issuing an offline token after successful authentication, the server creates an offline user session and offline client session.

The following caches are used to store offline sessions:

  • offlineSessions
  • offlineClientSessions

Like the user and client sessions caches, the offline user and client session caches are limited to 10000 entries per node by default. Items which are evicted from the memory will be loaded on-demand from the database when needed.

Password brute force detection

The loginFailures distributed cache is used to track data about failed login attempts. This cache is needed for the Brute Force Protection feature to work in a multi-node Red Hat build of Keycloak setup.

Action tokens

Action tokens are used for scenarios when a user needs to confirm an action asynchronously, for example in the emails sent by the forgot password flow. The actionTokens distributed cache is used to track metadata about action tokens.

Tip

You can see the applied Infinispan configuration in the logs by configuring --log-level=info,org.keycloak.connections.infinispan.DefaultInfinispanConnectionProviderFactory:debug.

10.2.2. Volatile user sessions
Copy link

By default, regular user sessions are stored in the database and loaded on-demand to the cache. It is possible to configure Red Hat build of Keycloak to store regular user sessions in the cache only and minimize calls to the database.

Since all the sessions in this setup are stored in-memory, there are two side effects related to this:

  • Losing sessions when all Red Hat build of Keycloak nodes restart.
  • Increased memory consumption.

When using volatile user sessions, the cache is the source of truth for user and client sessions. Red Hat build of Keycloak automatically adjusts the number of entries that can be stored in memory, and increases the number of copies to prevent data loss.

Follow these steps to enable this setup:

  1. Disable persistent-user-sessions feature using the following command: 

    bin/kc.sh start --features-disabled=persistent-user-sessions ...
    Copy to Clipboard Toggle word wrap
Note

Disabling persistent-user-sessions is not possible when multi-site feature is enabled.

10.2.3. Configuring cache maximum size
Copy link

In order to reduce memory usage, it’s possible to place an upper bound on the number of entries which are stored in a given cache. To specify an upper bound of on a cache, you must provide the following command line argument --cache-embedded-${CACHE_NAME}-max-count=, with ${CACHE_NAME} replaced with the name of the cache you would like to apply the upper bound to. For example, to apply an upper-bound of 1000 to the offlineSessions cache you would configure --cache-embedded-offline-sessions-max-count=1000. An upper bound can not be defined on the following caches: actionToken, authenticationSessions, loginFailures, work.

Setting a maximum cache size for sessions, clientSessions, offlineSessions and offlineClientSessions is not supported when volatile sessions are enabled.

10.2.4. Specify your own cache configuration file
Copy link

To specify your own cache configuration file, enter this command: 

bin/kc.[sh|bat] start --cache-config-file=my-cache-file.xml
Copy to Clipboard Toggle word wrap

The configuration file is relative to the conf/ directory.

10.2.5. Modifying cache configuration defaults
Copy link

Red Hat build of Keycloak automatically creates all required caches with the expected configurations. You can add additional caches or override the default cache configurations in conf/cache-ispn.xml or in your own file provided via --cache-config-file.

To see the applied Infinispan configuration in the logs, configure --log-level=info,org.keycloak.connections.infinispan.DefaultInfinispanConnectionProviderFactory:debug.

Warning

While overriding the default cache configurations via XML is technically possible, it is not supported. This is only recommended for advanced use-cases where the default cache configurations are proven to be problematic. The only supported way to change the default cache configurations is via the cache-... options.

In order to prevent a warning being logged when a modified default cache configuration is detected, add the following option: 

bin/kc.[sh|bat] start --cache-config-mutate=true
Copy to Clipboard Toggle word wrap

10.2.6. CLI options for remote server
Copy link

For configuration of Red Hat build of Keycloak server for high availability and multi-node clustered setup there was introduced following CLI options cache-remote-host, cache-remote-port, cache-remote-username and cache-remote-password simplifying configuration within the XML file. Once any of the declared CLI parameters are present, it is expected there is no configuration related to remote store present in the XML file.

Warning

Disabling security is not recommended in production!

In a development or test environment, it is easier to start an unsecured Infinispan server. For these use case, the CLI options cache-remote-tls-enabled disables the encryption (TLS) between Red Hat build of Keycloak and Data Grid. Red Hat build of Keycloak will fail to start if the Data Grid server is configured to accept only encrypted connections.

The CLI options cache-remote-username and cache-remote-password are optional and, if not set, Red Hat build of Keycloak will connect to the Data Grid server without presenting any credentials. If the Data Grid server has authentication enabled, Red Hat build of Keycloak will fail to start.

10.3. Topology aware data distribution
Copy link

Configuring Red Hat build of Keycloak to be aware of your network topology, increases data availability in the presence of hardware failures, as Infinispan is able to ensure that data is distributed correctly. For example, if num_owners=2 is configured for a cache, it will ensure that the two owners are not stored on the same node when possible.

Note

By default, user and client sessions are safely stored in the database, and they are not affected by these settings. The remaining distributed caches are affected by this configuration.

The following topology information is available to configure:

Site name

If your Red Hat build of Keycloak cluster is deployed between different datacenters, use this option to ensure the data replicas are stored in a different datacenter. It prevents data loss if a datacenter goes offline or fails.

Use the SPI option spi-cache-embedded—​default—​site-name (or environment variable KC_SPI_CACHE_EMBEDDED__DEFAULT__SITE_NAME). The value itself is not important, but each datacenter must have a unique value.

For example: --spi-cache-embedded—​default—​site-name=site-1

Rack name

If your Red Hat build of Keycloak cluster is running in different racks on your datacenter, set this option to ensure the data replicas are stored in a different physical rack. It prevents data loss if a rack is suddenly disconnected or fails.

Use the SPI option spi-cache-embedded—​default—​rack-name (or environment variable KC_SPI_CACHE_EMBEDDED__DEFAULT__RACK_NAME). The value itself is not important, but each rack must have a unique value.

For example: --spi-cache-embedded—​default—​rack-name=rack-1

Machine name

If you have multiple Red Hat build of Keycloak instances running on the same physical machine (using virtual machines or containers for example), use this option to ensure the data replicas are stored in different physical machines. It prevents data loss against a physical machine failure.

Use the SPI option spi-cache-embedded—​default—​machine-name (or environment variable KC_SPI_CACHE_EMBEDDED__DEFAULT__MACHINE_NAME). The value itself is not important, but each machine must have a unique value.

For example: --spi-cache-embedded—​default—​machine-name=machine-1

Note

The Red Hat build of Keycloak Operator automatically configure the machine name based on the Kubernetes node. It ensures that if multiple pods are scheduled on the same node, data replicas are still replicated across distinct nodes when possible. We recommend to set up anti-affinity rules and/or topology spread constraints to prevent multiple Pods from being scheduled on the same node, further reducing the risk of a single node failure causing data loss.

10.4. Transport stacks
Copy link

Transport stacks ensure that Red Hat build of Keycloak nodes in a cluster communicate in a reliable fashion. Red Hat build of Keycloak supports a wide range of transport stacks:

  • jdbc-ping
  • kubernetes (deprecated)
  • jdbc-ping-udp (deprecated)
  • tcp (deprecated)
  • udp (deprecated)
  • ec2 (deprecated)
  • azure (deprecated)
  • google (deprecated)

To apply a specific cache stack, enter this command: 

bin/kc.[sh|bat] start --cache-stack=<stack>
Copy to Clipboard Toggle word wrap

The default stack is set to jdbc-ping when distributed caches are enabled, which is backwards compatible with the defaults in the 26.x release stream of Red Hat build of Keycloak.

10.4.1. Available transport stacks
Copy link

The following table shows transport stacks that are available without any further configuration than using the --cache-stack runtime option:

Expand
Stack nameTransport protocolDiscovery

jdbc-ping

TCP

Database registry using the JGroups JDBC_PING2 protocol.

jdbc-ping-udp (deprecated)

UDP

Database registry using the JGroups JDBC_PING2 protocol.

The following table shows transport stacks that are available using the --cache-stack runtime option and a minimum configuration:

Expand
Stack nameTransport protocolDiscovery

kubernetes (deprecated)

TCP

DNS resolution using the JGroups DNS_PING protocol. It requires to set jgroups.dns.query to the headless service FQDN.

tcp (deprecated)

TCP

IP multicast using the JGroups MPING protocol. See below on how to configure a unique jgroups.mcast_addr or jgroups.mcast_port for each cluster.

udp (deprecated)

UDP

IP multicast using the JGroups PING protocol. See below on how to configure a unique jgroups.mcast_addr or jgroups.mcast_port for each cluster.

When using the tcp, udp or jdbc-ping-udp stack, each cluster must use a different multicast address and/or port so that their nodes form distinct clusters. By default, Red Hat build of Keycloak uses 239.6.7.8 as multicast address for jgroups.mcast_addr and 46655 for the multicast port jgroups.mcast_port.

Note

Use -D<property>=<value> to pass the properties via the JAVA_OPTS_APPEND environment variable or in the CLI command.

Additional Stacks

It is recommended to use one of the stacks available above. Additional stacks are provided by Infinispan, but it is outside the scope of this guide how to configure them. Please refer to Setting up Infinispan cluster transport and Customizing JGroups stacks for further documentation.

10.5. Securing transport stacks
Copy link

Encryption using TLS is enabled by default for TCP-based transport stacks, which is also the default configuration. No additional CLI options or modifications of the cache XML are required as long as you are using a TCP-based transport stack.

Note

If you are using a transport stack based on UDP or TCP_NIO2, proceed as follows to configure the encryption of the transport stack:

  1. Set the option cache-embedded-mtls-enabled to false.
  2. Follow the documentation in JGroups Encryption documentation and Encrypting cluster transport.

With TLS enabled, Red Hat build of Keycloak auto-generates a self-signed RSA 2048 bit certificate to secure the connection and uses TLS 1.3 to secure the communication. The keys and the certificate are stored in the database so they are available to all nodes. By default, the certificate is valid for 60 days and is rotated at runtime every 30 days. Use the option cache-embedded-mtls-rotation-interval-days to change this.

10.5.1. Running inside a service mesh
Copy link

When using a service mesh like Istio, you might need to allow a direct mTLS communication between the Red Hat build of Keycloak Pods to allow for the mutual authentication to work. Otherwise, you might see error messages like JGRP000006: failed accepting connection from peer SSLSocket that indicate that a wrong certificate was presented, and the cluster will not form correctly.

You then have the option to allow direct mTLS communication between the Red Hat build of Keycloak Pods, or rely on the service mesh transport security to encrypt the communication and to authenticate peers.

To allow direct mTLS communication for Red Hat build of Keycloak when using Istio:

  • Apply the following configuration to allow direct communication. 

    apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: infinispan-allow-nomtls
spec:
  selector:
    matchLabels:
      app: keycloak
    1 
    
  portLevelMtls:
    "7800":
    2 
    
      mode: PERMISSIVE
    Copy to Clipboard Toggle word wrap
    1
    Update the labels to match your Red Hat build of Keycloak deployment.
    2
    Port 7800 is the default. Adjust it if you change the data transmission port.

As an alternative, to disable the mTLS communication, and rely on the service mesh to encrypt the traffic:

  • Set the option cache-embedded-mtls-enabled to false.
  • Configure your service mesh to authorize only traffic from other Red Hat build of Keycloak Pods for the data transmission port (default: 7800).

10.5.2. Providing your own keys and certificates
Copy link

Although not recommended for standard setups, if it is essential in a specific setup, you can configure the keystore with the certificate for the transport stack manually. cache-embedded-mtls-key-store-file sets the path to the keystore, and cache-embedded-mtls-key-store-password sets the password to decrypt it. The truststore contains the valid certificates to accept connection from, and it can be configured with cache-embedded-mtls-trust-store-file (path to the truststore), and cache-embedded-mtls-trust-store-password (password to decrypt it). To restrict unauthorized access, always use a self-signed certificate for each Red Hat build of Keycloak deployment.

10.6. Network Ports
Copy link

To ensure a healthy Red Hat build of Keycloak clustering, some network ports need to be open. The table below shows the TCP ports that need to be open for the jdbc-ping stack, and a description of the traffic that goes through it.

Expand
PortOptionPropertyDescription

7800

cache-embedded-network-bind-port

jgroups.bind.port

Unicast data transmission.

57800

 

jgroups.fd.port-offset

Failure detection by protocol FD_SOCK2. It listens to the abrupt closing of a socket to suspect a Red Hat build of Keycloak server failure. The jgroups.fd.port-offset property defines the offset from the cache-embedded-network-bind-port option or jgroups.bind.port property. By default, the offset is set to 50000, making the failure detection port 57800.

Note

If an option is not available for the port you require, configure it using a system property -D<property>=<value> in your JAVA_OPTS_APPEND environment variable or in your CLI command.

10.7. Network bind address
Copy link

To ensure a healthy Red Hat build of Keycloak clustering, the network port must be bound on an interface that is accessible from all other nodes of the cluster.

By default, it picks a site local (non-routable) IP address, for example, from the 192.168.0.0/16 or 10.0.0.0/8 address range.

To override the address, set the option cache-embedded-network-bind-address=<IP>.

The following special values are also recognized:

Expand
ValueDescription

GLOBAL

Picks a global IP address if available. If not available, it falls back to SITE_LOCAL.

SITE_LOCAL

Picks a site-local (non-routable) IP address (for example, from the 192.168.0.0 or 10.0.0.0 address ranges). This is the default value.

LINK_LOCAL

Picks a link-local IP address from 169.254.1.0 through 169.254.254.255.

NON_LOOPBACK

Picks any non-loopback address.

LOOPBACK

Picks a loopback address (for example, 127.0.0.1).

match-interface:<regex>

Picks an address that matches a pattern against the interface name. For example, match-interface:tun0 or match-interface:eth.\*.

match-address:<regex>

Picks an address that matches a pattern against the host address. For example, match-address:192.168.\*.

match-host:<regex>

Picks an address that matches a pattern against the host name. For example, match-host:linux.\*.

To set up for IPv6 only and have Red Hat build of Keycloak pick the bind address automatically, use the following settings: 

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true"
Copy to Clipboard Toggle word wrap

For more details about JGroups transport, check the JGroups documentation page or the Infinispan documentation page.

10.8. Running instances on different networks
Copy link

If you run Red Hat build of Keycloak instances on different networks, for example behind firewalls or in containers, the different instances will not be able to reach each other by their local IP address. In such a case, set up a port forwarding rule (sometimes called “virtual server”) to their local IP address.

When using port forwarding, use the following options so each node correctly advertises its external address to the other nodes:

Expand
OptionDescription

cache-embedded-network-external-port

Port that other instances in the Red Hat build of Keycloak cluster should use to contact this node.

cache-embedded-network-external-address

IP address that other instances in the Red Hat build of Keycloak should use to contact this node.

10.9. Verify cluster and network health
Copy link

This section provides methods to verify that your Red Hat build of Keycloak cluster has formed correctly and that network communication between instances is functioning as expected. It is crucial to perform these checks after deployment to ensure high availability and data consistency.

To verify if the cluster is formed properly, check one of these locations:

  • Admin UI

    Access the Red Hat build of Keycloak Web UI, typically available at https://<your-host>/admin/master/console/#/master/providers. Under the Provider Info section, locate the connectionsInfinispan entry. Click on Show more to expand its details. You should find information about the cluster status and the health of individual caches.

    Infinispan Cluster Information in Web UI

  • Logs

    Infinispan logs a cluster view every time a new instance joins or leaves the cluster. Search for log entries with the ID ISPN000094.

    A healthy cluster view will show all expected nodes. For example: 

    ISPN000094: Received new cluster view for channel ISPN: [node1-26186|1] (2) [node1-26186, node2-37007]
    Copy to Clipboard Toggle word wrap

    This log entry indicates that the cluster named "ISPN" currently has 2 nodes: node1-26186 and node2-37007. The (2) confirms the total number of nodes in the cluster.

  • Metrics

    Red Hat build of Keycloak exposes Infinispan metrics via a Prometheus endpoint, which can be visualized in tools like Grafana. The metric vendor_cluster_size shows the current number of instances in the cluster. You should verify that this metric matches the expected number of running instances configured in your cluster.

    Refer to Clustering metrics for more information.

10.10. Exposing metrics from caches
Copy link

Metrics from caches are automatically exposed when the metrics are enabled.

To enable histograms for the cache metrics, set cache-metrics-histograms-enabled to true. While these metrics provide more insights into the latency distribution, collecting them might have a performance impact, so you should be cautious to activate them in an already saturated system. 

bin/kc.[sh|bat] start --metrics-enabled=true --cache-metrics-histograms-enabled=true
Copy to Clipboard Toggle word wrap

For more details about how to enable metrics, see Gaining insights with metrics.

10.11. Relevant options
Copy link

Expand
 Value

cache

Defines the cache mechanism for high-availability.

By default in production mode, a ispn cache is used to create a cluster between multiple server nodes. By default in development mode, a local cache disables clustering and is intended for development and testing purposes.

CLI: --cache
Env: KC_CACHE

ispn (default), local

cache-config-file

Defines the file from which cache configuration should be loaded from.

The configuration file is relative to the conf/ directory.

CLI: --cache-config-file
Env: KC_CACHE_CONFIG_FILE

 

cache-config-mutate

Determines whether changes to the default cache configurations are allowed.

This is only recommended for advanced use-cases where the default cache configurations are proven to be problematic. The only supported way to change the default cache configurations is via the other cache-…​ options.

CLI: --cache-config-mutate
Env: KC_CACHE_CONFIG_MUTATE

true, false (default)

cache-metrics-histograms-enabled

Enable histograms for metrics for the embedded caches.

CLI: --cache-metrics-histograms-enabled
Env: KC_CACHE_METRICS_HISTOGRAMS_ENABLED

Available only when metrics are enabled

true, false (default)

cache-stack

Define the default stack to use for cluster communication and node discovery.

Defaults to jdbc-ping if not set.

CLI: --cache-stack
Env: KC_CACHE_STACK

Available only when 'cache' type is set to 'ispn'

Use 'jdbc-ping' instead by leaving it unset Deprecated values: azure, ec2, google, jdbc-ping-udp, kubernetes, tcp, udp

jdbc-ping, kubernetes (deprecated), jdbc-ping-udp (deprecated), tcp (deprecated), udp (deprecated), ec2 (deprecated), azure (deprecated), google (deprecated), or any

10.11.1. Embedded Cache
Copy link

Expand
 Value

cache-embedded-authorization-max-count

The maximum number of entries that can be stored in-memory by the authorization cache.

CLI: --cache-embedded-authorization-max-count
Env: KC_CACHE_EMBEDDED_AUTHORIZATION_MAX_COUNT

 

cache-embedded-client-sessions-max-count

The maximum number of entries that can be stored in-memory by the clientSessions cache.

CLI: --cache-embedded-client-sessions-max-count
Env: KC_CACHE_EMBEDDED_CLIENT_SESSIONS_MAX_COUNT

Available only when embedded Infinispan clusters configured

 

cache-embedded-crl-max-count

The maximum number of entries that can be stored in-memory by the crl cache.

CLI: --cache-embedded-crl-max-count
Env: KC_CACHE_EMBEDDED_CRL_MAX_COUNT

 

cache-embedded-keys-max-count

The maximum number of entries that can be stored in-memory by the keys cache.

CLI: --cache-embedded-keys-max-count
Env: KC_CACHE_EMBEDDED_KEYS_MAX_COUNT

 

cache-embedded-mtls-enabled

Encrypts the network communication between Keycloak servers.

If no additional parameters about a keystore and truststore are provided, ephemeral key pairs and certificates are created and rotated automatically, which is recommended for standard setups.

CLI: --cache-embedded-mtls-enabled
Env: KC_CACHE_EMBEDDED_MTLS_ENABLED

Available only when a TCP based cache-stack is used

true (default), false

cache-embedded-mtls-key-store-file

The Keystore file path.

The Keystore must contain the certificate to use by the TLS protocol. By default, it looks up cache-mtls-keystore.p12 under conf/ directory.

CLI: --cache-embedded-mtls-key-store-file
Env: KC_CACHE_EMBEDDED_MTLS_KEY_STORE_FILE

Available only when property 'cache-embedded-mtls-enabled' is enabled

 

cache-embedded-mtls-key-store-password

The password to access the Keystore.

CLI: --cache-embedded-mtls-key-store-password
Env: KC_CACHE_EMBEDDED_MTLS_KEY_STORE_PASSWORD

Available only when property 'cache-embedded-mtls-enabled' is enabled

 

cache-embedded-mtls-rotation-interval-days

Rotation period in days of automatic JGroups MTLS certificates.

CLI: --cache-embedded-mtls-rotation-interval-days
Env: KC_CACHE_EMBEDDED_MTLS_ROTATION_INTERVAL_DAYS

Available only when property 'cache-embedded-mtls-enabled' is enabled

30 (default)

cache-embedded-mtls-trust-store-file

The Truststore file path.

It should contain the trusted certificates or the Certificate Authority that signed the certificates. By default, it lookup cache-mtls-truststore.p12 under conf/ directory.

CLI: --cache-embedded-mtls-trust-store-file
Env: KC_CACHE_EMBEDDED_MTLS_TRUST_STORE_FILE

Available only when property 'cache-embedded-mtls-enabled' is enabled

 

cache-embedded-mtls-trust-store-password

The password to access the Truststore.

CLI: --cache-embedded-mtls-trust-store-password
Env: KC_CACHE_EMBEDDED_MTLS_TRUST_STORE_PASSWORD

Available only when property 'cache-embedded-mtls-enabled' is enabled

 

cache-embedded-network-bind-address

IP address used by clustering transport.

By default, SITE_LOCAL is used.

CLI: --cache-embedded-network-bind-address
Env: KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS

Available only when Infinispan clustered embedded is enabled

 

cache-embedded-network-bind-port

The Port the clustering transport will bind to.

By default, port 7800 is used.

CLI: --cache-embedded-network-bind-port
Env: KC_CACHE_EMBEDDED_NETWORK_BIND_PORT

Available only when Infinispan clustered embedded is enabled

 

cache-embedded-network-external-address

IP address that other instances in the cluster should use to contact this node.

Set only if it is different to cache-embedded-network-bind-address, for example when this instance is behind a firewall.

CLI: --cache-embedded-network-external-address
Env: KC_CACHE_EMBEDDED_NETWORK_EXTERNAL_ADDRESS

Available only when Infinispan clustered embedded is enabled

 

cache-embedded-network-external-port

Port that other instances in the cluster should use to contact this node.

Set only if it is different to cache-embedded-network-bind-port, for example when this instance is behind a firewall

CLI: --cache-embedded-network-external-port
Env: KC_CACHE_EMBEDDED_NETWORK_EXTERNAL_PORT

Available only when Infinispan clustered embedded is enabled

 

cache-embedded-offline-client-sessions-max-count

The maximum number of entries that can be stored in-memory by the offlineClientSessions cache.

CLI: --cache-embedded-offline-client-sessions-max-count
Env: KC_CACHE_EMBEDDED_OFFLINE_CLIENT_SESSIONS_MAX_COUNT

Available only when embedded Infinispan clusters configured

 

cache-embedded-offline-sessions-max-count

The maximum number of entries that can be stored in-memory by the offlineSessions cache.

CLI: --cache-embedded-offline-sessions-max-count
Env: KC_CACHE_EMBEDDED_OFFLINE_SESSIONS_MAX_COUNT

Available only when embedded Infinispan clusters configured

 

cache-embedded-realms-max-count

The maximum number of entries that can be stored in-memory by the realms cache.

CLI: --cache-embedded-realms-max-count
Env: KC_CACHE_EMBEDDED_REALMS_MAX_COUNT

 

cache-embedded-sessions-max-count

The maximum number of entries that can be stored in-memory by the sessions cache.

CLI: --cache-embedded-sessions-max-count
Env: KC_CACHE_EMBEDDED_SESSIONS_MAX_COUNT

Available only when embedded Infinispan clusters configured

 

cache-embedded-users-max-count

The maximum number of entries that can be stored in-memory by the users cache.

CLI: --cache-embedded-users-max-count
Env: KC_CACHE_EMBEDDED_USERS_MAX_COUNT

 

10.11.2. Remote Cache
Copy link

Expand
 Value

cache-remote-backup-sites

Configures a list of backup sites names to where the external Infinispan cluster backups the Keycloak data.

CLI: --cache-remote-backup-sites
Env: KC_CACHE_REMOTE_BACKUP_SITES

Available only when remote host is set

 

cache-remote-host

The hostname of the external Infinispan cluster.

Available only when feature multi-site or clusterless is set.

CLI: --cache-remote-host
Env: KC_CACHE_REMOTE_HOST

 

cache-remote-password

The password for the authentication to the external Infinispan cluster.

It is optional if connecting to an unsecure external Infinispan cluster. If the option is specified, cache-remote-username is required as well.

CLI: --cache-remote-password
Env: KC_CACHE_REMOTE_PASSWORD

Available only when remote host is set

 

cache-remote-port

The port of the external Infinispan cluster.

CLI: --cache-remote-port
Env: KC_CACHE_REMOTE_PORT

Available only when remote host is set

11222 (default)

cache-remote-tls-enabled

Enable TLS support to communicate with a secured remote Infinispan server.

Recommended to be enabled in production.

CLI: --cache-remote-tls-enabled
Env: KC_CACHE_REMOTE_TLS_ENABLED

Available only when remote host is set

true (default), false

cache-remote-username

The username for the authentication to the external Infinispan cluster.

It is optional if connecting to an unsecure external Infinispan cluster. If the option is specified, cache-remote-password is required as well.

CLI: --cache-remote-username
Env: KC_CACHE_REMOTE_USERNAME

Available only when remote host is set

 

Chapter 11. Configuring outgoing HTTP requests
Copy link

Configure the client used for outgoing HTTP requests.

Red Hat build of Keycloak often needs to make requests to the applications and services that it secures. Red Hat build of Keycloak manages these outgoing connections using an HTTP client. This chapter shows how to configure the client, connection pool, proxy environment settings, timeouts, and more.

See Configuring trusted certificates for how to configure a Red Hat build of Keycloak Truststore so that Red Hat build of Keycloak is able to perform outgoing requests using TLS.

11.2. Client Configuration Command
Copy link

The HTTP client that Red Hat build of Keycloak uses for outgoing communication is highly configurable. To configure the Red Hat build of Keycloak outgoing HTTP client, enter this command: 

bin/kc.[sh|bat] start --spi-connections-http-client--default--<configurationoption>=<value>
Copy to Clipboard Toggle word wrap

The following are the command options:

establish-connection-timeout-millis
Maximum time in milliseconds until establishing a connection times out. Default: Not set.
socket-timeout-millis
Maximum time of inactivity between two data packets until a socket connection times out, in milliseconds. Default: 5000ms
connection-pool-size
Size of the connection pool for outgoing connections. Default: 128.
max-pooled-per-route
How many connections can be pooled per host. Default: 64.
connection-ttl-millis
Maximum connection time to live in milliseconds. Default: Not set.
max-connection-idle-time-millis
Maximum time an idle connection stays in the connection pool, in milliseconds. Idle connections will be removed from the pool by a background cleaner thread. Set this option to -1 to disable this check. Default: 900000.
disable-cookies
Enable or disable caching of cookies. Default: true.
client-keystore
File path to a Java keystore file. This keystore contains client certificates for mTLS.
client-keystore-password
Password for the client keystore. REQUIRED, when client-keystore is set.
client-key-password
Password for the private key of the client. REQUIRED, when client-keystore is set.
proxy-mappings
Specify proxy configurations for outgoing HTTP requests. For more details, see Section 11.3, “Proxy mappings for outgoing HTTP requests”.
disable-trust-manager
If an outgoing request requires HTTPS and this configuration option is set to true, you do not have to specify a truststore. This setting should be used only during development and never in production because it will disable verification of SSL certificates. Default: false.

11.3. Proxy mappings for outgoing HTTP requests
Copy link

To configure outgoing requests to use a proxy, you can use the following standard proxy environment variables to configure the proxy mappings: HTTP_PROXY, HTTPS_PROXY, and NO_PROXY.

  • The HTTP_PROXY and HTTPS_PROXY variables represent the proxy server that is used for outgoing HTTP requests. Red Hat build of Keycloak does not differentiate between the two variables. If you define both variables, HTTPS_PROXY takes precedence regardless of the actual scheme that the proxy server uses.
  • The NO_PROXY variable defines a comma separated list of hostnames that should not use the proxy. For each hostname that you specify, all its subdomains are also excluded from using proxy.

The environment variables can be lowercase or uppercase. Lowercase takes precedence. For example, if you define both HTTP_PROXY and http_proxy, http_proxy is used.

Example of proxy mappings and environment variables

HTTPS_PROXY=https://www-proxy.acme.com:8080
NO_PROXY=google.com,login.facebook.com
Copy to Clipboard Toggle word wrap

In this example, the following results occur:

  • All outgoing requests use the proxy https://www-proxy.acme.com:8080 except for requests to google.com or any subdomain of google.com, such as auth.google.com.
  • login.facebook.com and all its subdomains do not use the defined proxy, but groups.facebook.com uses the proxy because it is not a subdomain of login.facebook.com.

11.4. Proxy mappings using regular expressions
Copy link

An alternative to using environment variables for proxy mappings is to configure a comma-delimited list of proxy-mappings for outgoing requests sent by Red Hat build of Keycloak. A proxy-mapping consists of a regex-based hostname pattern and a proxy-uri, using the format hostname-pattern;proxy-uri.

For example, consider the following regex: 

.*\.(google|googleapis)\.com
Copy to Clipboard Toggle word wrap

You apply a regex-based hostname pattern by entering this command: 

bin/kc.[sh|bat] start --spi-connections-http-client--default--proxy-mappings='.*\\.(google|googleapis)\\.com;http://www-proxy.acme.com:8080'
Copy to Clipboard Toggle word wrap

The backslash character \ is escaped again because micro-profile config is used to parse the array of mappings.

To determine the proxy for the outgoing HTTP request, the following occurs:

  • The target hostname is matched against all configured hostname patterns.
  • The proxy-uri of the first matching pattern is used.
  • If no configured pattern matches the hostname, no proxy is used.

When your proxy server requires authentication, include the credentials of the proxy user in the format username:password@. For example: 

.*\.(google|googleapis)\.com;http://proxyuser:password@www-proxy.acme.com:8080
Copy to Clipboard Toggle word wrap

Example of regular expressions for proxy-mapping:

# All requests to Google APIs use http://www-proxy.acme.com:8080 as proxy
.*\.(google|googleapis)\.com;http://www-proxy.acme.com:8080

# All requests to internal systems use no proxy
.*\.acme\.com;NO_PROXY

# All other requests use http://fallback:8080 as proxy
.*;http://fallback:8080
Copy to Clipboard Toggle word wrap

In this example, the following occurs:

  • The special value NO_PROXY for the proxy-uri is used, which means that no proxy is used for hosts matching the associated hostname pattern.
  • A catch-all pattern ends the proxy-mappings, providing a default proxy for all outgoing requests.

11.5. Relevant options
Copy link

Expand
 Value

truststore-paths

List of pkcs12 (p12, pfx, or pkcs12 file extensions), PEM files, or directories containing those files that will be used as a system truststore.

CLI: --truststore-paths
Env: KC_TRUSTSTORE_PATHS

 

Chapter 12. Configuring trusted certificates
Copy link

Configure the Red Hat build of Keycloak Truststore to communicate through TLS.

When Red Hat build of Keycloak communicates with external services or has an incoming connection through TLS, it has to validate the remote certificate in order to ensure it is connecting to a trusted server. This is necessary in order to prevent man-in-the-middle attacks.

The certificates of these clients or servers, or the CA that signed these certificates, must be put in a truststore. This truststore is then configured for use by Red Hat build of Keycloak.

12.1. Configuring the System Truststore
Copy link

The existing Java default truststore certs will always be trusted. If you need additional certificates, which will be the case if you have self-signed or internal certificate authorities that are not recognized by the JRE, they can be included in the conf/truststores directory or subdirectories. The certs may be in PEM files, or PKCS12 files with extension .p12, .pfx, or .pkcs12. If in PKCS12, the certs must be unencrypted - meaning no password is expected.

If you need an alternative path, use the --truststore-paths option to specify additional files or directories where PEM or PKCS12 files are located. Paths are relative to where you launched Red Hat build of Keycloak, so absolute paths are recommended instead. If a directory is specified, it will be recursively scanned for truststore files.

After all applicable certs are included, the truststore will be used as the system default truststore via the javax.net.ssl properties, and as the default for internal usage within Red Hat build of Keycloak.

For example: 

bin/kc.[sh|bat] start --truststore-paths=/opt/truststore/myTrustStore.pfx,/opt/other-truststore/myOtherTrustStore.pem
Copy to Clipboard Toggle word wrap

It is still possible to directly set your own javax.net.ssl truststore System properties, but it’s recommended to use the --truststore-paths instead.

12.2. Hostname Verification Policy
Copy link

You may refine how hostnames are verified by TLS connections with the tls-hostname-verifier property.

  • DEFAULT (the default) allows wildcards in subdomain names (e.g. *.foo.com) to match names with the same number of levels (e.g. a.foo.com, but not a.b.foo.com) - with rules and exclusions for public suffixes based upon https://publicsuffix.org/list/
  • ANY means that the hostname is not verified - this mode should not be used in production.
  • WILDCARD (deprecated) allows wildcards in subdomain names (e.g. *.foo.com) to match anything, including multiple levels (e.g. a.b.foo.com). Use DEFAULT instead.

  • STRICT (deprecated) allows wildcards in subdomain names (e.g. *.foo.com) to match names with the same number of levels (e.g. a.foo.com, but not a.b.foo.com) - with some limited exclusions. Use DEFAULT instead.

    Please note that this setting does not apply to LDAP secure connections, which require strict hostname checking.

12.3. Relevant options
Copy link

Expand
 Value

tls-hostname-verifier

The TLS hostname verification policy for out-going HTTPS and SMTP requests.

ANY should not be used in production.

CLI: --tls-hostname-verifier
Env: KC_TLS_HOSTNAME_VERIFIER

STRICT and WILDCARD have been deprecated, use DEFAULT instead. Deprecated values: STRICT, WILDCARD

ANY, WILDCARD (deprecated), STRICT (deprecated), DEFAULT (default)

truststore-paths

List of pkcs12 (p12, pfx, or pkcs12 file extensions), PEM files, or directories containing those files that will be used as a system truststore.

CLI: --truststore-paths
Env: KC_TRUSTSTORE_PATHS

 

Configure Mutual TLS to verify clients that are connecting to Red Hat build of Keycloak.

In order to properly validate client certificates and enable certain authentication methods like two-way TLS or mTLS, you can set a trust store with all the certificates (and certificate chain) the server should be trusting. There are number of capabilities that rely on this trust store to properly authenticate clients using certificates such as Mutual TLS and X.509 Authentication.

13.1. Enabling mTLS
Copy link

Authentication using mTLS is disabled by default. To enable mTLS certificate handling when Red Hat build of Keycloak is the server and needs to validate certificates from requests made to Red Hat build of Keycloak endpoints, put the appropriate certificates in a truststore and use the following command to enable mTLS: 

bin/kc.[sh|bat] start --https-client-auth=<none|request|required>
Copy to Clipboard Toggle word wrap

Using the value required sets up Red Hat build of Keycloak to always ask for certificates and fail if no certificate is provided in a request. By setting the value to request, Red Hat build of Keycloak will also accept requests without a certificate and only validate the correctness of a certificate if it exists.

Warning

The mTLS configuration and the truststore is shared by all Realms. It is not possible to configure different truststores for different Realms.

Note

Management interface properties are inherited from the main HTTP server, including mTLS settings. It means when mTLS is set, it is also enabled for the management interface. To override the behavior, use the https-management-client-auth property.

13.2. Using a dedicated truststore for mTLS
Copy link

By default, Red Hat build of Keycloak uses the System Truststore to validate certificates. See Configuring trusted certificates for details.

If you need to use a dedicated truststore for mTLS, you can configure the location of this truststore by running the following command: 

bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file --https-trust-store-password=<value>
Copy to Clipboard Toggle word wrap

Recognized file extensions for a truststore:

  • .p12, .pkcs12, and .pfx for a pkcs12 file
  • .jks, and .truststore for a jks file
  • .ca, .crt, and .pem for a pem file

If your truststore does not have an extension matching its file type, you will also need to set the https-key-store-type option.

13.3. Additional resources
Copy link

13.3.1. Using mTLS for outgoing HTTP requests
Copy link

Be aware that this is the basic certificate configuration for mTLS use cases where Red Hat build of Keycloak acts as server. When Red Hat build of Keycloak acts as client instead, e.g. when Red Hat build of Keycloak tries to get a token from a token endpoint of a brokered identity provider that is secured by mTLS, you need to set up the HttpClient to provide the right certificates in the keystore for the outgoing request. To configure mTLS in these scenarios, see Configuring outgoing HTTP requests.

13.3.2. Configuring X.509 Authentication
Copy link

For more information on how to configure X.509 Authentication, see X.509 Client Certificate User Authentication section.

13.4. Relevant options
Copy link

Expand
 Value

https-client-auth 🛠

Configures the server to require/request client authentication.

CLI: --https-client-auth
Env: KC_HTTPS_CLIENT_AUTH

none (default), request, required

https-trust-store-file

The trust store which holds the certificate information of the certificates to trust.

CLI: --https-trust-store-file
Env: KC_HTTPS_TRUST_STORE_FILE

 

https-trust-store-password

The password of the trust store file.

CLI: --https-trust-store-password
Env: KC_HTTPS_TRUST_STORE_PASSWORD

 

https-trust-store-type

The type of the trust store file.

If not given, the type is automatically detected based on the file extension. If fips-mode is set to strict and no value is set, it defaults to BCFKS.

CLI: --https-trust-store-type
Env: KC_HTTPS_TRUST_STORE_TYPE

 

https-management-client-auth 🛠

Configures the management interface to require/request client authentication.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-client-auth
Env: KC_HTTPS_MANAGEMENT_CLIENT_AUTH

none (default), request, required

Chapter 14. Enabling and disabling features
Copy link

Configure Red Hat build of Keycloak to use optional features.

Red Hat build of Keycloak has packed some functionality in features, including some disabled features, such as Technology Preview and deprecated features. Other features are enabled by default, but you can disable them if they do not apply to your use of Red Hat build of Keycloak.

14.1. Enabling features
Copy link

Some supported features, and all preview features, are disabled by default. To enable a feature, enter this command: 

bin/kc.[sh|bat] build --features="<name>[,<name>]"
Copy to Clipboard Toggle word wrap

For example, to enable docker and token-exchange, enter this command: 

bin/kc.[sh|bat] build --features="docker,token-exchange"
Copy to Clipboard Toggle word wrap

To enable all preview features, enter this command: 

bin/kc.[sh|bat] build --features="preview"
Copy to Clipboard Toggle word wrap

Enabled feature may be versioned, or unversioned. If you use a versioned feature name, e.g. feature:v1, that exact feature version will be enabled as long as it still exists in the runtime. If you instead use an unversioned name, e.g. just feature, the selection of the particular supported feature version may change from release to release according to the following precedence:

  1. The highest default supported version
  2. The highest non-default supported version
  3. The highest deprecated version
  4. The highest preview version
  5. The highest experimental version

14.2. Disabling features
Copy link

To disable a feature that is enabled by default, enter this command: 

bin/kc.[sh|bat] build --features-disabled="<name>[,<name>]"
Copy to Clipboard Toggle word wrap

For example to disable impersonation, enter this command: 

bin/kc.[sh|bat] build --features-disabled="impersonation"
Copy to Clipboard Toggle word wrap

It is not allowed to have a feature in both the features-disabled list and the features list.

When a feature is disabled all versions of that feature are disabled.

14.3. Supported features
Copy link

The following list contains supported features that are enabled by default, and can be disabled if not needed.

Expand
FeatureDescription

account-api:v1

Account Management REST API

account:v3

Account Console version 3

admin-api:v1

Admin API

admin-fine-grained-authz:v2

Fine-Grained Admin Permissions version 2

admin:v2

New Admin Console

authorization:v1

Authorization Service

ciba:v1

OpenID Connect Client Initiated Backchannel Authentication (CIBA)

client-policies:v1

Client configuration policies

device-flow:v1

OAuth 2.0 Device Authorization Grant

dpop:v1

OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer

hostname:v2

Hostname Options V2

impersonation:v1

Ability for admins to impersonate users

kerberos:v1

Kerberos

login:v2

New Login Theme

opentelemetry:v1

OpenTelemetry Tracing

organization:v1

Organization support within realms

par:v1

OAuth 2.0 Pushed Authorization Requests (PAR)

passkeys:v1

Passkeys

persistent-user-sessions:v1

Persistent online user sessions across restarts and upgrades

recovery-codes:v1

Recovery codes

rolling-updates:v1

Rolling Updates

step-up-authentication:v1

Step-up Authentication

token-exchange-standard:v2

Standard Token Exchange version 2

update-email:v1

Update Email Action

user-event-metrics:v1

Collect metrics based on user events

web-authn:v1

W3C Web Authentication (WebAuthn)

14.3.1. Disabled by default
Copy link

The following list contains supported features that are disabled by default, and can be enabled if needed.

Expand
FeatureDescription

docker:v1

Docker Registry protocol

fips:v1

FIPS 140-2 mode

multi-site:v1

Multi-site support

14.4. Preview features
Copy link

Preview features are disabled by default and are not recommended for use in production. These features may change or be removed at a future release.

Expand
FeatureDescription

admin-fine-grained-authz:v1

Fine-Grained Admin Permissions

client-auth-federated:v1

Authenticates client based on assertions issued by identity provider

client-secret-rotation:v1

Client Secret Rotation

log-mdc:v1

Mapped Diagnostic Context (MDC) information in logs

rolling-updates:v2

Rolling Updates for patch releases

scripts:v1

Write custom authenticators using JavaScript

spiffe:v1

SPIFFE trust relationship provider

token-exchange:v1

Token Exchange Service

14.5. Deprecated features
Copy link

The following list contains deprecated features that will be removed in a future release. These features are disabled by default.

Expand
FeatureDescription

instagram-broker:v1

Instagram Identity Broker

login:v1

Legacy Login Theme

logout-all-sessions:v1

Logout all sessions logs out only regular sessions

passkeys-conditional-ui-authenticator:v1

Passkeys conditional UI authenticator

14.6. Relevant options
Copy link

Expand
 Value

features 🛠

Enables a set of one or more features.

CLI: --features
Env: KC_FEATURES

account-api[:v1], account[:v3], admin-api[:v1], admin-fine-grained-authz[:v1,v2], admin[:v2], authorization[:v1], ciba[:v1], client-auth-federated[:v1], client-policies[:v1], client-secret-rotation[:v1], client-types[:v1], clusterless[:v1], db-tidb[:v1], declarative-ui[:v1], device-flow[:v1], docker[:v1], dpop[:v1], dynamic-scopes[:v1], fips[:v1], hostname[:v2], impersonation[:v1], instagram-broker[:v1], ipa-tuura-federation[:v1], kerberos[:v1], kubernetes-service-accounts[:v1], log-mdc[:v1], login[:v2,v1], logout-all-sessions[:v1], multi-site[:v1], oid4vc-vci[:v1], opentelemetry[:v1], organization[:v1], par[:v1], passkeys-conditional-ui-authenticator[:v1], passkeys[:v1], persistent-user-sessions[:v1], preview, quick-theme[:v1], recovery-codes[:v1], rolling-updates[:v1,v2], scripts[:v1], spiffe[:v1], step-up-authentication[:v1], token-exchange-external-internal[:v2], token-exchange-standard[:v2], token-exchange[:v1], transient-users[:v1], update-email[:v1], user-event-metrics[:v1], web-authn[:v1], workflows[:v1]

features-disabled 🛠

Disables a set of one or more features.

CLI: --features-disabled
Env: KC_FEATURES_DISABLED

account, account-api, admin, admin-api, admin-fine-grained-authz, authorization, ciba, client-auth-federated, client-policies, client-secret-rotation, client-types, clusterless, db-tidb, declarative-ui, device-flow, docker, dpop, dynamic-scopes, fips, impersonation, instagram-broker, ipa-tuura-federation, kerberos, kubernetes-service-accounts, log-mdc, login, logout-all-sessions, multi-site, oid4vc-vci, opentelemetry, organization, par, passkeys, passkeys-conditional-ui-authenticator, persistent-user-sessions, preview, quick-theme, recovery-codes, rolling-updates, scripts, spiffe, step-up-authentication, token-exchange, token-exchange-external-internal, token-exchange-standard, transient-users, update-email, user-event-metrics, web-authn, workflows

Chapter 15. Configuring providers
Copy link

Configure providers for Red Hat build of Keycloak.

The server is built with extensibility in mind and for that it provides a number of Service Provider Interfaces or SPIs, each one responsible for providing a specific capability to the server. In this chapter, you are going to understand the core concepts around the configuration of SPIs and their respective providers.

After reading this chapter, you should be able to use the concepts and the steps herein explained to install, uninstall, enable, disable, and configure any provider, including those you have implemented to extend the server capabilities in order to better fulfill your requirements.

15.1. Configuration option format
Copy link

Providers can be configured by using a specific configuration format. The format consists of: 

spi-<spi-id>--<provider-id>--<property>=<value>
Copy to Clipboard Toggle word wrap

Or if there is no possibility of ambiguity between multiple providers: 

spi-<spi-id>-<provider-id>-<property>=<value>
Copy to Clipboard Toggle word wrap

The <spi-id> is the name of the SPI you want to configure.

The <provider-id> is the id of the provider you want to configure. This is the id set to the corresponding provider factory implementation.

The <property> is the actual name of the property you want to set for a given provider

Note

the property name enabled is effectively reserved for enabling / disabling a provider

All those names (for spi, provider, and property) should be in lower case and if the name is in camel-case such as myKeycloakProvider, it should include dashes (-) before upper-case letters as follows: my-keycloak-provider.

Taking the HttpClientSpi SPI as an example, the name of the SPI is connectionsHttpClient and one of the provider implementations available is named default. In order to set the connectionPoolSize property you would use a configuration option as follows: 

spi-connections-http-client--default--connection-pool-size=10
Copy to Clipboard Toggle word wrap

15.1.1. Setting a provider configuration option
Copy link

Provider configuration options are provided when starting the server. See all support configuration sources and formats for options in Configuring Red Hat build of Keycloak. For example via a command line option:

Setting the connection-pool-size for the default provider of the connections-http-client SPI

bin/kc.[sh|bat] start --spi-connections-http-client--default--connection-pool-size=10
Copy to Clipboard Toggle word wrap

15.2. Build time options
Copy link

15.2.1. Configuring a single provider for an SPI
Copy link

Depending on the SPI, multiple provider implementations can co-exist but only one of them is going to be used at runtime. For these SPIs, a specific provider is the primary implementation that is going to be active and used at runtime. The format consists of: 

spi-<spi-id>--provider=<provider-id>
Copy to Clipboard Toggle word wrap
Note

spi-<spi-id>-provider=<provider-id> may still be used, but the server will not properly detect when reaugmentation is needed.

To configure a provider as the single provider you should run the build command as follows:

Marking the mycustomprovider provider as the single provider for the email-template SPI

bin/kc.[sh|bat] build --spi-email-template--provider=mycustomprovider
Copy to Clipboard Toggle word wrap

15.2.2. Configuring a default provider for an SPI
Copy link

Depending on the SPI, multiple provider implementations can co-exist and one is used by default. For these SPIs, a specific provider is the default implementation that is going to selected unless a specific provider is requested. The format consists of: 

spi-<spi-id>--provider-default=<provider-id>
Copy to Clipboard Toggle word wrap
Note

spi-<spi-id>-provider-default=<provider-id> may still be used, but the server will not properly detect when reaugmentation is needed.

The following logic is used to determine the default provider:

  1. The explicitly configured default provider
  2. The provider with the highest order (providers with order ⇐ 0 are ignored)
  3. The provider with the id set to default

To configure a provider as the default provider you should run the build command as follows:

Marking the mycustomhash provider as the default provider for the password-hashing SPI

bin/kc.[sh|bat] build --spi-password-hashing--provider-default=mycustomprovider
Copy to Clipboard Toggle word wrap

15.2.3. Enabling and disabling a provider
Copy link

The format consists of: 

spi-<spi-id>--<provider-id>--enabled=<boolean>
Copy to Clipboard Toggle word wrap
Note

spi-<spi-id>-<provider-id>-enabled=<boolean> may still be used, but the server will not properly detect when reaugmentation is needed.

To enable or disable a provider you should run the build command as follows:

Enabling a provider

bin/kc.[sh|bat] build --spi-email-template--mycustomprovider--enabled=true
Copy to Clipboard Toggle word wrap

To disable a provider, use the same command and set the enabled property to false.

15.3. Installing and uninstalling a provider
Copy link

Custom providers should be packaged in a Java Archive (JAR) file and copied to the providers directory of the distribution. After that if you are using --optimized, you must run the build command in order to update the server’s provider registry with the implementations from the JAR file.

This step is needed in order to optimize the server runtime so that all providers are known ahead-of-time rather than discovered only when starting the server or at runtime.

Warning

Do not install untrusted provider JARs! There is a single class loader for the entire application, and JARs in the providers directory are given precedent over built-in libraries. There is also no built-in sandboxing of what state or methods are available to provider logic. Providers can do whatever the server process can which includes direct access to the DB, reading all server configuration (incl. credentials), etc.

To uninstall a provider, you should remove the JAR file from the providers directory and run the build command again.

15.4. Using third-party dependencies
Copy link

When implementing a provider you might need to use some third-party dependency that is not available from the server distribution.

In this case, you should copy any additional dependency to the providers directory and run the build command. Once you do that, the server is going to make these additional dependencies available at runtime for any provider that depends on them.

15.5. References
Copy link

Chapter 16. Configuring logging
Copy link

Configure logging for Red Hat build of Keycloak.

Red Hat build of Keycloak uses the JBoss Logging framework. The following is a high-level overview for the available log handlers with the common parent log handler root:

  • console
  • file
  • syslog

16.1. Logging configuration
Copy link

Logging is done on a per-category basis in Red Hat build of Keycloak. You can configure logging for the root log level or for more specific categories such as org.hibernate or org.keycloak. It is also possible to tailor log levels for each particular log handler.

This chapter describes how to configure logging.

16.1.1. Log levels
Copy link

The following table defines the available log levels.

Expand
LevelDescription

FATAL

Critical failures with complete inability to serve any kind of request.

ERROR

A significant error or problem leading to the inability to process requests.

WARN

A non-critical error or problem that might not require immediate correction.

INFO

Red Hat build of Keycloak lifecycle events or important information. Low frequency.

DEBUG

More detailed information for debugging purposes, such as database logs. Higher frequency.

TRACE

Most detailed debugging information. Very high frequency.

ALL

Special level for all log messages.

OFF

Special level to turn logging off entirely (not recommended).

16.1.2. Configuring the root log level
Copy link

When no log level configuration exists for a more specific category logger, the enclosing category is used instead. When there is no enclosing category, the root logger level is used.

To set the root log level, enter the following command: 

bin/kc.[sh|bat] start --log-level=<root-level>
Copy to Clipboard Toggle word wrap

Use these guidelines for this command:

  • For <root-level>, supply a level defined in the preceding table.
  • The log level is case-insensitive. For example, you could either use DEBUG or debug.
  • If you were to accidentally set the log level twice, the last occurrence in the list becomes the log level. For example, if you included the syntax --log-level="info,…​,DEBUG,…​", the root logger would be DEBUG.

16.1.3. Configuring category-specific log levels
Copy link

You can set different log levels for specific areas in Red Hat build of Keycloak. Use this command to provide a comma-separated list of categories for which you want a different log level: 

bin/kc.[sh|bat] start --log-level="<root-level>,<org.category1>:<org.category1-level>"
Copy to Clipboard Toggle word wrap

A configuration that applies to a category also applies to its sub-categories unless you include a more specific matching sub-category.

Example

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug,org.hibernate.hql.internal.ast:info"
Copy to Clipboard Toggle word wrap

This example sets the following log levels:

  • Root log level for all loggers is set to INFO.
  • The hibernate log level in general is set to debug.
  • To keep SQL abstract syntax trees from creating verbose log output, the specific subcategory org.hibernate.hql.internal.ast is set to info. As a result, the SQL abstract syntax trees are omitted instead of appearing at the debug level.

16.1.4. Adding context for log messages
Copy link

Note

Log messages with Mapped Diagnostic Context (MDC) is Preview and is not fully supported. This feature is disabled by default.

You can enable additional context information for each log line like the current realm and client that is executing the request.

Use the option log-mdc-enabled to enable it.

Example configuration

bin/kc.[sh|bat] start --features=log-mdc --log-mdc-enabled=true
Copy to Clipboard Toggle word wrap

Example output

2025-06-20 14:13:01,772 {kc.clientId=security-admin-console, kc.realmName=master} INFO ...
Copy to Clipboard Toggle word wrap

Specify which keys to be added by setting the configuration option log-mdc-keys.

16.1.5. Configuring levels as individual options
Copy link

When configuring category-specific log levels, you can also set the log levels as individual log-level-<category> options instead of using the log-level option for that. This is useful when you want to set the log levels for selected categories without overwriting the previously set log-level option.

Example

If you start the server as: 

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug"
Copy to Clipboard Toggle word wrap

you can then set an environmental variable KC_LOG_LEVEL_ORG_KEYCLOAK=trace to change the log level for the org.keycloak category.

The log-level-<category> options take precedence over log-level. This allows you to override what was set in the log-level option. For instance if you set KC_LOG_LEVEL_ORG_HIBERNATE=trace for the CLI example above, the org.hibernate category will use the trace level instead of debug.

Bear in mind that when using the environmental variables, the category name must be in uppercase and the dots must be replaced with underscores. When using other config sources, the category name must be specified "as is", for example: 

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug" --log-level-org.keycloak=trace
Copy to Clipboard Toggle word wrap

16.2. Enabling log handlers
Copy link

To enable log handlers, enter the following command: 

bin/kc.[sh|bat] start --log="<handler1>,<handler2>"
Copy to Clipboard Toggle word wrap

The available handlers are:

  • console
  • file
  • syslog

The more specific handler configuration mentioned below will only take effect when the handler is added to this comma-separated list.

16.2.1. Specify log level for each handler
Copy link

The log-level property specifies the global root log level and levels for selected categories. However, a more fine-grained approach for log levels is necessary to comply with the modern application requirements.

To set log levels for particular handlers, properties in format log-<handler>-level (where <handler> is available log handler) were introduced.

It means properties for log level settings look like this:

  • log-console-level - Console log handler
  • log-file-level - File log handler
  • log-syslog-level - Syslog log handler
Note

The log-<handler>-level properties are available only when the particular log handlers are enabled. More information in log handlers settings below.

Only log levels specified in Section 16.1.1, “Log levels” section are accepted, and must be in lowercase. There is no support for specifying particular categories for log handlers yet.

16.2.1.1. General principle
Copy link

It is necessary to understand that setting the log levels for each particular handler does not override the root level specified in the log-level property. Log handlers respect the root log level, which represents the maximal verbosity for the whole logging system. It means individual log handlers can be configured to be less verbose than the root logger, but not more.

Specifically, when an arbitrary log level is defined for the handler, it does not mean the log records with the log level will be present in the output. In that case, the root log-level must also be assessed. Log handler levels provide the restriction for the root log level, and the default log level for log handlers is all - without any restriction.

16.2.1.2. Examples
Copy link

Example: debug for file handler, but info for console handler:

bin/kc.[sh|bat] start --log=console,file --log-level=debug --log-console-level=info
Copy to Clipboard Toggle word wrap

The root log level is set to debug, so every log handler inherits the value - so does the file log handler. To hide debug records in the console, we need to set the minimal (least severe) level to info for the console handler.

Example: warn for all handlers, but debug for file handler:

bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug --log-console-level=warn --log-syslog-level=warn
Copy to Clipboard Toggle word wrap

The root level must be set to the most verbose required level (debug in this case), and other log handlers must be amended accordingly.

Example: info for all handlers, but debug+org.keycloak.events:trace for Syslog handler:

bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug,org.keycloak.events:trace, --log-syslog-level=trace --log-console-level=info --log-file-level=info
Copy to Clipboard Toggle word wrap

In order to see the org.keycloak.events:trace, the trace level must be set for the Syslog handler.

16.2.2. Use different JSON format for log handlers
Copy link

Every log handler provides the ability to have structured log output in JSON format. It can be enabled by properties in the format log-<handler>-output=json (where <handler> is a log handler).

If you need a different format of the produced JSON, you can leverage the following JSON output formats:

  • default (default)
  • ecs

The ecs value refers to the ECS (Elastic Common Schema).

ECS is an open-source, community-driven specification that defines a common set of fields to be used with Elastic solutions. The ECS specification is being converged with OpenTelemetry Semantic Conventions with the goal of creating a single standard maintained by OpenTelemetry.

In order to change the JSON output format, properties in the format log-<handler>-json-format (where <handler> is a log handler) were introduced:

  • log-console-json-format - Console log handler
  • log-file-json-format - File log handler
  • log-syslog-json-format - Syslog log handler
16.2.2.1. Example
Copy link

If you want to have JSON logs in ECS (Elastic Common Schema) format for the console log handler, you can enter the following command: 

bin/kc.[sh|bat] start --log-console-output=json --log-console-json-format=ecs
Copy to Clipboard Toggle word wrap

Example Log Message

{"@timestamp":"2025-02-03T14:53:22.539484211+01:00","event.sequence":9608,"log.logger":"io.quarkus","log.level":"INFO","message":"Keycloak 999.0.0-SNAPSHOT on JVM (powered by Quarkus 3.17.8) started in 4.615s. Listening on: http://0.0.0.0:8080","process.thread.name":"main","process.thread.id":1,"mdc":{},"ndc":"","host.hostname":"host-name","process.name":"/usr/lib/jvm/jdk-21.0.3+9/bin/java","process.pid":77561,"data_stream.type":"logs","ecs.version":"1.12.2","service.environment":"prod","service.name":"Keycloak","service.version":"999.0.0-SNAPSHOT"}
Copy to Clipboard Toggle word wrap

16.2.3. Asynchronous logging
Copy link

Red Hat build of Keycloak supports asynchronous logging, which might be useful for deployments requiring high throughput and low latency. Asynchronous logging uses a separate thread to take care of processing all log records. The logging handlers are invoked in exactly the same way as with synchronous logging, only done in separate threads. You can enable asynchronous logging for all Red Hat build of Keycloak log handlers. A dedicated thread will be created for every log handler with enabled asynchronous logging.

The underlying mechanism for asynchronous logging uses a queue for processing log records. Every new log record is added to the queue and then published to the particular log handler with enabled asynchronous logging. Every log handler has a different queue.

If the queue is already full, it blocks the main thread and waits for free space in the queue.

16.2.3.1. When to use asynchronous logging
Copy link
  • You need lower latencies for incoming requests
  • You need higher throughput
  • You have small worker thread pool and want to offload logging to separate threads
  • You want to reduce the impact of I/O-heavy log handlers
  • You are logging to remote destinations (e.g., network syslog servers) and want to avoid blocking worker threads
Warning

Be aware that enabling asynchronous logging might bring some additional memory overhead due to the additional separate thread and the inner queue. In that case, it is not recommended to use it for resource-constrained environments. Additionally, unexpected server shutdowns create a risk of losing log records.

16.2.3.2. Enable asynchronous logging
Copy link

You can enable asynchronous logging globally for all log handlers by using log-async property as follows: 

bin/kc.[sh|bat] start --log-async=true
Copy to Clipboard Toggle word wrap

Or you can enable the asynchronous logging for every specific handler by using properties in the format log-<handler>-async (where <handler> is a log handler). If the property for a specific handler is not set, the value from the parent log-async property is used.

You can use these properties as follows: 

bin/kc.[sh|bat] start --log-console-async=true --log-file-async=true --log-syslog-async=true
Copy to Clipboard Toggle word wrap
  • log-console-async - Console log handler
  • log-file-async - File log handler
  • log-syslog-async - Syslog log handler
16.2.3.3. Change queue length
Copy link

You can change the size of the queue used for the asynchronous logging. The default size is 512 log records in the queue.

You can change the queue length as follows: 

bin/kc.[sh|bat] start --log-console-async-queue-length=512 --log-file-async-queue-length=512 --log-syslog-async-queue-length=512
Copy to Clipboard Toggle word wrap

These properties are available only when asynchronous logging is enabled for these specific log handlers.

16.2.4. HTTP Access Logging
Copy link

Red Hat build of Keycloak supports HTTP access logging to record details of incoming HTTP requests. While access logs are often used for debugging and traffic analysis, they are also important for security auditing and compliance monitoring, helping administrators track access patterns, identify suspicious activity, and maintain audit trails.

These logs are written at the INFO level, so make sure your logging configuration includes this level — either globally (e.g. log-level=info) or specifically for the access log category (e.g. log-level=org.keycloak.http.access-log:info). When HTTP access logs are enabled, they are shown by default, as INFO level is the default log level for Red Hat build of Keycloak.

16.2.4.1. How to enable
Copy link

You can enable HTTP access logging by using http-access-log-enabled property as follows: 

bin/kc.[sh|bat] start --http-access-log-enabled=true
Copy to Clipboard Toggle word wrap
16.2.4.2. Change log format/pattern
Copy link

You can change format/pattern of the access log records by using http-access-log-pattern property as follows: 

bin/kc.[sh|bat] start --http-access-log-pattern=combined
Copy to Clipboard Toggle word wrap

Predefined named patterns:

  • common (default) - prints basic information about the request
  • combined - prints basic information about the request + information about referer and user agent
  • long - prints comprehensive information about the request with all its headers

You can even specify your own pattern with your required data to be logged, such as: 

bin/kc.[sh|bat] start --http-access-log-pattern='%A %{METHOD} %{REQUEST_URL} %{i,User-Agent}'
Copy to Clipboard Toggle word wrap

Consult the Quarkus documentation for the full list of variables that can be used.

16.2.4.3. Exclude specific URL paths
Copy link

It is possible to exclude specific URL paths from the HTTP access logging, so they will not be recorded.

You can use regular expressions to exclude them, such as: 

bin/kc.[sh|bat] start --http-access-log-exclude='/realms/my-internal-realm/.*'
Copy to Clipboard Toggle word wrap

In this case, all calls to the /realms/my-internal-realm/ and subsequent paths will be excluded from the HTTP Access log.

16.3. Console log handler
Copy link

The console log handler is enabled by default, providing unstructured log messages for the console.

16.3.1. Configuring the console log format
Copy link

Red Hat build of Keycloak uses a pattern-based logging formatter that generates human-readable text logs by default.

The logging format template for these lines can be applied at the root level. The default format template is:

  • %d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n

The format string supports the symbols in the following table:

Expand
SymbolSummaryDescription

%%

%

Renders a simple % character.

%c

Category

Renders the log category name.

%d{xxx}

Date

Renders a date with the given date format string.String syntax defined by java.text.SimpleDateFormat

%e

Exception

Renders a thrown exception.

%h

Hostname

Renders the simple host name.

%H

Qualified host name

Renders the fully qualified hostname, which may be the same as the simple host name, depending on the OS configuration.

%i

Process ID

Renders the current process PID.

%m

Full Message

Renders the log message and an exception, if thrown.

%n

Newline

Renders the platform-specific line separator string.

%N

Process name

Renders the name of the current process.

%p

Level

Renders the log level of the message.

%r

Relative time

Render the time in milliseconds since the start of the application log.

%s

Simple message

Renders only the log message without exception trace.

%t

Thread name

Renders the thread name.

%t{id}

Thread ID

Render the thread ID.

%z{<zone name>}

Timezone

Set the time zone of log output to <zone name>.

%L

Line number

Render the line number of the log message.

16.3.2. Setting the logging format
Copy link

To set the logging format for a logged line, perform these steps:

  1. Build your desired format template using the preceding table.

  2. Enter the following command: 

    bin/kc.[sh|bat] start --log-console-format="'<format>'"
    Copy to Clipboard Toggle word wrap

Note that you need to escape characters when invoking commands containing special shell characters such as ; using the CLI. Therefore, consider setting it in the configuration file instead.

Example: Abbreviate the fully qualified category name

bin/kc.[sh|bat] start --log-console-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"
Copy to Clipboard Toggle word wrap

This example abbreviates the category name to three characters by setting [%c{3.}] in the template instead of the default [%c].

16.3.3. Configuring JSON or plain console logging
Copy link

By default, the console log handler logs plain unstructured data to the console. To use structured JSON log output instead, enter the following command: 

bin/kc.[sh|bat] start --log-console-output=json
Copy to Clipboard Toggle word wrap

Example Log Message

{"timestamp":"2025-02-03T14:52:20.290353085+01:00","sequence":9605,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Keycloak 999.0.0-SNAPSHOT on JVM (powered by Quarkus 3.17.8) started in 4.440s. Listening on: http://0.0.0.0:8080","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host-name","processName":"/usr/lib/jvm/jdk-21.0.3+9/bin/java","processId":76944}
Copy to Clipboard Toggle word wrap

When using JSON output, colors are disabled and the format settings set by --log-console-format will not apply.

To use unstructured logging, enter the following command: 

bin/kc.[sh|bat] start --log-console-output=default
Copy to Clipboard Toggle word wrap

Example Log Message

2025-02-03 14:53:56,653 INFO  [io.quarkus] (main) Keycloak 999.0.0-SNAPSHOT on JVM (powered by Quarkus 3.17.8) started in 4.795s. Listening on: http://0.0.0.0:8080
Copy to Clipboard Toggle word wrap

16.3.4. Colors
Copy link

Colored console log output for unstructured logs is disabled by default. Colors may improve readability, but they can cause problems when shipping logs to external log aggregation systems. To enable or disable color-coded console log output, enter following command: 

bin/kc.[sh|bat] start --log-console-color=<false|true>
Copy to Clipboard Toggle word wrap

16.3.5. Configuring the console log level
Copy link

Log level for console log handler can be specified by --log-console-level property as follows: 

bin/kc.[sh|bat] start --log-console-level=warn
Copy to Clipboard Toggle word wrap

For more information, see the section Section 16.2.1, “Specify log level for each handler” above.

16.4. File logging
Copy link

As an alternative to logging to the console, you can use unstructured logging to a file.

16.4.1. Enable file logging
Copy link

Logging to a file is disabled by default. To enable it, enter the following command: 

bin/kc.[sh|bat] start --log="console,file"
Copy to Clipboard Toggle word wrap

A log file named keycloak.log is created inside the data/log directory of your Red Hat build of Keycloak installation.

To change where the log file is created and the file name, perform these steps:

  1. Create a writable directory to store the log file.

    If the directory is not writable, Red Hat build of Keycloak will start correctly, but it will issue an error and no log file will be created.

  2. Enter this command: 

    bin/kc.[sh|bat] start --log="console,file" --log-file=<path-to>/<your-file.log>
    Copy to Clipboard Toggle word wrap

16.4.3. Configuring the file handler format
Copy link

To configure a different logging format for the file log handler, enter the following command: 

bin/kc.[sh|bat] start --log-file-format="<pattern>"
Copy to Clipboard Toggle word wrap

See Section 16.3.1, “Configuring the console log format” for more information and a table of the available pattern configuration.

16.4.4. Configuring the file log level
Copy link

Log level for file log handler can be specified by --log-file-level property as follows: 

bin/kc.[sh|bat] start --log-file-level=warn
Copy to Clipboard Toggle word wrap

For more information, see the section Section 16.2.1, “Specify log level for each handler” above.

16.5. Centralized logging using Syslog
Copy link

Red Hat build of Keycloak provides the ability to send logs to a remote Syslog server. It utilizes the protocol defined in RFC 5424.

16.5.1. Enable the Syslog handler
Copy link

To enable logging using Syslog, add it to the list of activated log handlers as follows: 

bin/kc.[sh|bat] start --log="console,syslog"
Copy to Clipboard Toggle word wrap

16.5.2. Configuring the Syslog Application Name
Copy link

To set a different application name, add the --log-syslog-app-name option as follows: 

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-app-name=kc-p-itadmins
Copy to Clipboard Toggle word wrap

If not set, the application name defaults to keycloak.

16.5.3. Configuring the Syslog endpoint
Copy link

To configure the endpoint(host:port) of your centralized logging system, enter the following command and substitute the values with your specific values: 

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-endpoint=myhost:12345
Copy to Clipboard Toggle word wrap

When the Syslog handler is enabled, the host is using localhost as host value. The Default port is 514.

16.5.4. Configuring the Syslog log level
Copy link

Log level for Syslog log handler can be specified by --log-syslog-level property as follows: 

bin/kc.[sh|bat] start --log-syslog-level=warn
Copy to Clipboard Toggle word wrap

For more information, see the section Section 16.2.1, “Specify log level for each handler” above.

16.5.5. Configuring the Syslog protocol
Copy link

Syslog uses TCP as the default protocol for communication. To use UDP instead of TCP, add the --log-syslog-protocol option as follows: 

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-protocol=udp
Copy to Clipboard Toggle word wrap

The available protocols are: tpc, udp, and ssl-tcp.

16.5.6. Configuring the Syslog counting framing
Copy link

By default, Syslog messages sent over TCP or SSL-TCP are prefixed with the message size, as required by certain Syslog receivers. This behavior is controlled by the --log-syslog-counting-framing option.

To explicitly enable or disable this feature, use the following command: 

bin/kc.[sh|bat] start --log-syslog-counting-framing=true
Copy to Clipboard Toggle word wrap

You can set the value to one of the following:

  • protocol-dependent (default) – Enable counting framing only when the log-syslog-protocol is tcp or ssl-tcp.
  • true – Always enable counting framing by prefixing messages with their size.
  • false – Never use counting framing.

Note that using protocol-dependent ensures compatibility with most Syslog servers by enabling the prefix only when required by the protocol.

16.5.7. Configuring the Syslog log format
Copy link

To set the logging format for a logged line, perform these steps:

  1. Build your desired format template using the preceding table.

  2. Enter the following command: 

    bin/kc.[sh|bat] start --log-syslog-format="'<format>'"
    Copy to Clipboard Toggle word wrap

Note that you need to escape characters when invoking commands containing special shell characters such as ; using the CLI. Therefore, consider setting it in the configuration file instead.

Example: Abbreviate the fully qualified category name

bin/kc.[sh|bat] start --log-syslog-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"
Copy to Clipboard Toggle word wrap

This example abbreviates the category name to three characters by setting [%c{3.}] in the template instead of the default [%c].

16.5.8. Configuring the Syslog type
Copy link

Syslog uses different message formats based on particular RFC specifications. To change the Syslog type with a different message format, use the --log-syslog-type option as follows: 

bin/kc.[sh|bat] start --log-syslog-type=rfc3164
Copy to Clipboard Toggle word wrap

Possible values for the --log-syslog-type option are:

  • rfc5424 (default)
  • rfc3164

The preferred Syslog type is RFC 5424, which obsoletes RFC 3164, known as BSD Syslog protocol.

To set the maximum length of the message allowed to be sent (in bytes), use the --log-syslog-max-length option as follows: 

bin/kc.[sh|bat] start --log-syslog-max-length=1536
Copy to Clipboard Toggle word wrap

The length can be specified in memory size format with the appropriate suffix, like 1k or 1K. The length includes the header and the message.

If the length is not explicitly set, the default values are set based on the --log-syslog-type option as follows:

  • 2048B - for RFC 5424
  • 1024B - for RFC 3164

16.5.10. Configuring the Syslog structured output
Copy link

By default, the Syslog log handler sends plain unstructured data to the Syslog server. To use structured JSON log output instead, enter the following command: 

bin/kc.[sh|bat] start --log-syslog-output=json
Copy to Clipboard Toggle word wrap

Example Log Message

2024-04-05T12:32:20.616+02:00 host keycloak 2788276 io.quarkus - {"timestamp":"2024-04-05T12:32:20.616208533+02:00","sequence":9948,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Profile prod activated. ","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host","processName":"QuarkusEntryPoint","processId":2788276}
Copy to Clipboard Toggle word wrap

When using JSON output, colors are disabled and the format settings set by --log-syslog-format will not apply.

To use unstructured logging, enter the following command: 

bin/kc.[sh|bat] start --log-syslog-output=default
Copy to Clipboard Toggle word wrap

Example Log Message

2024-04-05T12:31:38.473+02:00 host keycloak 2787568 io.quarkus - 2024-04-05 12:31:38,473 INFO  [io.quarkus] (main) Profile prod activated.
Copy to Clipboard Toggle word wrap

As you can see, the timestamp is present twice, so you can amend it correspondingly via the --log-syslog-format property.

16.6. Relevant options
Copy link

Expand
 Value

log

Enable one or more log handlers in a comma-separated list.

CLI: --log
Env: KC_LOG

console, file, syslog

log-async

Indicates whether to log asynchronously to all handlers.

CLI: --log-async
Env: KC_LOG_ASYNC

true, false (default)

log-level

The log level of the root category or a comma-separated list of individual categories and their levels.

For the root category, you don’t need to specify a category.

CLI: --log-level
Env: KC_LOG_LEVEL

[info] (default)

log-level-<category>

The log level of a category.

Takes precedence over the log-level option.

CLI: --log-level-<category>
Env: KC_LOG_LEVEL_<CATEGORY>

off, fatal, error, warn, info, debug, trace, all

log-mdc-enabled 🛠

Indicates whether to add information about the realm and other information to the mapped diagnostic context.

All elements will be prefixed with kc.

CLI: --log-mdc-enabled
Env: KC_LOG_MDC_ENABLED

Available only when log-mdc preview feature is enabled

true, false (default)

log-mdc-keys

Defines which information should be added to the mapped diagnostic context as a comma-separated list.

CLI: --log-mdc-keys
Env: KC_LOG_MDC_KEYS

Available only when MDC logging is enabled

realmName, clientId, userId, ipAddress, org, sessionId, authenticationSessionId, authenticationTabId

16.6.1. Console
Copy link

Expand
 Value

log-console-async

Indicates whether to log asynchronously to console.

If not set, value from the parent property log-async is used.

CLI: --log-console-async
Env: KC_LOG_CONSOLE_ASYNC

Available only when Console log handler is activated

true, false (default)

log-console-async-queue-length

The queue length to use before flushing writing when logging to console.

CLI: --log-console-async-queue-length
Env: KC_LOG_CONSOLE_ASYNC_QUEUE_LENGTH

Available only when Console log handler is activated and asynchronous logging is enabled

512 (default)

log-console-color

Enable or disable colors when logging to console.

CLI: --log-console-color
Env: KC_LOG_CONSOLE_COLOR

Available only when Console log handler is activated

true, false (default)

log-console-format

The format of unstructured console log entries.

If the format has spaces in it, escape the value using "<format>".

CLI: --log-console-format
Env: KC_LOG_CONSOLE_FORMAT

Available only when Console log handler is activated

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n (default)

log-console-include-mdc

Include mdc information in the console log.

If the log-console-format option is specified, this option has no effect.

CLI: --log-console-include-mdc
Env: KC_LOG_CONSOLE_INCLUDE_MDC

Available only when Console log handler and MDC logging are activated

true (default), false

log-console-include-trace

Include tracing information in the console log.

If the log-console-format option is specified, this option has no effect.

CLI: --log-console-include-trace
Env: KC_LOG_CONSOLE_INCLUDE_TRACE

Available only when Console log handler and Tracing is activated

true (default), false

log-console-json-format

Set the format of the produced JSON.

CLI: --log-console-json-format
Env: KC_LOG_CONSOLE_JSON_FORMAT

Available only when Console log handler is activated and output is set to 'json'

default (default), ecs

log-console-level

Set the log level for the console handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-console-level
Env: KC_LOG_CONSOLE_LEVEL

Available only when Console log handler is activated

off, fatal, error, warn, info, debug, trace, all (default)

log-console-output

Set the log output to JSON or default (plain) unstructured logging.

CLI: --log-console-output
Env: KC_LOG_CONSOLE_OUTPUT

Available only when Console log handler is activated

default (default), json

16.6.2. File
Copy link

Expand
 Value

log-file

Set the log file path and filename.

CLI: --log-file
Env: KC_LOG_FILE

Available only when File log handler is activated

data/log/keycloak.log (default)

log-file-async

Indicates whether to log asynchronously to file log.

If not set, value from the parent property log-async is used.

CLI: --log-file-async
Env: KC_LOG_FILE_ASYNC

Available only when File log handler is activated

true, false (default)

log-file-async-queue-length

The queue length to use before flushing writing when logging to file log.

CLI: --log-file-async-queue-length
Env: KC_LOG_FILE_ASYNC_QUEUE_LENGTH

Available only when File log handler is activated and asynchronous logging is enabled

512 (default)

log-file-format

Set a format specific to file log entries.

CLI: --log-file-format
Env: KC_LOG_FILE_FORMAT

Available only when File log handler is activated

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n (default)

log-file-include-mdc

Include MDC information in the file log.

If the log-file-format option is specified, this option has no effect.

CLI: --log-file-include-mdc
Env: KC_LOG_FILE_INCLUDE_MDC

Available only when File log handler and MDC logging are activated

true (default), false

log-file-include-trace

Include tracing information in the file log.

If the log-file-format option is specified, this option has no effect.

CLI: --log-file-include-trace
Env: KC_LOG_FILE_INCLUDE_TRACE

Available only when File log handler and Tracing is activated

true (default), false

log-file-json-format

Set the format of the produced JSON.

CLI: --log-file-json-format
Env: KC_LOG_FILE_JSON_FORMAT

Available only when File log handler is activated and output is set to 'json'

default (default), ecs

log-file-level

Set the log level for the file handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-file-level
Env: KC_LOG_FILE_LEVEL

Available only when File log handler is activated

off, fatal, error, warn, info, debug, trace, all (default)

log-file-output

Set the log output to JSON or default (plain) unstructured logging.

CLI: --log-file-output
Env: KC_LOG_FILE_OUTPUT

Available only when File log handler is activated

default (default), json

16.6.3. Syslog
Copy link

Expand
 Value

log-syslog-app-name

Set the app name used when formatting the message in RFC5424 format.

CLI: --log-syslog-app-name
Env: KC_LOG_SYSLOG_APP_NAME

Available only when Syslog is activated

keycloak (default)

log-syslog-async

Indicates whether to log asynchronously to Syslog.

If not set, value from the parent property log-async is used.

CLI: --log-syslog-async
Env: KC_LOG_SYSLOG_ASYNC

Available only when Syslog is activated

true, false (default)

log-syslog-async-queue-length

The queue length to use before flushing writing when logging to Syslog.

CLI: --log-syslog-async-queue-length
Env: KC_LOG_SYSLOG_ASYNC_QUEUE_LENGTH

Available only when Syslog is activated and asynchronous logging is enabled

512 (default)

log-syslog-counting-framing

If true, the message being sent is prefixed with the size of the message.

If protocol-dependent, the default value is true when log-syslog-protocol is tcp or ssl-tcp, otherwise false.

CLI: --log-syslog-counting-framing
Env: KC_LOG_SYSLOG_COUNTING_FRAMING

Available only when Syslog is activated

true, false, protocol-dependent (default)

log-syslog-endpoint

Set the IP address and port of the Syslog server.

CLI: --log-syslog-endpoint
Env: KC_LOG_SYSLOG_ENDPOINT

Available only when Syslog is activated

localhost:514 (default)

log-syslog-format

Set a format specific to Syslog entries.

CLI: --log-syslog-format
Env: KC_LOG_SYSLOG_FORMAT

Available only when Syslog is activated

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n (default)

log-syslog-include-mdc

Include MDC information in the Syslog.

If the log-syslog-format option is specified, this option has no effect.

CLI: --log-syslog-include-mdc
Env: KC_LOG_SYSLOG_INCLUDE_MDC

Available only when Syslog handler and MDC logging are activated

true (default), false

log-syslog-include-trace

Include tracing information in the Syslog.

If the log-syslog-format option is specified, this option has no effect.

CLI: --log-syslog-include-trace
Env: KC_LOG_SYSLOG_INCLUDE_TRACE

Available only when Syslog handler and Tracing is activated

true (default), false

log-syslog-json-format

Set the format of the produced JSON.

CLI: --log-syslog-json-format
Env: KC_LOG_SYSLOG_JSON_FORMAT

Available only when Syslog is activated and output is set to 'json'

default (default), ecs

log-syslog-level

Set the log level for the Syslog handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-syslog-level
Env: KC_LOG_SYSLOG_LEVEL

Available only when Syslog is activated

off, fatal, error, warn, info, debug, trace, all (default)

log-syslog-max-length

Set the maximum length, in bytes, of the message allowed to be sent.

The length includes the header and the message. If not set, the default value is 2048 when log-syslog-type is rfc5424 (default) and 1024 when log-syslog-type is rfc3164.

CLI: --log-syslog-max-length
Env: KC_LOG_SYSLOG_MAX_LENGTH

Available only when Syslog is activated

 

log-syslog-output

Set the Syslog output to JSON or default (plain) unstructured logging.

CLI: --log-syslog-output
Env: KC_LOG_SYSLOG_OUTPUT

Available only when Syslog is activated

default (default), json

log-syslog-protocol

Set the protocol used to connect to the Syslog server.

CLI: --log-syslog-protocol
Env: KC_LOG_SYSLOG_PROTOCOL

Available only when Syslog is activated

tcp (default), udp, ssl-tcp

log-syslog-type

Set the Syslog type used to format the sent message.

CLI: --log-syslog-type
Env: KC_LOG_SYSLOG_TYPE

Available only when Syslog is activated

rfc5424 (default), rfc3164

16.6.4. HTTP Access log
Copy link

Expand
 Value

http-access-log-enabled

If HTTP access logging is enabled.

By default this will log records in console.

CLI: --http-access-log-enabled
Env: KC_HTTP_ACCESS_LOG_ENABLED

true, false (default)

http-access-log-exclude

A regular expression that can be used to exclude some paths from logging.

For instance, /realms/my-realm/.* will exclude all subsequent endpoints for realm my-realm from the log.

CLI: --http-access-log-exclude
Env: KC_HTTP_ACCESS_LOG_EXCLUDE

Available only when HTTP Access log is enabled

 

http-access-log-pattern

The HTTP access log pattern.

You can use the available named formats, or use custom format described in Quarkus documentation.

CLI: --http-access-log-pattern
Env: KC_HTTP_ACCESS_LOG_PATTERN

Available only when HTTP Access log is enabled

common (default), combined, long, or any

Chapter 17. FIPS 140-2 support
Copy link

Configure Red Hat build of Keycloak server for FIPS compliance.

The Federal Information Processing Standard Publication 140-2, (FIPS 140-2), is a U.S. government computer security standard used to approve cryptographic modules. Red Hat build of Keycloak supports running in FIPS 140-2 compliant mode. In this case, Red Hat build of Keycloak will use only FIPS approved cryptography algorithms for its functionality.

To run in FIPS 140-2, Red Hat build of Keycloak should run on a FIPS 140-2 enabled system. This requirement usually assumes RHEL or Fedora where FIPS was enabled during installation. See RHEL documentation for the details. When the system is in FIPS mode, it makes sure that the underlying OpenJDK is in FIPS mode as well and would use only FIPS enabled security providers.

To check that the system is in FIPS mode, you can check it with the following command from the command line: 

fips-mode-setup --check
Copy to Clipboard Toggle word wrap

If the system is not in FIPS mode, you can enable it with the following command, however it is recommended that system is in FIPS mode since the installation rather than subsequently enabling it as follows: 

fips-mode-setup --enable
Copy to Clipboard Toggle word wrap

17.1. BouncyCastle library
Copy link

Red Hat build of Keycloak internally uses the BouncyCastle library for many cryptography utilities. Please note that the default version of the BouncyCastle library that shipped with Red Hat build of Keycloak is not FIPS compliant; however, BouncyCastle also provides a FIPS validated version of its library. The FIPS validated BouncyCastle library is not shipped with Red Hat build of Keycloak as Red Hat build of Keycloak cannot provide official support of it. Therefore, to run in FIPS compliant mode, you need to download BouncyCastle-FIPS bits and add them to the Red Hat build of Keycloak distribution. When Red Hat build of Keycloak executes in fips mode, it will use the BCFIPS bits instead of the default BouncyCastle bits, which achieves FIPS compliance.

17.1.1. BouncyCastle FIPS bits
Copy link

BouncyCastle FIPS can be downloaded from the BouncyCastle official page. Then you can add them to the directory KEYCLOAK_HOME/providers of your distribution. Make sure to use proper versions compatible with BouncyCastle Red Hat build of Keycloak dependencies. The supported BCFIPS bits needed are:

  • bc-fips version 2.1.2.
  • bctls-fips version 2.1.22.
  • bcpkix-fips version 2.1.10.
  • bcutil-fips version 2.1.5.

17.2. Generating keystore
Copy link

You can create either pkcs12 or bcfks keystore to be used for the Red Hat build of Keycloak server SSL.

17.2.1. PKCS12 keystore
Copy link

The p12 (or pkcs12) keystore (and/or truststore) works well in BCFIPS non-approved mode.

PKCS12 keystore can be generated with OpenJDK 21 Java on RHEL 9 in the standard way. For instance, the following command can be used to generate the keystore: 

keytool -genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpassword \
  -keystore $KEYCLOAK_HOME/conf/server.keystore \
  -alias localhost \
  -dname CN=localhost -keypass passwordpassword
Copy to Clipboard Toggle word wrap

The pkcs12 keystores in FIPS mode do not manage secret (symmetric) keys. This limitation is imposed by the BCFIPS provider which does not allow this type of keys inside the pkcs12 keystore type.

When the system is in FIPS mode, the default java.security file is changed in order to use FIPS enabled security providers, so no additional configuration is needed. Additionally, in the PKCS12 keystore, you can store PBE (password-based encryption) keys simply by using the keytool command, which makes it ideal for using it with Red Hat build of Keycloak KeyStore Vault and/or to store configuration properties in the KeyStore Config Source. For more details, see the Configuring Red Hat build of Keycloak and the Using a vault.

17.2.2. BCFKS keystore
Copy link

BCFKS keystore generation requires the use of the BouncyCastle FIPS libraries and a custom security file.

You can start by creating a helper file, such as /tmp/kc.keystore-create.java.security. The content of the file needs only to have the following property: 

securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS
Copy to Clipboard Toggle word wrap

Next, enter a command such as the following to generate the keystore: 

keytool -keystore $KEYCLOAK_HOME/conf/server.keystore \
  -storetype bcfks \
  -providername BCFIPS \
  -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
  -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
  -providerpath $KEYCLOAK_HOME/providers/bc-fips-*.jar \
  -alias localhost \
  -genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpassword \
  -dname CN=localhost -keypass passwordpassword \
  -J-Djava.security.properties=/tmp/kc.keystore-create.java.security
Copy to Clipboard Toggle word wrap
Warning

Using self-signed certificates is for demonstration purposes only, so replace these certificates with proper certificates when you move to a production environment.

Similar options are needed when you are doing any other manipulation with keystore/truststore of bcfks type.

17.3. Running the server.
Copy link

To run the server with BCFIPS in non-approved mode, enter the following command
bin/kc.[sh|bat] start --features=fips --hostname=localhost --https-key-store-password=passwordpassword --log-level=INFO,org.keycloak.common.crypto:TRACE,org.keycloak.crypto:TRACE
Copy to Clipboard Toggle word wrap
Note

In non-approved mode, the default keystore type (as well as default truststore type) is PKCS12. Hence if you generated a BCFKS keystore as described above, it is also required to use the command --https-key-store-type=bcfks. A similar command might be needed for the truststore as well if you want to use it.

Note

You can disable logging in production if everything works as expected.

17.4. Strict mode
Copy link

There is the fips-mode option, which is automatically set to non-strict when the fips feature is enabled. This means to run BCFIPS in the "non-approved mode". The more secure alternative is to use --features=fips --fips-mode=strict in which case BouncyCastle FIPS will use "approved mode". Using that option results in stricter security requirements on cryptography and security algorithms.

Note

In strict mode, the default keystore type (as well as default truststore type) is BCFKS. If you want to use a different keystore type it is required to use the option --https-key-store-type with appropriate type. A similar command might be needed for the truststore as well if you want to use it.

When starting the server, you can include TRACE level in the startup command. For example: 

--log-level=INFO,org.keycloak.common.crypto.CryptoIntegration:TRACE
Copy to Clipboard Toggle word wrap

By using TRACE level, you can check that the startup log contains KC provider with the note about Approved Mode such as the following: 

KC(BCFIPS version 2.0102 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
Copy to Clipboard Toggle word wrap

17.4.1. Cryptography restrictions in strict mode
Copy link

  • As mentioned in the previous section, strict mode may not work with pkcs12 keystore. It is required to use another keystore (like bcfks) as mentioned earlier. Also jks and pkcs12 keystores are not supported in Red Hat build of Keycloak when using strict mode. Some examples are importing or generating a keystore of an OIDC or SAML client in the Admin Console or for a java-keystore provider in the realm keys.
  • User passwords must be 14 characters or longer. Red Hat build of Keycloak uses PBKDF2 based password encoding by default. BCFIPS approved mode requires passwords to be at least 112 bits (effectively 14 characters) with PBKDF2 algorithm. If you want to allow a shorter password, set the property max-padding-length of provider pbkdf2-sha512 of SPI password-hashing to 14 to provide additional padding when verifying a hash created by this algorithm. This setting is also backwards compatible with previously stored passwords. For example, if the user’s database is in a non-FIPS environment and you have shorter passwords and you want to verify them now with Red Hat build of Keycloak using BCFIPS in approved mode, the passwords should work. So effectively, you can use an option such as the following when starting the server: 
--spi-password-hashing--pbkdf2-sha512--max-padding-length=14
Copy to Clipboard Toggle word wrap
Note

Using the option above does not break FIPS compliance. However, note that longer passwords are good practice anyway. For example, passwords auto-generated by modern browsers match this requirement as they are longer than 14 characters. If you want to omit the option for max-padding-length, you can set the password policy to your realms to have passwords at least 14 characters long.

Note

When you are migrating from Red Hat build of Keycloak older than 24, or if you explicitly set the password policy to override the default hashing algorithm, it is possible that some of your users use an older algorithm like pbkdf2-sha256. In this case, consider adding the --spi-password-hashing--pbkdf2-sha256--max-padding-length=14 option to ensure that users having their passwords hashed with the older pbkdf2-sha256 can log in because their passwords may be shorter than 14 characters.

  • RSA keys of 1024 bits do not work (2048 is the minimum). This applies for keys used by the Red Hat build of Keycloak realm itself (Realm keys from the Keys tab in the admin console), but also client keys and IDP keys
  • HMAC SHA-XXX keys must be at least 112 bits (or 14 characters long). For example if you use OIDC clients with the client authentication Signed Jwt with Client Secret (or client-secret-jwt in the OIDC notation), then your client secrets should be at least 14 characters long. Note that for good security, it is recommended to use client secrets generated by the Red Hat build of Keycloak server, which always fulfils this requirement.
  • The bc-fips version 1.0.2.4 deals with the end of the transition period for PKCS 1.5 RSA encryption. Therefore JSON Web Encryption (JWE) with algorithm RSA1_5 is not allowed in strict mode by default (BC provides the system property -Dorg.bouncycastle.rsa.allow_pkcs15_enc=true as backward compatibility option for the moment). RSA-OAEP and RSA-OAEP-256 are still available as before.

17.5. Other restrictions
Copy link

To have SAML working, make sure that a XMLDSig security provider is available in your security providers. To have Kerberos working, make sure that a SunJGSS security provider is available. In FIPS enabled RHEL 9 in OpenJDK 21, the XMLDSig security provider may be already enabled in the java.security by default and the same applies with latest OpenJDK 17. But with older OpenJDK 17, it may not be enabled by default, which means that SAML effectively cannot work.

To have SAML working, you can manually add the provider into JAVA_HOME/conf/security/java.security into the list fips providers. For example, add the line such as the following in case that it is not already available in your FIPS security providers: 

fips.provider.7=XMLDSig
Copy to Clipboard Toggle word wrap

Adding this security provider should work well. In fact, it is FIPS compliant and is already added by default in the OpenJDK 21 and newer versions of OpenJDK 17. Details are in the bugzilla.

Note

It is recommended to look at JAVA_HOME/conf/security/java.security and check all configured providers here and make sure that the number matches. In other words, fips.provider.7 assumes that there are already 6 providers configured with prefix like fips.provider.N in this file.

If you prefer not to edit your java.security file inside java itself, you can create a custom java security file (for example named kc.java.security) and add only the single property above for adding XMLDSig provider into that file. Then start your Red Hat build of Keycloak server with this property file attached: 

-Djava.security.properties=/location/to/your/file/kc.java.security
Copy to Clipboard Toggle word wrap

For Kerberos/SPNEGO, the security provider SunJGSS is not yet fully FIPS compliant. Hence it is not recommended to add it to your list of security providers if you want to be FIPS compliant. The KERBEROS feature is disabled by default in Red Hat build of Keycloak when it is executed on FIPS platform and when security provider is not available. Details are in the bugzilla.

17.6. Run the CLI on the FIPS host
Copy link

If you want to run Client Registration CLI (kcreg.sh|bat script) or Admin CLI (kcadm.sh|bat script), the CLI must also use the BouncyCastle FIPS dependencies instead of plain BouncyCastle dependencies. To achieve this, you may copy the jars to the CLI library folder and that is enough. CLI tool will automatically use BCFIPS dependencies instead of plain BC when it detects that corresponding BCFIPS jars are present (see above for the versions used). For example, use command such as the following before running the CLI: 

cp $KEYCLOAK_HOME/providers/bc-fips-*.jar $KEYCLOAK_HOME/bin/client/lib/
cp $KEYCLOAK_HOME/providers/bctls-fips-*.jar $KEYCLOAK_HOME/bin/client/lib/
cp $KEYCLOAK_HOME/providers/bcutil-fips-*.jar $KEYCLOAK_HOME/bin/client/lib/
Copy to Clipboard Toggle word wrap
Note

When trying to use BCFKS truststore/keystore with CLI, you may see issues due this truststore is not the default java keystore type. It can be good to specify it as default in java security properties. For example run this command on unix based systems before doing any operation with kcadm|kcreg clients: 

echo "keystore.type=bcfks
fips.keystore.type=bcfks" > /tmp/kcadm.java.security
export KC_OPTS="-Djava.security.properties=/tmp/kcadm.java.security"
Copy to Clipboard Toggle word wrap

When you want Red Hat build of Keycloak in FIPS mode to be executed inside a container, your "host" must be using FIPS mode as well. The container will then "inherit" FIPS mode from the parent host. See this section in the RHEL documentation for the details.

The Red Hat build of Keycloak container image will automatically be in fips mode when executed from the host in FIPS mode. However, make sure that the Red Hat build of Keycloak container also uses BCFIPS jars (instead of BC jars) and proper options when started.

Regarding this, it is best to build your own container image as described in the Running Red Hat build of Keycloak in a container and tweak it to use BCFIPS etc.

For example in the current directory, you can create sub-directory files and add:

  • BC FIPS jar files as described above
  • Custom keystore file - named for example keycloak-fips.keystore.bcfks
  • Security file kc.java.security with added provider for SAML (Not needed with OpenJDK 21 or newer OpenJDK 17)

Then create Containerfile in the current directory similar to this:

Containerfile:

FROM registry.redhat.io/rhbk/keycloak-rhel9:26.4 as builder

ADD files /tmp/files/

WORKDIR /opt/keycloak
RUN cp /tmp/files/*.jar /opt/keycloak/providers/
RUN cp /tmp/files/keycloak-fips.keystore.* /opt/keycloak/conf/server.keystore
RUN cp /tmp/files/kc.java.security /opt/keycloak/conf/

RUN /opt/keycloak/bin/kc.sh build --features=fips --fips-mode=strict

FROM registry.redhat.io/rhbk/keycloak-rhel9:26.4
COPY --from=builder /opt/keycloak/ /opt/keycloak/

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
Copy to Clipboard Toggle word wrap

Then build FIPS as an optimized Docker image and start it as described in the Running Red Hat build of Keycloak in a container. These steps require that you use arguments as described above when starting the image.

17.8. Migration from non-fips environment
Copy link

If you previously used Red Hat build of Keycloak in a non-fips environment, it is possible to migrate it to a FIPS environment including its data. However, restrictions and considerations exist as mentioned in previous sections, namely:

  • Starting with Red Hat build of Keycloak 25, the default algorithm for password hashing is argon2. However, this algorithm is not supported for FIPS 140-2. This means that if your users hashed their password with argon2, they will not be able to login after switch to the FIPS environment. If you plan to migrate to the FIPS environment, consider setting the Password policy for your realm from the beginning (before any users are created) and override the default algorithm for example to pbkdf2-sha512, which is FIPS compliant. This strategy helps to make the migration to the FIPS environment to be smooth. Otherwise, if your users are already on argon2 passwords, simply ask users to reset the password after migrating to the FIPS environment. For instance, ask users to use "Forget password" or send the email for reset-password to all users.
  • Make sure all the Red Hat build of Keycloak functionality relying on keystores uses only supported keystore types. This differs based on whether strict or non-strict mode is used.
  • Kerberos authentication may not work. If your authentication flow uses Kerberos authenticator, this authenticator will be automatically switched to DISABLED when migrated to FIPS environment. It is recommended to remove any Kerberos user storage providers from your realm and disable Kerberos related functionality in LDAP providers before switching to FIPS environment.

In addition to the preceding requirements, be sure to doublecheck this before switching to FIPS strict mode:

  • Make sure that all the Red Hat build of Keycloak functionality relying on keys (for example, realm or client keys) use RSA keys of at least 2048 bits
  • Make sure that clients relying on Signed JWT with Client Secret use at least 14 characters long secrets (ideally generated secrets)
  • Password length restriction as described earlier. In case your users have shorter passwords, be sure to start the server with the max padding length set to 14 of PBKDF2 provider as mentioned earlier. If you prefer to avoid this option, you can for instance ask all your users to reset their password (for example by the Forgot password link) during the first authentication in the new environment.

Red Hat build of Keycloak is supported and tested on a FIPS enabled RHEL 8 system and ubi8 image. It is supported with RHEL 9 (and ubi9 image) as well. Running on the non-RHEL compatible platform or on the non-FIPS enabled platform, the FIPS compliance cannot be strictly guaranteed and cannot be officially supported.

If you are still restricted to running Red Hat build of Keycloak on such a system, you can at least update your security providers configured in java.security file. This update does not amount to FIPS compliance, but at least the setup is closer to it. It can be done by providing a custom security file with only an overridden list of security providers as described earlier. For a list of recommended providers, see the OpenJDK 21 documentation.

You can check the Red Hat build of Keycloak server log at startup to see if the correct security providers are used. TRACE logging should be enabled for crypto-related Red Hat build of Keycloak packages as described in the Keycloak startup command earlier.

Chapter 18. Configuring the Management Interface
Copy link

Configure Red Hat build of Keycloak’s management interface for endpoints such as metrics and health checks.

The management interface allows accessing management endpoints via a different HTTP server than the primary one. It provides the possibility to hide endpoints like /metrics or /health from the outside world and, therefore, hardens the security. The most significant advantage might be seen in Kubernetes environments as the specific management port might not be exposed.

18.1. Management interface configuration
Copy link

The management interface is turned on when something is exposed on it. Management endpoints such as /metrics and /health are exposed on the default management port 9000 when metrics and health are enabled. The management interface provides a set of options and is fully configurable.

Note

If management interface properties are not explicitly set, their values are automatically inherited from the default HTTP server.

18.1.1. Port
Copy link

In order to change the port for the management interface, you can use the Red Hat build of Keycloak option http-management-port.

18.1.2. Relative path
Copy link

You can change the relative path of the management interface, as the prefix path for the management endpoints can be different. You can achieve it via the Red Hat build of Keycloak option http-management-relative-path.

For instance, if you set the CLI option --http-management-relative-path=/management, the metrics, and health endpoints will be accessed on the /management/metrics and /management/health paths.

User is automatically redirected to the path where Red Hat build of Keycloak is hosted when the relative path is specified. It means when the relative path is set to /management, and the user access localhost:9000/, the page is redirected to localhost:9000/management.

Note

If you do not explicitly set the value for it, the value from the http-relative-path property is used. For instance, if you set the CLI option --http-relative-path=/auth, these endpoints are accessible on the /auth/metrics and /auth/health paths.

18.1.3. TLS support
Copy link

When the TLS is set for the default Red Hat build of Keycloak server, by default the management interface will be accessible through HTTPS as well. The management interface can run only either on HTTP or HTTPS, not both as for the main server.

Note

If you do not want the management interface to use HTTPS, you may set the http-management-scheme option to http.

Specific Red Hat build of Keycloak management interface options with the prefix https-management-* were provided for setting different TLS parameters for the management HTTP server. Their function is similar to their counterparts for the main HTTP server, for details see Configuring TLS. When these options are not explicitly set, the TLS parameters are inherited from the default HTTP server.

18.1.4. Disable Management interface
Copy link

The management interface is automatically turned off when nothing is exposed on it. Currently, only health checks and metrics are exposed on the management interface regardless. If you want to disable exposing them on the management interface, set the Red Hat build of Keycloak property legacy-observability-interface to true.

Warning

Exposing health and metrics endpoints on the default server is not recommended for security reasons, and you should always use the management interface. Beware, the legacy-observability-interface option is deprecated and will be removed in future releases. It only allows you to give more time for the migration.

18.2. Relevant options
Copy link

Expand
 Value

http-management-health-enabled 🛠

If health endpoints should be exposed on the management interface.

If false, health endpoints will be exposed on the main interface.

CLI: --http-management-health-enabled
Env: KC_HTTP_MANAGEMENT_HEALTH_ENABLED

Available only when health is enabled

true (default), false

http-management-port

Port of the management interface.

Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --http-management-port
Env: KC_HTTP_MANAGEMENT_PORT

9000 (default)

http-management-relative-path 🛠

Set the path relative to / for serving resources from management interface.

The path must start with a /. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --http-management-relative-path
Env: KC_HTTP_MANAGEMENT_RELATIVE_PATH

/ (default)

http-management-scheme

Configures the management interface scheme.

If inherited, the management interface will inherit the HTTPS settings of the main interface. If http, the management interface will be accessible via HTTP - it will not inherit HTTPS settings and cannot be configured for HTTPS.

CLI: --http-management-scheme
Env: KC_HTTP_MANAGEMENT_SCHEME

http, inherited (default)

https-management-certificate-file

The file path to a server certificate or certificate chain in PEM format for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificate-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_FILE

Available only when http-management-scheme is inherited

 

https-management-certificate-key-file

The file path to a private key in PEM format for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificate-key-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_KEY_FILE

Available only when http-management-scheme is inherited

 

https-management-certificates-reload-period

Interval on which to reload key store, trust store, and certificate files referenced by https-management-* options for the management server.

May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificates-reload-period
Env: KC_HTTPS_MANAGEMENT_CERTIFICATES_RELOAD_PERIOD

Available only when http-management-scheme is inherited

1h (default)

https-management-client-auth 🛠

Configures the management interface to require/request client authentication.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-client-auth
Env: KC_HTTPS_MANAGEMENT_CLIENT_AUTH

none (default), request, required

https-management-key-store-file

The key store which holds the certificate information instead of specifying separate files for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-key-store-file
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_FILE

Available only when http-management-scheme is inherited

 

https-management-key-store-password

The password of the key store file for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-key-store-password
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_PASSWORD

Available only when http-management-scheme is inherited

password (default)

legacy-observability-interface 🛠

If metrics/health endpoints should be exposed on the main HTTP server (not recommended).

If set to true, the management interface is disabled.

CLI: --legacy-observability-interface
Env: KC_LEGACY_OBSERVABILITY_INTERFACE

DEPRECATED.

true, false (default)

Chapter 19. Importing and exporting realms
Copy link

Import and export realms as JSON files.

In this chapter, you are going to understand the different approaches for importing and exporting realms using JSON files.

19.1. Import / Export Commands
Copy link

Note

Exporting and importing into single files can produce large files which may run the export / import process out of memory. If your database contains more than 50,000 users, export to a directory and not a single file. The default count of users per file is fifty, but you may use a much larger value if desired.

The import and export commands are essentially server launches that exit before bringing up the full server. They are not currently designed to be run from the same machine as a running server instance, which may result in port or other conflicts.

It is recommended that all Red Hat build of Keycloak nodes are stopped prior to using the kc.[sh|bat] export command. This ensures that the results will have no consistency issues with user or realm modifications during the export.

It is required that all Red Hat build of Keycloak nodes are stopped prior to performing an kc.[sh|bat] import command with the override option. The command does not attach to the cache cluster, so overwriting a realm will lead to inconsistent caches in the cluster, which then would show and use inconsistent or outdated information. Instead of overwriting a realm with the import command, consider using the Admin API to delete realms that need to be overwritten prior to running the import.

When using the export and the import commands below, Red Hat build of Keycloak needs to know how to connect to the database where the information about realms, clients, users and other entities is stored. As described in Configuring Red Hat build of Keycloak that information can be provided as command line parameters, environment variables or a configuration file. Use the --help command line option for each command to see the available options.

Some of the configuration options are build time configuration options. As default, Red Hat build of Keycloak will re-build automatically for the export and import commands if it detects a change of a build time parameter.

If you have built an optimized version of Red Hat build of Keycloak with the build command as outlined in Configuring Red Hat build of Keycloak, use the command line option --optimized to have Red Hat build of Keycloak skip the build check for a faster startup time. When doing this, remove the build time options from the command line and keep only the runtime options.

Note

if you do not use --optimized keep in mind that an import or export command may implicitly create or update an optimized build for you - if you are running the command from the same machine as a server instance, this may impact the next start of your server.

19.1.2. Exporting a Realm to a Directory
Copy link

To export a realm, you can use the export command. Your Red Hat build of Keycloak server instance must not be started when invoking this command. 

bin/kc.[sh|bat] export --help
Copy to Clipboard Toggle word wrap

To export a realm to a directory, you can use the --dir <dir> option. 

bin/kc.[sh|bat] export --dir <dir>
Copy to Clipboard Toggle word wrap

When exporting realms to a directory, the server is going to create separate files for each realm being exported.

19.1.2.1. Configuring how users are exported
Copy link

You are also able to configure how users are going to be exported by setting the --users <strategy> option. The values available for this option are:

different_files
Users export into different json files, depending on the maximum number of users per file set by --users-per-file. This is the default value.
skip
Skips exporting users.
realm_file
Users will be exported to the same file as the realm settings. For a realm named "foo", this would be "foo-realm.json" with realm data and users.
same_file
All users are exported to one explicit file. So you will get two json files for a realm, one with realm data and one with users.

If you are exporting users using the different_files strategy, you can set how many users per file you want by setting the --users-per-file option. The default value is 50. 

bin/kc.[sh|bat] export --dir <dir> --users different_files --users-per-file 100
Copy to Clipboard Toggle word wrap

19.1.3. Exporting a Realm to a File
Copy link

To export a realm to a file, you can use the --file <file> option. 

bin/kc.[sh|bat] export --file <file>
Copy to Clipboard Toggle word wrap

When exporting realms to a file, the server is going to use the same file to store the configuration for all the realms being exported.

19.1.4. Exporting a specific realm
Copy link

If you do not specify a specific realm to export, all realms are exported. To export a single realm, you can use the --realm option as follows: 

bin/kc.[sh|bat] export [--dir|--file] <path> --realm my-realm
Copy to Clipboard Toggle word wrap

19.1.5. Import File Naming Conventions
Copy link

When you export a realm specific file name conventions are used, which must also be used for importing from a directory or import at startup. The realm file to be imported must be named <realm name>-realm.json. Regular and federated user files associated with a realm must be named <realm-name>-users-<file number>.json and <realm-name>-federated-users-<file number>.json. Failure to use this convention will result in errors or user files not being imported.

19.1.6. Importing a Realm from a Directory
Copy link

To import a realm, you can use the import command. Your Red Hat build of Keycloak server instance must not be started when invoking this command. 

bin/kc.[sh|bat] import --help
Copy to Clipboard Toggle word wrap

After exporting a realm to a directory, you can use the --dir <dir> option to import the realm back to the server as follows: 

bin/kc.[sh|bat] import --dir <dir>
Copy to Clipboard Toggle word wrap

When importing realms using the import command, you are able to set if existing realms should be skipped, or if they should be overridden with the new configuration. For that, you can set the --override option as follows: 

bin/kc.[sh|bat] import --dir <dir> --override false
Copy to Clipboard Toggle word wrap

By default, the --override option is set to true so that realms are always overridden with the new configuration.

19.1.7. Importing a Realm from a File
Copy link

To import a realm previously exported in a single file, you can use the --file <file> option as follows: 

bin/kc.[sh|bat] import --file <file>
Copy to Clipboard Toggle word wrap

You are able to use placeholders to resolve values from environment variables for any realm configuration.

Realm configuration using placeholders

{
    "realm": "${MY_REALM_NAME}",
    "enabled": true,
    ...
}
Copy to Clipboard Toggle word wrap

In the example above, the value set to the MY_REALM_NAME environment variable is going to be used to set the realm property.

Note

there are currently no restrictions on what environment variables may be referenced. When environment variables are used to convey sensitive information, take care to ensure placeholders references do not inappropriately expose sensitive environment variable values.

19.2. Importing a Realm during Startup
Copy link

You are also able to import realms when the server is starting by using the --import-realm option. 

bin/kc.[sh|bat] start --import-realm
Copy to Clipboard Toggle word wrap

When you set the --import-realm option, the server is going to try to import any realm configuration file from the data/import directory. Only regular files using the .json extension are read from this directory, sub-directories are ignored.

Note

For the Red Hat build of Keycloak containers, the import directory is /opt/keycloak/data/import

If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating realms and potentially lose state between server restarts.

To re-create realms you should explicitly run the import command prior to starting the server.

Note

The server will not fully start until the imports are complete.

You can also import and export a realm using the Admin Console. This functionality is different from the other CLI options described in previous sections because the Admin Console requires the cluster to be online. The Admin Console also offers only the capability to partially export a realm. In this case, the current realm settings, along with some resources like clients, roles, and groups, can be exported. The users for that realm cannot be exported using this method.

Note

When using the Admin Console export, the realm and the selected resources are always exported to a file named realm-export.json. Also, all sensitive values like passwords and client secrets will be masked with * symbols.

To export a realm using the Admin Console, perform these steps:

  1. Select a realm.
  2. Click Realm settings in the menu.

  3. Point to the Action menu in the top right corner of the realm settings screen, and select Partial export.

    A list of resources appears along with the realm configuration.

  4. Select the resources you want to export.
  5. Click Export.
Note

Realms exported from the Admin Console are not suitable for backups or data transfer between servers. Only CLI exports are suitable for backups or data transfer between servers.

Warning

If the realm contains many groups, roles, and clients, the operation may cause the server to be unresponsive to user requests for a while. Use this feature with caution, especially on a production system.

In a similar way, you can import a previously exported realm. Perform these steps:

  1. Click Realm settings in the menu.

  2. Point to the Action menu in the top right corner of the realm settings screen, and select Partial import.

    A prompt appears where you can select the file you want to import. Based on this file, you see the resources you can import along with the realm settings.

  3. Click Import.

You can also control what Red Hat build of Keycloak should do if the imported resource already exists. These options exist:

Fail import
Abort the import.
Skip
Skip the duplicate resources without aborting the process
Overwrite
Replace the existing resources with the ones being imported.
Note

The Admin Console partial import can also import files created by the CLI export command. In other words, full exports created by the CLI can be imported by using the Admin Console. If the file contains users, those users will also be available for importing into the current realm.

Chapter 20. Using a vault
Copy link

Configure and use a vault in Red Hat build of Keycloak.

Red Hat build of Keycloak provides two out-of-the-box implementations of the Vault SPI: a plain-text file-based vault and Java KeyStore-based vault.

The file-based vault implementation is especially useful for Kubernetes/OpenShift secrets. You can mount Kubernetes secrets into the Red Hat build of Keycloak Container, and the data fields will be available in the mounted folder with a flat-file structure.

The Java KeyStore-based vault implementation is useful for storing secrets in bare metal installations. You can use the KeyStore vault, which is encrypted using a password.

20.1. Available integrations
Copy link

Secrets stored in the vaults can be used at the following places of the Administration Console:

  • Obtain the SMTP Mail server Password
  • Obtain the LDAP Bind Credential when using LDAP-based User Federation
  • Obtain the OIDC identity providers Client Secret when integrating external identity providers

20.2. Enabling a vault
Copy link

For enabling the file-based vault you need to build Red Hat build of Keycloak first using the following build option: 

bin/kc.[sh|bat] build --vault=file
Copy to Clipboard Toggle word wrap

Analogically, for the Java KeyStore-based you need to specify the following build option: 

bin/kc.[sh|bat] build --vault=keystore
Copy to Clipboard Toggle word wrap

20.3. Configuring the file-based vault
Copy link

Kubernetes/OpenShift secrets are basically mounted files. To configure a directory where these files should be mounted, enter this command: 

bin/kc.[sh|bat] start --vault-dir=/my/path
Copy to Clipboard Toggle word wrap

20.3.2. Realm-specific secret files
Copy link

Kubernetes/OpenShift Secrets are used on a per-realm basis in Red Hat build of Keycloak, which requires a naming convention for the file in place: 

${vault.<realmname>_<secretname>}
Copy to Clipboard Toggle word wrap

20.4. Configuring the Java KeyStore-based vault
Copy link

In order to use the Java KeyStore-based vault, you need to create a KeyStore file first. You can use the following command for doing so: 

keytool -importpass -alias <realm-name>_<alias> -keystore keystore.p12 -storepass keystorepassword
Copy to Clipboard Toggle word wrap

and then enter a value you want to store in the vault. Note that the format of the -alias parameter depends on the key resolver used. The default key resolver is REALM_UNDERSCORE_KEY.

This by default results to storing the value in a form of generic PBEKey (password based encryption) within SecretKeyEntry.

You can then start Red Hat build of Keycloak using the following runtime options: 

bin/kc.[sh|bat] start  --vault-file=/path/to/keystore.p12 --vault-pass=<value> --vault-type=<value>
Copy to Clipboard Toggle word wrap

Note that the --vault-type parameter is optional and defaults to PKCS12.

Secrets stored in the vault can then be accessed in a realm via the following placeholder (assuming using the REALM_UNDERSCORE_KEY key resolver): ${vault.realm-name_alias}.

20.5. Using underscores in the secret names
Copy link

To process the secret correctly, you double all underscores in the <secretname>. When REALM_UNDERSCORE_KEY key resolver is used, underscores in <realmname> are also doubled and <secretname> and <realmname> is separated by a single underscore.

Example

  • Realm Name: sso_realm
  • Desired Name: ldap_credential
  • Resulting file name: 
sso__realm_ldap__credential
Copy to Clipboard Toggle word wrap

Note the doubled underscores between sso and realm and also between ldap and credential.

To learn more about key resolvers, see Key resolvers section in the Server Administration guide.

Example setup

  • A realm named secrettest
  • A desired Name ldapBc for the bind Credential
  • Resulting file name: secrettest_ldapBc

Usage in Admin Console

You can then use this secret from the Admin Console by using ${vault.ldapBc} as the value for the Bind Credential when configuring your LDAP User federation.

20.7. Relevant options
Copy link

Expand
 Value

vault 🛠

Enables a vault provider.

CLI: --vault
Env: KC_VAULT

file, keystore

vault-dir

If set, secrets can be obtained by reading the content of files within the given directory.

CLI: --vault-dir
Env: KC_VAULT_DIR

 

vault-file

Path to the keystore file.

CLI: --vault-file
Env: KC_VAULT_FILE

 

vault-pass

Password for the vault keystore.

CLI: --vault-pass
Env: KC_VAULT_PASS

 

vault-type

Specifies the type of the keystore file.

CLI: --vault-type
Env: KC_VAULT_TYPE

PKCS12 (default)

Chapter 21. All configuration
Copy link

Review build options and configuration for Red Hat build of Keycloak.

21.1. Cache
Copy link

Expand
 Value

cache

Defines the cache mechanism for high-availability.

By default in production mode, a ispn cache is used to create a cluster between multiple server nodes. By default in development mode, a local cache disables clustering and is intended for development and testing purposes.

CLI: --cache
Env: KC_CACHE

ispn (default), local

cache-config-file

Defines the file from which cache configuration should be loaded from.

The configuration file is relative to the conf/ directory.

CLI: --cache-config-file
Env: KC_CACHE_CONFIG_FILE

 

cache-config-mutate

Determines whether changes to the default cache configurations are allowed.

This is only recommended for advanced use-cases where the default cache configurations are proven to be problematic. The only supported way to change the default cache configurations is via the other cache-…​ options.

CLI: --cache-config-mutate
Env: KC_CACHE_CONFIG_MUTATE

true, false (default)

cache-embedded-authorization-max-count

The maximum number of entries that can be stored in-memory by the authorization cache.

CLI: --cache-embedded-authorization-max-count
Env: KC_CACHE_EMBEDDED_AUTHORIZATION_MAX_COUNT

 

cache-embedded-client-sessions-max-count

The maximum number of entries that can be stored in-memory by the clientSessions cache.

CLI: --cache-embedded-client-sessions-max-count
Env: KC_CACHE_EMBEDDED_CLIENT_SESSIONS_MAX_COUNT

Available only when embedded Infinispan clusters configured

 

cache-embedded-crl-max-count

The maximum number of entries that can be stored in-memory by the crl cache.

CLI: --cache-embedded-crl-max-count
Env: KC_CACHE_EMBEDDED_CRL_MAX_COUNT

 

cache-embedded-keys-max-count

The maximum number of entries that can be stored in-memory by the keys cache.

CLI: --cache-embedded-keys-max-count
Env: KC_CACHE_EMBEDDED_KEYS_MAX_COUNT

 

cache-embedded-mtls-enabled

Encrypts the network communication between Keycloak servers.

If no additional parameters about a keystore and truststore are provided, ephemeral key pairs and certificates are created and rotated automatically, which is recommended for standard setups.

CLI: --cache-embedded-mtls-enabled
Env: KC_CACHE_EMBEDDED_MTLS_ENABLED

Available only when a TCP based cache-stack is used

true (default), false

cache-embedded-mtls-key-store-file

The Keystore file path.

The Keystore must contain the certificate to use by the TLS protocol. By default, it looks up cache-mtls-keystore.p12 under conf/ directory.

CLI: --cache-embedded-mtls-key-store-file
Env: KC_CACHE_EMBEDDED_MTLS_KEY_STORE_FILE

Available only when property 'cache-embedded-mtls-enabled' is enabled

 

cache-embedded-mtls-key-store-password

The password to access the Keystore.

CLI: --cache-embedded-mtls-key-store-password
Env: KC_CACHE_EMBEDDED_MTLS_KEY_STORE_PASSWORD

Available only when property 'cache-embedded-mtls-enabled' is enabled

 

cache-embedded-mtls-rotation-interval-days

Rotation period in days of automatic JGroups MTLS certificates.

CLI: --cache-embedded-mtls-rotation-interval-days
Env: KC_CACHE_EMBEDDED_MTLS_ROTATION_INTERVAL_DAYS

Available only when property 'cache-embedded-mtls-enabled' is enabled

30 (default)

cache-embedded-mtls-trust-store-file

The Truststore file path.

It should contain the trusted certificates or the Certificate Authority that signed the certificates. By default, it lookup cache-mtls-truststore.p12 under conf/ directory.

CLI: --cache-embedded-mtls-trust-store-file
Env: KC_CACHE_EMBEDDED_MTLS_TRUST_STORE_FILE

Available only when property 'cache-embedded-mtls-enabled' is enabled

 

cache-embedded-mtls-trust-store-password

The password to access the Truststore.

CLI: --cache-embedded-mtls-trust-store-password
Env: KC_CACHE_EMBEDDED_MTLS_TRUST_STORE_PASSWORD

Available only when property 'cache-embedded-mtls-enabled' is enabled

 

cache-embedded-network-bind-address

IP address used by clustering transport.

By default, SITE_LOCAL is used.

CLI: --cache-embedded-network-bind-address
Env: KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS

Available only when Infinispan clustered embedded is enabled

 

cache-embedded-network-bind-port

The Port the clustering transport will bind to.

By default, port 7800 is used.

CLI: --cache-embedded-network-bind-port
Env: KC_CACHE_EMBEDDED_NETWORK_BIND_PORT

Available only when Infinispan clustered embedded is enabled

 

cache-embedded-network-external-address

IP address that other instances in the cluster should use to contact this node.

Set only if it is different to cache-embedded-network-bind-address, for example when this instance is behind a firewall.

CLI: --cache-embedded-network-external-address
Env: KC_CACHE_EMBEDDED_NETWORK_EXTERNAL_ADDRESS

Available only when Infinispan clustered embedded is enabled

 

cache-embedded-network-external-port

Port that other instances in the cluster should use to contact this node.

Set only if it is different to cache-embedded-network-bind-port, for example when this instance is behind a firewall

CLI: --cache-embedded-network-external-port
Env: KC_CACHE_EMBEDDED_NETWORK_EXTERNAL_PORT

Available only when Infinispan clustered embedded is enabled

 

cache-embedded-offline-client-sessions-max-count

The maximum number of entries that can be stored in-memory by the offlineClientSessions cache.

CLI: --cache-embedded-offline-client-sessions-max-count
Env: KC_CACHE_EMBEDDED_OFFLINE_CLIENT_SESSIONS_MAX_COUNT

Available only when embedded Infinispan clusters configured

 

cache-embedded-offline-sessions-max-count

The maximum number of entries that can be stored in-memory by the offlineSessions cache.

CLI: --cache-embedded-offline-sessions-max-count
Env: KC_CACHE_EMBEDDED_OFFLINE_SESSIONS_MAX_COUNT

Available only when embedded Infinispan clusters configured

 

cache-embedded-realms-max-count

The maximum number of entries that can be stored in-memory by the realms cache.

CLI: --cache-embedded-realms-max-count
Env: KC_CACHE_EMBEDDED_REALMS_MAX_COUNT

 

cache-embedded-sessions-max-count

The maximum number of entries that can be stored in-memory by the sessions cache.

CLI: --cache-embedded-sessions-max-count
Env: KC_CACHE_EMBEDDED_SESSIONS_MAX_COUNT

Available only when embedded Infinispan clusters configured

 

cache-embedded-users-max-count

The maximum number of entries that can be stored in-memory by the users cache.

CLI: --cache-embedded-users-max-count
Env: KC_CACHE_EMBEDDED_USERS_MAX_COUNT

 

cache-metrics-histograms-enabled

Enable histograms for metrics for the embedded caches.

CLI: --cache-metrics-histograms-enabled
Env: KC_CACHE_METRICS_HISTOGRAMS_ENABLED

Available only when metrics are enabled

true, false (default)

cache-remote-backup-sites

Configures a list of backup sites names to where the external Infinispan cluster backups the Keycloak data.

CLI: --cache-remote-backup-sites
Env: KC_CACHE_REMOTE_BACKUP_SITES

Available only when remote host is set

 

cache-remote-host

The hostname of the external Infinispan cluster.

Available only when feature multi-site or clusterless is set.

CLI: --cache-remote-host
Env: KC_CACHE_REMOTE_HOST

 

cache-remote-password

The password for the authentication to the external Infinispan cluster.

It is optional if connecting to an unsecure external Infinispan cluster. If the option is specified, cache-remote-username is required as well.

CLI: --cache-remote-password
Env: KC_CACHE_REMOTE_PASSWORD

Available only when remote host is set

 

cache-remote-port

The port of the external Infinispan cluster.

CLI: --cache-remote-port
Env: KC_CACHE_REMOTE_PORT

Available only when remote host is set

11222 (default)

cache-remote-tls-enabled

Enable TLS support to communicate with a secured remote Infinispan server.

Recommended to be enabled in production.

CLI: --cache-remote-tls-enabled
Env: KC_CACHE_REMOTE_TLS_ENABLED

Available only when remote host is set

true (default), false

cache-remote-username

The username for the authentication to the external Infinispan cluster.

It is optional if connecting to an unsecure external Infinispan cluster. If the option is specified, cache-remote-password is required as well.

CLI: --cache-remote-username
Env: KC_CACHE_REMOTE_USERNAME

Available only when remote host is set

 

cache-stack

Define the default stack to use for cluster communication and node discovery.

Defaults to jdbc-ping if not set.

CLI: --cache-stack
Env: KC_CACHE_STACK

Available only when 'cache' type is set to 'ispn'

Use 'jdbc-ping' instead by leaving it unset Deprecated values: azure, ec2, google, jdbc-ping-udp, kubernetes, tcp, udp

jdbc-ping, kubernetes (deprecated), jdbc-ping-udp (deprecated), tcp (deprecated), udp (deprecated), ec2 (deprecated), azure (deprecated), google (deprecated), or any

21.2. Config
Copy link

Expand
 Value

config-keystore

Specifies a path to the KeyStore Configuration Source.

CLI: --config-keystore
Env: KC_CONFIG_KEYSTORE

 

config-keystore-password

Specifies a password to the KeyStore Configuration Source.

CLI: --config-keystore-password
Env: KC_CONFIG_KEYSTORE_PASSWORD

 

config-keystore-type

Specifies a type of the KeyStore Configuration Source.

CLI: --config-keystore-type
Env: KC_CONFIG_KEYSTORE_TYPE

PKCS12 (default)

21.3. Database
Copy link

Expand
 Value

db 🛠

The database vendor.

In production mode the default value of dev-file is deprecated, you should explicitly specify the db instead.

Named key: db-kind-<datasource> 🛠

CLI: --db
Env: KC_DB

dev-file (default), dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb

db-debug-jpql

Add JPQL information as comments to SQL statements to debug JPA SQL statement generation.

Named key: db-debug-jpql-<datasource>

CLI: --db-debug-jpql
Env: KC_DB_DEBUG_JPQL

true, false (default)

db-driver 🛠

The fully qualified class name of the JDBC driver.

If not set, a default driver is set accordingly to the chosen database.

Named key: db-driver-<datasource> 🛠

CLI: --db-driver
Env: KC_DB_DRIVER

 

db-log-slow-queries-threshold

Log SQL statements slower than the configured threshold with logger org.

hibernate.SQL_SLOW and log-level info.

Named key: db-log-slow-queries-threshold-<datasource>

CLI: --db-log-slow-queries-threshold
Env: KC_DB_LOG_SLOW_QUERIES_THRESHOLD

10000 (default)

db-password

The password of the database user.

Named key: db-password-<datasource>

CLI: --db-password
Env: KC_DB_PASSWORD

 

db-pool-initial-size

The initial size of the connection pool.

Named key: db-pool-initial-size-<datasource>

CLI: --db-pool-initial-size
Env: KC_DB_POOL_INITIAL_SIZE

 

db-pool-max-lifetime

The maximum time a connection remains in the pool, after which it will be closed upon return and replaced as necessary.

May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d].

CLI: --db-pool-max-lifetime
Env: KC_DB_POOL_MAX_LIFETIME

 

db-pool-max-size

The maximum size of the connection pool.

Named key: db-pool-max-size-<datasource>

CLI: --db-pool-max-size
Env: KC_DB_POOL_MAX_SIZE

100 (default)

db-pool-min-size

The minimal size of the connection pool.

Named key: db-pool-min-size-<datasource>

CLI: --db-pool-min-size
Env: KC_DB_POOL_MIN_SIZE

 

db-schema

The database schema to be used.

Named key: db-schema-<datasource>

CLI: --db-schema
Env: KC_DB_SCHEMA

 

db-url

The full database JDBC URL.

If not provided, a default URL is set based on the selected database vendor. For instance, if using postgres, the default JDBC URL would be jdbc:postgresql://localhost/keycloak.

Named key: db-url-full-<datasource>

CLI: --db-url
Env: KC_DB_URL

 

db-url-database

Sets the database name of the default JDBC URL of the chosen vendor.

If the db-url option is set, this option is ignored.

Named key: db-url-database-<datasource>

CLI: --db-url-database
Env: KC_DB_URL_DATABASE

 

db-url-host

Sets the hostname of the default JDBC URL of the chosen vendor.

If the db-url option is set, this option is ignored.

Named key: db-url-host-<datasource>

CLI: --db-url-host
Env: KC_DB_URL_HOST

 

db-url-port

Sets the port of the default JDBC URL of the chosen vendor.

If the db-url option is set, this option is ignored.

Named key: db-url-port-<datasource>

CLI: --db-url-port
Env: KC_DB_URL_PORT

 

db-url-properties

Sets the properties of the default JDBC URL of the chosen vendor.

Make sure to set the properties accordingly to the format expected by the database vendor, as well as appending the right character at the beginning of this property value. If the db-url option is set, this option is ignored.

Named key: db-url-properties-<datasource>

CLI: --db-url-properties
Env: KC_DB_URL_PROPERTIES

 

db-username

The username of the database user.

Named key: db-username-<datasource>

CLI: --db-username
Env: KC_DB_USERNAME

 

21.4. Database - additional datasources
Copy link

Expand
 Value

db-debug-jpql-<datasource>

Used for named <datasource>.

Add JPQL information as comments to SQL statements to debug JPA SQL statement generation.

CLI: --db-debug-jpql-<datasource>
Env: KC_DB_DEBUG_JPQL_<DATASOURCE>

true, false (default)

db-driver-<datasource> 🛠

Used for named <datasource>.

The fully qualified class name of the JDBC driver. If not set, a default driver is set accordingly to the chosen database.

CLI: --db-driver-<datasource>
Env: KC_DB_DRIVER_<DATASOURCE>

 

db-enabled-<datasource>

If the named datasource <datasource> should be enabled at runtime.

CLI: --db-enabled-<datasource>
Env: KC_DB_ENABLED_<DATASOURCE>

true (default), false

db-kind-<datasource> 🛠

Used for named <datasource>.

The database vendor. In production mode the default value of dev-file is deprecated, you should explicitly specify the db instead.

CLI: --db-kind-<datasource>
Env: KC_DB_KIND_<DATASOURCE>

dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb

db-log-slow-queries-threshold-<datasource>

Used for named <datasource>.

Log SQL statements slower than the configured threshold with logger org.hibernate.SQL_SLOW and log-level info.

CLI: --db-log-slow-queries-threshold-<datasource>
Env: KC_DB_LOG_SLOW_QUERIES_THRESHOLD_<DATASOURCE>

10000 (default)

db-password-<datasource>

Used for named <datasource>.

The password of the database user.

CLI: --db-password-<datasource>
Env: KC_DB_PASSWORD_<DATASOURCE>

 

db-pool-initial-size-<datasource>

Used for named <datasource>.

The initial size of the connection pool.

CLI: --db-pool-initial-size-<datasource>
Env: KC_DB_POOL_INITIAL_SIZE_<DATASOURCE>

 

db-pool-max-size-<datasource>

Used for named <datasource>.

The maximum size of the connection pool.

CLI: --db-pool-max-size-<datasource>
Env: KC_DB_POOL_MAX_SIZE_<DATASOURCE>

100 (default)

db-pool-min-size-<datasource>

Used for named <datasource>.

The minimal size of the connection pool.

CLI: --db-pool-min-size-<datasource>
Env: KC_DB_POOL_MIN_SIZE_<DATASOURCE>

 

db-schema-<datasource>

Used for named <datasource>.

The database schema to be used.

CLI: --db-schema-<datasource>
Env: KC_DB_SCHEMA_<DATASOURCE>

 

db-url-database-<datasource>

Used for named <datasource>.

Sets the database name of the default JDBC URL of the chosen vendor. If the db-url option is set, this option is ignored.

CLI: --db-url-database-<datasource>
Env: KC_DB_URL_DATABASE_<DATASOURCE>

 

db-url-full-<datasource>

Used for named <datasource>.

The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor. For instance, if using postgres, the default JDBC URL would be jdbc:postgresql://localhost/keycloak.

CLI: --db-url-full-<datasource>
Env: KC_DB_URL_FULL_<DATASOURCE>

 

db-url-host-<datasource>

Used for named <datasource>.

Sets the hostname of the default JDBC URL of the chosen vendor. If the db-url option is set, this option is ignored.

CLI: --db-url-host-<datasource>
Env: KC_DB_URL_HOST_<DATASOURCE>

 

db-url-port-<datasource>

Used for named <datasource>.

Sets the port of the default JDBC URL of the chosen vendor. If the db-url option is set, this option is ignored.

CLI: --db-url-port-<datasource>
Env: KC_DB_URL_PORT_<DATASOURCE>

 

db-url-properties-<datasource>

Used for named <datasource>.

Sets the properties of the default JDBC URL of the chosen vendor. Make sure to set the properties accordingly to the format expected by the database vendor, as well as appending the right character at the beginning of this property value. If the db-url option is set, this option is ignored.

CLI: --db-url-properties-<datasource>
Env: KC_DB_URL_PROPERTIES_<DATASOURCE>

 

db-username-<datasource>

Used for named <datasource>.

The username of the database user.

CLI: --db-username-<datasource>
Env: KC_DB_USERNAME_<DATASOURCE>

 

21.5. Transaction
Copy link

Expand
 Value

transaction-xa-enabled 🛠

If set to true, XA datasources will be used.

Named key: transaction-xa-enabled-<datasource> 🛠

CLI: --transaction-xa-enabled
Env: KC_TRANSACTION_XA_ENABLED

true, false (default)

transaction-xa-enabled-<datasource> 🛠

If set to true, XA for <datasource> datasource will be used.

CLI: --transaction-xa-enabled-<datasource>
Env: KC_TRANSACTION_XA_ENABLED_<DATASOURCE>

true (default), false

21.6. Feature
Copy link

Expand
 Value

features 🛠

Enables a set of one or more features.

CLI: --features
Env: KC_FEATURES

account-api[:v1], account[:v3], admin-api[:v1], admin-fine-grained-authz[:v1,v2], admin[:v2], authorization[:v1], ciba[:v1], client-auth-federated[:v1], client-policies[:v1], client-secret-rotation[:v1], client-types[:v1], clusterless[:v1], db-tidb[:v1], declarative-ui[:v1], device-flow[:v1], docker[:v1], dpop[:v1], dynamic-scopes[:v1], fips[:v1], hostname[:v2], impersonation[:v1], instagram-broker[:v1], ipa-tuura-federation[:v1], kerberos[:v1], kubernetes-service-accounts[:v1], log-mdc[:v1], login[:v2,v1], logout-all-sessions[:v1], multi-site[:v1], oid4vc-vci[:v1], opentelemetry[:v1], organization[:v1], par[:v1], passkeys-conditional-ui-authenticator[:v1], passkeys[:v1], persistent-user-sessions[:v1], preview, quick-theme[:v1], recovery-codes[:v1], rolling-updates[:v1,v2], scripts[:v1], spiffe[:v1], step-up-authentication[:v1], token-exchange-external-internal[:v2], token-exchange-standard[:v2], token-exchange[:v1], transient-users[:v1], update-email[:v1], user-event-metrics[:v1], web-authn[:v1], workflows[:v1]

features-disabled 🛠

Disables a set of one or more features.

CLI: --features-disabled
Env: KC_FEATURES_DISABLED

account, account-api, admin, admin-api, admin-fine-grained-authz, authorization, ciba, client-auth-federated, client-policies, client-secret-rotation, client-types, clusterless, db-tidb, declarative-ui, device-flow, docker, dpop, dynamic-scopes, fips, impersonation, instagram-broker, ipa-tuura-federation, kerberos, kubernetes-service-accounts, log-mdc, login, logout-all-sessions, multi-site, oid4vc-vci, opentelemetry, organization, par, passkeys, passkeys-conditional-ui-authenticator, persistent-user-sessions, preview, quick-theme, recovery-codes, rolling-updates, scripts, spiffe, step-up-authentication, token-exchange, token-exchange-external-internal, token-exchange-standard, transient-users, update-email, user-event-metrics, web-authn, workflows

21.7. Hostname v2
Copy link

Expand
 Value

hostname

Address at which is the server exposed.

Can be a full URL, or just a hostname. When only hostname is provided, scheme, port and context path are resolved from the request.

CLI: --hostname
Env: KC_HOSTNAME

Available only when hostname:v2 feature is enabled

 

hostname-admin

Address for accessing the administration console.

Use this option if you are exposing the administration console using a reverse proxy on a different address than specified in the hostname option.

CLI: --hostname-admin
Env: KC_HOSTNAME_ADMIN

Available only when hostname:v2 feature is enabled

 

hostname-backchannel-dynamic

Enables dynamic resolving of backchannel URLs, including hostname, scheme, port and context path.

Set to true if your application accesses Keycloak via a private network. If set to true, hostname option needs to be specified as a full URL.

CLI: --hostname-backchannel-dynamic
Env: KC_HOSTNAME_BACKCHANNEL_DYNAMIC

Available only when hostname:v2 feature is enabled

true, false (default)

hostname-debug

Toggles the hostname debug page that is accessible at /realms/master/hostname-debug.

CLI: --hostname-debug
Env: KC_HOSTNAME_DEBUG

Available only when hostname:v2 feature is enabled

true, false (default)

hostname-strict

Disables dynamically resolving the hostname from request headers.

Should always be set to true in production, unless your reverse proxy overwrites the Host header. If enabled, the hostname option needs to be specified.

CLI: --hostname-strict
Env: KC_HOSTNAME_STRICT

Available only when hostname:v2 feature is enabled

true (default), false

21.8. HTTP(S)
Copy link

Expand
 Value

http-enabled

Enables the HTTP listener.

Enabled by default in development mode. Typically not enabled in production unless the server is fronted by a TLS termination proxy.

CLI: --http-enabled
Env: KC_HTTP_ENABLED

true, false (default)

http-host

The HTTP Host.

CLI: --http-host
Env: KC_HTTP_HOST

0.0.0.0 (default)

http-max-queued-requests

Maximum number of queued HTTP requests.

Use this to shed load in an overload situation. Excess requests will return a "503 Server not Available" response.

CLI: --http-max-queued-requests
Env: KC_HTTP_MAX_QUEUED_REQUESTS

 

http-metrics-histograms-enabled

Enables a histogram with default buckets for the duration of HTTP server requests.

CLI: --http-metrics-histograms-enabled
Env: KC_HTTP_METRICS_HISTOGRAMS_ENABLED

Available only when metrics are enabled

true, false (default)

http-metrics-slos

Service level objectives for HTTP server requests.

Use this instead of the default histogram, or use it in combination to add additional buckets. Specify a list of comma-separated values defined in milliseconds. Example with buckets from 5ms to 10s: 5,10,25,50,250,500,1000,2500,5000,10000

CLI: --http-metrics-slos
Env: KC_HTTP_METRICS_SLOS

Available only when metrics are enabled

 

http-pool-max-threads

The maximum number of threads.

If this is not specified then it will be automatically sized to the greater of 4 * the number of available processors and 50. For example if there are 4 processors the max threads will be 50. If there are 48 processors it will be 192.

CLI: --http-pool-max-threads
Env: KC_HTTP_POOL_MAX_THREADS

 

http-port

The used HTTP port.

CLI: --http-port
Env: KC_HTTP_PORT

8080 (default)

http-relative-path 🛠

Set the path relative to / for serving resources.

The path must start with a /.

CLI: --http-relative-path
Env: KC_HTTP_RELATIVE_PATH

/ (default)

https-certificate-file

The file path to a server certificate or certificate chain in PEM format.

CLI: --https-certificate-file
Env: KC_HTTPS_CERTIFICATE_FILE

 

https-certificate-key-file

The file path to a private key in PEM format.

CLI: --https-certificate-key-file
Env: KC_HTTPS_CERTIFICATE_KEY_FILE

 

https-certificates-reload-period

Interval on which to reload key store, trust store, and certificate files referenced by https-* options.

May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable.

CLI: --https-certificates-reload-period
Env: KC_HTTPS_CERTIFICATES_RELOAD_PERIOD

1h (default)

https-cipher-suites

The cipher suites to use.

If none is given, a reasonable default is selected.

CLI: --https-cipher-suites
Env: KC_HTTPS_CIPHER_SUITES

 

https-client-auth 🛠

Configures the server to require/request client authentication.

CLI: --https-client-auth
Env: KC_HTTPS_CLIENT_AUTH

none (default), request, required

https-key-store-file

The key store which holds the certificate information instead of specifying separate files.

CLI: --https-key-store-file
Env: KC_HTTPS_KEY_STORE_FILE

 

https-key-store-password

The password of the key store file.

CLI: --https-key-store-password
Env: KC_HTTPS_KEY_STORE_PASSWORD

password (default)

https-key-store-type

The type of the key store file.

If not given, the type is automatically detected based on the file extension. If fips-mode is set to strict and no value is set, it defaults to BCFKS.

CLI: --https-key-store-type
Env: KC_HTTPS_KEY_STORE_TYPE

 

https-port

The used HTTPS port.

CLI: --https-port
Env: KC_HTTPS_PORT

8443 (default)

https-protocols

The list of protocols to explicitly enable.

If a value is not supported by the JRE / security configuration, it will be silently ignored.

CLI: --https-protocols
Env: KC_HTTPS_PROTOCOLS

TLSv1.3, TLSv1.2, or any

https-trust-store-file

The trust store which holds the certificate information of the certificates to trust.

CLI: --https-trust-store-file
Env: KC_HTTPS_TRUST_STORE_FILE

 

https-trust-store-password

The password of the trust store file.

CLI: --https-trust-store-password
Env: KC_HTTPS_TRUST_STORE_PASSWORD

 

https-trust-store-type

The type of the trust store file.

If not given, the type is automatically detected based on the file extension. If fips-mode is set to strict and no value is set, it defaults to BCFKS.

CLI: --https-trust-store-type
Env: KC_HTTPS_TRUST_STORE_TYPE

 

21.9. HTTP Access log
Copy link

Expand
 Value

http-access-log-enabled

If HTTP access logging is enabled.

By default this will log records in console.

CLI: --http-access-log-enabled
Env: KC_HTTP_ACCESS_LOG_ENABLED

true, false (default)

http-access-log-exclude

A regular expression that can be used to exclude some paths from logging.

For instance, /realms/my-realm/.* will exclude all subsequent endpoints for realm my-realm from the log.

CLI: --http-access-log-exclude
Env: KC_HTTP_ACCESS_LOG_EXCLUDE

Available only when HTTP Access log is enabled

 

http-access-log-pattern

The HTTP access log pattern.

You can use the available named formats, or use custom format described in Quarkus documentation.

CLI: --http-access-log-pattern
Env: KC_HTTP_ACCESS_LOG_PATTERN

Available only when HTTP Access log is enabled

common (default), combined, long, or any

21.10. Health
Copy link

Expand
 Value

health-enabled 🛠

If the server should expose health check endpoints.

If enabled, health checks are available at the /health, /health/ready and /health/live endpoints.

CLI: --health-enabled
Env: KC_HEALTH_ENABLED

true, false (default)

21.11. Management
Copy link

Expand
 Value

http-management-health-enabled 🛠

If health endpoints should be exposed on the management interface.

If false, health endpoints will be exposed on the main interface.

CLI: --http-management-health-enabled
Env: KC_HTTP_MANAGEMENT_HEALTH_ENABLED

Available only when health is enabled

true (default), false

http-management-port

Port of the management interface.

Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --http-management-port
Env: KC_HTTP_MANAGEMENT_PORT

9000 (default)

http-management-relative-path 🛠

Set the path relative to / for serving resources from management interface.

The path must start with a /. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --http-management-relative-path
Env: KC_HTTP_MANAGEMENT_RELATIVE_PATH

/ (default)

http-management-scheme

Configures the management interface scheme.

If inherited, the management interface will inherit the HTTPS settings of the main interface. If http, the management interface will be accessible via HTTP - it will not inherit HTTPS settings and cannot be configured for HTTPS.

CLI: --http-management-scheme
Env: KC_HTTP_MANAGEMENT_SCHEME

http, inherited (default)

https-management-certificate-file

The file path to a server certificate or certificate chain in PEM format for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificate-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_FILE

Available only when http-management-scheme is inherited

 

https-management-certificate-key-file

The file path to a private key in PEM format for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificate-key-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_KEY_FILE

Available only when http-management-scheme is inherited

 

https-management-certificates-reload-period

Interval on which to reload key store, trust store, and certificate files referenced by https-management-* options for the management server.

May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-certificates-reload-period
Env: KC_HTTPS_MANAGEMENT_CERTIFICATES_RELOAD_PERIOD

Available only when http-management-scheme is inherited

1h (default)

https-management-client-auth 🛠

Configures the management interface to require/request client authentication.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-client-auth
Env: KC_HTTPS_MANAGEMENT_CLIENT_AUTH

none (default), request, required

https-management-key-store-file

The key store which holds the certificate information instead of specifying separate files for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-key-store-file
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_FILE

Available only when http-management-scheme is inherited

 

https-management-key-store-password

The password of the key store file for the management server.

If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --https-management-key-store-password
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_PASSWORD

Available only when http-management-scheme is inherited

password (default)

legacy-observability-interface 🛠

If metrics/health endpoints should be exposed on the main HTTP server (not recommended).

If set to true, the management interface is disabled.

CLI: --legacy-observability-interface
Env: KC_LEGACY_OBSERVABILITY_INTERFACE

DEPRECATED.

true, false (default)

21.12. Metrics
Copy link

Expand
 Value

metrics-enabled 🛠

If the server should expose metrics.

If enabled, metrics are available at the /metrics endpoint.

CLI: --metrics-enabled
Env: KC_METRICS_ENABLED

true, false (default)

21.13. Proxy
Copy link

Expand
 Value

proxy-headers

The proxy headers that should be accepted by the server.

Misconfiguration might leave the server exposed to security vulnerabilities. Takes precedence over the deprecated proxy option.

CLI: --proxy-headers
Env: KC_PROXY_HEADERS

forwarded, xforwarded

proxy-protocol-enabled

Whether the server should use the HA PROXY protocol when serving requests from behind a proxy.

When set to true, the remote address returned will be the one from the actual connecting client. Cannot be enabled when the proxy-headers is used.

CLI: --proxy-protocol-enabled
Env: KC_PROXY_PROTOCOL_ENABLED

true, false (default)

proxy-trusted-addresses

A comma separated list of trusted proxy addresses.

If set, then proxy headers from other addresses will be ignored. By default all addresses are trusted. A trusted proxy address is specified as an IP address (IPv4 or IPv6) or Classless Inter-Domain Routing (CIDR) notation. Available only when proxy-headers is set.

CLI: --proxy-trusted-addresses
Env: KC_PROXY_TRUSTED_ADDRESSES

 

21.14. Vault
Copy link

Expand
 Value

vault 🛠

Enables a vault provider.

CLI: --vault
Env: KC_VAULT

file, keystore

vault-dir

If set, secrets can be obtained by reading the content of files within the given directory.

CLI: --vault-dir
Env: KC_VAULT_DIR

 

vault-file

Path to the keystore file.

CLI: --vault-file
Env: KC_VAULT_FILE

 

vault-pass

Password for the vault keystore.

CLI: --vault-pass
Env: KC_VAULT_PASS

 

vault-type

Specifies the type of the keystore file.

CLI: --vault-type
Env: KC_VAULT_TYPE

PKCS12 (default)

21.15. Logging
Copy link

Expand
 Value

log

Enable one or more log handlers in a comma-separated list.

CLI: --log
Env: KC_LOG

console, file, syslog

log-async

Indicates whether to log asynchronously to all handlers.

CLI: --log-async
Env: KC_LOG_ASYNC

true, false (default)

log-console-async

Indicates whether to log asynchronously to console.

If not set, value from the parent property log-async is used.

CLI: --log-console-async
Env: KC_LOG_CONSOLE_ASYNC

Available only when Console log handler is activated

true, false (default)

log-console-async-queue-length

The queue length to use before flushing writing when logging to console.

CLI: --log-console-async-queue-length
Env: KC_LOG_CONSOLE_ASYNC_QUEUE_LENGTH

Available only when Console log handler is activated and asynchronous logging is enabled

512 (default)

log-console-color

Enable or disable colors when logging to console.

CLI: --log-console-color
Env: KC_LOG_CONSOLE_COLOR

Available only when Console log handler is activated

true, false (default)

log-console-format

The format of unstructured console log entries.

If the format has spaces in it, escape the value using "<format>".

CLI: --log-console-format
Env: KC_LOG_CONSOLE_FORMAT

Available only when Console log handler is activated

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n (default)

log-console-include-mdc

Include mdc information in the console log.

If the log-console-format option is specified, this option has no effect.

CLI: --log-console-include-mdc
Env: KC_LOG_CONSOLE_INCLUDE_MDC

Available only when Console log handler and MDC logging are activated

true (default), false

log-console-include-trace

Include tracing information in the console log.

If the log-console-format option is specified, this option has no effect.

CLI: --log-console-include-trace
Env: KC_LOG_CONSOLE_INCLUDE_TRACE

Available only when Console log handler and Tracing is activated

true (default), false

log-console-json-format

Set the format of the produced JSON.

CLI: --log-console-json-format
Env: KC_LOG_CONSOLE_JSON_FORMAT

Available only when Console log handler is activated and output is set to 'json'

default (default), ecs

log-console-level

Set the log level for the console handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-console-level
Env: KC_LOG_CONSOLE_LEVEL

Available only when Console log handler is activated

off, fatal, error, warn, info, debug, trace, all (default)

log-console-output

Set the log output to JSON or default (plain) unstructured logging.

CLI: --log-console-output
Env: KC_LOG_CONSOLE_OUTPUT

Available only when Console log handler is activated

default (default), json

log-file

Set the log file path and filename.

CLI: --log-file
Env: KC_LOG_FILE

Available only when File log handler is activated

data/log/keycloak.log (default)

log-file-async

Indicates whether to log asynchronously to file log.

If not set, value from the parent property log-async is used.

CLI: --log-file-async
Env: KC_LOG_FILE_ASYNC

Available only when File log handler is activated

true, false (default)

log-file-async-queue-length

The queue length to use before flushing writing when logging to file log.

CLI: --log-file-async-queue-length
Env: KC_LOG_FILE_ASYNC_QUEUE_LENGTH

Available only when File log handler is activated and asynchronous logging is enabled

512 (default)

log-file-format

Set a format specific to file log entries.

CLI: --log-file-format
Env: KC_LOG_FILE_FORMAT

Available only when File log handler is activated

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n (default)

log-file-include-mdc

Include MDC information in the file log.

If the log-file-format option is specified, this option has no effect.

CLI: --log-file-include-mdc
Env: KC_LOG_FILE_INCLUDE_MDC

Available only when File log handler and MDC logging are activated

true (default), false

log-file-include-trace

Include tracing information in the file log.

If the log-file-format option is specified, this option has no effect.

CLI: --log-file-include-trace
Env: KC_LOG_FILE_INCLUDE_TRACE

Available only when File log handler and Tracing is activated

true (default), false

log-file-json-format

Set the format of the produced JSON.

CLI: --log-file-json-format
Env: KC_LOG_FILE_JSON_FORMAT

Available only when File log handler is activated and output is set to 'json'

default (default), ecs

log-file-level

Set the log level for the file handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-file-level
Env: KC_LOG_FILE_LEVEL

Available only when File log handler is activated

off, fatal, error, warn, info, debug, trace, all (default)

log-file-output

Set the log output to JSON or default (plain) unstructured logging.

CLI: --log-file-output
Env: KC_LOG_FILE_OUTPUT

Available only when File log handler is activated

default (default), json

log-level

The log level of the root category or a comma-separated list of individual categories and their levels.

For the root category, you don’t need to specify a category.

CLI: --log-level
Env: KC_LOG_LEVEL

[info] (default)

log-level-<category>

The log level of a category.

Takes precedence over the log-level option.

CLI: --log-level-<category>
Env: KC_LOG_LEVEL_<CATEGORY>

off, fatal, error, warn, info, debug, trace, all

log-mdc-enabled 🛠

Indicates whether to add information about the realm and other information to the mapped diagnostic context.

All elements will be prefixed with kc.

CLI: --log-mdc-enabled
Env: KC_LOG_MDC_ENABLED

Available only when log-mdc preview feature is enabled

true, false (default)

log-mdc-keys

Defines which information should be added to the mapped diagnostic context as a comma-separated list.

CLI: --log-mdc-keys
Env: KC_LOG_MDC_KEYS

Available only when MDC logging is enabled

realmName, clientId, userId, ipAddress, org, sessionId, authenticationSessionId, authenticationTabId

log-syslog-app-name

Set the app name used when formatting the message in RFC5424 format.

CLI: --log-syslog-app-name
Env: KC_LOG_SYSLOG_APP_NAME

Available only when Syslog is activated

keycloak (default)

log-syslog-async

Indicates whether to log asynchronously to Syslog.

If not set, value from the parent property log-async is used.

CLI: --log-syslog-async
Env: KC_LOG_SYSLOG_ASYNC

Available only when Syslog is activated

true, false (default)

log-syslog-async-queue-length

The queue length to use before flushing writing when logging to Syslog.

CLI: --log-syslog-async-queue-length
Env: KC_LOG_SYSLOG_ASYNC_QUEUE_LENGTH

Available only when Syslog is activated and asynchronous logging is enabled

512 (default)

log-syslog-counting-framing

If true, the message being sent is prefixed with the size of the message.

If protocol-dependent, the default value is true when log-syslog-protocol is tcp or ssl-tcp, otherwise false.

CLI: --log-syslog-counting-framing
Env: KC_LOG_SYSLOG_COUNTING_FRAMING

Available only when Syslog is activated

true, false, protocol-dependent (default)

log-syslog-endpoint

Set the IP address and port of the Syslog server.

CLI: --log-syslog-endpoint
Env: KC_LOG_SYSLOG_ENDPOINT

Available only when Syslog is activated

localhost:514 (default)

log-syslog-format

Set a format specific to Syslog entries.

CLI: --log-syslog-format
Env: KC_LOG_SYSLOG_FORMAT

Available only when Syslog is activated

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n (default)

log-syslog-include-mdc

Include MDC information in the Syslog.

If the log-syslog-format option is specified, this option has no effect.

CLI: --log-syslog-include-mdc
Env: KC_LOG_SYSLOG_INCLUDE_MDC

Available only when Syslog handler and MDC logging are activated

true (default), false

log-syslog-include-trace

Include tracing information in the Syslog.

If the log-syslog-format option is specified, this option has no effect.

CLI: --log-syslog-include-trace
Env: KC_LOG_SYSLOG_INCLUDE_TRACE

Available only when Syslog handler and Tracing is activated

true (default), false

log-syslog-json-format

Set the format of the produced JSON.

CLI: --log-syslog-json-format
Env: KC_LOG_SYSLOG_JSON_FORMAT

Available only when Syslog is activated and output is set to 'json'

default (default), ecs

log-syslog-level

Set the log level for the Syslog handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-syslog-level
Env: KC_LOG_SYSLOG_LEVEL

Available only when Syslog is activated

off, fatal, error, warn, info, debug, trace, all (default)

log-syslog-max-length

Set the maximum length, in bytes, of the message allowed to be sent.

The length includes the header and the message. If not set, the default value is 2048 when log-syslog-type is rfc5424 (default) and 1024 when log-syslog-type is rfc3164.

CLI: --log-syslog-max-length
Env: KC_LOG_SYSLOG_MAX_LENGTH

Available only when Syslog is activated

 

log-syslog-output

Set the Syslog output to JSON or default (plain) unstructured logging.

CLI: --log-syslog-output
Env: KC_LOG_SYSLOG_OUTPUT

Available only when Syslog is activated

default (default), json

log-syslog-protocol

Set the protocol used to connect to the Syslog server.

CLI: --log-syslog-protocol
Env: KC_LOG_SYSLOG_PROTOCOL

Available only when Syslog is activated

tcp (default), udp, ssl-tcp

log-syslog-type

Set the Syslog type used to format the sent message.

CLI: --log-syslog-type
Env: KC_LOG_SYSLOG_TYPE

Available only when Syslog is activated

rfc5424 (default), rfc3164

21.16. Tracing
Copy link

Expand
 Value

tracing-compression

OpenTelemetry compression method used to compress payloads.

If unset, compression is disabled.

CLI: --tracing-compression
Env: KC_TRACING_COMPRESSION

Available only when Tracing is enabled

gzip, none (default)

tracing-enabled 🛠

Enables the OpenTelemetry tracing.

CLI: --tracing-enabled
Env: KC_TRACING_ENABLED

Available only when 'opentelemetry' feature is enabled

true, false (default)

tracing-endpoint

OpenTelemetry endpoint to connect to.

CLI: --tracing-endpoint
Env: KC_TRACING_ENDPOINT

Available only when Tracing is enabled

http://localhost:4317 (default)

tracing-infinispan-enabled

Enables the OpenTelemetry tracing for embedded Infinispan.

CLI: --tracing-infinispan-enabled
Env: KC_TRACING_INFINISPAN_ENABLED

Available only when tracing and embedded Infinispan is enabled

true (default), false

tracing-jdbc-enabled 🛠

Enables the OpenTelemetry JDBC tracing.

CLI: --tracing-jdbc-enabled
Env: KC_TRACING_JDBC_ENABLED

Available only when Tracing is enabled

true (default), false

tracing-protocol

OpenTelemetry protocol used for the telemetry data.

CLI: --tracing-protocol
Env: KC_TRACING_PROTOCOL

Available only when Tracing is enabled

grpc (default), http/protobuf

tracing-resource-attributes

OpenTelemetry resource attributes present in the exported trace to characterize the telemetry producer.

Values in format key1=val1,key2=val2. For more information, check the Tracing guide.

CLI: --tracing-resource-attributes
Env: KC_TRACING_RESOURCE_ATTRIBUTES

Available only when Tracing is enabled

 

tracing-sampler-ratio

OpenTelemetry sampler ratio.

Probability that a span will be sampled. Expected double value in interval [0,1].

CLI: --tracing-sampler-ratio
Env: KC_TRACING_SAMPLER_RATIO

Available only when Tracing is enabled

1.0 (default)

tracing-sampler-type 🛠

OpenTelemetry sampler to use for tracing.

CLI: --tracing-sampler-type
Env: KC_TRACING_SAMPLER_TYPE

Available only when Tracing is enabled

always_on, always_off, traceidratio (default), parentbased_always_on, parentbased_always_off, parentbased_traceidratio

tracing-service-name

OpenTelemetry service name.

Takes precedence over service.name defined in the tracing-resource-attributes property.

CLI: --tracing-service-name
Env: KC_TRACING_SERVICE_NAME

Available only when Tracing is enabled

keycloak (default)

21.17. Events
Copy link

Expand
 Value

event-metrics-user-enabled 🛠

Create metrics based on user events.

CLI: --event-metrics-user-enabled
Env: KC_EVENT_METRICS_USER_ENABLED

Available only when metrics are enabled and feature user-event-metrics is enabled

true, false (default)

event-metrics-user-events

Comma-separated list of events to be collected for user event metrics.

This option can be used to reduce the number of metrics created as by default all user events create a metric.

CLI: --event-metrics-user-events
Env: KC_EVENT_METRICS_USER_EVENTS

Available only when user event metrics are enabled

Use remove_credential instead of remove_totp, and update_credential instead of update_totp and update_password. Deprecated values: remove_totp, update_totp, update_password

authreqid_to_token, client_delete, client_info, client_initiated_account_linking, client_login, client_register, client_update, code_to_token, custom_required_action, delete_account, execute_action_token, execute_actions, federated_identity_link, federated_identity_override_link, grant_consent, identity_provider_first_login, identity_provider_link_account, identity_provider_login, identity_provider_post_login, identity_provider_response, identity_provider_retrieve_token, impersonate, introspect_token, invalid_signature, invite_org, login, logout, oauth2_device_auth, oauth2_device_code_to_token, oauth2_device_verify_user_code, oauth2_extension_grant, permission_token, pushed_authorization_request, refresh_token, register, register_node, remove_credential, remove_federated_identity, remove_totp (deprecated), reset_password, restart_authentication, revoke_grant, send_identity_provider_link, send_reset_password, send_verify_email, token_exchange, unregister_node, update_consent, update_credential, update_email, update_password (deprecated), update_profile, update_totp (deprecated), user_disabled_by_permanent_lockout, user_disabled_by_temporary_lockout, user_info_request, verify_email, verify_profile

event-metrics-user-tags

Comma-separated list of tags to be collected for user event metrics.

By default only realm is enabled to avoid a high metrics cardinality.

CLI: --event-metrics-user-tags
Env: KC_EVENT_METRICS_USER_TAGS

Available only when user event metrics are enabled

realm, idp, clientId

21.18. Truststore
Copy link

Expand
 Value

tls-hostname-verifier

The TLS hostname verification policy for out-going HTTPS and SMTP requests.

ANY should not be used in production.

CLI: --tls-hostname-verifier
Env: KC_TLS_HOSTNAME_VERIFIER

STRICT and WILDCARD have been deprecated, use DEFAULT instead. Deprecated values: STRICT, WILDCARD

ANY, WILDCARD (deprecated), STRICT (deprecated), DEFAULT (default)

truststore-paths

List of pkcs12 (p12, pfx, or pkcs12 file extensions), PEM files, or directories containing those files that will be used as a system truststore.

CLI: --truststore-paths
Env: KC_TRUSTSTORE_PATHS

 

21.19. Security
Copy link

Expand
 Value

fips-mode 🛠

Sets the FIPS mode.

If non-strict is set, FIPS is enabled but on non-approved mode. For full FIPS compliance, set strict to run on approved mode. This option defaults to disabled when fips feature is disabled, which is by default. This option defaults to non-strict when fips feature is enabled.

CLI: --fips-mode
Env: KC_FIPS_MODE

non-strict, strict

21.20. Export
Copy link

Expand
 Value

dir

Set the path to a directory where files will be created with the exported data.

CLI: --dir
Env: KC_DIR

 

file

Set the path to a file that will be created with the exported data.

To export more than 50000 users, export to a directory with different files instead.

CLI: --file
Env: KC_FILE

 

realm

Set the name of the realm to export.

If not set, all realms are going to be exported.

CLI: --realm
Env: KC_REALM

 

users

Set how users should be exported.

CLI: --users
Env: KC_USERS

skip, realm_file, same_file, different_files (default)

users-per-file

Set the number of users per file.

It is used only if users is set to different_files.

CLI: --users-per-file
Env: KC_USERS_PER_FILE

50 (default)

21.21. Import
Copy link

Expand
 Value

dir

Set the path to a directory where files will be read from.

CLI: --dir
Env: KC_DIR

 

file

Set the path to a file that will be read.

CLI: --file
Env: KC_FILE

 

override

Set if existing data should be overwritten.

If set to false, data will be ignored.

CLI: --override
Env: KC_OVERRIDE

true (default), false

21.22. Bootstrap Admin
Copy link

Expand
 Value

bootstrap-admin-client-id

Client id for the temporary bootstrap admin service account.

Used only when the master realm is created. Available only when bootstrap admin client secret is set.

CLI: --bootstrap-admin-client-id
Env: KC_BOOTSTRAP_ADMIN_CLIENT_ID

temp-admin (default)

bootstrap-admin-client-secret

Client secret for the temporary bootstrap admin service account.

Used only when the master realm is created. Use a non-CLI configuration option for this option if possible.

CLI: --bootstrap-admin-client-secret
Env: KC_BOOTSTRAP_ADMIN_CLIENT_SECRET

 

bootstrap-admin-password

Temporary bootstrap admin password.

Used only when the master realm is created. Use a non-CLI configuration option for this option if possible.

CLI: --bootstrap-admin-password
Env: KC_BOOTSTRAP_ADMIN_PASSWORD

 

bootstrap-admin-username

Temporary bootstrap admin username.

Used only when the master realm is created. Available only when bootstrap admin password is set.

CLI: --bootstrap-admin-username
Env: KC_BOOTSTRAP_ADMIN_USERNAME

temp-admin (default)

Chapter 22. All provider configuration
Copy link

Review provider configuration options.

22.1. authentication-sessions
Copy link

22.1.1. infinispan
Copy link

Expand
 Value

spi-authentication-sessions--infinispan--auth-sessions-limit

The maximum number of concurrent authentication sessions per RootAuthenticationSession.

CLI: --spi-authentication-sessions--infinispan--auth-sessions-limit
Env: KC_SPI_AUTHENTICATION_SESSIONS__INFINISPAN__AUTH_SESSIONS_LIMIT

300 (default) or any int

22.1.2. remote
Copy link

Expand
 Value

spi-authentication-sessions--remote--auth-sessions-limit

The maximum number of concurrent authentication sessions per RootAuthenticationSession.

CLI: --spi-authentication-sessions--remote--auth-sessions-limit
Env: KC_SPI_AUTHENTICATION_SESSIONS__REMOTE__AUTH_SESSIONS_LIMIT

300 (default) or any int

spi-authentication-sessions--remote--max-retries

The maximum number of retries if an error occurs.

A value of zero or less disable any retries.

CLI: --spi-authentication-sessions--remote--max-retries
Env: KC_SPI_AUTHENTICATION_SESSIONS__REMOTE__MAX_RETRIES

10 (default) or any int

spi-authentication-sessions--remote--retry-base-time

The base back-off time in milliseconds.

CLI: --spi-authentication-sessions--remote--retry-base-time
Env: KC_SPI_AUTHENTICATION_SESSIONS__REMOTE__RETRY_BASE_TIME

10 (default) or any int

22.2. brute-force-protector
Copy link

22.2.1. default-brute-force-detector
Copy link

Expand
 Value

spi-brute-force-protector--default-brute-force-detector--allow-concurrent-requests

If concurrent logins are allowed by the brute force protection.

CLI: --spi-brute-force-protector--default-brute-force-detector--allow-concurrent-requests
Env: KC_SPI_BRUTE_FORCE_PROTECTOR__DEFAULT_BRUTE_FORCE_DETECTOR__ALLOW_CONCURRENT_REQUESTS

true, false (default)

22.3. cache-embedded
Copy link

22.3.1. default
Copy link

Expand
 Value

spi-cache-embedded--default--action-tokens-owners

Sets the number of owners for the actionTokens distributed cache.

It defines the number of copies of your data in the cluster.

CLI: --spi-cache-embedded--default--action-tokens-owners
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__ACTION_TOKENS_OWNERS

any Integer

spi-cache-embedded--default--authentication-sessions-owners

Sets the number of owners for the authenticationSessions distributed cache.

It defines the number of copies of your data in the cluster.

CLI: --spi-cache-embedded--default--authentication-sessions-owners
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__AUTHENTICATION_SESSIONS_OWNERS

any Integer

spi-cache-embedded--default--authorization-max-count

The maximum number of entries that can be stored in-memory by the authorization cache.

CLI: --spi-cache-embedded--default--authorization-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__AUTHORIZATION_MAX_COUNT

any Integer

spi-cache-embedded--default--authorization-revisions-max-count

The maximum number of entries that can be stored in-memory by the authorizationRevisions cache.

CLI: --spi-cache-embedded--default--authorization-revisions-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__AUTHORIZATION_REVISIONS_MAX_COUNT

any Integer

spi-cache-embedded--default--client-sessions-max-count

The maximum number of entries that can be stored in-memory by the clientSessions cache.

CLI: --spi-cache-embedded--default--client-sessions-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__CLIENT_SESSIONS_MAX_COUNT

any Integer

spi-cache-embedded--default--client-sessions-owners

Sets the number of owners for the clientSessions distributed cache.

It defines the number of copies of your data in the cluster.

CLI: --spi-cache-embedded--default--client-sessions-owners
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__CLIENT_SESSIONS_OWNERS

any Integer

spi-cache-embedded--default--config-file

Defines the file from which cache configuration should be loaded from.

The configuration file is relative to the conf/ directory.

CLI: --spi-cache-embedded--default--config-file
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__CONFIG_FILE

any String

spi-cache-embedded--default--crl-max-count

The maximum number of entries that can be stored in-memory by the crl cache.

CLI: --spi-cache-embedded--default--crl-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__CRL_MAX_COUNT

any Integer

spi-cache-embedded--default--keys-max-count

The maximum number of entries that can be stored in-memory by the keys cache.

CLI: --spi-cache-embedded--default--keys-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__KEYS_MAX_COUNT

any Integer

spi-cache-embedded--default--login-failures-owners

Sets the number of owners for the loginFailures distributed cache.

It defines the number of copies of your data in the cluster.

CLI: --spi-cache-embedded--default--login-failures-owners
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__LOGIN_FAILURES_OWNERS

any Integer

spi-cache-embedded--default--machine-name

The name of the physical machine where this instance runs.

It can be set if multiple Keycloak instances are running in the same physical machines. Infinispan takes into consideration this value to keep the backup data spread between different machines.

CLI: --spi-cache-embedded--default--machine-name
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__MACHINE_NAME

any String

spi-cache-embedded--default--metrics-histograms-enabled

Enable histograms for metrics for the embedded caches.

CLI: --spi-cache-embedded--default--metrics-histograms-enabled
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__METRICS_HISTOGRAMS_ENABLED

true, false (default)

spi-cache-embedded--default--network-bind-address

IP address used by clustering transport.

By default, SITE_LOCAL is used.

CLI: --spi-cache-embedded--default--network-bind-address
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__NETWORK_BIND_ADDRESS

any String

spi-cache-embedded--default--network-bind-port

The Port the clustering transport will bind to.

By default, port 7800 is used.

CLI: --spi-cache-embedded--default--network-bind-port
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__NETWORK_BIND_PORT

any Integer

spi-cache-embedded--default--network-external-address

IP address that other instances in the cluster should use to contact this node.

Set only if it is different to cache-embedded-network-bind-address, for example when this instance is behind a firewall.

CLI: --spi-cache-embedded--default--network-external-address
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__NETWORK_EXTERNAL_ADDRESS

any String

spi-cache-embedded--default--network-external-port

Port that other instances in the cluster should use to contact this node.

Set only if it is different to cache-embedded-network-bind-port, for example when this instance is behind a firewall

CLI: --spi-cache-embedded--default--network-external-port
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__NETWORK_EXTERNAL_PORT

any Integer

spi-cache-embedded--default--node-name

Sets the name of the current node.

This is a friendly name to make logs, etc. make more sense.

CLI: --spi-cache-embedded--default--node-name
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__NODE_NAME

any String

spi-cache-embedded--default--offline-client-sessions-max-count

The maximum number of entries that can be stored in-memory by the offlineClientSessions cache.

CLI: --spi-cache-embedded--default--offline-client-sessions-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__OFFLINE_CLIENT_SESSIONS_MAX_COUNT

any Integer

spi-cache-embedded--default--offline-sessions-max-count

The maximum number of entries that can be stored in-memory by the offlineSessions cache.

CLI: --spi-cache-embedded--default--offline-sessions-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__OFFLINE_SESSIONS_MAX_COUNT

any Integer

spi-cache-embedded--default--rack-name

The name of the rack where this instance runs.

It can be set if multiple Keycloak instances are running in the same physical rack. Infinispan takes into consideration this value to keep the backup data spread between different racks.

CLI: --spi-cache-embedded--default--rack-name
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__RACK_NAME

any String

spi-cache-embedded--default--realm-revisions-max-count

The maximum number of entries that can be stored in-memory by the realmRevisions cache.

CLI: --spi-cache-embedded--default--realm-revisions-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__REALM_REVISIONS_MAX_COUNT

any Integer

spi-cache-embedded--default--realms-max-count

The maximum number of entries that can be stored in-memory by the realms cache.

CLI: --spi-cache-embedded--default--realms-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__REALMS_MAX_COUNT

any Integer

spi-cache-embedded--default--sessions-max-count

The maximum number of entries that can be stored in-memory by the sessions cache.

CLI: --spi-cache-embedded--default--sessions-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__SESSIONS_MAX_COUNT

any Integer

spi-cache-embedded--default--sessions-owners

Sets the number of owners for the sessions distributed cache.

It defines the number of copies of your data in the cluster.

CLI: --spi-cache-embedded--default--sessions-owners
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__SESSIONS_OWNERS

any Integer

spi-cache-embedded--default--site-name

The name of the site (availability zone) where this instance runs.

It can be set if running Keycloak in different availability zones. Infinispan takes into consideration this value to keep the backup data spread between different sites.

CLI: --spi-cache-embedded--default--site-name
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__SITE_NAME

any String

spi-cache-embedded--default--user-revisions-max-count

The maximum number of entries that can be stored in-memory by the userRevisions cache.

CLI: --spi-cache-embedded--default--user-revisions-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__USER_REVISIONS_MAX_COUNT

any Integer

spi-cache-embedded--default--users-max-count

The maximum number of entries that can be stored in-memory by the users cache.

CLI: --spi-cache-embedded--default--users-max-count
Env: KC_SPI_CACHE_EMBEDDED__DEFAULT__USERS_MAX_COUNT

any Integer

22.4. cache-remote
Copy link

22.4.1. default
Copy link

Expand
 Value

spi-cache-remote--default--auth-realm

Specifies the Infinispan server realm to be used for authentication.

CLI: --spi-cache-remote--default--auth-realm
Env: KC_SPI_CACHE_REMOTE__DEFAULT__AUTH_REALM

default (default) or any String

spi-cache-remote--default--backup-sites

Configures a list of backup sites names to where the external Infinispan cluster backups the Keycloak data.

CLI: --spi-cache-remote--default--backup-sites
Env: KC_SPI_CACHE_REMOTE__DEFAULT__BACKUP_SITES

any List

spi-cache-remote--default--client-intelligence

Specifies the level of intelligence the Hot Rod client should have.

CLI: --spi-cache-remote--default--client-intelligence
Env: KC_SPI_CACHE_REMOTE__DEFAULT__CLIENT_INTELLIGENCE

BASIC, TOPOLOGY_AWARE, HASH_DISTRIBUTION_AWARE (default)

spi-cache-remote--default--connection-pool-exhausted-action

Specifies what happens when asking for a connection from a server’s pool, and that pool is exhausted.

CLI: --spi-cache-remote--default--connection-pool-exhausted-action
Env: KC_SPI_CACHE_REMOTE__DEFAULT__CONNECTION_POOL_EXHAUSTED_ACTION

EXCEPTION, WAIT, CREATE_NEW (default)

spi-cache-remote--default--connection-pool-max-active

Sets the maximum number of connections per Infinispan server instance.

CLI: --spi-cache-remote--default--connection-pool-max-active
Env: KC_SPI_CACHE_REMOTE__DEFAULT__CONNECTION_POOL_MAX_ACTIVE

16 (default) or any Integer

spi-cache-remote--default--hostname

The hostname of the external Infinispan cluster.

CLI: --spi-cache-remote--default--hostname
Env: KC_SPI_CACHE_REMOTE__DEFAULT__HOSTNAME

any String

spi-cache-remote--default--password

The password for the authentication to the external Infinispan cluster.

It is optional if connecting to an unsecure external Infinispan cluster. If the option is specified, cache-remote-username is required as well.

CLI: --spi-cache-remote--default--password
Env: KC_SPI_CACHE_REMOTE__DEFAULT__PASSWORD

any String

spi-cache-remote--default--port

The port of the external Infinispan cluster.

CLI: --spi-cache-remote--default--port
Env: KC_SPI_CACHE_REMOTE__DEFAULT__PORT

11222 (default) or any Integer

spi-cache-remote--default--properties-file

Path to the properties file with the Hot Rod client configuration.

CLI: --spi-cache-remote--default--properties-file
Env: KC_SPI_CACHE_REMOTE__DEFAULT__PROPERTIES_FILE

any File

spi-cache-remote--default--sasl-mechanism

Selects the SASL mechanism to use for the connection to the Infinispan server.

CLI: --spi-cache-remote--default--sasl-mechanism
Env: KC_SPI_CACHE_REMOTE__DEFAULT__SASL_MECHANISM

SCRAM-SHA-512 (default) or any String

spi-cache-remote--default--tls-enabled

Enable TLS support to communicate with a secured remote Infinispan server.

Recommended to be enabled in production.

CLI: --spi-cache-remote--default--tls-enabled
Env: KC_SPI_CACHE_REMOTE__DEFAULT__TLS_ENABLED

true (default), false

spi-cache-remote--default--tls-sni-hostname

Specifies the TLS SNI hostname for the connection to the Infinispan server.

CLI: --spi-cache-remote--default--tls-sni-hostname
Env: KC_SPI_CACHE_REMOTE__DEFAULT__TLS_SNI_HOSTNAME

any String

spi-cache-remote--default--username

The username for the authentication to the external Infinispan cluster.

It is optional if connecting to an unsecure external Infinispan cluster. If the option is specified, cache-remote-password is required as well.

CLI: --spi-cache-remote--default--username
Env: KC_SPI_CACHE_REMOTE__DEFAULT__USERNAME

any String

22.5. ciba-auth-channel
Copy link

22.5.1. ciba-http-auth-channel
Copy link

Expand
 Value

spi-ciba-auth-channel--ciba-http-auth-channel--http-authentication-channel-uri

The HTTP(S) URI of the authentication channel.

CLI: --spi-ciba-auth-channel--ciba-http-auth-channel--http-authentication-channel-uri
Env: KC_SPI_CIBA_AUTH_CHANNEL__CIBA_HTTP_AUTH_CHANNEL__HTTP_AUTHENTICATION_CHANNEL_URI

any string

22.6. connections-http-client
Copy link

22.6.1. default
Copy link

Expand
 Value

spi-connections-http-client--default--client-key-password

The key password.

CLI: --spi-connections-http-client--default--client-key-password
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__CLIENT_KEY_PASSWORD

-1 (default) or any string

spi-connections-http-client--default--client-keystore

The file path of the key store from where the key material is going to be read from to set-up TLS connections.

CLI: --spi-connections-http-client--default--client-keystore
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__CLIENT_KEYSTORE

any string

spi-connections-http-client--default--client-keystore-password

The key store password.

CLI: --spi-connections-http-client--default--client-keystore-password
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__CLIENT_KEYSTORE_PASSWORD

any string

spi-connections-http-client--default--connection-pool-size

Assigns maximum total connection value.

CLI: --spi-connections-http-client--default--connection-pool-size
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__CONNECTION_POOL_SIZE

any int

spi-connections-http-client--default--connection-ttl-millis

Sets maximum time, in milliseconds, to live for persistent connections.

CLI: --spi-connections-http-client--default--connection-ttl-millis
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__CONNECTION_TTL_MILLIS

-1 (default) or any long

spi-connections-http-client--default--disable-cookies

Disables state (cookie) management.

CLI: --spi-connections-http-client--default--disable-cookies
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__DISABLE_COOKIES

true (default), false

spi-connections-http-client--default--disable-trust-manager

Disable trust management and hostname verification.

NOTE this is a security hole, so only set this option if you cannot or do not want to verify the identity of the host you are communicating with.

CLI: --spi-connections-http-client--default--disable-trust-manager
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__DISABLE_TRUST_MANAGER

true, false (default)

spi-connections-http-client--default--establish-connection-timeout-millis

When trying to make an initial socket connection, what is the timeout?

CLI: --spi-connections-http-client--default--establish-connection-timeout-millis
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__ESTABLISH_CONNECTION_TIMEOUT_MILLIS

-1 (default) or any long

spi-connections-http-client--default--max-connection-idle-time-millis

Sets the time, in milliseconds, for evicting idle connections from the pool.

CLI: --spi-connections-http-client--default--max-connection-idle-time-millis
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__MAX_CONNECTION_IDLE_TIME_MILLIS

900000 (default) or any long

spi-connections-http-client--default--max-consumed-response-size

Maximum size of a response consumed by the client (to prevent denial of service)

CLI: --spi-connections-http-client--default--max-consumed-response-size
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__MAX_CONSUMED_RESPONSE_SIZE

10000000 (default) or any long

spi-connections-http-client--default--max-pooled-per-route

Assigns maximum connection per route value.

CLI: --spi-connections-http-client--default--max-pooled-per-route
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__MAX_POOLED_PER_ROUTE

64 (default) or any int

spi-connections-http-client--default--proxy-mappings

Denotes the combination of a regex based hostname pattern and a proxy-uri in the form of hostnamePattern;proxyUri.

CLI: --spi-connections-http-client--default--proxy-mappings
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__PROXY_MAPPINGS

any string

spi-connections-http-client--default--reuse-connections

If connections should be reused.

CLI: --spi-connections-http-client--default--reuse-connections
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__REUSE_CONNECTIONS

true (default), false

spi-connections-http-client--default--socket-timeout-millis

Socket inactivity timeout.

CLI: --spi-connections-http-client--default--socket-timeout-millis
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__DEFAULT__SOCKET_TIMEOUT_MILLIS

5000 (default) or any long

22.6.2. opentelemetry
Copy link

Expand
 Value

spi-connections-http-client--opentelemetry--client-key-password

The key password.

CLI: --spi-connections-http-client--opentelemetry--client-key-password
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__CLIENT_KEY_PASSWORD

-1 (default) or any string

spi-connections-http-client--opentelemetry--client-keystore

The file path of the key store from where the key material is going to be read from to set-up TLS connections.

CLI: --spi-connections-http-client--opentelemetry--client-keystore
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__CLIENT_KEYSTORE

any string

spi-connections-http-client--opentelemetry--client-keystore-password

The key store password.

CLI: --spi-connections-http-client--opentelemetry--client-keystore-password
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__CLIENT_KEYSTORE_PASSWORD

any string

spi-connections-http-client--opentelemetry--connection-pool-size

Assigns maximum total connection value.

CLI: --spi-connections-http-client--opentelemetry--connection-pool-size
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__CONNECTION_POOL_SIZE

any int

spi-connections-http-client--opentelemetry--connection-ttl-millis

Sets maximum time, in milliseconds, to live for persistent connections.

CLI: --spi-connections-http-client--opentelemetry--connection-ttl-millis
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__CONNECTION_TTL_MILLIS

-1 (default) or any long

spi-connections-http-client--opentelemetry--disable-cookies

Disables state (cookie) management.

CLI: --spi-connections-http-client--opentelemetry--disable-cookies
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__DISABLE_COOKIES

true (default), false

spi-connections-http-client--opentelemetry--disable-trust-manager

Disable trust management and hostname verification.

NOTE this is a security hole, so only set this option if you cannot or do not want to verify the identity of the host you are communicating with.

CLI: --spi-connections-http-client--opentelemetry--disable-trust-manager
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__DISABLE_TRUST_MANAGER

true, false (default)

spi-connections-http-client--opentelemetry--establish-connection-timeout-millis

When trying to make an initial socket connection, what is the timeout?

CLI: --spi-connections-http-client--opentelemetry--establish-connection-timeout-millis
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__ESTABLISH_CONNECTION_TIMEOUT_MILLIS

-1 (default) or any long

spi-connections-http-client--opentelemetry--max-connection-idle-time-millis

Sets the time, in milliseconds, for evicting idle connections from the pool.

CLI: --spi-connections-http-client--opentelemetry--max-connection-idle-time-millis
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__MAX_CONNECTION_IDLE_TIME_MILLIS

900000 (default) or any long

spi-connections-http-client--opentelemetry--max-consumed-response-size

Maximum size of a response consumed by the client (to prevent denial of service)

CLI: --spi-connections-http-client--opentelemetry--max-consumed-response-size
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__MAX_CONSUMED_RESPONSE_SIZE

10000000 (default) or any long

spi-connections-http-client--opentelemetry--max-pooled-per-route

Assigns maximum connection per route value.

CLI: --spi-connections-http-client--opentelemetry--max-pooled-per-route
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__MAX_POOLED_PER_ROUTE

64 (default) or any int

spi-connections-http-client--opentelemetry--proxy-mappings

Denotes the combination of a regex based hostname pattern and a proxy-uri in the form of hostnamePattern;proxyUri.

CLI: --spi-connections-http-client--opentelemetry--proxy-mappings
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__PROXY_MAPPINGS

any string

spi-connections-http-client--opentelemetry--reuse-connections

If connections should be reused.

CLI: --spi-connections-http-client--opentelemetry--reuse-connections
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__REUSE_CONNECTIONS

true (default), false

spi-connections-http-client--opentelemetry--socket-timeout-millis

Socket inactivity timeout.

CLI: --spi-connections-http-client--opentelemetry--socket-timeout-millis
Env: KC_SPI_CONNECTIONS_HTTP_CLIENT__OPENTELEMETRY__SOCKET_TIMEOUT_MILLIS

5000 (default) or any long

22.7. connections-jpa
Copy link

22.7.1. quarkus
Copy link

Expand
 Value

spi-connections-jpa--quarkus--initialize-empty

Initialize database if empty.

If set to false the database has to be manually initialized. If you want to manually initialize the database set migrationStrategy to manual which will create a file with SQL commands to initialize the database.

CLI: --spi-connections-jpa--quarkus--initialize-empty
Env: KC_SPI_CONNECTIONS_JPA__QUARKUS__INITIALIZE_EMPTY

true (default), false

spi-connections-jpa--quarkus--migration-export

Path for where to write manual database initialization/migration file.

CLI: --spi-connections-jpa--quarkus--migration-export
Env: KC_SPI_CONNECTIONS_JPA__QUARKUS__MIGRATION_EXPORT

any string

spi-connections-jpa--quarkus--migration-strategy

Strategy to use to migrate database.

Valid values are update, manual and validate. Update will automatically migrate the database schema. Manual will export the required changes to a file with SQL commands that you can manually execute on the database. Validate will simply check if the database is up-to-date.

CLI: --spi-connections-jpa--quarkus--migration-strategy
Env: KC_SPI_CONNECTIONS_JPA__QUARKUS__MIGRATION_STRATEGY

update (default), manual, validate

22.8. credential
Copy link

22.8.1. keycloak-password
Copy link

Expand
 Value

spi-credential--keycloak-password--validations-counter-tags

Comma-separated list of tags to be used when publishing password validation counter metric.

CLI: --spi-credential--keycloak-password--validations-counter-tags
Env: KC_SPI_CREDENTIAL__KEYCLOAK_PASSWORD__VALIDATIONS_COUNTER_TAGS

realm, algorithm, hashing_strength, outcome

22.9. crl-storage
Copy link

22.9.1. infinispan
Copy link

Expand
 Value

spi-crl-storage--infinispan--cache-time

Interval in seconds that the CRL is cached.

The next update time of the CRL is always a minimum if present. Zero or a negative value means CRL is cached until the next update time specified in the CRL (or infinite if the CRL does not contain the next update).

CLI: --spi-crl-storage--infinispan--cache-time
Env: KC_SPI_CRL_STORAGE__INFINISPAN__CACHE_TIME

-1 (default) or any int

spi-crl-storage--infinispan--min-time-between-requests

Minimum interval in seconds between two requests to retrieve the CRL.

The CRL is not updated from the URL again until this minimum time has passed since the previous refresh. In theory this option is never used if the CRL is refreshed correctly in the next update time. The interval should be a positive number. Default 10 seconds.

CLI: --spi-crl-storage--infinispan--min-time-between-requests
Env: KC_SPI_CRL_STORAGE__INFINISPAN__MIN_TIME_BETWEEN_REQUESTS

10 (default) or any int

22.10. datastore
Copy link

22.10.1. legacy
Copy link

Expand
 Value

spi-datastore--legacy--allow-migrate-existing-database-to-snapshot

By default, it is not allowed to run the snapshot/development server against the database, which was previously migrated to some officially released server version.

As an attempt of doing this indicates that you are trying to run development server against production database, which can result in a loss or corruption of data, and also does not allow upgrading. If it is really intended, you can use this option, which will allow to use nightly/development server against production database when explicitly switch to true. This option is recommended just in the development environments and should be never used in the production!

CLI: --spi-datastore--legacy--allow-migrate-existing-database-to-snapshot
Env: KC_SPI_DATASTORE__LEGACY__ALLOW_MIGRATE_EXISTING_DATABASE_TO_SNAPSHOT

true, false (default)

22.11. dblock
Copy link

22.11.1. jpa
Copy link

Expand
 Value

spi-dblock--jpa--lock-wait-timeout

The maximum time to wait when waiting to release a database lock.

CLI: --spi-dblock--jpa--lock-wait-timeout
Env: KC_SPI_DBLOCK__JPA__LOCK_WAIT_TIMEOUT

any int

22.12. device-representation
Copy link

22.12.1. device-representation
Copy link

Expand
 Value

spi-device-representation--device-representation--cache-size

Sets the maximum number of parsed user-agent values in the local cache.

CLI: --spi-device-representation--device-representation--cache-size
Env: KC_SPI_DEVICE_REPRESENTATION__DEVICE_REPRESENTATION__CACHE_SIZE

2048 (default) or any Integer

22.13. events-listener
Copy link

22.13.1. email
Copy link

Expand
 Value

spi-events-listener--email--exclude-events

A comma-separated list of events that should not be sent via email to the user’s account.

CLI: --spi-events-listener--email--exclude-events
Env: KC_SPI_EVENTS_LISTENER__EMAIL__EXCLUDE_EVENTS

authreqid_to_token, authreqid_to_token_error, client_delete, client_delete_error, client_info, client_info_error, client_initiated_account_linking, client_initiated_account_linking_error, client_login, client_login_error, client_register, client_register_error, client_update, client_update_error, code_to_token, code_to_token_error, custom_required_action, custom_required_action_error, delete_account, delete_account_error, execute_action_token, execute_action_token_error, execute_actions, execute_actions_error, federated_identity_link, federated_identity_link_error, federated_identity_override_link, federated_identity_override_link_error, grant_consent, grant_consent_error, identity_provider_first_login, identity_provider_first_login_error, identity_provider_link_account, identity_provider_link_account_error, identity_provider_login, identity_provider_login_error, identity_provider_post_login, identity_provider_post_login_error, identity_provider_response, identity_provider_response_error, identity_provider_retrieve_token, identity_provider_retrieve_token_error, impersonate, impersonate_error, introspect_token, introspect_token_error, invalid_signature, invalid_signature_error, invite_org, invite_org_error, login, login_error, logout, logout_error, oauth2_device_auth, oauth2_device_auth_error, oauth2_device_code_to_token, oauth2_device_code_to_token_error, oauth2_device_verify_user_code, oauth2_device_verify_user_code_error, oauth2_extension_grant, oauth2_extension_grant_error, permission_token, permission_token_error, pushed_authorization_request, pushed_authorization_request_error, refresh_token, refresh_token_error, register, register_error, register_node, register_node_error, remove_credential, remove_credential_error, remove_federated_identity, remove_federated_identity_error, remove_totp, remove_totp_error, reset_password, reset_password_error, restart_authentication, restart_authentication_error, revoke_grant, revoke_grant_error, send_identity_provider_link, send_identity_provider_link_error, send_reset_password, send_reset_password_error, send_verify_email, send_verify_email_error, token_exchange, token_exchange_error, unregister_node, unregister_node_error, update_consent, update_consent_error, update_credential, update_credential_error, update_email, update_email_error, update_password, update_password_error, update_profile, update_profile_error, update_totp, update_totp_error, user_disabled_by_permanent_lockout, user_disabled_by_permanent_lockout_error, user_disabled_by_temporary_lockout, user_disabled_by_temporary_lockout_error, user_info_request, user_info_request_error, validate_access_token, validate_access_token_error, verify_email, verify_email_error, verify_profile, verify_profile_error

spi-events-listener--email--include-events

A comma-separated list of events that should be sent via email to the user’s account.

CLI: --spi-events-listener--email--include-events
Env: KC_SPI_EVENTS_LISTENER__EMAIL__INCLUDE_EVENTS

authreqid_to_token, authreqid_to_token_error, client_delete, client_delete_error, client_info, client_info_error, client_initiated_account_linking, client_initiated_account_linking_error, client_login, client_login_error, client_register, client_register_error, client_update, client_update_error, code_to_token, code_to_token_error, custom_required_action, custom_required_action_error, delete_account, delete_account_error, execute_action_token, execute_action_token_error, execute_actions, execute_actions_error, federated_identity_link, federated_identity_link_error, federated_identity_override_link, federated_identity_override_link_error, grant_consent, grant_consent_error, identity_provider_first_login, identity_provider_first_login_error, identity_provider_link_account, identity_provider_link_account_error, identity_provider_login, identity_provider_login_error, identity_provider_post_login, identity_provider_post_login_error, identity_provider_response, identity_provider_response_error, identity_provider_retrieve_token, identity_provider_retrieve_token_error, impersonate, impersonate_error, introspect_token, introspect_token_error, invalid_signature, invalid_signature_error, invite_org, invite_org_error, login, login_error, logout, logout_error, oauth2_device_auth, oauth2_device_auth_error, oauth2_device_code_to_token, oauth2_device_code_to_token_error, oauth2_device_verify_user_code, oauth2_device_verify_user_code_error, oauth2_extension_grant, oauth2_extension_grant_error, permission_token, permission_token_error, pushed_authorization_request, pushed_authorization_request_error, refresh_token, refresh_token_error, register, register_error, register_node, register_node_error, remove_credential, remove_credential_error, remove_federated_identity, remove_federated_identity_error, remove_totp, remove_totp_error, reset_password, reset_password_error, restart_authentication, restart_authentication_error, revoke_grant, revoke_grant_error, send_identity_provider_link, send_identity_provider_link_error, send_reset_password, send_reset_password_error, send_verify_email, send_verify_email_error, token_exchange, token_exchange_error, unregister_node, unregister_node_error, update_consent, update_consent_error, update_credential, update_credential_error, update_email, update_email_error, update_password, update_password_error, update_profile, update_profile_error, update_totp, update_totp_error, user_disabled_by_permanent_lockout, user_disabled_by_permanent_lockout_error, user_disabled_by_temporary_lockout, user_disabled_by_temporary_lockout_error, user_info_request, user_info_request_error, validate_access_token, validate_access_token_error, verify_email, verify_email_error, verify_profile, verify_profile_error

22.13.2. jboss-logging
Copy link

Expand
 Value

spi-events-listener--jboss-logging--error-level

The log level for error messages.

CLI: --spi-events-listener--jboss-logging--error-level
Env: KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__ERROR_LEVEL

debug, error, fatal, info, trace, warn (default)

spi-events-listener--jboss-logging--include-representation

When "true" the "representation" field with the JSON admin object is also added to the message.

The realm should be also configured to include representation for the admin events.

CLI: --spi-events-listener--jboss-logging--include-representation
Env: KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__INCLUDE_REPRESENTATION

true, false (default)

spi-events-listener--jboss-logging--quotes

The quotes to use for values, it should be one character like " or '.

Use "none" if quotes are not needed.

CLI: --spi-events-listener--jboss-logging--quotes
Env: KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__QUOTES

" (default) or any string

spi-events-listener--jboss-logging--sanitize

If true the log messages are sanitized to avoid line breaks.

If false messages are not sanitized.

CLI: --spi-events-listener--jboss-logging--sanitize
Env: KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__SANITIZE

true (default), false

spi-events-listener--jboss-logging--success-level

The log level for success messages.

CLI: --spi-events-listener--jboss-logging--success-level
Env: KC_SPI_EVENTS_LISTENER__JBOSS_LOGGING__SUCCESS_LEVEL

debug (default), error, fatal, info, trace, warn

22.14. export
Copy link

22.14.1. dir
Copy link

Expand
 Value

spi-export--dir--dir

Directory to export to

CLI: --spi-export--dir--dir
Env: KC_SPI_EXPORT__DIR__DIR

any string

spi-export--dir--realm-name

Realm to export

CLI: --spi-export--dir--realm-name
Env: KC_SPI_EXPORT__DIR__REALM_NAME

any string

spi-export--dir--users-export-strategy

Users export strategy

CLI: --spi-export--dir--users-export-strategy
Env: KC_SPI_EXPORT__DIR__USERS_EXPORT_STRATEGY

DIFFERENT_FILES (default) or any string

spi-export--dir--users-per-file

Users per exported file

CLI: --spi-export--dir--users-per-file
Env: KC_SPI_EXPORT__DIR__USERS_PER_FILE

50 (default) or any int

22.14.2. single-file
Copy link

Expand
 Value

spi-export--single-file--file

File to export to

CLI: --spi-export--single-file--file
Env: KC_SPI_EXPORT__SINGLE_FILE__FILE

any string

spi-export--single-file--realm-name

Realm to export

CLI: --spi-export--single-file--realm-name
Env: KC_SPI_EXPORT__SINGLE_FILE__REALM_NAME

any string

22.15. group
Copy link

22.15.1. jpa
Copy link

Expand
 Value

spi-group--jpa--escape-slashes-in-group-path

If true slashes / in group names are escaped with the character ~ when converted to paths.

CLI: --spi-group--jpa--escape-slashes-in-group-path
Env: KC_SPI_GROUP__JPA__ESCAPE_SLASHES_IN_GROUP_PATH

true, false (default)

spi-group--jpa--searchable-attributes

The list of attributes separated by comma that are allowed in client attribute searches.

CLI: --spi-group--jpa--searchable-attributes
Env: KC_SPI_GROUP__JPA__SEARCHABLE_ATTRIBUTES

any string

22.16. import
Copy link

22.16.1. dir
Copy link

Expand
 Value

spi-import--dir--dir

Directory to import from

CLI: --spi-import--dir--dir
Env: KC_SPI_IMPORT__DIR__DIR

any string

spi-import--dir--realm-name

Realm to export

CLI: --spi-import--dir--realm-name
Env: KC_SPI_IMPORT__DIR__REALM_NAME

any string

spi-import--dir--strategy

Strategy for import: IGNORE_EXISTING, OVERWRITE_EXISTING

CLI: --spi-import--dir--strategy
Env: KC_SPI_IMPORT__DIR__STRATEGY

any string

22.16.2. single-file
Copy link

Expand
 Value

spi-import--single-file--file

File to import from

CLI: --spi-import--single-file--file
Env: KC_SPI_IMPORT__SINGLE_FILE__FILE

any string

spi-import--single-file--realm-name

Realm to export

CLI: --spi-import--single-file--realm-name
Env: KC_SPI_IMPORT__SINGLE_FILE__REALM_NAME

any string

spi-import--single-file--strategy

Strategy for import: IGNORE_EXISTING, OVERWRITE_EXISTING

CLI: --spi-import--single-file--strategy
Env: KC_SPI_IMPORT__SINGLE_FILE__STRATEGY

any string

22.17. jgroups-mtls
Copy link

22.17.1. default
Copy link

Expand
 Value

spi-jgroups-mtls--default--enabled

Encrypts the network communication between Keycloak servers.

If no additional parameters about a keystore and truststore are provided, ephemeral key pairs and certificates are created and rotated automatically, which is recommended for standard setups.

CLI: --spi-jgroups-mtls--default--enabled
Env: KC_SPI_JGROUPS_MTLS__DEFAULT__ENABLED

true (default), false

spi-jgroups-mtls--default--keystore-file

The Keystore file path.

The Keystore must contain the certificate to use by the TLS protocol. By default, it looks up cache-mtls-keystore.p12 under conf/ directory.

CLI: --spi-jgroups-mtls--default--keystore-file
Env: KC_SPI_JGROUPS_MTLS__DEFAULT__KEYSTORE_FILE

any String

spi-jgroups-mtls--default--keystore-password

The password to access the Keystore.

CLI: --spi-jgroups-mtls--default--keystore-password
Env: KC_SPI_JGROUPS_MTLS__DEFAULT__KEYSTORE_PASSWORD

any Password

spi-jgroups-mtls--default--rotation

Rotation period in days of automatic JGroups MTLS certificates.

CLI: --spi-jgroups-mtls--default--rotation
Env: KC_SPI_JGROUPS_MTLS__DEFAULT__ROTATION

30 (default) or any Integer

spi-jgroups-mtls--default--truststore-file

The Truststore file path.

It should contain the trusted certificates or the Certificate Authority that signed the certificates. By default, it lookup cache-mtls-truststore.p12 under conf/ directory.

CLI: --spi-jgroups-mtls--default--truststore-file
Env: KC_SPI_JGROUPS_MTLS__DEFAULT__TRUSTSTORE_FILE

any String

spi-jgroups-mtls--default--truststore-password

The password to access the Truststore.

CLI: --spi-jgroups-mtls--default--truststore-password
Env: KC_SPI_JGROUPS_MTLS__DEFAULT__TRUSTSTORE_PASSWORD

any Password

22.18. load-balancer-check
Copy link

22.18.1. remote
Copy link

Expand
 Value

spi-load-balancer-check--remote--poll-interval

The Remote caches poll interval, in milliseconds, for connection availability

CLI: --spi-load-balancer-check--remote--poll-interval
Env: KC_SPI_LOAD_BALANCER_CHECK__REMOTE__POLL_INTERVAL

5000 (default) or any int

22.19. login-protocol
Copy link

22.19.1. openid-connect
Copy link

Expand
 Value

spi-login-protocol--openid-connect--add-req-params-fail-fast

Whether the fail-fast strategy should be enforced in case if the limit for some standard OIDC parameter or additional OIDC parameter is not met for the parameters sent to the OIDC authentication request.

If false, then all additional request parameters to not meet the configuration are silently ignored. If true, an exception will be raised and OIDC authentication request will not be allowed.

CLI: --spi-login-protocol--openid-connect--add-req-params-fail-fast
Env: KC_SPI_LOGIN_PROTOCOL__OPENID_CONNECT__ADD_REQ_PARAMS_FAIL_FAST

true, false (default)

spi-login-protocol--openid-connect--add-req-params-max-number

Maximum number of additional request parameters sent to the OIDC authentication request.

As 'additional request parameter' is meant some custom parameter not directly treated as standard OIDC/OAuth2 protocol parameter. Additional parameters might be useful for example to add custom claims to the OIDC token (in case that also particular protocol mappers are configured).

CLI: --spi-login-protocol--openid-connect--add-req-params-max-number
Env: KC_SPI_LOGIN_PROTOCOL__OPENID_CONNECT__ADD_REQ_PARAMS_MAX_NUMBER

5 (default) or any int

spi-login-protocol--openid-connect--add-req-params-max-overall-size

Maximum size of all additional request parameters values together.

See add-req-params-max-number for more details about additional request parameters

CLI: --spi-login-protocol--openid-connect--add-req-params-max-overall-size
Env: KC_SPI_LOGIN_PROTOCOL__OPENID_CONNECT__ADD_REQ_PARAMS_MAX_OVERALL_SIZE

2147483647 (default) or any int

spi-login-protocol--openid-connect--add-req-params-max-size

Maximum size of single additional request parameter value See add-req-params-max-number for more details about additional request parameters

CLI: --spi-login-protocol--openid-connect--add-req-params-max-size
Env: KC_SPI_LOGIN_PROTOCOL__OPENID_CONNECT__ADD_REQ_PARAMS_MAX_SIZE

2000 (default) or any int

spi-login-protocol--openid-connect--req-params-default-max-size

Maximum default length of the standard OIDC parameter sent to the OIDC authentication request.

This applies to most of the standard parameters like for example state, nonce etc. The exception is login_hint parameter, which has maximum length of 255 characters.

CLI: --spi-login-protocol--openid-connect--req-params-default-max-size
Env: KC_SPI_LOGIN_PROTOCOL__OPENID_CONNECT__REQ_PARAMS_DEFAULT_MAX_SIZE

4000 (default) or any int

spi-login-protocol--openid-connect--req-params-max-size--login_hint

Maximum length of the standard OIDC authentication request parameter overriden for the specified parameter.

Useful if some standard OIDC parameter should have different limit than req-params-default-max-size. It is needed to add the name of the parameter after this prefix into the configuration. In this example, the login_hint parameter is used, but this format is supported for any known standard OIDC/OAuth2 parameter.

CLI: --spi-login-protocol--openid-connect--req-params-max-size--login_hint
Env: KC_SPI_LOGIN_PROTOCOL__OPENID_CONNECT__REQ_PARAMS_MAX_SIZE__LOGIN_HINT

any int

22.20. login-failure
Copy link

22.20.1. remote
Copy link

Expand
 Value

spi-login-failure--remote--max-retries

The maximum number of retries if an error occurs.

A value of zero or less disable any retries.

CLI: --spi-login-failure--remote--max-retries
Env: KC_SPI_LOGIN_FAILURE__REMOTE__MAX_RETRIES

10 (default) or any int

spi-login-failure--remote--retry-base-time

The base back-off time in milliseconds.

CLI: --spi-login-failure--remote--retry-base-time
Env: KC_SPI_LOGIN_FAILURE__REMOTE__RETRY_BASE_TIME

10 (default) or any int

22.21. mapped-diagnostic-context
Copy link

22.21.1. default
Copy link

Expand
 Value

spi-mapped-diagnostic-context--default--mdc-keys

Comma-separated list of MDC keys to add to the Mapped Diagnostic Context.

CLI: --spi-mapped-diagnostic-context--default--mdc-keys
Env: KC_SPI_MAPPED_DIAGNOSTIC_CONTEXT__DEFAULT__MDC_KEYS

realmName, clientId, userId, ipAddress, org, sessionId, authenticationSessionId, authenticationTabId

22.22. password-hashing
Copy link

22.22.1. argon2
Copy link

Expand
 Value

spi-password-hashing--argon2--cpu-cores

Maximum parallel CPU cores to use for hashing

CLI: --spi-password-hashing--argon2--cpu-cores
Env: KC_SPI_PASSWORD_HASHING__ARGON2__CPU_CORES

any int

spi-password-hashing--argon2--hash-length

Hash length

CLI: --spi-password-hashing--argon2--hash-length
Env: KC_SPI_PASSWORD_HASHING__ARGON2__HASH_LENGTH

32 (default) or any int

spi-password-hashing--argon2--iterations

Iterations

CLI: --spi-password-hashing--argon2--iterations
Env: KC_SPI_PASSWORD_HASHING__ARGON2__ITERATIONS

5 (default) or any int

spi-password-hashing--argon2--memory

Memory size (KB)

CLI: --spi-password-hashing--argon2--memory
Env: KC_SPI_PASSWORD_HASHING__ARGON2__MEMORY

7168 (default) or any int

spi-password-hashing--argon2--parallelism

Parallelism

CLI: --spi-password-hashing--argon2--parallelism
Env: KC_SPI_PASSWORD_HASHING__ARGON2__PARALLELISM

1 (default) or any int

spi-password-hashing--argon2--type

Type

CLI: --spi-password-hashing--argon2--type
Env: KC_SPI_PASSWORD_HASHING__ARGON2__TYPE

id (default), d, i

spi-password-hashing--argon2--version

Version

CLI: --spi-password-hashing--argon2--version
Env: KC_SPI_PASSWORD_HASHING__ARGON2__VERSION

1.3 (default), 1.0

22.23. public-key-storage
Copy link

22.23.1. infinispan
Copy link

Expand
 Value

spi-public-key-storage--infinispan--max-cache-time

Maximum interval in seconds that keys are cached when they are retrieved via all keys methods.

When all keys for the entry are retrieved there is no way to detect if a key is missing (different to the case when the key is retrieved via ID for example). In that situation this option forces a refresh from time to time. This time can be overriden by the protocol (for example using cacheDuration or validUntil in the SAML descriptor). Default 24 hours.

CLI: --spi-public-key-storage--infinispan--max-cache-time
Env: KC_SPI_PUBLIC_KEY_STORAGE__INFINISPAN__MAX_CACHE_TIME

86400 (default) or any int

spi-public-key-storage--infinispan--min-time-between-requests

Minimum interval in seconds between two requests to retrieve the new public keys.

The server will always try to download new public keys when a single key is requested and not found. However it will avoid the download if the previous refresh was done less than 10 seconds ago (by default). This behavior is used to avoid DoS attacks against the external keys endpoint.

CLI: --spi-public-key-storage--infinispan--min-time-between-requests
Env: KC_SPI_PUBLIC_KEY_STORAGE__INFINISPAN__MIN_TIME_BETWEEN_REQUESTS

10 (default) or any int

22.24. required-action
Copy link

22.24.1. CONFIGURE_RECOVERY_AUTHN_CODES
Copy link

Expand
 Value

spi-required-action--CONFIGURE_RECOVERY_AUTHN_CODES--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--CONFIGURE_RECOVERY_AUTHN_CODES--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__CONFIGURE_RECOVERY_AUTHN_CODES__MAX_AUTH_AGE

300 (default) or any String

spi-required-action--CONFIGURE_RECOVERY_AUTHN_CODES--warning_threshold

When user has smaller amount of remaining recovery codes on his account than the value configured here, account console will show warning to the user, which will recommend him to setup new set of recovery codes.

CLI: --spi-required-action--CONFIGURE_RECOVERY_AUTHN_CODES--warning_threshold
Env: KC_SPI_REQUIRED_ACTION__CONFIGURE_RECOVERY_AUTHN_CODES__WARNING_THRESHOLD

4 (default) or any Integer

22.24.2. CONFIGURE_TOTP
Copy link

Expand
 Value

spi-required-action--CONFIGURE_TOTP--add-recovery-codes

If this option is enabled, the user will be required to configure recovery codes following the OTP configuration.

If the user already has recovery codes configured, Keycloak will not ask for setting them up. As a prerequisite, enable the recovery codes required action and enable recovery codes in your authentication flow.

CLI: --spi-required-action--CONFIGURE_TOTP--add-recovery-codes
Env: KC_SPI_REQUIRED_ACTION__CONFIGURE_TOTP__ADD_RECOVERY_CODES

true, false (default)

spi-required-action--CONFIGURE_TOTP--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--CONFIGURE_TOTP--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__CONFIGURE_TOTP__MAX_AUTH_AGE

300 (default) or any String

22.24.3. TERMS_AND_CONDITIONS
Copy link

Expand
 Value

spi-required-action--TERMS_AND_CONDITIONS--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--TERMS_AND_CONDITIONS--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__TERMS_AND_CONDITIONS__MAX_AUTH_AGE

300 (default) or any String

22.24.4. UPDATE_EMAIL
Copy link

Expand
 Value

spi-required-action--UPDATE_EMAIL--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--UPDATE_EMAIL--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__UPDATE_EMAIL__MAX_AUTH_AGE

300 (default) or any String

spi-required-action--UPDATE_EMAIL--verify-email

If enabled, the user will be forced to verify the email regardless if email verification is enabled at the realm level or not.

Otherwise, verification will be based on the realm level setting.

CLI: --spi-required-action--UPDATE_EMAIL--verify-email
Env: KC_SPI_REQUIRED_ACTION__UPDATE_EMAIL__VERIFY_EMAIL

true, false (default)

22.24.5. UPDATE_PASSWORD
Copy link

Expand
 Value

spi-required-action--UPDATE_PASSWORD--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--UPDATE_PASSWORD--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__UPDATE_PASSWORD__MAX_AUTH_AGE

300 (default) or any String

22.24.6. UPDATE_PROFILE
Copy link

Expand
 Value

spi-required-action--UPDATE_PROFILE--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--UPDATE_PROFILE--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__UPDATE_PROFILE__MAX_AUTH_AGE

300 (default) or any String

22.24.7. VERIFY_EMAIL
Copy link

Expand
 Value

spi-required-action--VERIFY_EMAIL--email-resend-cooldown-seconds

Minimum delay in seconds before another email verification email can be sent.

CLI: --spi-required-action--VERIFY_EMAIL--email-resend-cooldown-seconds
Env: KC_SPI_REQUIRED_ACTION__VERIFY_EMAIL__EMAIL_RESEND_COOLDOWN_SECONDS

30 (default) or any String

spi-required-action--VERIFY_EMAIL--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--VERIFY_EMAIL--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__VERIFY_EMAIL__MAX_AUTH_AGE

300 (default) or any String

22.24.8. VERIFY_PROFILE
Copy link

Expand
 Value

spi-required-action--VERIFY_PROFILE--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--VERIFY_PROFILE--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__VERIFY_PROFILE__MAX_AUTH_AGE

300 (default) or any String

22.24.9. delete_credential
Copy link

Expand
 Value

spi-required-action--delete_credential--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--delete_credential--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__DELETE_CREDENTIAL__MAX_AUTH_AGE

300 (default) or any String

22.24.11. update_user_locale
Copy link

Expand
 Value

spi-required-action--update_user_locale--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--update_user_locale--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__UPDATE_USER_LOCALE__MAX_AUTH_AGE

300 (default) or any String

22.24.12. webauthn-register
Copy link

Expand
 Value

spi-required-action--webauthn-register--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--webauthn-register--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__WEBAUTHN_REGISTER__MAX_AUTH_AGE

300 (default) or any String

22.24.13. webauthn-register-passwordless
Copy link

Expand
 Value

spi-required-action--webauthn-register-passwordless--max_auth_age

Configures the duration in seconds this action can be used after the last authentication before the user is required to re-authenticate.

This parameter is used just in the context of AIA when the kc_action parameter is available in the request, which is for instance when user himself updates his password in the account console.

CLI: --spi-required-action--webauthn-register-passwordless--max_auth_age
Env: KC_SPI_REQUIRED_ACTION__WEBAUTHN_REGISTER_PASSWORDLESS__MAX_AUTH_AGE

300 (default) or any String

22.25. resource-encoding
Copy link

22.25.1. gzip
Copy link

Expand
 Value

spi-resource-encoding--gzip--excluded-content-types

A space separated list of content-types to exclude from encoding.

CLI: --spi-resource-encoding--gzip--excluded-content-types
Env: KC_SPI_RESOURCE_ENCODING__GZIP__EXCLUDED_CONTENT_TYPES

image/png image/jpeg (default) or any string

22.26. security-profile
Copy link

22.26.1. default
Copy link

Expand
 Value

spi-security-profile--default--name

Name for the security configuration file to use.

File name.json is searched in classapth and conf installation folder.

CLI: --spi-security-profile--default--name
Env: KC_SPI_SECURITY_PROFILE__DEFAULT__NAME

any string

22.27. single-use-object
Copy link

22.27.1. infinispan
Copy link

Expand
 Value

spi-single-use-object--infinispan--persist-revoked-tokens

If revoked tokens are stored persistently across restarts

CLI: --spi-single-use-object--infinispan--persist-revoked-tokens
Env: KC_SPI_SINGLE_USE_OBJECT__INFINISPAN__PERSIST_REVOKED_TOKENS

true (default), false

22.27.2. remote
Copy link

Expand
 Value

spi-single-use-object--remote--persist-revoked-tokens

If revoked tokens are stored persistently across restarts

CLI: --spi-single-use-object--remote--persist-revoked-tokens
Env: KC_SPI_SINGLE_USE_OBJECT__REMOTE__PERSIST_REVOKED_TOKENS

true (default), false

22.28. sticky-session-encoder
Copy link

22.28.1. infinispan
Copy link

Expand
 Value

spi-sticky-session-encoder--infinispan--should-attach-route

If the route should be attached to cookies to reflect the node that owns a particular session.

CLI: --spi-sticky-session-encoder--infinispan--should-attach-route
Env: KC_SPI_STICKY_SESSION_ENCODER__INFINISPAN__SHOULD_ATTACH_ROUTE

true (default), false

22.28.2. remote
Copy link

Expand
 Value

spi-sticky-session-encoder--remote--should-attach-route

If the route should be attached to cookies to reflect the node that owns a particular session.

CLI: --spi-sticky-session-encoder--remote--should-attach-route
Env: KC_SPI_STICKY_SESSION_ENCODER__REMOTE__SHOULD_ATTACH_ROUTE

true (default), false

22.29. truststore
Copy link

22.29.1. file
Copy link

Expand
 Value

spi-truststore--file--file

DEPRECATED: The file path of the trust store from where the certificates are going to be read from to validate TLS connections.

CLI: --spi-truststore--file--file
Env: KC_SPI_TRUSTSTORE__FILE__FILE

any string

spi-truststore--file--hostname-verification-policy

DEPRECATED: The hostname verification policy.

CLI: --spi-truststore--file--hostname-verification-policy
Env: KC_SPI_TRUSTSTORE__FILE__HOSTNAME_VERIFICATION_POLICY

ANY, WILDCARD, STRICT, DEFAULT (default)

spi-truststore--file--password

DEPRECATED: The trust store password.

CLI: --spi-truststore--file--password
Env: KC_SPI_TRUSTSTORE__FILE__PASSWORD

any string

spi-truststore--file--type

DEPRECATED: Type of the truststore.

If not provided, the type would be detected based on the truststore file extension or platform default type.

CLI: --spi-truststore--file--type
Env: KC_SPI_TRUSTSTORE__FILE__TYPE

any string

22.30. user-profile
Copy link

22.30.1. declarative-user-profile
Copy link

Expand
 Value

spi-user-profile--declarative-user-profile--admin-read-only-attributes

Array of regular expressions to identify fields that should be treated read-only so administrators can’t change them.

CLI: --spi-user-profile--declarative-user-profile--admin-read-only-attributes
Env: KC_SPI_USER_PROFILE__DECLARATIVE_USER_PROFILE__ADMIN_READ_ONLY_ATTRIBUTES

any MultivaluedString

spi-user-profile--declarative-user-profile--max-email-local-part-length

To set user profile max email local part length

CLI: --spi-user-profile--declarative-user-profile--max-email-local-part-length
Env: KC_SPI_USER_PROFILE__DECLARATIVE_USER_PROFILE__MAX_EMAIL_LOCAL_PART_LENGTH

any String

spi-user-profile--declarative-user-profile--read-only-attributes

Array of regular expressions to identify fields that should be treated read-only so users can’t change them.

CLI: --spi-user-profile--declarative-user-profile--read-only-attributes
Env: KC_SPI_USER_PROFILE__DECLARATIVE_USER_PROFILE__READ_ONLY_ATTRIBUTES

any MultivaluedString

22.31. user-sessions
Copy link

22.31.1. infinispan
Copy link

Expand
 Value

spi-user-sessions--infinispan--max-batch-size

Maximum size of a batch (only applicable to persistent sessions

CLI: --spi-user-sessions--infinispan--max-batch-size
Env: KC_SPI_USER_SESSIONS__INFINISPAN__MAX_BATCH_SIZE

4 (default) or any int

spi-user-sessions--infinispan--offline-client-session-cache-entry-lifespan-override

Override how long offline client sessions should be kept in memory in seconds (deprecated, to be removed in Keycloak 27)

CLI: --spi-user-sessions--infinispan--offline-client-session-cache-entry-lifespan-override
Env: KC_SPI_USER_SESSIONS__INFINISPAN__OFFLINE_CLIENT_SESSION_CACHE_ENTRY_LIFESPAN_OVERRIDE

any int

spi-user-sessions--infinispan--offline-session-cache-entry-lifespan-override

Override how long offline user sessions should be kept in memory in seconds (deprecated, to be removed in Keycloak 27)

CLI: --spi-user-sessions--infinispan--offline-session-cache-entry-lifespan-override
Env: KC_SPI_USER_SESSIONS__INFINISPAN__OFFLINE_SESSION_CACHE_ENTRY_LIFESPAN_OVERRIDE

any int

spi-user-sessions--infinispan--use-batches

Enable or disable batch writes to the database.

Enabled by default with the persistent-user-sessions Feature

CLI: --spi-user-sessions--infinispan--use-batches
Env: KC_SPI_USER_SESSIONS__INFINISPAN__USE_BATCHES

true, false (default)

spi-user-sessions--infinispan--use-caches

Enable or disable caches.

Enabled by default unless the external feature to use only external remote caches is used

CLI: --spi-user-sessions--infinispan--use-caches
Env: KC_SPI_USER_SESSIONS__INFINISPAN__USE_CACHES

true, false

22.31.2. remote
Copy link

Expand
 Value

spi-user-sessions--remote--batch-size

Batch size when streaming session from the remote cache

CLI: --spi-user-sessions--remote--batch-size
Env: KC_SPI_USER_SESSIONS__REMOTE__BATCH_SIZE

1024 (default) or any int

spi-user-sessions--remote--max-retries

The maximum number of retries if an error occurs.

A value of zero or less disable any retries.

CLI: --spi-user-sessions--remote--max-retries
Env: KC_SPI_USER_SESSIONS__REMOTE__MAX_RETRIES

10 (default) or any int

spi-user-sessions--remote--retry-base-time

The base back-off time in milliseconds.

CLI: --spi-user-sessions--remote--retry-base-time
Env: KC_SPI_USER_SESSIONS__REMOTE__RETRY_BASE_TIME

10 (default) or any int

22.32. well-known
Copy link

22.32.1. oauth-authorization-server
Copy link

Expand
 Value

spi-well-known--oauth-authorization-server--include-client-scopes

If client scopes should be used to calculate the list of supported scopes.

CLI: --spi-well-known--oauth-authorization-server--include-client-scopes
Env: KC_SPI_WELL_KNOWN__OAUTH_AUTHORIZATION_SERVER__INCLUDE_CLIENT_SCOPES

true (default), false

spi-well-known--oauth-authorization-server--openid-configuration-override

The file path from where the metadata should be loaded from.

You can use an absolute file path or, if the file is in the server classpath, use the classpath: prefix to load the file from the classpath.

CLI: --spi-well-known--oauth-authorization-server--openid-configuration-override
Env: KC_SPI_WELL_KNOWN__OAUTH_AUTHORIZATION_SERVER__OPENID_CONFIGURATION_OVERRIDE

any string

22.32.2. openid-configuration
Copy link

Expand
 Value

spi-well-known--openid-configuration--include-client-scopes

If client scopes should be used to calculate the list of supported scopes.

CLI: --spi-well-known--openid-configuration--include-client-scopes
Env: KC_SPI_WELL_KNOWN__OPENID_CONFIGURATION__INCLUDE_CLIENT_SCOPES

true (default), false

spi-well-known--openid-configuration--openid-configuration-override

The file path from where the metadata should be loaded from.

You can use an absolute file path or, if the file is in the server classpath, use the classpath: prefix to load the file from the classpath.

CLI: --spi-well-known--openid-configuration--openid-configuration-override
Env: KC_SPI_WELL_KNOWN__OPENID_CONFIGURATION__OPENID_CONFIGURATION_OVERRIDE

any string

Execute the update compatibility command to check if Red Hat build of Keycloak supports a rolling update for a change in your deployment.

Use the update compatibility command to determine if you can update your deployment with a rolling update strategy when enabling or disabling features or changing the Red Hat build of Keycloak version, configurations or providers and themes. The outcome shows whether a rolling update is possible or if a recreate update is required.

In its current version, it shows that a rolling update is possible when the Red Hat build of Keycloak version is the same for the old and the new version. Future versions of Red Hat build of Keycloak might change that behavior to use additional information from the configuration, the image and the version to determine if a rolling update is possible.

Note

In the next iteration of this feature, it is possible to use rolling update strategy also when updating to the following patch release of Red Hat build of Keycloak. Refer to Section 23.4, “Rolling updates for patch releases” section for more details.

This is fully scriptable, so your update procedure can use that information to perform a rolling or recreate strategy depending on the change performed. It is also GitOps friendly, as it allows storing the metadata of the previous configuration in a file. Use this file in a CI/CD pipeline with the new configuration to determine if a rolling update is possible or if a recreate update is needed.

If you are using the Red Hat build of Keycloak Operator, continue to the Avoiding downtime with rolling updates chapter and the Auto strategy for more information.

23.1. Supported update strategies
Copy link

Rolling Update
In this guide, a rolling update is an update that can be performed with zero downtime for your deployment, which consists of at least two nodes. Update your Red Hat build of Keycloak one by one; shut down one of your old deployment nodes and start a new deployment node. Wait until the new node’s start-up probe returns success before proceeding to the next Red Hat build of Keycloak node. See chapter Tracking instance status with health checks for details on how to enable and use the start-up probe.
Recreate Update
A recreate update is not compatible with zero-downtime and requires downtime to be applied. Shut down all nodes of the cluster running the old version before starting the nodes with the new version.

To determine if a rolling update is possible:

  1. Run the update compatibility command to generate the required metadata with the old configuration.
  2. Check the metadata with the new configuration to determine the update strategy.
Note

If you do not use --optimized keep in mind that an update command may implicitly create or update an optimized build for you - if you are running the command from the same machine as a server instance, this may impact the next start of your server.

Warning

Consumers of these commands should not rely on the internal behavior or the structure of the metadata file. Instead, they should rely only on the exit code of the check command to benefit from future enhancements on the internal logic to determine when a rolling update is possible.

23.2.1. Generating the Metadata
Copy link

To generate the metadata, execute the following command using the same Red Hat build of Keycloak version and configuration options:

Generate and save the metadata from the current deployment.

bin/kc.[sh|bat] update-compatibility metadata --file=/path/to/file.json
Copy to Clipboard Toggle word wrap

This command accepts all options used by the start command. The command displays the metadata, in JSON format, in the console for debugging purposes. The --file parameter allows you to save the metadata to a file. Use this file with the subsequent check command.

Warning

Ensure that all configuration options, whether set via environment variables or CLI arguments, are included when running the above command.

Omitting any configuration options results in incomplete metadata, and could lead to a wrong reported result in the next step.

23.2.2. Checking the Metadata
Copy link

This command checks the metadata generated by the previous command and compares it with the current configuration and Red Hat build of Keycloak version. If you are updating to a new Red Hat build of Keycloak version, this command must be executed with the new version.

Check the metadata from a previous deployment.

bin/kc.[sh|bat] update-compatibility check --file=/path/to/file.json
Copy to Clipboard Toggle word wrap

Warning
  • Ensure that all configuration options, whether set via environment variables or CLI arguments, are included when running this command.
  • Verify that the correct Red Hat build of Keycloak version is used.

Failure to meet these requirements results in an incorrect outcome.

The command prints the result to the console. For example, if a rolling update is possible, it displays:

Rolling Update possible message

[OK] Rolling Update is available.
Copy to Clipboard Toggle word wrap

If no rolling update is possible, the command provides details about the incompatibility:

Rolling Update not possible message

[keycloak] Rolling Update is not available. 'keycloak.version' is incompatible: 26.2.0 -> 26.2.1
1
Copy to Clipboard Toggle word wrap

1
In this example, the Keycloak version 26.2.0 is not compatible with version 26.2.1 and a rolling update is not possible.
Note

In the next iteration of this feature, it is possible to use rolling update strategy also when updating to the following patch release of Red Hat build of Keycloak. Refer to Section 23.4, “Rolling updates for patch releases” section for more details.

Command exit code

Use the command’s exit code to determine the update type in your automation pipeline:

Expand
Exit CodeDescription

0

Rolling Update is possible.

1

Unexpected error occurred (such as the metadata file is missing or corrupted).

2

Invalid CLI option.

3

Rolling Update is not possible. The deployment must be shut down before applying the new configuration.

4

Rolling Update is not possible. The feature rolling-updates is disabled.

23.3. Rolling incompatible changes
Copy link

The following configuration changes return a "Rolling Update is not possible" result code.

23.3.1. Features
Copy link

23.3.1.1. Recreate always
Copy link

The enabling or disabling of the following features requires a recreate update:

Expand
FeatureDescription

multi-site:v1

Multi-site support

persistent-user-sessions:v1

Persistent online user sessions across restarts and upgrades

23.3.1.2. Recreate on feature version change
Copy link

Changing the following features versions triggers a recreate update:

Expand
FeatureDescription

login:v1

Legacy Login Theme

login:v2

New Login Theme

passkeys-conditional-ui-authenticator:v1

Passkeys conditional UI authenticator

23.3.2. Configuration options
Copy link

Changing the value of one of the following CLI options triggers a recreate update:

Expand
Table 23.1. Cache
OptionRationale

--cache

The ispn and local configurations are mutually exclusive, changing from one to another will lead to data loss.

--cache-config-file

Changing the configuration file could result in incompatible cache or transport configurations, resulting in clusters not forming as expected.

--cache-stack

Changing stack will result in the cluster not forming during rolling update and will lead to data loss.

--cache-embedded-mtls-enabled

Enabling/Disabling TLS will result in the cluster not forming during rolling update and will lead to data loss.

--cache-remote-host

Connecting to a new remote cache will cause previously cached data to be lost.

--cache-remote-port

Connecting to a new remote cache will cause previously cached data to be lost.

Warning

Red Hat build of Keycloak does not verify changes to the content of the cache configuration file provided via --cache-config-file. If you change this file, you need to review and test your changes to ensure that nodes using the new configuration can form a cluster with the nodes running the old configuration. If a cluster cannot be formed, you should shut down Red Hat build of Keycloak running the old configuration first before migrating to the new configuration.

Expand
Table 23.2. Database
OptionRationale

--db

Migration to a new database vendor should be applied to all cluster members to ensure data consistency.

--db-schema

Migration to a new database schema should be applied to all cluster members to ensure data consistency.

--db-url-database

Migration to a new database name should be applied to all cluster members to ensure data consistency.

--db-url-host

All cluster members should be connecting to the same database to ensure data consistency.

--db-url-port

All cluster members should be connecting to the same database to ensure data consistency.

Warning

Red Hat build of Keycloak allows changes to the --db-url option to be rolled out in order to facilitate changes to JDBC properties. Great care should be taken when updating this value as changes to the host, port or database name could lead to distinct cluster members connecting to a different database, resulting in data consistency issues.

23.4. Rolling updates for patch releases
Copy link

Warning

This behavior is currently in preview mode, and it is not recommended for use in production.

It is possible to configure the Red Hat build of Keycloak compatibility command to allow rolling updates when upgrading to a newer patch version in the same major.minor release stream.

To enable this behavior for compatibility check command enable feature rolling-updates:v2 as shown in the following example. 

bin/kc.[sh|bat] update-compatibility check --file=/path/to/file.json --features=rolling-updates:v2
Copy to Clipboard Toggle word wrap

Note there is no change needed when generating metadata using metadata command.

Recommended Configuration:

  • Enable sticky sessions in your loadbalancer to avoid users bouncing between different versions of Red Hat build of Keycloak as this could result in users needing to refresh their Account Console and Admin UI multiple times while the upgrade is progressing.

Supported functionality during rolling updates:

  • Users can log in and log out for OpenID Connect clients.
  • OpenID Connect clients can perform all operations, for example, refreshing tokens and querying the user info endpoint.

Known limitations:

  • If there have been changes to the Account Console or Admin UI in the patch release, and the user opened the Account Console or Admin UI before or during the upgrade, the user might see an error message and be asked to reload the application while navigating in browser during or after the upgrade.
  • If the two patch releases of Red Hat build of Keycloak use different versions of the embedded Infinispan, no rolling update of Red Hat build of Keycloak be performed.

23.5. Further reading
Copy link

The Red Hat build of Keycloak Operator uses the functionality described above to determine if a rolling update is possible. See the Avoiding downtime with rolling updates chapter and the Auto strategy for more information.

23.6. Relevant options
Copy link

Expand
 Value

features 🛠

Enables a set of one or more features.

CLI: --features
Env: KC_FEATURES

account-api[:v1], account[:v3], admin-api[:v1], admin-fine-grained-authz[:v1,v2], admin[:v2], authorization[:v1], ciba[:v1], client-auth-federated[:v1], client-policies[:v1], client-secret-rotation[:v1], client-types[:v1], clusterless[:v1], db-tidb[:v1], declarative-ui[:v1], device-flow[:v1], docker[:v1], dpop[:v1], dynamic-scopes[:v1], fips[:v1], hostname[:v2], impersonation[:v1], instagram-broker[:v1], ipa-tuura-federation[:v1], kerberos[:v1], kubernetes-service-accounts[:v1], log-mdc[:v1], login[:v2,v1], logout-all-sessions[:v1], multi-site[:v1], oid4vc-vci[:v1], opentelemetry[:v1], organization[:v1], par[:v1], passkeys-conditional-ui-authenticator[:v1], passkeys[:v1], persistent-user-sessions[:v1], preview, quick-theme[:v1], recovery-codes[:v1], rolling-updates[:v1,v2], scripts[:v1], spiffe[:v1], step-up-authentication[:v1], token-exchange-external-internal[:v2], token-exchange-standard[:v2], token-exchange[:v1], transient-users[:v1], update-email[:v1], user-event-metrics[:v1], web-authn[:v1], workflows[:v1]

features-disabled 🛠

Disables a set of one or more features.

CLI: --features-disabled
Env: KC_FEATURES_DISABLED

account, account-api, admin, admin-api, admin-fine-grained-authz, authorization, ciba, client-auth-federated, client-policies, client-secret-rotation, client-types, clusterless, db-tidb, declarative-ui, device-flow, docker, dpop, dynamic-scopes, fips, impersonation, instagram-broker, ipa-tuura-federation, kerberos, kubernetes-service-accounts, log-mdc, login, logout-all-sessions, multi-site, oid4vc-vci, opentelemetry, organization, par, passkeys, passkeys-conditional-ui-authenticator, persistent-user-sessions, preview, quick-theme, recovery-codes, rolling-updates, scripts, spiffe, step-up-authentication, token-exchange, token-exchange-external-internal, token-exchange-standard, transient-users, update-email, user-event-metrics, web-authn, workflows

Legal Notice
Copy link

Copyright © 2025 Red Hat, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat