Chapter 19. All configuration

cache 🛠

Defines the cache mechanism for high-availability.

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

CLI: --cache
Env: KC_CACHE

ispn (default), local

cache-config-file 🛠

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

The configuration file is relative to the conf/ directory.

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

cache-embedded-mtls-enabled

Encrypts the network communication between Keycloak servers.

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

true, false (default)

cache-embedded-mtls-key-store-file

The Keystore file path.

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

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

cache-embedded-mtls-key-store-password

The password to access the Keystore.

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

cache-embedded-mtls-trust-store-file

The Truststore file path.

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

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

cache-embedded-mtls-trust-store-password

The password to access the Truststore.

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

cache-remote-host

The hostname of the remote server for the remote store configuration.

It replaces the host attribute of remote-server tag of the configuration specified via XML file (see cache-config-file option.). If the option is specified, cache-remote-username and cache-remote-password are required as well and the related configuration in XML file should not be present.

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

cache-remote-password

The password for the authentication to the remote server for the remote store.

It replaces the password attribute of digest tag of the configuration specified via XML file (see cache-config-file option.). If the option is specified, cache-remote-host and cache-remote-username are required as well and the related configuration in XML file should not be present.

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

cache-remote-port

The port of the remote server for the remote store configuration.

It replaces the port attribute of remote-server tag of the configuration specified via XML file (see cache-config-file option.).

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

11222 (default)

cache-remote-username

The username for the authentication to the remote server for the remote store.

It replaces the username attribute of digest tag of the configuration specified via XML file (see cache-config-file option.). If the option is specified, cache-remote-host and cache-remote-password are required as well and the related configuration in XML file should not be present.

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

cache-stack 🛠

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

This option only takes effect if cache is set to ispn. Default: udp.

CLI: --cache-stack
Env: KC_CACHE_STACK

tcp, udp, kubernetes, ec2, azure, google

db 🛠

The database vendor.

CLI: --db
Env: KC_DB

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

db-driver 🛠

The fully qualified class name of the JDBC driver.

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

CLI: --db-driver
Env: KC_DB_DRIVER

db-password

The password of the database user.

CLI: --db-password
Env: KC_DB_PASSWORD

db-pool-initial-size

The initial size of the connection pool.

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

db-pool-max-size

The maximum size of the connection pool.

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

100 (default)

db-pool-min-size

The minimal size of the connection pool.

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

db-schema

The database schema to be used.

CLI: --db-schema
Env: KC_DB_SCHEMA

db-url

The full database JDBC URL.

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

CLI: --db-url
Env: KC_DB_URL

db-url-database

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

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

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

db-url-host

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

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

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

db-url-port

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

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

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

db-url-properties

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

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

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

db-username

The username of the database user.

CLI: --db-username
Env: KC_DB_USERNAME

transaction-xa-enabled 🛠

If set to false, Keycloak uses a non-XA datasource in case the database does not support XA transactions.

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

true (default), false

features 🛠

Enables a set of one or more features.

CLI: --features
Env: KC_FEATURES

account-api[:v1], account2[:v1], account3[:v1], admin-api[:v1], admin-fine-grained-authz[:v1], admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1], client-secret-rotation[:v1], client-types[:v1], declarative-ui[:v1], device-flow[:v1], docker[:v1], dpop[:v1], dynamic-scopes[:v1], fips[:v1], hostname[:v1], impersonation[:v1], js-adapter[:v1], kerberos[:v1], linkedin-oauth[:v1], login2[:v1], multi-site[:v1], offline-session-preloading[:v1], oid4vc-vci[:v1], par[:v1], preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1], token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1]

features-disabled 🛠

Disables a set of one or more features.

CLI: --features-disabled
Env: KC_FEATURES_DISABLED

account-api, account2, account3, admin-api, admin-fine-grained-authz, admin2, authorization, ciba, client-policies, client-secret-rotation, client-types, declarative-ui, device-flow, docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos, linkedin-oauth, login2, multi-site, offline-session-preloading, oid4vc-vci, par, preview, recovery-codes, scripts, step-up-authentication, token-exchange, transient-users, update-email, web-authn

