In the example above, the db-url value is set in all three configuration sources. The actual value that is used at startup would be the cliValue. If --db-url=cliValue is not used, the used value would be KC_DB_URL=envVarValue, and last but not least the db-url=confFileValue would be used when no environment variable with the same Key is present. When this value is specified in a user defined configuration file and in conf/keycloak.conf, the value from the user defined configuration file takes precedence.

The following example shows how the configuration for the db url host looks for all three configuration sources:

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

export KC_DB_URL_HOST=mykeycloakdb

db-url-host=mykeycloakdb

It is possible to 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}

To specify a fallback value in case the environment variable can not be resolved, use a ::

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

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 invoking the following command:

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

Keycloak is packed with a CLI that helps you to configure Keycloak. To find out about the available configuration, invoke the following command:

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

Alternatively, you can find all server options at the Chapter 3, All configuration guide.

In most cases, the available configuration options should suffice to configure the server. However, you might need to use properties directly from the underlying Quarkus framework to enable a specific behavior or capability that is missing in the keycloak configuration.

If possible, avoid using properties directly from Quarkus. These are considered unsupported by Keycloak. If your need is essential, consider opening an enhancement request first and help us to improve Keycloak’s configuration to fit your needs.

If that’s not possible, you can configure the server using raw Quarkus properties:

For a complete list of Quarkus properties, see the Quarkus documentation. Be aware that Keycloak uses a subset of quarkus extensions, so not all properties will be available.

When a quarkus property is a runtime property (no lock icon shown in the quarkus guide), it is also handled as runtime property for Keycloak. When a quarkus property is a build time property, you have to invoke a build for the property to be applied. See the sections below for further information around the build command.

Note that some quarkus properties are mapped by the Keycloak configuration, for example quarkus.http.port and similar properties that are needed to configure Keycloak. If the property is used by Keycloak, defining the same underlying property key in quarkus.properties will have no effect, as the keycloak configuration value takes precedence over the quarkus property value.

The development mode is targeted for people trying out Keycloak the first time and get it up and running quickly. It also offers convenient defaults for developers, for example to develop a new Keycloak theme.

The development mode is started by invoking the following command:

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

The production mode is targeted for deployments of Keycloak into production environments and follows a "secure by default" principle.

The production mode is started by invoking the following command:

bin/kc.[sh|bat] start

Without further configuration, this command will not start Keycloak and show you an error instead. This is done on purpose, because Keycloak follows a "secure by default" principle in this mode and expects to have a hostname setup and a HTTPS/TLS setup available when started in production mode.

Make sure to follow the steps outlined in the Chapter 2, Configuring Keycloak for production guide before deploying Keycloak to production environments.

By default, example configuration options for the production mode are commented out in the default conf/keycloak.conf file. These give you an idea about the main configuration to consider when running Keycloak in production.

By default, when the start or start-dev commands are used, Keycloak runs a build command under the covers for convenience reasons. This build command performs a set of optimizations to achieve an optimized startup- and runtime-behavior. The build process can take some time, usually a few seconds. Especially when running Keycloak in containerized environments like Kubernetes or OpenShift, startup time is important. So in order to avoid the time that gets lost when running a build as part of Keycloaks first startup, it is possible and recommended to invoke a build explicitly before starting up, for example as a separate step in a CI/CD pipeline.

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

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

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

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

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

db-url-host=keycloak-postgres
db-username=keycloak
db-password=change_me
hostname=mykeycloak.acme.com
https-certificate-file

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

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

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

FROM quay.io/keycloak/keycloak:latest 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 quay.io/keycloak/keycloak:latest
COPY --from=builder /opt/keycloak/ /opt/keycloak/

# change these values to point to a running postgres instance
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"]

The build process includes multiple stages:

To install custom providers, you just need to define a step to include the JAR file(s) into the /opt/keycloak/providers directory:

# A example build step that downloads a JAR file from a URL and adds it to the providers directory
RUN curl -sL <MY_PROVIDER_JAR_URL> -o /opt/keycloak/providers/myprovider.jar

To build the actual docker image, run the following command from the directory containing your Dockerfile:

podman|docker build . -t mykeycloak

To start the image, run:

podman|docker run --name mykeycloak -p 8443:8443 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        mykeycloak \
        start --optimized

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:8443/health, https://localhost:8443/health/ready and https://localhost:8443/health/live.

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

When you use a pair of matching certificate and private key files in PEM format, you configure 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

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

You can set a secure password for your truststore using the https-trust-store-password option:

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

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

The following is an example configuration for a truststore that allows you to create trustful connections to all mycompany.org domains and its subdomains:

