Search

Chapter 4. Configuring TLS

download PDF

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.

4.1. Configuring TLS in Red Hat build of Keycloak

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.

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

Red Hat build of Keycloak creates a keystore out of these files in memory and uses this keystore afterwards.

4.1.2. Providing a Java 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

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

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

4.2. 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>]

To also allow TLSv1.2, use a command such as the following: kc.sh start --https-protocols=TLSv1.3,TLSv1.2.

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

4.4. Using a truststore

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
Note

This trust store is targeted for authenticating clients where Red Hat build of Keycloak is acting as a server. For configuring a trust store where Red Hat build of Keycloak is acting as a client to external services through TLS, see Configuring trusted certificates.

4.4.1. Setting the truststore password

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.

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

4.6. Enabling mutual TLS

Authentication using mTLS is disabled by default. To enable mTLS certificate handling when Red Hat build of Keycloak is the server and needs to validate certificates from requests made to Red Hat build of Keycloak endpoints, put the appropriate certificates in Red Hat build of 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 Red Hat build of Keycloak to always ask for certificates and fail if no certificate is provided in a request. By setting the value to request, Red Hat build of 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 Red Hat build of Keycloak acts as server. When Red Hat build of Keycloak acts as client instead, e.g. when Red Hat build of 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.

4.7. Relevant options

 Value

http-enabled

Enables the HTTP listener.

CLI: --http-enabled
Env: KC_HTTP_ENABLED

true, false (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.

 
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.