59 lines
3.5 KiB
Text
59 lines
3.5 KiB
Text
<#import "/templates/guide.adoc" as tmpl>
|
|
<#import "/templates/kc.adoc" as kc>
|
|
<#import "/templates/links.adoc" as links>
|
|
|
|
<@tmpl.guide
|
|
title="Configuring TLS"
|
|
summary="Learn how to configure {project_name}'s https certificates for ingoing and outgoing requests."
|
|
includedOptions="https-* http-enabled"
|
|
excludedOptions="https-trust-store-* https-client-auth https-management-client-auth">
|
|
|
|
Transport Layer Security (short: TLS) is crucial to exchange data over a secured channel.
|
|
For production environments, you should never expose {project_name} endpoints through HTTP, as sensitive data is at the core of what {project_name} exchanges with other applications.
|
|
In this {section}, you will learn how to configure {project_name} to use HTTPS/TLS.
|
|
|
|
{project_name} 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 {project_name} 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"/>
|
|
|
|
{project_name} creates a keystore out of these files in memory and uses this keystore afterwards.
|
|
|
|
== Providing a Java Keystore
|
|
When no keystore file is explicitly configured, but `http-enabled` is set to false, {project_name} looks for a `conf/server.keystore` file.
|
|
|
|
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
|
|
You can set a secure password for your keystore using the `https-key-store-password` option:
|
|
<@kc.start parameters="--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 <@links.server id="vault"/> and <@links.server id="configuration-production" />.
|
|
|
|
== Configuring TLS protocols
|
|
By default, {project_name} 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=<protocol>[,<protocol>]"/>
|
|
|
|
To also allow TLSv1.2, use a command such as the following: `kc.sh start --https-protocols=TLSv1.3,TLSv1.2`.
|
|
|
|
== Switching the HTTPS port
|
|
{project_name} listens for HTTPS traffic on port `8443`. To change this port, use the following command:
|
|
<@kc.start parameters="--https-port=<port>"/>
|
|
|
|
== Certificate and Key Reloading
|
|
|
|
By default {project_name} 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.
|
|
|
|
</@tmpl.guide>
|