Server Configuration Guide

Red Hat build of Keycloak loads the configuration from four sources, which are listed here in order of application.

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

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.

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

export KC_DB_URL_HOST=mykeycloakdb

db-url-host=mykeycloakdb

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

db-url-host=${MY_DB_HOST}

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

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

keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v

bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=keystorepass --config-keystore-type=PKCS12

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

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

bin/kc.[sh|bat] start

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.

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

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

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

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

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:

You can read more at the specific Quarkus guide

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.

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

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

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.

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. When deployed to a cluster, the embedded Infinispan server communication should be secured. You secure this communication either by enabling authentication and encryption or by isolating the network used for cluster communication.

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

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"

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

bin/kc.[sh|bat] start-dev --bootstrap-admin-client-id tmpadm --bootstrap-admin-client-secret secret

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.

bin/kc.[sh|bat] bootstrap-admin user

bin/kc.[sh|bat] bootstrap-admin user --username tmpadm --password:env PASS_VAR

bin/kc.[sh|bat] bootstrap-admin service

bin/kc.[sh|bat] bootstrap-admin service --client-id tmpclient --client-secret:env=SECRET_VAR

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>

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}

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}

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.

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

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

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.

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>

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>

If you are installing from a zip file then by default there will be an install root directory of rhbk-26.0.7, 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.

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

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.

FROM registry.redhat.io/rhbk/keycloak-rhel9:26 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
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"]

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

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

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 /

podman build . -t mykeycloak

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

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:

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

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 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        registry.redhat.io/rhbk/keycloak-rhel9:26 \
        start-dev

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 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
        registry.redhat.io/rhbk/keycloak-rhel9:26 \
        start \
        --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>

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

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 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 \
        start-dev --import-realm

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

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 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 \
        start-dev

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

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

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

bin/kc.[sh|bat] start --https-key-store-password=<value>

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

To also allow TLSv1.2, use a command such as the following: kc.sh start --https-protocols=TLSv1.3,TLSv1.2.

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>

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.

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

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

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

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

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.

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

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.

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.

bin/kc.[sh|bat] start --hostname-strict false --proxy-headers forwarded

bin/kc.[sh|bat] start --hostname my.keycloak.org --proxy-headers xforwarded

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --proxy-headers xforwarded

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

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.

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:

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:

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.

bin/kc.[sh|bat] start --hostname my.keycloak.org

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic true

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443

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

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

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

bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-debug=true

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

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

For example:

bin/kc.[sh|bat] start --proxy-headers forwarded

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.

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.

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:

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

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.

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

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.

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

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.

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

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.

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

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

bin/kc.[sh|bat] build --spi-x509cert-lookup-provider=<provider>

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

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:

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.

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.

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.

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 default schema is keycloak, but you can change it by using the db-schema configuration option.

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

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.

The server uses a default JDBC driver accordingly to the database you chose.

To set a different driver you can set the db-driver with the fully qualified class name of the JDBC driver:

bin/kc.[sh|bat] start --db postgres --db-driver=my.Driver

Regardless of the driver you set, the default driver is always available at runtime.

Only set this property if you really need to. For instance, when leveraging the capabilities from a JDBC Driver Wrapper for a specific cloud database service.

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

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

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.

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:

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

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

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

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

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

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual

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

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-initialize-empty=false

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

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql>

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 are using a UDP transport stack so that nodes are discovered using IP multicast transport based on UDP. For most production environments, there are better discovery alternatives to UDP available. 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

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.

Red Hat build of Keycloak provides a cache configuration file with sensible defaults located at conf/cache-ispn.xml.

The cache configuration is a regular Infinispan configuration file.

The following table gives an overview of the specific caches Red Hat build of Keycloak uses. You configure these caches in conf/cache-ispn.xml:

bin/kc.[sh|bat] start --cache-config-file=my-cache-file.xml

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

To apply a specific cache stack, enter this command:

bin/kc.[sh|bat] start --cache-stack=<stack>

The default stack is set to udp when distributed caches are enabled.

bin/kc.[sh|bat] start --cache-stack=<ec2|google|azure>

<jgroups>
    <stack name="my-encrypt-udp" extends="udp">
    <SSL_KEY_EXCHANGE keystore_name="server.jks"
        keystore_password="password"
        stack.combine="INSERT_AFTER"
        stack.position="VERIFY_SUSPECT2"/>
        <ASYM_ENCRYPT asym_keylength="2048"
        asym_algorithm="RSA"
        change_key_on_coord_leave = "false"
        change_key_on_leave = "false"
        use_external_key_exchange = "true"
        stack.combine="INSERT_BEFORE"
        stack.position="pbcast.NAKACK2"/>
    </stack>