bin/kc.[sh|bat] start --spi-truststore-file-file=path/to/truststore.jks --spi-truststore-file-password=change_me --spi-truststore-file-hostname-verification-policy=WILDCARD

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

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.

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

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 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 following caches are used to store both user and client sessions:

By relying on a distributable cache, user and client sessions are available to any node in the cluster so that users can be redirected to any node without loosing their 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.

As an OpenID Connect Provider, the server is also capable of authenticating users and issuing offline tokens. Similarly to regular user and client sessions, when an offline token is issued by the server upon successful authentication, the server also creates a user and client sessions. However, due to the nature of offline tokens, offline sessions are handled differently as they are long-lived and should survive a complete cluster shutdown. Because of that, they are also persisted to the database.

The following caches are used to store offline sessions:

Upon a cluster restart, offline sessions are lazily loaded from the database and kept in a shared cache using the two caches above.

Distributed caches replicate cache entries on a subset of nodes in a cluster and assigns entries to fixed owner nodes.

Each distributed cache has two owners per default, which means that two nodes have a copy of the specific cache entries. Non-owner nodes query the owners of a specific cache to obtain data. When both owner nodes are offline, all data is lost. This situation usually leads to users being logged out at the next request and having to log in again.

The default number of owners is enough to survive 1 node (owner) failure in a cluster setup with at least three nodes. You are free to change the number of owners accordingly to better fit into your availability requirements. To change the number of owners, open conf/cache-ispn.xml and change the value for owners=<value> for the distributed caches to your desired value.

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

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

The configuration file is relative to the conf/ directory.

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

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

The following table shows transport stacks that are supported by Keycloak, but need some extra steps to work. Note that none of these stacks are Kubernetes / OpenShift stacks, so no need exists to enable the "google" stack if you want to run Keycloak on top of the Google Kubernetes engine. In that case, use the kubernetes stack. Instead, when you have a distributed cache setup running on AWS EC2 instances, you would need to set the stack to ec2, because ec2 does not support a default discovery mechanism such as UDP.

Cloud vendor specific stacks have additional dependencies for Keycloak. For more information and links to repositories with these dependencies, see the Infinispan documentation.

To provide the dependencies to Keycloak, put the respective JAR in the providers directory and build Keycloak by entering this command:

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

If none of the available transport stacks are enough for your deployment, you are able to change your cache configuration file and define your own transport stack.

For more details, see Using inline JGroups stacks.

<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_SUSPECT"/>
        <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>

By default, the value set to the cache-stack option has precedence over the transport stack you define in the cache configuration file. If you are defining a custom stack, make sure the cache-stack option is not used for the custom changes to take effect.

The current Infinispan cache implementation should be secured by various security measures such as RBAC, ACLs, and Transport stack encryption. For more information about securing cache communication, see the Infinispan security guide.

The following table defines the available log levels.

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>

Use these guidelines for this command:

You can set different log levels for specific areas in 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>

A configuration that applies to a category also applies to its sub-categories unless you include a more specific matching sub-category.

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

This example sets the following log levels:

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:

The format string supports the symbols in the following table:

To set the logging format for a logged line, perform these steps:

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.

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

This example abbreviates the category name to three characters by setting [%c{3.}] in the template instead of the default [%c].

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

