Chapter 22. 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, 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

File

cache-config-mutate

Determines whether changes to the default cache configurations are allowed.

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

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

true, false

false

cache-embedded-authorization-max-count

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

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

Integer

cache-embedded-client-sessions-max-count

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

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

Available only when embedded Infinispan clusters configured

Integer

cache-embedded-crl-max-count

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

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

Integer

cache-embedded-keys-max-count

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

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

Integer

cache-embedded-mtls-enabled

Encrypts the network communication between Keycloak servers.

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

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

Available only when a TCP based cache-stack is used

true, false

true

cache-embedded-mtls-key-store-file

The Keystore file path.

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

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

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

String

cache-embedded-mtls-key-store-password

The password to access the Keystore.

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

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

String

cache-embedded-mtls-rotation-interval-days

Rotation period in days of automatic JGroups MTLS certificates.

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

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

Integer

30

cache-embedded-mtls-trust-store-file

The Truststore file path.

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

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

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

String

cache-embedded-mtls-trust-store-password

The password to access the Truststore.

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

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

String

cache-embedded-network-bind-address

IP address used by clustering transport.

By default, SITE_LOCAL is used.

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

Available only when Infinispan clustered embedded is enabled

String

cache-embedded-network-bind-port

The Port the clustering transport will bind to.

By default, port 7800 is used.

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

Available only when Infinispan clustered embedded is enabled

Integer

cache-embedded-network-external-address

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

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

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

Available only when Infinispan clustered embedded is enabled

String

cache-embedded-network-external-port

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

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

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

Available only when Infinispan clustered embedded is enabled

Integer

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

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

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

Available only when embedded Infinispan clusters configured

Integer

cache-embedded-offline-sessions-max-count

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

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

Available only when embedded Infinispan clusters configured

Integer

cache-embedded-realms-max-count

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

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

Integer

cache-embedded-sessions-max-count

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

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

Available only when embedded Infinispan clusters configured

Integer

cache-embedded-users-max-count

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

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

Integer

cache-metrics-histograms-enabled

Enable histograms for metrics for the embedded caches.

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

Available only when metrics are enabled

true, false

false

cache-remote-backup-sites

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

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

Available only when remote host is set

List

cache-remote-host

The hostname of the external Infinispan cluster.

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

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

String

cache-remote-password

The password for the authentication to the external Infinispan cluster.

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

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

Available only when remote host is set

String

cache-remote-port

The port of the external Infinispan cluster.

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

Available only when remote host is set

Integer

11222

cache-remote-tls-enabled

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

Recommended to be enabled in production.

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

Available only when remote host is set

true, false

true

cache-remote-username

The username for the authentication to the external Infinispan cluster.

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

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

Available only when remote host is set

String

cache-stack

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

Defaults to jdbc-ping if not set.

CLI: --cache-stack
Env: KC_CACHE_STACK

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

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

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

config-keystore

Specifies a path to the KeyStore Configuration Source.

CLI: --config-keystore
Env: KC_CONFIG_KEYSTORE

String

config-keystore-password

Specifies a password to the KeyStore Configuration Source.

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

String

config-keystore-type

Specifies a type of the KeyStore Configuration Source.

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

String

PKCS12

db 🛠

The database vendor.

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

Named key: db-kind-<datasource> 🛠

CLI: --db
Env: KC_DB

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

dev-file

db-connect-timeout

Sets the JDBC driver connection timeout and login timeout.

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

CLI: --db-connect-timeout
Env: KC_DB_CONNECT_TIMEOUT

String

10s

db-debug-jpql

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

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

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

true, false

false

db-driver 🛠

The fully qualified class name of the JDBC driver.

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

Named key: db-driver-<datasource> 🛠

CLI: --db-driver
Env: KC_DB_DRIVER

String

db-log-slow-queries-threshold

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

hibernate.SQL_SLOW and log-level info.

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

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

Integer

10000

db-password

The password of the database user.

Named key: db-password-<datasource>

CLI: --db-password
Env: KC_DB_PASSWORD

String

db-pool-initial-size

The initial size of the connection pool.

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

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

Integer

db-pool-max-lifetime

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

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

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

String

db-pool-max-size

The maximum size of the connection pool.

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

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

Integer

100

db-pool-min-size

The minimal size of the connection pool.

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

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

Integer

db-schema

The database schema to be used.

Named key: db-schema-<datasource>

CLI: --db-schema
Env: KC_DB_SCHEMA

String

db-tls-mode

Sets the TLS mode for the database connection.

If disabled, it uses the driver’s default value. When set to verify-server, it enables encryption and server identity verification. The database server certificate or Certificate Authority (CA) certificate is required.

Named key: db-tls-mode-<datasource>

CLI: --db-tls-mode
Env: KC_DB_TLS_MODE

disabled, verify-server

disabled

db-tls-trust-store-file

The path to the truststore file containing the database server certificates or Certificate Authority (CA) certificates used to verify the database server’s identity.

Named key: db-tls-trust-store-file-<datasource>

CLI: --db-tls-trust-store-file
Env: KC_DB_TLS_TRUST_STORE_FILE

File

db-tls-trust-store-password

The password to access the truststore file specified in db-tls-trust-store-file (if required and supported by the JDBC driver).

Named key: db-tls-trust-store-password-<datasource>

CLI: --db-tls-trust-store-password
Env: KC_DB_TLS_TRUST_STORE_PASSWORD

String

db-tls-trust-store-type

The type of the truststore file.

Common values include JKS (Java KeyStore) and PKCS12. If not specified, it uses the driver’s default.

Named key: db-tls-trust-store-type-<datasource>