</jgroups>

<cache-container name="keycloak">
    <transport lock-timeout="60000" stack="my-encrypt-udp"/>
    ...
</cache-container>

The current Infinispan cache implementation should be secured by various security measures such as RBAC, ACLs, and transport stack encryption.

JGroups handles all the communication between Red Hat build of Keycloak server, and it supports Java SSL sockets for TCP communication. Red Hat build of Keycloak uses CLI options to configure the TLS communication without having to create a customized JGroups stack or modifying the cache XML file.

To enable TLS, cache-embedded-mtls-enabled must be set to true. It requires a keystore with the certificate to use: 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, use a self-signed certificate for each Red Hat build of Keycloak deployment.

For JGroups stacks with UDP or TCP_NIO2, see the JGroups Encryption documentation on how to set up the protocol stack.

For more information about securing cache communication, see the Infinispan security guide.

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

For more details about how to enable metrics, see Enabling Red Hat build of Keycloak Metrics.

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.

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>

The following are the command options:

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

HTTPS_PROXY=https://www-proxy.acme.com:8080
NO_PROXY=google.com,login.facebook.com

In this example, the following results occur:

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

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'

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:

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

# 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

In this example, the following occurs:

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

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.

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

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>

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.

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>

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>]"

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

bin/kc.[sh|bat] build --features="docker,token-exchange"

To enable all preview features, enter this command:

bin/kc.[sh|bat] build --features="preview"

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:

To disable a feature that is enabled by default, enter this command:

bin/kc.[sh|bat] build --features-disabled="<name>[,<name>]"

For example to disable impersonation, enter this command:

bin/kc.[sh|bat] build --features-disabled="impersonation"

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.

The following list contains supported features that are enabled by default, and can be disabled if not needed.

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.

The following list contains deprecated features that will be removed in a future release. These features are disabled by default.

Providers can be configured by using a specific configuration format. The format consists of:

spi-<spi-id>-<provider-id>-<property>=<value>

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.

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

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:

bin/kc.[sh|bat] start --spi-connections-http-client-default-connection-pool-size=10

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.

To configure a provider as the single provider you should run the build command as follows:

bin/kc.[sh|bat] build --spi-email-template-provider=mycustomprovider

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 following logic is used to determine the default provider:

To configure a provider as the default provider you should run the build command as follows:

bin/kc.[sh|bat] build --spi-password-hashing-provider-default=mycustomprovider

To enable or disable a provider you should run the build command as follows:

bin/kc.[sh|bat] build --spi-email-template-mycustomprovider-enabled=true

To disable a provider, use the same command and set the enabled property to false.

Custom providers should be packaged in a Java Archive (JAR) file and copied to the providers directory of the distribution. After that, 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.

To uninstall a provider, you should remove the JAR file from the providers directory and run the build command again.

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.

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.

bin/kc.[sh|bat] start --log-level=<root-level>

bin/kc.[sh|bat] start --log-level="<root-level>,<org.category1>:<org.category1-level>"

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug,org.hibernate.hql.internal.ast:info"

To enable log handlers, enter the following command:

bin/kc.[sh|bat] start --log="<handler1>,<handler2>"

The available handlers are:

The more specific handler configuration mentioned below will only take effect when the handler is added to this comma-separated list.

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:

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.

bin/kc.[sh|bat] start --log=console,file --log-level=debug --log-console-level=info

bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug --log-console-level=warn --log-syslog-level=warn

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

The console log handler is enabled by default, providing unstructured log messages for the console.

bin/kc.[sh|bat] start --log-console-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"

bin/kc.[sh|bat] start --log-console-output=json

{"timestamp":"2022-02-25T10:31:32.452+01:00","sequence":8442,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.253s. Listening on: http://0.0.0.0:8080","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host-name","processName":"QuarkusEntryPoint","processId":36946}

bin/kc.[sh|bat] start --log-console-output=default

2022-03-02 10:36:50,603 INFO  [io.quarkus] (main) Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.615s. Listening on: http://0.0.0.0:8080

bin/kc.[sh|bat] start --log-console-color=<false|true>

bin/kc.[sh|bat] start --log-console-level=warn

As an alternative to logging to the console, you can use unstructured logging to a file.

bin/kc.[sh|bat] start --log="console,file"

bin/kc.[sh|bat] start --log-file-format="<pattern>"

bin/kc.[sh|bat] start --log-file-level=warn

Red Hat build of Keycloak provides the ability to send logs to a remote Syslog server. It utilizes the protocol defined in RFC 5424.

bin/kc.[sh|bat] start --log="console,syslog"

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-app-name=kc-p-itadmins

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-endpoint=myhost:12345

bin/kc.[sh|bat] start --log-syslog-level=warn

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-protocol=udp

bin/kc.[sh|bat] start --log-syslog-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"

bin/kc.[sh|bat] start --log-syslog-type=rfc3164

bin/kc.[sh|bat] start --log-syslog-max-length=1536

bin/kc.[sh|bat] start --log-syslog-output=json

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}