hostname

Hostname for the Keycloak server.

CLI: --hostname
Env: KC_HOSTNAME

hostname-admin

The hostname for accessing the administration console.

Use this option if you are exposing the administration console using a hostname other than the value set to the hostname option.

CLI: --hostname-admin
Env: KC_HOSTNAME_ADMIN

hostname-admin-url

Set the base URL for accessing the administration console, including scheme, host, port and path

CLI: --hostname-admin-url
Env: KC_HOSTNAME_ADMIN_URL

hostname-debug

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

CLI: --hostname-debug
Env: KC_HOSTNAME_DEBUG

true, false (default)

hostname-path

This should be set if proxy uses a different context-path for Keycloak.

CLI: --hostname-path
Env: KC_HOSTNAME_PATH

hostname-port

The port used by the proxy when exposing the hostname.

Set this option if the proxy uses a port other than the default HTTP and HTTPS ports.

CLI: --hostname-port
Env: KC_HOSTNAME_PORT

-1 (default)

hostname-strict

Disables dynamically resolving the hostname from request headers.

Should always be set to true in production, unless proxy verifies the Host header.

CLI: --hostname-strict
Env: KC_HOSTNAME_STRICT

true (default), false

hostname-strict-backchannel

By default backchannel URLs are dynamically resolved from request headers to allow internal and external applications.

If all applications use the public URL this option should be enabled.

CLI: --hostname-strict-backchannel
Env: KC_HOSTNAME_STRICT_BACKCHANNEL

true, false (default)

hostname-url

Set the base URL for frontend URLs, including scheme, host, port and path.

CLI: --hostname-url
Env: KC_HOSTNAME_URL

http-enabled

Enables the HTTP listener.

CLI: --http-enabled
Env: KC_HTTP_ENABLED

true, false (default)

http-host

The used HTTP Host.

CLI: --http-host
Env: KC_HTTP_HOST

0.0.0.0 (default)

http-max-queued-requests

Maximum number of queued HTTP requests.

Use this to shed load in an overload situation. Excess requests will return a "503 Server not Available" response.

CLI: --http-max-queued-requests
Env: KC_HTTP_MAX_QUEUED_REQUESTS

http-pool-max-threads

The maximum number of threads.

If this is not specified then it will be automatically sized to the greatest of 8 * the number of available processors and 200. For example if there are 4 processors the max threads will be 200. If there are 48 processors it will be 384.

CLI: --http-pool-max-threads
Env: KC_HTTP_POOL_MAX_THREADS

http-port

The used HTTP port.

CLI: --http-port
Env: KC_HTTP_PORT

8080 (default)

http-relative-path 🛠

Set the path relative to / for serving resources.

The path must start with a /.

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

/ (default)

https-certificate-file

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

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

https-certificate-key-file

The file path to a private key in PEM format.

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

https-cipher-suites

The cipher suites to use.

If none is given, a reasonable default is selected.

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

https-client-auth 🛠

Configures the server to require/request client authentication.

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

none (default), request, required

https-key-store-file

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

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

https-key-store-password

The password of the key store file.

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

password (default)

https-key-store-type

The type of the key store file.

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

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

https-port

The used HTTPS port.

CLI: --https-port
Env: KC_HTTPS_PORT

8443 (default)

https-protocols

The list of protocols to explicitly enable.

CLI: --https-protocols
Env: KC_HTTPS_PROTOCOLS

[TLSv1.3,TLSv1.2] (default)

https-trust-store-file

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

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

DEPRECATED. Use the System Truststore instead, see the docs for details.

https-trust-store-password

The password of the trust store file.

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

DEPRECATED. Use the System Truststore instead, see the docs for details.

https-trust-store-type

The type of the trust store file.

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

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

DEPRECATED. Use the System Truststore instead, see the docs for details.

health-enabled 🛠

If the server should expose health check endpoints.

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

CLI: --health-enabled
Env: KC_HEALTH_ENABLED

true, false (default)

config-keystore

Specifies a path to the KeyStore Configuration Source.

CLI: --config-keystore
Env: KC_CONFIG_KEYSTORE

