keycloak-scim/docs/guides/server/enabletls.adoc

<#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 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 {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.

== Configuring TLS in {project_name}
{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.

== 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>"/>

== 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:

<@kc.start parameters="--https-trust-store-file=/path/to/file"/>

NOTE: This trust store is targeted for authenticating clients where {project_name} is acting as a server. For configuring a trust store
where {project_name} is acting as a client to external services through TLS, see <@links.server id="keycloak-truststore"/>.

=== Setting the truststore password
You can set a secure password for your truststore using the `https-trust-store-password` option:
<@kc.start parameters="--https-trust-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" />.

== Enabling mutual TLS
Authentication using mTLS is disabled by default. To enable mTLS certificate handling when {project_name} is the server and needs to validate certificates from requests made to {project_name} endpoints, put the appropriate certificates in {project_name} truststore and use the following command to enable mTLS:

<@kc.start parameters="--https-client-auth=<none|request|required>"/>

Using the value `required` sets up {project_name} to always ask for certificates and fail if no certificate is provided in a request. By setting the value to `request`, {project_name} 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 {project_name} acts as server. When {project_name} acts as client instead, e.g. when {project_name} 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 <@links.server id="outgoinghttp"/>.

NOTE: Management interface properties are inherited from the main HTTP server, including mTLS settings.
It means when mTLS is set, it is also enabled for the management interface.
To override the behavior, use the `https-management-client-auth` property.

== 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>