Configuring TLS

Configure Keycloak's https certificates for ingoing and outgoing requests.

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

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

Providing certificates in PEM format

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.

Providing a Keystore

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

Recognized file extensions for a keystore:

  • .p12, .pkcs12, and .pfx for a pkcs12 file

  • .jks, and .keystore for a jks file

  • .key, .crt, and .pem for a pem file

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

Setting the Keystore password

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

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

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

Securing credentials

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

Configuring TLS protocols

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

bin/kc.[sh|bat] start --https-protocols=<protocol>[,<protocol>]

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

Switching the HTTPS port

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

bin/kc.[sh|bat] start --https-port=<port>

Certificate and Key Reloading

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

Relevant options

Type or Values Default

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

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

Management server

Type or Values Default

https-management-certificate-file

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

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

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

Available only when http-management-scheme is inherited

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-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
On this page
Edit this guide