config-keystore-password

Specifies a password to the KeyStore Configuration Source.

CLI: --config-keystore-password
Env: KC_CONFIG_KEYSTORE_PASSWORD

config-keystore-type

Specifies a type of the KeyStore Configuration Source.

CLI: --config-keystore-type
Env: KC_CONFIG_KEYSTORE_TYPE

PKCS12 (default)

metrics-enabled 🛠

If the server should expose metrics.

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

CLI: --metrics-enabled
Env: KC_METRICS_ENABLED

true, false (default)

proxy

The proxy address forwarding mode if the server is behind a reverse proxy.

CLI: --proxy
Env: KC_PROXY

DEPRECATED. Use: proxy-headers.

none (default), edge, reencrypt, passthrough

proxy-headers

The proxy headers that should be accepted by the server.

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

CLI: --proxy-headers
Env: KC_PROXY_HEADERS

forwarded, xforwarded

vault 🛠

Enables a vault provider.

CLI: --vault
Env: KC_VAULT

file, keystore

vault-dir

If set, secrets can be obtained by reading the content of files within the given directory.

CLI: --vault-dir
Env: KC_VAULT_DIR

vault-file

Path to the keystore file.

CLI: --vault-file
Env: KC_VAULT_FILE

vault-pass

Password for the vault keystore.

CLI: --vault-pass
Env: KC_VAULT_PASS

vault-type

Specifies the type of the keystore file.

CLI: --vault-type
Env: KC_VAULT_TYPE

PKCS12 (default)

log

Enable one or more log handlers in a comma-separated list.

CLI: --log
Env: KC_LOG

console, file

log-console-color

Enable or disable colors when logging to console.

CLI: --log-console-color
Env: KC_LOG_CONSOLE_COLOR

true, false (default)

log-console-format

The format of unstructured console log entries.

If the format has spaces in it, escape the value using "<format>".

CLI: --log-console-format
Env: KC_LOG_CONSOLE_FORMAT

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n (default)

log-console-output

Set the log output to JSON or default (plain) unstructured logging.

CLI: --log-console-output
Env: KC_LOG_CONSOLE_OUTPUT

default (default), json

log-file

Set the log file path and filename.

CLI: --log-file
Env: KC_LOG_FILE

data/log/keycloak.log (default)

log-file-format

Set a format specific to file log entries.

CLI: --log-file-format
Env: KC_LOG_FILE_FORMAT

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n (default)

log-file-output

Set the log output to JSON or default (plain) unstructured logging.

CLI: --log-file-output
Env: KC_LOG_FILE_OUTPUT

default (default), json

log-level

The log level of the root category or a comma-separated list of individual categories and their levels.

For the root category, you don’t need to specify a category.

CLI: --log-level
Env: KC_LOG_LEVEL

[info] (default)

tls-hostname-verifier

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

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

ANY, WILDCARD (default), STRICT

truststore-paths

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

CLI: --truststore-paths
Env: KC_TRUSTSTORE_PATHS

fips-mode 🛠

Sets the FIPS mode.

If non-strict is set, FIPS is enabled but on non-approved mode. For full FIPS compliance, set strict to run on approved mode. This option defaults to disabled when fips feature is disabled, which is by default. This option defaults to non-strict when fips feature is enabled.

CLI: --fips-mode
Env: KC_FIPS_MODE

non-strict, strict

dir

Set the path to a directory where files will be created with the exported data.

CLI: --dir
Env: KC_DIR

realm

Set the name of the realm to export.

If not set, all realms are going to be exported.

CLI: --realm
Env: KC_REALM

users

Set how users should be exported.

CLI: --users
Env: KC_USERS

skip, realm_file, same_file, different_files (default)

users-per-file

Set the number of users per file.

It is used only if users is set to different_files. Increasing this number leads to exponentially increasing export times.

CLI: --users-per-file
Env: KC_USERS_PER_FILE

50 (default)

file

Set the path to a file that will be read.

CLI: --file
Env: KC_FILE

override

Set if existing data should be overwritten.

If set to false, data will be ignored.

CLI: --override
Env: KC_OVERRIDE

true (default), false