bin/kc.[sh|bat] start --https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pemTransport 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.
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.pemKeycloak creates a keystore out of these files in memory and uses this keystore afterwards.
When no keystore file is explicitly configured, but http-enabled is set to false, Keycloak looks for a conf/server.keystore file.
As an alternative, you can use an existing keystore by running the following command:
bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-fileYou 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.
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>]To also allow TLSv1.2, use a command such as the following: kc.sh start --https-protocols=TLSv1.3,TLSv1.2.
Keycloak listens for HTTPS traffic on port 8443. To change this port, use the following command:
bin/kc.[sh|bat] start --https-port=<port>In order to properly validate client certificates and enable certain authentication methods like two-way TLS or mTLS, you can set a trust store with all the certificates (and certificate chain) the server should be trusting. There are number of capabilities that rely on this trust store to properly authenticate clients using certificates such as:
Mutual-TLS Client Authentication
End-User X.509 Browser Authentication
You can configure the location of this truststore by running the following command:
bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file| This trust store is targeted for authenticating clients where Keycloak is acting as a server. For configuring a trust store where Keycloak is acting as a client to external services through TLS, see Configuring trusted certificates. |
You can set a secure password for your truststore using the https-trust-store-password option:
bin/kc.[sh|bat] start --https-trust-store-password=<value>If no password is set, the default password password is used.
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.
Authentication using mTLS is disabled by default. To enable mTLS certificate handling when Keycloak is the server and needs to validate certificates from requests made to Keycloak endpoints, put the appropriate certificates in Keycloak truststore and use the following command to enable mTLS:
bin/kc.[sh|bat] start --https-client-auth=<none|request|required>Using the value required sets up Keycloak to always ask for certificates and fail if no certificate is provided in a request. By setting the value to request, Keycloak will also accept requests without a certificate and only validate the correctness of a certificate if it exists.
Be aware that this is the basic certificate configuration for mTLS use cases where Keycloak acts as server. When Keycloak acts as client instead, e.g. when Keycloak tries to get a token from a token endpoint of a brokered identity provider that is secured by mTLS, you need to set up the HttpClient to provide the right certificates in the keystore for the outgoing request. To configure mTLS in these scenarios, see Configuring outgoing HTTP requests.
| Value | |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
(default) |
|
|
|
(default) |
|
(default) |
DEPRECATED. Use the System Truststore instead, see the docs for details. |
|
DEPRECATED. Use the System Truststore instead, see the docs for details. |
|
DEPRECATED. Use the System Truststore instead, see the docs for details. |