{"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}

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

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

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>

Logging to a file is disabled by default. To enable it, enter the following command:

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

A log file named keycloak.log is created inside the data/log directory of your Keycloak installation.

To change where the log file is created and the file name, perform these steps:

To configure a different logging format for the file log handler, enter the following command:

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

Please see the Section 10.3.1, “Configuring the console log format” section in this guide for more information and a table of the available pattern configuration.

To enable logging using GELF, add it to the list of activated log handlers.

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

To configure the Host and Port of your centralized logging system, enter the following command and substitute the values with your specific values: .Host and port of the GELF server:

bin/kc.[sh|bat] start --log=console,gelf --log-gelf-host=myhost --log-gelf-port=12345

When the GELF handler is enabled, the host is using localhost as host value and UDP for communication. To use TCP instead of UDP, prefix the host value with tcp:. The Default port is 12201.

bin/kc.[sh|bat] start --log=console,gelf --log-gelf-include-stack-trace=false

bin/kc.[sh|bat] start --log=console,gelf --log-gelf-timestamp-format="'yyyy-MM-dd HH:mm:ss'"

Alternatively, you could use the config file to avoid escaping:

log-gelf-timestamp-format=yyyy-MM-dd HH:mm:ss

The default timestamp format is yyyy-MM-dd HH:mm:ss,SSS. You can use the available SimpleDateFormat patterns to define an appropriate timestamp.

bin/kc.[sh|bat] start --log=console,gelf --log-gelf-facility=MyKeycloak

To use the CLI to configure Keycloak and use whitespaces for facility, enter the following command:

bin/kc.[sh|bat] start --log=console,gelf --log-gelf-facility="'my keycloak'"

Alternatively, you could use the config file to avoid escaping:

log-gelf-facility=my keycloak

bin/kc.[sh|bat] start --log=console,gelf --log-gelf-max-message-size=16384

The maximum size of one GELF log message is set in Bytes. The preceding example increases the size to 16kb. When messages exceed the maximum size, GELF submits the message in multiple chunks.

bin/kc.[sh|bat] start --log=console,gelf --log-gelf-include-message-parameters=false

bin/kc.[sh|bat] start --log=console,gelf --log-gelf-include-location=false

The following example shows how to send Keycloak logs to the Graylog centralized logging stack. This example assumes you have a container tool such as docker installed to start the compose.yml.

version: '3.8'

services:
  elasticsearch:
    image: docker.io/elastic/elasticsearch:7.10.2
    ports:
      - "9200:9200"
    environment:
      ES_JAVA_OPTS: "-Xms512m -Xmx512m"
      discovery.type: "single-node"
    networks:
      - graylog

  mongo:
    image: mongo:4.4
    networks:
      - graylog

  graylog:
    image: graylog/graylog:4.3.3
    ports:
      - "9000:9000"
      - "12201:12201/udp"
      - "1514:1514"
    environment:
      GRAYLOG_HTTP_EXTERNAL_URI: "http://127.0.0.1:9000/"
      # CHANGE ME (must be at least 16 characters)!
      GRAYLOG_PASSWORD_SECRET: "forpasswordencryption"
      # Password: admin
      GRAYLOG_ROOT_PASSWORD_SHA2: "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918"
    networks:
      - graylog
    depends_on:
      - elasticsearch
      - mongo

networks:
  graylog:
    driver: bridge

docker compose up -d

curl -H "Content-Type: application/json" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "X-Requested-By: curl" -X POST -v -d \
'{"title":"udp input","configuration":{"recv_buffer_size":262144,"bind_address":"0.0.0.0","port":12201,"decompress_size_limit":8388608},"type":"org.graylog2.inputs.gelf.udp.GELFUDPInput","global":true}' \
http://localhost:9000/api/system/inputs

log=console,gelf
log-gelf-host=localhost
log-gelf-port=12201

The following example shows how to send Keycloak logs to the ELK centralized logging stack. It assumes you have a container tool such as docker installed to start the compose.yml.

/ELK
  - compose.yml
  - pipelines/
    - gelf.conf

input {
  gelf {
    port => 12201
  }
}
output {
  stdout {}
  elasticsearch {
    hosts => ["http://elasticsearch:9200"]
  }
}

# Launch Elasticsearch
version: '3.8'

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch-oss:6.8.2
    ports:
      - "9200:9200"
      - "9300:9300"
    environment:
      ES_JAVA_OPTS: "-Xms512m -Xmx512m"
    networks:
      - elk

  logstash:
    image: docker.elastic.co/logstash/logstash-oss:6.8.2
    volumes:
      - source: ./pipelines #the source dir gelf.conf resides
        target: /usr/share/logstash/pipeline
        type: bind
    ports:
      - "12201:12201/udp"
      - "5000:5000"
      - "9600:9600"
    networks:
      - elk
    depends_on:
      - elasticsearch

  kibana:
    image: docker.elastic.co/kibana/kibana-oss:6.8.2
    ports:
      - "5601:5601"
    networks:
      - elk
    depends_on:
      - elasticsearch

networks:
  elk:
    driver: bridge

docker compose up -d

log=console,gelf
log-gelf-host=localhost
log-gelf-port=12201

To keep log storage costs and verbosity low, it is often wanted to only store a subset of the verbose application logs inside a centralized log management system. To configure Keycloak to use a different log level for the logs you want to ingest, use the following configuration:

log=console,gelf
log-gelf-level=<desired-log-level>
...

log=console,gelf
log-level=INFO
log-gelf-level=warn
...

Looking at your ingested logs, you will see only messages of level warn or above will appear.

Keep in mind that --log-level is setting the leading log level, so for example when you invoke the following command:

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

nothing below the error level will be sent to your logging stack. That means that even GELF in this example will receive only error level log messages.

Currently, the Keycloak configuration does not support partly dynamic configuration keys, as they are used in quarkus properties. For example, they are used when defining quarkus.log.handler.gelf.additional-field.<my-name>.value.

To add user-defined fields, you can provide these fields through a quarkus.properties file. Refer to the Chapter 1, Configuring Keycloak guide and the Using unsupported server options section.