bin/kc.[sh|bat] start --log-syslog-output=default

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.

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 cannot be shipped with Red Hat build of Keycloak due to license constraints and 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.

You can create either pkcs12 or bcfks keystore to be used for the Red Hat build of Keycloak server SSL.

keytool -genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpassword \
  -keystore $KEYCLOAK_HOME/conf/server.keystore \
  -alias localhost \
  -dname CN=localhost -keypass passwordpassword

securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS

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

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

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.

When starting the server, you can check that the startup log contains KC provider with the note about Approved Mode such as the following:

KC(BCFIPS version 2.0 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,

--spi-password-hashing-pbkdf2-sha512-max-padding-length=14

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

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.

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

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.

The algorithm EdDSA cannot be used in FIPS mode. Although the current BCFIPS provider supports Ed25519 and Ed448 curves, the resulting keys do not implement the standard JDK interfaces to manage them (EdECKey, EdECPublicKey, EdECPrivateKey,…​), and Red Hat build of Keycloak cannot use them for signatures.

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/

echo "keystore.type=bcfks
fips.keystore.type=bcfks" > /tmp/kcadm.java.security
export KC_OPTS="-Djava.security.properties=/tmp/kcadm.java.security"

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:

Then create Containerfile in the current directory similar to this:

FROM registry.redhat.io/rhbk/keycloak-rhel9:26 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
COPY --from=builder /opt/keycloak/ /opt/keycloak/

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

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.

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:

In addition to the preceding requirements, be sure to doublecheck this before switching to FIPS strict mode:

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.

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.

Red Hat build of Keycloak exposes 4 health endpoints:

See the Quarkus SmallRye Health docs for information on the meaning of each endpoint.

These endpoints respond with HTTP status 200 OK on success or 503 Service Unavailable on failure, and a JSON object like the following:

{
    "status": "UP",
    "checks": []
}

{
    "status": "UP",
    "checks": [
        {
            "name": "Keycloak database connections health check",
            "status": "UP"
        }
    ]
}

It is possible to enable the health checks using the build time option health-enabled:

bin/kc.[sh|bat] build --health-enabled=true

By default, no check is returned from the health endpoints.

It is recommended that the health endpoints be monitored by external HTTP requests. Due to security measures that remove curl and other packages from the Red Hat build of Keycloak container image, local command-based monitoring will not function easily.

If you are not using Red Hat build of Keycloak in a container, use whatever you want to access the health check endpoints.

curl --head -fsS http://localhost:9000/health/ready

The table below shows the available checks.

For some checks, you’ll need to also enable metrics as indicated by the Requires Metrics column. To enable metrics use the metrics-enabled option as follows:

bin/kc.[sh|bat] build --health-enabled=true --metrics-enabled=true

It is possible to enable metrics using the build time option metrics-enabled:

bin/kc.[sh|bat] start --metrics-enabled=true

Red Hat build of Keycloak exposes metrics at the following endpoint on the management interface at:

For more information about the management interface, see Configuring the Management Interface. The response from the endpoint uses a application/openmetrics-text content type and it is based on the Prometheus (OpenMetrics) text format. The snippet below is an example of a response:

# HELP base_gc_total Displays the total number of collections that have occurred. This attribute lists -1 if the collection count is undefined for this collector.
# TYPE base_gc_total counter
base_gc_total{name="G1 Young Generation",} 14.0
# HELP jvm_memory_usage_after_gc_percent The percentage of long-lived heap pool used after the last GC event, in the range [0..1]
# TYPE jvm_memory_usage_after_gc_percent gauge
jvm_memory_usage_after_gc_percent{area="heap",pool="long-lived",} 0.0
# HELP jvm_threads_peak_threads The peak live thread count since the Java virtual machine started or peak was reset
# TYPE jvm_threads_peak_threads gauge
jvm_threads_peak_threads 113.0
# HELP agroal_active_count Number of active connections. These connections are in use and not available to be acquired.
# TYPE agroal_active_count gauge
agroal_active_count{datasource="default",} 0.0
# HELP base_memory_maxHeap_bytes Displays the maximum amount of memory, in bytes, that can be used for memory management.
# TYPE base_memory_maxHeap_bytes gauge
base_memory_maxHeap_bytes 1.6781410304E10
# HELP process_start_time_seconds Start time of the process since unix epoch.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1.675188449054E9
# HELP system_load_average_1m The sum of the number of runnable entities queued to available processors and the number of runnable entities running on the available processors averaged over a period of time
# TYPE system_load_average_1m gauge
system_load_average_1m 4.005859375

...

The table below summarizes the available metrics groups:

It is possible to enable exposing traces using the build time option tracing-enabled, and enabling opentelemetry feature as follows:

bin/kc.[sh|bat] start --tracing-enabled=true --features=opentelemetry

By default, the trace exporters send out data in batches, using the gRPC protocol and endpoint http://localhost:4317.

The default service name is keycloak, specified via the tracing-service-name property, which takes precedence over service.name defined in the tracing-resource-attributes property.

For more information about resource attributes that can be provided via the tracing-resource-attributes property, see the Quarkus OpenTelemetry Resource guide.

For more tracing settings, see all possible configurations below.

In order to see the captured Red Hat build of Keycloak traces, the basic setup with leveraging the Jaeger tracing platform might be used. For development purposes, the Jaeger-all-in-one can be used to see traces as easily as possible.

podman run --name jaeger \
-p 16686:16686 \
-p 4317:4317 \
-p 4318:4318 \
jaegertracing/all-in-one

21.2.1. Exposed ports

• :16686 - Jaeger UI
• :4317 - OpenTelemetry Protocol gRPC receiver (default)
• :4318 - OpenTelemetry Protocol HTTP receiver

You can visit the Jaeger UI on http://localhost:16686/ to see the tracing information. The Jaeger UI might look like this with an arbitrary Red Hat build of Keycloak trace:

When tracing is enabled, the trace information is included in the log messages of all enabled log handlers (see more in Configuring logging). It can be useful for associating log events to request execution, which might provide better traceability and debugging. All log lines originating from the same request will have the same traceId in the log.

The log message also contains a sampled flag, which relates to the sampling described below and indicates whether the span was sampled - sent to the collector.

The format of the log records may start as follows:

2024-08-05 15:27:07,144 traceId=b636ac4c665ceb901f7fdc3fc7e80154, parentId=d59cea113d0c2549, spanId=d59cea113d0c2549, sampled=true WARN  [org.keycloak.events] ...

bin/kc.[sh|bat] start --tracing-enabled=true --features=opentelemetry --log=console --log-console-include-trace=false

Sampler decides whether a trace should be discarded or forwarded, effectively reducing overhead by limiting the number of collected traces sent to the collector. It helps manage resource consumption, which leads to avoiding the huge storage costs of tracing every single request and potential performance penalty.

Red Hat build of Keycloak supports several built-in OpenTelemetry samplers, such as:

The used sampler can be changed via the tracing-sampler-type property.

When the tracing is enabled when using the Red Hat build of Keycloak Operator, certain information about the deployment is propagated to the underlying containers.

You can filter out the required traces in your tracing backend based on their tags:

Red Hat build of Keycloak Operator automatically sets the KC_TRACING_SERVICE_NAME and KC_TRACING_RESOURCE_ATTRIBUTES environment variables for each Red Hat build of Keycloak container included in pods it manages.

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.

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

To export a realm to a directory, you can use the --dir <dir> option.

bin/kc.[sh|bat] export --dir <dir>

When exporting realms to a directory, the server is going to create separate files for each realm being exported.

bin/kc.[sh|bat] export --dir <dir> --users different_files --users-per-file 100

To export a realm to a file, you can use the --file <file> option.

bin/kc.[sh|bat] export --file <file>

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.

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

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

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>

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

By default, the --override option is set to true so that realms are always overridden with the new configuration.

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>

You are able to use placeholders to resolve values from environment variables for any realm configuration.

{
    "realm": "${MY_REALM_NAME}",
    "enabled": true,
    ...
}

In the example above, the value set to the MY_REALM_NAME environment variable is going to be used to set the realm property.

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

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.

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.

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

To export a realm using the Admin Console, perform these steps:

In a similar way, you can import a previously exported realm. Perform these steps:

You can also control what Red Hat build of Keycloak should do if the imported resource already exists. These options exist:

Secrets stored in the vaults can be used at the following places of the Administration Console:

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

Analogically, for the Java KeyStore-based you need to specify the following build option:

bin/kc.[sh|bat] build --vault=keystore

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

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>

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

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.

sso__realm_ldap__credential

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.