CLI: --db-tls-trust-store-type
Env: KC_DB_TLS_TRUST_STORE_TYPE

String

db-url

The full database JDBC URL.

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

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

CLI: --db-url
Env: KC_DB_URL

String

db-url-database

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

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

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

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

String

db-url-host

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

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

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

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

String

db-url-port

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

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

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

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

Integer

db-url-properties

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

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

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

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

String

db-username

The username of the database user.

Named key: db-username-<datasource>

CLI: --db-username
Env: KC_DB_USERNAME

String

db-debug-jpql-<datasource>

Used for named <datasource>.

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

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

true, false

false

db-driver-<datasource> 🛠

Used for named <datasource>.

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

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

String

db-enabled-<datasource>

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

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

true, false

true

db-kind-<datasource> 🛠

Used for named <datasource>.

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

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

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

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

Used for named <datasource>.

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

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

Integer

10000

db-password-<datasource>

Used for named <datasource>.

The password of the database user.

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

String

db-pool-initial-size-<datasource>

Used for named <datasource>.

The initial size of the connection pool.

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

Integer

db-pool-max-size-<datasource>

Used for named <datasource>.

The maximum size of the connection pool.

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

Integer

100

db-pool-min-size-<datasource>

Used for named <datasource>.

The minimal size of the connection pool.

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

Integer

db-schema-<datasource>

Used for named <datasource>.

The database schema to be used.

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

String

db-tls-mode-<datasource>

Used for named <datasource>.

Sets the TLS mode for the database connection. If disabled, it uses the driver’s default value. When set to verify-server, it enables encryption and server identity verification. The database server certificate or Certificate Authority (CA) certificate is required.

CLI: --db-tls-mode-<datasource>
Env: KC_DB_TLS_MODE_<DATASOURCE>

disabled, verify-server

disabled

db-tls-trust-store-file-<datasource>

Used for named <datasource>.

The path to the truststore file containing the database server certificates or Certificate Authority (CA) certificates used to verify the database server’s identity.

CLI: --db-tls-trust-store-file-<datasource>
Env: KC_DB_TLS_TRUST_STORE_FILE_<DATASOURCE>

File

db-tls-trust-store-password-<datasource>

Used for named <datasource>.

The password to access the truststore file specified in db-tls-trust-store-file (if required and supported by the JDBC driver).

CLI: --db-tls-trust-store-password-<datasource>
Env: KC_DB_TLS_TRUST_STORE_PASSWORD_<DATASOURCE>

String

db-tls-trust-store-type-<datasource>

Used for named <datasource>.

The type of the truststore file. Common values include JKS (Java KeyStore) and PKCS12. If not specified, it uses the driver’s default.

CLI: --db-tls-trust-store-type-<datasource>
Env: KC_DB_TLS_TRUST_STORE_TYPE_<DATASOURCE>

String

db-url-database-<datasource>

Used for named <datasource>.

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

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

String

db-url-full-<datasource>

Used for named <datasource>.

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

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

String

db-url-host-<datasource>

Used for named <datasource>.

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

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

String

db-url-port-<datasource>

Used for named <datasource>.

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

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

Integer

db-url-properties-<datasource>

Used for named <datasource>.

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

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

String

db-username-<datasource>

Used for named <datasource>.

The username of the database user.

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

String

transaction-default-timeout

The default transaction timeout.

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

CLI: --transaction-default-timeout
Env: KC_TRANSACTION_DEFAULT_TIMEOUT

String

5m

transaction-setup-timeout

The transaction timeout for database migration/import/export transactions.

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

CLI: --transaction-setup-timeout
Env: KC_TRANSACTION_SETUP_TIMEOUT

String

30m

transaction-xa-enabled 🛠

If set to true, XA datasources will be used.

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

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

true, false

false

transaction-xa-enabled-<datasource> 🛠

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

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

true, false

true

feature-<name> 🛠

Enable/Disable specific feature <feature>.

It takes precedence over the features, and features-disabled options. Possible values are: enabled, disabled, or specific version (lowercase) that will be enabled (f.e. v2)

CLI: --feature-<name>
Env: KC_FEATURE_<NAME>

String

features 🛠

Enables a set of one or more features.

CLI: --features
Env: KC_FEATURES

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

features-disabled 🛠

Disables a set of one or more features.

CLI: --features-disabled
Env: KC_FEATURES_DISABLED

account, account-api, admin, admin-api, admin-fine-grained-authz, authorization, ciba, cimd, client-admin-api, client-auth-federated, client-policies, client-secret-rotation, client-types, clusterless, db-tidb, declarative-ui, device-flow, docker, dpop, dynamic-scopes, fips, http-optimized-serializers, identity-brokering-api, impersonation, instagram-broker, ipa-tuura-federation, jwt-authorization-grant, kerberos, kubernetes-service-accounts, log-mdc, login, logout-all-sessions, multi-site, oid4vc-vci, oid4vc-vci-preauth-code, openapi, opentelemetry, opentelemetry-logs, opentelemetry-metrics, organization, par, passkeys, passkeys-conditional-ui-authenticator, persistent-user-sessions, preview, quick-theme, recovery-codes, resource-indicators, scim-api, scripts, spiffe, step-up-authentication, step-up-authentication-saml, token-exchange, token-exchange-external-internal, token-exchange-standard, transient-users, update-email, user-event-metrics, web-authn, workflows

hostname

Address at which is the server exposed.

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

CLI: --hostname
Env: KC_HOSTNAME

Available only when hostname:v2 feature is enabled

String

hostname-admin

Address for accessing the administration console.

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

CLI: --hostname-admin
Env: KC_HOSTNAME_ADMIN

Available only when hostname:v2 feature is enabled

String

