diff --git a/docs/guides/src/main/server/enabletls.adoc b/docs/guides/src/main/server/enabletls.adoc index 1a4ae81651..0e4ec07935 100644 --- a/docs/guides/src/main/server/enabletls.adoc +++ b/docs/guides/src/main/server/enabletls.adoc @@ -2,48 +2,56 @@ <#import "/templates/kc.adoc" as kc> <@tmpl.guide -title="Configure TLS" -summary="Learn how to configure Keycloak's https certificates for in- and outgoing requests as well as mTLS." +title="Configuring TLS" +summary="Learn how to configure Keycloak's https certificates for ingoing and outgoing requests as well as mTLS." includedOptions="https-* http-enabled"> -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. +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. -== Configure TLS in Keycloak -Keycloak can be configured to load the needed certificate infrastructure using files in PEM format or from a Java KeyStore. When both alternatives are set up, the PEM files takes precedence over the Java KeyStores. +== Configuring TLS in Keycloak +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 / private key files in PEM format, configure Keycloak to use them by running: +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: <@kc.start parameters="--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 Java KeyStore -When no keystore file is configured explicitly, but `http.enabled` is set to false, Keycloak looks for a `conf/server.keystore` file by default. +=== Providing a Java 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: +As an alternative, you can use an existing keystore by running the following command: <@kc.start parameters="--https-key-store-file=/path/to/existing-keystore-file"/> -==== Setting the KeyStore password +==== Setting the Keystore password You can set a secure password for your keystore using the `https.key-store.password` option: <@kc.start parameters="--https-key-store-password="/> + If no password is set, the default password `password` is used. -== Configure TLS protocols -By default, Keycloak does not enable deprecated TLS protocols. In situations where clients only support deprecated protocols, first consider upgrading the client, but as a temporary work-around you can enable deprecated protocols with: +== 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: <@kc.start parameters="--https-protocols=[,]"/> -To also allow TLSv1.2, use for example `kc.sh start --https-protocols=TLSv1.3,TLSv1.2`. +To also allow TLSv1.2, use a command such as the following: `kc.sh start --https-protocols=TLSv1.3,TLSv1.2`. -== Switch the HTTPS port -Keycloak listens for HTTPS traffic on port `8443` by default. To change this port, use: +== Switching the HTTPS port +Keycloak listens for HTTPS traffic on port `8443`. To change this port, use the following command: <@kc.start parameters="--https-port="/> == Using a truststore -Keycloak uses a truststore to store certificates to verify clients that are communicating with Keycloak, e.g. to use mutualTLS, certificate-bound tokens or X.509 authentication. This truststore is used for outgoing https requests as well as mTLS requests. +Keycloak uses a truststore to store certificates to verify clients that are communicating with Keycloak. +Examples of client requests are for using mutualTLS, certificate-bound tokens or X.509 authentication. +This truststore is used for outgoing https requests as well as mTLS requests. -You can configure the location of this truststore by running: +You can configure the location of this truststore by running the following command: <@kc.start parameters="--https-trust-store-file=/path/to/file"/> === Setting the truststore password @@ -52,6 +60,8 @@ You can set a secure password for your truststore using the `https.trust-store.p If no password is set, the default password `password` is used. == Securing credentials -We recommend to not set any password in plaintext via the CLI or in `conf/keycloak.conf`, but instead using good practices such as using a vault / mounted secret. Please refer to the Vault Guide / Production deployment guide for more advice. +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 the Vault Guide / Production deployment guide. - \ No newline at end of file + +