Red Hat SummitChapter 6. Configuring TLS
Configure Red Hat build of 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 Red Hat build of Keycloak endpoints through HTTP, as sensitive data is at the core of what Red Hat build of Keycloak exchanges with other applications. In this chapter, you will learn how to configure Red Hat build of Keycloak to use HTTPS/TLS.
Red Hat build of 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.
6.1. Providing certificates in PEM format
When you use a pair of matching certificate and private key files in PEM format, you configure Red Hat build of 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
bin/kc.[sh|bat] start --https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pemRed Hat build of Keycloak creates a keystore out of these files in memory and uses this keystore afterwards.
6.2. Providing a Keystore
When no keystore file is explicitly configured, but http-enabled is set to false, Red Hat build of Keycloak looks for a conf/server.keystore file.
As an alternative, you can use an existing keystore by running the following command:
bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-file
bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-fileRecognized file extensions for a keystore:
-
.p12,.pkcs12, and.pfxfor a pkcs12 file -
.jks, and.keystorefor a jks file -
.key,.crt, and.pemfor 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.
6.2.1. 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>
bin/kc.[sh|bat] start --https-key-store-password=<value>
If no password is set, the default password password is used.
6.2.1.1. 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 Red Hat build of Keycloak for production.
6.3. Configuring TLS protocols
By default, Red Hat build of 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>]
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.
6.4. Switching the HTTPS port
Red Hat build of Keycloak listens for HTTPS traffic on port 8443. To change this port, use the following command:
bin/kc.[sh|bat] start --https-port=<port>
bin/kc.[sh|bat] start --https-port=<port>6.5. Certificate and Key Reloading
By default Red Hat build of 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.
6.6. Relevant options
| Value | |
|---|---|
|
|
|
|
| |
|
| |
|
| (default) |
|
| |
|
| |
|
| (default) |
|
| |
|
| (default) |
|
| (default) |
6.6.1. Management server
| Value | |
|---|---|
|
| |
|
| |
|
| (default) |
|
| |
|
| (default) |
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}