hostname-backchannel-dynamic

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

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

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

Available only when hostname:v2 feature is enabled

true, false

false

hostname-debug

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

CLI: --hostname-debug
Env: KC_HOSTNAME_DEBUG

Available only when hostname:v2 feature is enabled

true, false

false

hostname-strict

Disables dynamically resolving the hostname from request headers.

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

CLI: --hostname-strict
Env: KC_HOSTNAME_STRICT

Available only when hostname:v2 feature is enabled

true, false

true

http-accept-non-normalized-paths

If the server should accept paths that are not normalized according to RFC3986 or that contain a double slash (//) or semicolon (;).

While accepting those requests might be relevant for legacy applications, it is recommended to disable it to allow for more concise URL filtering.

CLI: --http-accept-non-normalized-paths
Env: KC_HTTP_ACCEPT_NON_NORMALIZED_PATHS

DEPRECATED.

true, false

false

http-enabled

Enables the HTTP listener.

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

CLI: --http-enabled
Env: KC_HTTP_ENABLED

true, false

false

http-host

The HTTP Host.

In prod mode or when running on Windows Subsystem For Linux the default is to bind to all network addresses (0.0.0.0), which means the server may be accessible from other machines on your network. Otherwise defaults to localhost.

CLI: --http-host
Env: KC_HTTP_HOST

String

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

Integer

http-metrics-histograms-enabled

Enables a histogram with default buckets for the duration of HTTP server requests.

CLI: --http-metrics-histograms-enabled
Env: KC_HTTP_METRICS_HISTOGRAMS_ENABLED

Available only when metrics are enabled

true, false

false

http-metrics-slos

Service level objectives for HTTP server requests.

Use this instead of the default histogram, or use it in combination to add additional buckets. Specify a list of comma-separated values defined in milliseconds. Example with buckets from 5ms to 10s: 5,10,25,50,250,500,1000,2500,5000,10000

CLI: --http-metrics-slos
Env: KC_HTTP_METRICS_SLOS

Available only when metrics are enabled

String

http-pool-max-threads

The maximum number of threads.

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

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

Integer

http-port

The used HTTP port.

CLI: --http-port
Env: KC_HTTP_PORT

Integer

8080

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

String

/

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

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

File

https-certificates-reload-period

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

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

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

String

1h

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

String

https-client-auth 🛠

Configures the server to require/request client authentication.

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

none, request, required

none

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

File

https-key-store-password

The password of the key store file.

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

String

password

https-key-store-type

The type of the key store file.

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

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

String

https-port

The used HTTPS port.

CLI: --https-port
Env: KC_HTTPS_PORT

Integer

8443

https-protocols

The list of protocols to explicitly enable.

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

CLI: --https-protocols
Env: KC_HTTPS_PROTOCOLS

TLSv1.3, TLSv1.2, or any

TLSv1.3,TLSv1.2

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

File

https-trust-store-password

The password of the trust store file.

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

String

https-trust-store-type

The type of the trust store file.

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

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

String

shutdown-delay

Length of the pre-shutdown phase during which the server prepares for shutdown.

May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. This period allows for loadbalancer reconfiguration and draining of TLS/HTTP keepalive connections.

CLI: --shutdown-delay
Env: KC_SHUTDOWN_DELAY

String

1s

shutdown-timeout

The shutdown period waiting for currently running HTTP requests to finish.

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

CLI: --shutdown-timeout
Env: KC_SHUTDOWN_TIMEOUT

String

1s

http-access-log-enabled

If HTTP access logging is enabled.

By default this will log records in console.

CLI: --http-access-log-enabled
Env: KC_HTTP_ACCESS_LOG_ENABLED

true, false

false

http-access-log-exclude

A regular expression that can be used to exclude some paths from logging.

For instance, /realms/my-realm/.* will exclude all subsequent endpoints for realm my-realm from the log.

CLI: --http-access-log-exclude
Env: KC_HTTP_ACCESS_LOG_EXCLUDE

Available only when HTTP Access log is enabled

String

http-access-log-file-enabled

If HTTP access logging should be done to a separate file.

CLI: --http-access-log-file-enabled
Env: KC_HTTP_ACCESS_LOG_FILE_ENABLED

Available only when HTTP Access log is enabled

true, false

false

http-access-log-file-name

The HTTP access log file base name, which will create a log file name concatenating base and suffix (e.

g. keycloak-http-access.log). The file is located in the /data/log directory of the distribution.

CLI: --http-access-log-file-name
Env: KC_HTTP_ACCESS_LOG_FILE_NAME

Available only when HTTP Access logging to file is enabled

String

keycloak-http-access

http-access-log-file-rotate

If the HTTP Access log file should be rotated daily.

CLI: --http-access-log-file-rotate
Env: KC_HTTP_ACCESS_LOG_FILE_ROTATE

Available only when HTTP Access logging to file is enabled

true, false

true

http-access-log-file-suffix

The HTTP access log file suffix.

When rotation is enabled, a date-based suffix .{yyyy-MM-dd} is added before the specified suffix. If multiple rotations occur on the same day, an incremental index is appended to the date.

CLI: --http-access-log-file-suffix
Env: KC_HTTP_ACCESS_LOG_FILE_SUFFIX

Available only when HTTP Access logging to file is enabled

String

.log

http-access-log-masked-cookies

Set of HTTP Cookie headers whose values must be masked when the long pattern or %{ALL_REQUEST_HEADERS} format is enabled with the http-access-log-pattern option.

Selected security sensitive cookies are always masked.

CLI: --http-access-log-masked-cookies
Env: KC_HTTP_ACCESS_LOG_MASKED_COOKIES

Available only when HTTP Access log is enabled

List

http-access-log-masked-headers

Set of HTTP headers whose values must be masked when the long pattern or %{ALL_REQUEST_HEADERS} format is enabled with the http-access-log-pattern option.

Selected security sensitive headers are always masked.

CLI: --http-access-log-masked-headers
Env: KC_HTTP_ACCESS_LOG_MASKED_HEADERS

Available only when HTTP Access log is enabled

List

http-access-log-pattern

The HTTP access log pattern.

You can use the available named formats, or use custom format described in Quarkus documentation.

CLI: --http-access-log-pattern
Env: KC_HTTP_ACCESS_LOG_PATTERN

Available only when HTTP Access log is enabled

common, combined, long, or any

common

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

false

http-management-health-enabled 🛠

If health endpoints should be exposed on the management interface.

If false, health endpoints will be exposed on the main interface.

CLI: --http-management-health-enabled
Env: KC_HTTP_MANAGEMENT_HEALTH_ENABLED

Available only when health is enabled

true, false

true

http-management-port

Port of the management interface.

Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --http-management-port
Env: KC_HTTP_MANAGEMENT_PORT

Integer

9000

http-management-relative-path 🛠

Set the path relative to / for serving resources from management interface.

The path must start with a /. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.

CLI: --http-management-relative-path
Env: KC_HTTP_MANAGEMENT_RELATIVE_PATH

String

/

http-management-scheme

Configures the management interface scheme.

If inherited, the management interface will inherit the HTTPS settings of the main interface. If http, the management interface will be accessible via HTTP - it will not inherit HTTPS settings and cannot be configured for HTTPS.

CLI: --http-management-scheme
Env: KC_HTTP_MANAGEMENT_SCHEME

http, inherited

inherited

https-management-certificate-file

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

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

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

Available only when http-management-scheme is inherited

File

https-management-certificate-key-file

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

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

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

Available only when http-management-scheme is inherited

File

https-management-certificates-reload-period

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

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

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

Available only when http-management-scheme is inherited

String

1h

https-management-client-auth 🛠

Configures the management interface to require/request client authentication.

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

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

none, request, required

none

https-management-key-store-file

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

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

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

Available only when http-management-scheme is inherited

File

https-management-key-store-password

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

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

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

Available only when http-management-scheme is inherited

String

password

legacy-observability-interface 🛠

If metrics/health endpoints should be exposed on the main HTTP server (not recommended).

If set to true, the management interface is disabled.

CLI: --legacy-observability-interface
Env: KC_LEGACY_OBSERVABILITY_INTERFACE

DEPRECATED.

true, false

false

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

false

proxy-headers

The proxy headers that should be accepted by the server.

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

CLI: --proxy-headers
Env: KC_PROXY_HEADERS

forwarded, xforwarded

proxy-protocol-enabled

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

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

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

true, false

false

proxy-trusted-addresses

A comma separated list of trusted proxy addresses.

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

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

List

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

Path

vault-file

Path to the keystore file.

CLI: --vault-file
Env: KC_VAULT_FILE

Path

vault-pass

Password for the vault keystore.

CLI: --vault-pass
Env: KC_VAULT_PASS

String

vault-type

Specifies the type of the keystore file.

CLI: --vault-type
Env: KC_VAULT_TYPE

String

PKCS12

log

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

CLI: --log
Env: KC_LOG

console, file, syslog

console

log-async

Indicates whether to log asynchronously to all handlers.

CLI: --log-async
Env: KC_LOG_ASYNC

true, false

false

log-console-async

Indicates whether to log asynchronously to console.

If not set, value from the parent property log-async is used.

CLI: --log-console-async
Env: KC_LOG_CONSOLE_ASYNC

Available only when Console log handler is activated

true, false

false

log-console-async-queue-length

The queue length to use before flushing writing when logging to console.

CLI: --log-console-async-queue-length
Env: KC_LOG_CONSOLE_ASYNC_QUEUE_LENGTH

Available only when Console log handler is activated and asynchronous logging is enabled

Integer

512

log-console-color

Enable or disable colors when logging to console.

If this is not present then an attempt will be made to guess if the terminal supports color.

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

Available only when Console log handler is activated

true, false

log-console-format

The format of unstructured console log entries.

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

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

Available only when Console log handler is activated

String

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

log-console-include-mdc

Include mdc information in the console log.

If the log-console-format option is specified, this option has no effect.

CLI: --log-console-include-mdc
Env: KC_LOG_CONSOLE_INCLUDE_MDC

Available only when Console log handler and MDC logging are activated

true, false

true

log-console-include-trace

Include tracing information in the console log.

If the log-console-format option is specified, this option has no effect.

CLI: --log-console-include-trace
Env: KC_LOG_CONSOLE_INCLUDE_TRACE

Available only when Console log handler and Tracing is activated

true, false

true

log-console-json-format

Set the format of the produced JSON.

CLI: --log-console-json-format
Env: KC_LOG_CONSOLE_JSON_FORMAT

Available only when Console log handler is activated and output is set to 'json'

default, ecs

default

log-console-level

Set the log level for the console handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-console-level
Env: KC_LOG_CONSOLE_LEVEL

Available only when Console log handler is activated

off, fatal, error, warn, info, debug, trace, all

all

log-console-output

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

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

Available only when Console log handler is activated

default, json

default

log-file

Set the log file path and filename.

CLI: --log-file
Env: KC_LOG_FILE

Available only when File log handler is activated

File

data/log/keycloak.log

log-file-async

Indicates whether to log asynchronously to file log.

If not set, value from the parent property log-async is used.

CLI: --log-file-async
Env: KC_LOG_FILE_ASYNC

Available only when File log handler is activated

true, false

false

log-file-async-queue-length

The queue length to use before flushing writing when logging to file log.

CLI: --log-file-async-queue-length
Env: KC_LOG_FILE_ASYNC_QUEUE_LENGTH

Available only when File log handler is activated and asynchronous logging is enabled

Integer

512

log-file-format

Set a format specific to file log entries.

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

Available only when File log handler is activated

String

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

log-file-include-mdc

Include MDC information in the file log.

If the log-file-format option is specified, this option has no effect.

CLI: --log-file-include-mdc
Env: KC_LOG_FILE_INCLUDE_MDC

Available only when File log handler and MDC logging are activated

true, false

true

log-file-include-trace

Include tracing information in the file log.

If the log-file-format option is specified, this option has no effect.

CLI: --log-file-include-trace
Env: KC_LOG_FILE_INCLUDE_TRACE

Available only when File log handler and Tracing is activated

true, false

true

log-file-json-format

Set the format of the produced JSON.

CLI: --log-file-json-format
Env: KC_LOG_FILE_JSON_FORMAT

Available only when File log handler is activated and output is set to 'json'

default, ecs

default

log-file-level

Set the log level for the file handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-file-level
Env: KC_LOG_FILE_LEVEL

Available only when File log handler is activated

off, fatal, error, warn, info, debug, trace, all

all

log-file-output

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

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

Available only when File log handler is activated

default, json

default

log-file-rotation-enabled

Enables log file rotation.

CLI: --log-file-rotation-enabled
Env: KC_LOG_FILE_ROTATION_ENABLED

Available only when File log handler is activated

true, false

true

log-file-rotation-file-suffix

Set the log file handler rotation file suffix.

When used, the file will be rotated based on its suffix. Example: .yyyy-MM-dd to rotate daily. Note: If the suffix ends with .zip or .gz, the rotation file will also be compressed.

CLI: --log-file-rotation-file-suffix
Env: KC_LOG_FILE_ROTATION_FILE_SUFFIX

Available only when File log handler is activated and log file rotation is enabled

String

log-file-rotation-max-backup-index

The maximum number of backup log files to keep.

CLI: --log-file-rotation-max-backup-index
Env: KC_LOG_FILE_ROTATION_MAX_BACKUP_INDEX

Available only when File log handler is activated and log file rotation is enabled

Integer

5

log-file-rotation-max-file-size

The maximum log file size, after which a rotation is executed.

Supports size suffixes (e.g. 10M, 1G).

CLI: --log-file-rotation-max-file-size
Env: KC_LOG_FILE_ROTATION_MAX_FILE_SIZE

Available only when File log handler is activated and log file rotation is enabled

String

10M

log-file-rotation-rotate-on-boot

Indicates whether to rotate log files on server start.

CLI: --log-file-rotation-rotate-on-boot
Env: KC_LOG_FILE_ROTATION_ROTATE_ON_BOOT

Available only when File log handler is activated and log file rotation is enabled

true, false

true

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

List

info

log-level-<category>

The log level of a category.

Takes precedence over the log-level option.

CLI: --log-level-<category>
Env: KC_LOG_LEVEL_<CATEGORY>

off, fatal, error, warn, info, debug, trace, all

log-mdc-enabled 🛠

Indicates whether to add information about the realm and other information to the mapped diagnostic context.

All elements will be prefixed with kc.

CLI: --log-mdc-enabled
Env: KC_LOG_MDC_ENABLED

Available only when log-mdc preview feature is enabled

true, false

false

log-mdc-keys

Defines which information should be added to the mapped diagnostic context as a comma-separated list.

CLI: --log-mdc-keys
Env: KC_LOG_MDC_KEYS

Available only when MDC logging is enabled

realmName, clientId, userId, ipAddress, org, sessionId, authenticationSessionId, authenticationTabId

realmName,clientId,org,sessionId,authenticationSessionId,authenticationTabId

log-service-environment

Set the `service.

environment` field in JSON log entries for all log handlers. In ECS format, defaults to the Quarkus profile if not set.

CLI: --log-service-environment
Env: KC_LOG_SERVICE_ENVIRONMENT

String

log-service-name

Set the `service.

name` field in JSON log entries for all log handlers.

CLI: --log-service-name
Env: KC_LOG_SERVICE_NAME

String

keycloak

log-syslog-app-name

Set the app name used when formatting the message in RFC5424 format.

CLI: --log-syslog-app-name
Env: KC_LOG_SYSLOG_APP_NAME

Available only when Syslog is activated

String

keycloak

log-syslog-async

Indicates whether to log asynchronously to Syslog.

If not set, value from the parent property log-async is used.

CLI: --log-syslog-async
Env: KC_LOG_SYSLOG_ASYNC

Available only when Syslog is activated

true, false

false

log-syslog-async-queue-length

The queue length to use before flushing writing when logging to Syslog.

CLI: --log-syslog-async-queue-length
Env: KC_LOG_SYSLOG_ASYNC_QUEUE_LENGTH

Available only when Syslog is activated and asynchronous logging is enabled

Integer

512

log-syslog-counting-framing

If true, the message being sent is prefixed with the size of the message.

If protocol-dependent, the default value is true when log-syslog-protocol is tcp or ssl-tcp, otherwise false.

CLI: --log-syslog-counting-framing
Env: KC_LOG_SYSLOG_COUNTING_FRAMING

Available only when Syslog is activated

true, false, protocol-dependent

protocol-dependent

log-syslog-endpoint

Set the IP address and port of the Syslog server.

CLI: --log-syslog-endpoint
Env: KC_LOG_SYSLOG_ENDPOINT

Available only when Syslog is activated

String

localhost:514

log-syslog-format

Set a format specific to Syslog entries.

CLI: --log-syslog-format
Env: KC_LOG_SYSLOG_FORMAT

Available only when Syslog is activated

String

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

log-syslog-include-mdc

Include MDC information in the Syslog.

If the log-syslog-format option is specified, this option has no effect.

CLI: --log-syslog-include-mdc
Env: KC_LOG_SYSLOG_INCLUDE_MDC

Available only when Syslog handler and MDC logging are activated

true, false

true

log-syslog-include-trace

Include tracing information in the Syslog.

If the log-syslog-format option is specified, this option has no effect.

CLI: --log-syslog-include-trace
Env: KC_LOG_SYSLOG_INCLUDE_TRACE

Available only when Syslog handler and Tracing is activated

true, false

true

log-syslog-json-format

Set the format of the produced JSON.

CLI: --log-syslog-json-format
Env: KC_LOG_SYSLOG_JSON_FORMAT

Available only when Syslog is activated and output is set to 'json'

default, ecs

default

log-syslog-level

Set the log level for the Syslog handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

CLI: --log-syslog-level
Env: KC_LOG_SYSLOG_LEVEL

Available only when Syslog is activated

off, fatal, error, warn, info, debug, trace, all

all

log-syslog-max-length

Set the maximum length, in bytes, of the message allowed to be sent.

The length includes the header and the message. If not set, the default value is 2048 when log-syslog-type is rfc5424 (default) and 1024 when log-syslog-type is rfc3164.

CLI: --log-syslog-max-length
Env: KC_LOG_SYSLOG_MAX_LENGTH

Available only when Syslog is activated

String

log-syslog-output

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

CLI: --log-syslog-output
Env: KC_LOG_SYSLOG_OUTPUT

Available only when Syslog is activated

default, json

default

log-syslog-protocol

Set the protocol used to connect to the Syslog server.

CLI: --log-syslog-protocol
Env: KC_LOG_SYSLOG_PROTOCOL

Available only when Syslog is activated

tcp, udp, ssl-tcp

tcp

log-syslog-type

Set the Syslog type used to format the sent message.

CLI: --log-syslog-type
Env: KC_LOG_SYSLOG_TYPE

Available only when Syslog is activated

rfc5424, rfc3164

rfc5424

telemetry-endpoint

OpenTelemetry endpoint to connect to.

CLI: --telemetry-endpoint
Env: KC_TELEMETRY_ENDPOINT

Available only when any of available OpenTelemetry components (Logs, Metrics, Traces) is turned on

String

http://localhost:4317

telemetry-header-<header>

General OpenTelemetry header that will be part of the exporter request (mainly useful for providing Authorization header).

Check the documentation on how to set environment variables for headers containing special characters or custom case-sensitive headers.

CLI: --telemetry-header-<header>
Env: KC_TELEMETRY_HEADER_<HEADER>

Available only when any of available OpenTelemetry components (Logs, Metrics, Traces) is turned on

String

telemetry-logs-enabled 🛠

Enables exporting logs to a destination handling OpenTelemetry logs.

CLI: --telemetry-logs-enabled
Env: KC_TELEMETRY_LOGS_ENABLED

Available only when feature 'opentelemetry-logs:v1' is enabled

true, false

false

telemetry-logs-endpoint

OpenTelemetry endpoint to export logs to.

If not given, the value is inherited from the telemetry-endpoint option.

CLI: --telemetry-logs-endpoint
Env: KC_TELEMETRY_LOGS_ENDPOINT

Available only when Telemetry Logs functionality ('telemetry-logs-enabled') is enabled

String

telemetry-logs-header-<header>

OpenTelemetry header that will be part of the log exporter request (mainly useful for providing Authorization header).

Check the documentation on how to set environment variables for headers containing special characters or custom case-sensitive headers.

CLI: --telemetry-logs-header-<header>
Env: KC_TELEMETRY_LOGS_HEADER_<HEADER>

Available only when Telemetry Logs functionality ('telemetry-logs-enabled') is enabled

String

telemetry-logs-level

The most verbose log level exported to the telemetry endpoint.

For more information, check the Telemetry guide.

CLI: --telemetry-logs-level
Env: KC_TELEMETRY_LOGS_LEVEL

Available only when Telemetry Logs functionality ('telemetry-logs-enabled') is enabled

off, fatal, error, warn, info, debug, trace, all

all

telemetry-logs-protocol

OpenTelemetry protocol used for exporting logs.

If not given, the value is inherited from the telemetry-protocol option.

CLI: --telemetry-logs-protocol
Env: KC_TELEMETRY_LOGS_PROTOCOL

Available only when Telemetry Logs functionality ('telemetry-logs-enabled') is enabled

grpc, http/protobuf

telemetry-metrics-enabled 🛠

Enables exporting metrics to a destination handling OpenTelemetry metrics.

CLI: --telemetry-metrics-enabled
Env: KC_TELEMETRY_METRICS_ENABLED

Available only when metrics and feature 'opentelemetry-metrics:v1' are enabled

true, false

false

telemetry-metrics-endpoint

OpenTelemetry endpoint to connect to for Metrics.

If not given, the value is inherited from the telemetry-endpoint option.

CLI: --telemetry-metrics-endpoint
Env: KC_TELEMETRY_METRICS_ENDPOINT

Available only when metrics ('metrics-enabled') and Telemetry Metrics functionality ('telemetry-metrics-enabled') are enabled

String

telemetry-metrics-header-<header>

OpenTelemetry header that will be part of the metrics exporter request (mainly useful for providing Authorization header).

Check the documentation on how to set environment variables for headers containing special characters or custom case-sensitive headers.

CLI: --telemetry-metrics-header-<header>
Env: KC_TELEMETRY_METRICS_HEADER_<HEADER>

Available only when metrics ('metrics-enabled') and Telemetry Metrics functionality ('telemetry-metrics-enabled') are enabled

String

telemetry-metrics-interval

The interval between the start of two metric export attempts to the destination handling OpenTelemetry metrics data.

It accepts simplified format for time units as java.time.Duration (like 5000ms, 30s, 5m, 1h). If the value is only a number, it represents time in seconds.

CLI: --telemetry-metrics-interval
Env: KC_TELEMETRY_METRICS_INTERVAL

Available only when metrics ('metrics-enabled') and Telemetry Metrics functionality ('telemetry-metrics-enabled') are enabled

String

60s

telemetry-metrics-protocol

OpenTelemetry protocol used for the metrics telemetry data.

If not given, the value is inherited from the telemetry-protocol option.

CLI: --telemetry-metrics-protocol
Env: KC_TELEMETRY_METRICS_PROTOCOL

Available only when metrics ('metrics-enabled') and Telemetry Metrics functionality ('telemetry-metrics-enabled') are enabled

grpc, http/protobuf

telemetry-protocol

OpenTelemetry protocol used for the communication between server and OpenTelemetry collector.

CLI: --telemetry-protocol
Env: KC_TELEMETRY_PROTOCOL

Available only when any of available OpenTelemetry components (Logs, Metrics, Traces) is turned on

grpc, http/protobuf

grpc

telemetry-resource-attributes

OpenTelemetry resource attributes characterize the telemetry producer.

Values in format key1=val1,key2=val2.

CLI: --telemetry-resource-attributes
Env: KC_TELEMETRY_RESOURCE_ATTRIBUTES

Available only when any of available OpenTelemetry components (Logs, Metrics, Traces) is turned on

List

telemetry-service-name

OpenTelemetry service name.

Takes precedence over service.name defined in the telemetry-resource-attributes property.

CLI: --telemetry-service-name
Env: KC_TELEMETRY_SERVICE_NAME

Available only when any of available OpenTelemetry components (Logs, Metrics, Traces) is turned on

String

keycloak

tracing-compression

OpenTelemetry compression method used to compress payloads.

If unset, compression is disabled.

CLI: --tracing-compression
Env: KC_TRACING_COMPRESSION

Available only when Tracing is enabled

gzip, none

none

tracing-enabled 🛠

Enables the OpenTelemetry tracing.

CLI: --tracing-enabled
Env: KC_TRACING_ENABLED

Available only when 'opentelemetry' feature is enabled

true, false

false

tracing-endpoint

OpenTelemetry endpoint to connect to for traces.

If not given, the value is inherited from the telemetry-endpoint option.

CLI: --tracing-endpoint
Env: KC_TRACING_ENDPOINT

Available only when Tracing is enabled

String

http://localhost:4317

tracing-header-<header>

OpenTelemetry header that will be part of the exporter request (mainly useful for providing Authorization header).

Check the documentation on how to set environment variables for headers containing special characters or custom case-sensitive headers.

CLI: --tracing-header-<header>
Env: KC_TRACING_HEADER_<HEADER>

Available only when Tracing is enabled

String

tracing-infinispan-enabled

Enables the OpenTelemetry tracing for embedded Infinispan.

CLI: --tracing-infinispan-enabled
Env: KC_TRACING_INFINISPAN_ENABLED

Available only when tracing and embedded Infinispan is enabled

true, false

true

tracing-jdbc-enabled 🛠

Enables the OpenTelemetry JDBC tracing.

CLI: --tracing-jdbc-enabled
Env: KC_TRACING_JDBC_ENABLED

Available only when Tracing is enabled

true, false

true

tracing-protocol

OpenTelemetry protocol used for the telemetry data.

If not given, the value is inherited from the telemetry-protocol option.

CLI: --tracing-protocol
Env: KC_TRACING_PROTOCOL

Available only when Tracing is enabled

grpc, http/protobuf

grpc

tracing-resource-attributes

OpenTelemetry resource attributes present in the exported trace to characterize the telemetry producer.

Values in format key1=val1,key2=val2. If not given, the value is inherited from the telemetry-resource-attributes option. For more information, check the Tracing guide.

CLI: --tracing-resource-attributes
Env: KC_TRACING_RESOURCE_ATTRIBUTES

Available only when Tracing is enabled

DEPRECATED. Resource attributes are not directly related to Tracing and you should use the Telemetry option which takes precedence. Use: telemetry-resource-attributes.

List

tracing-sampler-ratio

OpenTelemetry sampler ratio.

Probability that a span will be sampled. Expected double value in interval [0,1].

CLI: --tracing-sampler-ratio
Env: KC_TRACING_SAMPLER_RATIO

Available only when Tracing is enabled

Double

1.0

tracing-sampler-type 🛠

OpenTelemetry sampler to use for tracing.

CLI: --tracing-sampler-type
Env: KC_TRACING_SAMPLER_TYPE

Available only when Tracing is enabled

always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio

traceidratio

tracing-service-name

OpenTelemetry service name.

Takes precedence over service.name defined in the tracing-resource-attributes property. If not given, the value is inherited from the telemetry-service-name option.

CLI: --tracing-service-name
Env: KC_TRACING_SERVICE_NAME

Available only when Tracing is enabled

DEPRECATED. Service name is not directly related to Tracing and you should use the Telemetry option which takes precedence. Use: telemetry-service-name.

String

keycloak

event-metrics-user-enabled 🛠

Create metrics based on user events.

CLI: --event-metrics-user-enabled
Env: KC_EVENT_METRICS_USER_ENABLED

Available only when metrics are enabled and feature user-event-metrics is enabled

true, false

false

event-metrics-user-events

Comma-separated list of events to be collected for user event metrics.

This option can be used to reduce the number of metrics created as by default all user events create a metric.

CLI: --event-metrics-user-events
Env: KC_EVENT_METRICS_USER_EVENTS

Available only when user event metrics are enabled

Use remove_credential instead of remove_totp, and update_credential instead of update_totp and update_password. Deprecated values: remove_totp, update_totp, update_password

authreqid_to_token, client_delete, client_info, client_initiated_account_linking, client_login, client_register, client_update, code_to_token, custom_required_action, delete_account, execute_action_token, execute_actions, federated_identity_link, federated_identity_override_link, grant_consent, identity_provider_first_login, identity_provider_link_account, identity_provider_login, identity_provider_post_login, identity_provider_response, identity_provider_retrieve_token, impersonate, introspect_token, invalid_signature, invite_org, jwt_authorization_grant, login, logout, oauth2_device_auth, oauth2_device_code_to_token, oauth2_device_verify_user_code, oauth2_extension_grant, permission_token, pushed_authorization_request, refresh_token, register, register_node, remove_credential, remove_federated_identity, remove_totp (deprecated), reset_password, restart_authentication, revoke_grant, send_identity_provider_link, send_reset_password, send_verify_email, token_exchange, unregister_node, update_consent, update_credential, update_email, update_password (deprecated), update_profile, update_totp (deprecated), user_disabled_by_permanent_lockout, user_disabled_by_temporary_lockout, user_info_request, user_session_deleted, verifiable_credential_create_offer, verifiable_credential_nonce_request, verifiable_credential_offer_request, verifiable_credential_pre_authorized_grant, verifiable_credential_request, verify_email, verify_profile

event-metrics-user-tags

Comma-separated list of tags to be collected for user event metrics.

By default only realm is enabled to avoid a high metrics cardinality.

CLI: --event-metrics-user-tags
Env: KC_EVENT_METRICS_USER_TAGS

Available only when user event metrics are enabled

realm, idp, clientId

realm

tls-hostname-verifier

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

ANY should not be used in production.

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

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

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

DEFAULT

truststore-kubernetes-enabled

If enabled, the server will automatically include the default Kubernetes service account CA certificate from "/var/run/secrets/kubernetes.

io/serviceaccount/ca.crt" and the OpenShift service CA certificate from "/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt" when running in a container environment.

CLI: --truststore-kubernetes-enabled
Env: KC_TRUSTSTORE_KUBERNETES_ENABLED

true, false

true

truststore-paths

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

CLI: --truststore-paths
Env: KC_TRUSTSTORE_PATHS

List

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

disabled

dir

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

CLI: --dir
Env: KC_DIR

String

file

Set the path to a file that will be created with the exported data.

To export more than 50000 users, export to a directory with different files instead.

CLI: --file
Env: KC_FILE

String

realm

Set the name of the realm to export.

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

CLI: --realm
Env: KC_REALM

String

users

Set how users should be exported.

CLI: --users
Env: KC_USERS

skip, realm_file, same_file, different_files

different_files

users-per-file

Set the number of users per file.

It is used only if users is set to different_files.

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

Integer

50

dir

Set the path to a directory where files will be read from.

CLI: --dir
Env: KC_DIR

String

file

Set the path to a file that will be read.

CLI: --file
Env: KC_FILE

String

override

Set if existing data should be overwritten.

If set to false, data will be ignored.

CLI: --override
Env: KC_OVERRIDE

true, false

true

openapi-enabled 🛠

If the server should expose OpenAPI Endpoint.

If enabled, OpenAPI is available at /openapi.

CLI: --openapi-enabled
Env: KC_OPENAPI_ENABLED

Available only when OpenAPI feature is enabled

true, false

false

openapi-ui-enabled 🛠

If the server should expose OpenApi-UI Endpoint.

If enabled, OpenAPI UI is available at /openapi/ui.

CLI: --openapi-ui-enabled
Env: KC_OPENAPI_UI_ENABLED

Available only when OpenAPI Endpoint is enabled

true, false

false

server-async-bootstrap

If true, endpoints are opened while the bootstrap runs in the background.

If false, endpoints are opened after bootstrap completes, ensuring the server is ready to handle requests. Async bootstrap is enabled by default when the health endpoints are also enabled, unless this option is explicitly set to false.

CLI: --server-async-bootstrap
Env: KC_SERVER_ASYNC_BOOTSTRAP

true, false

bootstrap-admin-client-id

Client id for the temporary bootstrap admin service account.

Used only when the master realm is created. Available only when bootstrap admin client secret is set.

CLI: --bootstrap-admin-client-id
Env: KC_BOOTSTRAP_ADMIN_CLIENT_ID

String

temp-admin

bootstrap-admin-client-secret

Client secret for the temporary bootstrap admin service account.

Used only when the master realm is created. Use a non-CLI configuration option for this option if possible.

CLI: --bootstrap-admin-client-secret
Env: KC_BOOTSTRAP_ADMIN_CLIENT_SECRET

String

bootstrap-admin-password

Temporary bootstrap admin password.

Used only when the master realm is created. Use a non-CLI configuration option for this option if possible.

CLI: --bootstrap-admin-password
Env: KC_BOOTSTRAP_ADMIN_PASSWORD

String

bootstrap-admin-username

Temporary bootstrap admin username.

Used only when the master realm is created. Available only when bootstrap admin password is set.

CLI: --bootstrap-admin-username
Env: KC_BOOTSTRAP_ADMIN_USERNAME

String

temp-admin