
:guide-id: enabletls
:guide-title: Configuring TLS
:guide-summary: Configure {project_name}'s https certificates for ingoing and outgoing requests.
:guide-priority: 999
:guide-tile-visible: true
:version: 26.3.0

include::../attributes.adoc[]

[[enabletls]]
= Configuring TLS

ifeval::["" == "true"]
WARNING: This {section} is describing a feature which is currently in preview.
ifeval::["" == ""]
Please provide your feedback while we’re continuing to work on this.
endif::[]
ifeval::["" != ""]
Please provide your feedback by link:[joining this discussion] while we’re continuing to work on this.
endif::[]
endif::[]


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:

[source,bash]
----
bin/kc.[sh|bat] start --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 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:
[source,bash]
----
bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-file
----

Recognized file extensions for a keystore:

* `.p12`, `.pkcs12`, and `.pfx` for a pkcs12 file
* `.jks`, and `.keystore` for a jks file
* `.key`, `.crt`, and `.pem` for 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.

=== Setting the Keystore password
You can set a secure password for your keystore using the `https-key-store-password` option:
[source,bash]
----
bin/kc.[sh|bat] start --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 link:{links_server_vault_url}[{links_server_vault_name}] and link:{links_server_configuration-production_url}[{links_server_configuration-production_name}].

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

[source,bash]
----
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`.

== Switching the HTTPS port
{project_name} listens for HTTPS traffic on port `8443`. To change this port, use the following command:
[source,bash]
----
bin/kc.[sh|bat] start --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.

== Relevant options

[cols="12a,4",role="options"]
|===
| |Value

|
[.options-key]#`+http-enabled+`# 

[.options-description]#Enables the HTTP listener.#

[role="options-extended"]
--
[.options-description-extended]#Enabled by default in development mode. Typically not enabled in production unless the server is fronted by a TLS termination proxy.#

*CLI:* `+--http-enabled+` +
*Env:* `+KC_HTTP_ENABLED+`
--



|
`+true+`, `+false+` (default)

|
[.options-key]#`+https-certificate-file+`# 

[.options-description]#The file path to a server certificate or certificate chain in PEM format.#

[role="options-extended"]
--


*CLI:* `+--https-certificate-file+` +
*Env:* `+KC_HTTPS_CERTIFICATE_FILE+`
--



|

|
[.options-key]#`+https-certificate-key-file+`# 

[.options-description]#The file path to a private key in PEM format.#

[role="options-extended"]
--


*CLI:* `+--https-certificate-key-file+` +
*Env:* `+KC_HTTPS_CERTIFICATE_KEY_FILE+`
--



|

|
[.options-key]#`+https-certificates-reload-period+`# 

[.options-description]#Interval on which to reload key store, trust store, and certificate files referenced by https-* options.#

[role="options-extended"]
--
[.options-description-extended]#May be a java.time.Duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable.#

*CLI:* `+--https-certificates-reload-period+` +
*Env:* `+KC_HTTPS_CERTIFICATES_RELOAD_PERIOD+`
--



|[.options-default]#`+1h+`# (default)

|
[.options-key]#`+https-cipher-suites+`# 

[.options-description]#The cipher suites to use.#

[role="options-extended"]
--
[.options-description-extended]#If none is given, a reasonable default is selected.#

*CLI:* `+--https-cipher-suites+` +
*Env:* `+KC_HTTPS_CIPHER_SUITES+`
--



|

|
[.options-key]#`+https-key-store-file+`# 

[.options-description]#The key store which holds the certificate information instead of specifying separate files.#

[role="options-extended"]
--


*CLI:* `+--https-key-store-file+` +
*Env:* `+KC_HTTPS_KEY_STORE_FILE+`
--



|

|
[.options-key]#`+https-key-store-password+`# 

[.options-description]#The password of the key store file.#

[role="options-extended"]
--


*CLI:* `+--https-key-store-password+` +
*Env:* `+KC_HTTPS_KEY_STORE_PASSWORD+`
--



|[.options-default]#`+password+`# (default)

|
[.options-key]#`+https-key-store-type+`# 

[.options-description]#The type of the key store file.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the type is automatically detected based on the file extension. 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+`
--



|

|
[.options-key]#`+https-port+`# 

[.options-description]#The used HTTPS port.#

[role="options-extended"]
--


*CLI:* `+--https-port+` +
*Env:* `+KC_HTTPS_PORT+`
--



|[.options-default]#`+8443+`# (default)

|
[.options-key]#`+https-protocols+`# 

[.options-description]#The list of protocols to explicitly enable.#

[role="options-extended"]
--


*CLI:* `+--https-protocols+` +
*Env:* `+KC_HTTPS_PROTOCOLS+`
--



|[.options-default]#`+[TLSv1.3,TLSv1.2]+`# (default)


|===

=== Management server
[cols="12a,4",role="options"]
|===
| |Value

|
[.options-key]#`+https-management-certificate-file+`# 

[.options-description]#The file path to a server certificate or certificate chain in PEM format for the management server.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-certificate-file+` +
*Env:* `+KC_HTTPS_MANAGEMENT_CERTIFICATE_FILE+`
--



|

|
[.options-key]#`+https-management-certificate-key-file+`# 

[.options-description]#The file path to a private key in PEM format for the management server.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-certificate-key-file+` +
*Env:* `+KC_HTTPS_MANAGEMENT_CERTIFICATE_KEY_FILE+`
--



|

|
[.options-key]#`+https-management-certificates-reload-period+`# 

[.options-description]#Interval on which to reload key store, trust store, and certificate files referenced by https-management-* options for the management server.#

[role="options-extended"]
--
[.options-description-extended]#May be a java.time.Duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d]. Must be greater than 30 seconds. Use -1 to disable. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-certificates-reload-period+` +
*Env:* `+KC_HTTPS_MANAGEMENT_CERTIFICATES_RELOAD_PERIOD+`
--



|[.options-default]#`+1h+`# (default)

|
[.options-key]#`+https-management-key-store-file+`# 

[.options-description]#The key store which holds the certificate information instead of specifying separate files for the management server.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-key-store-file+` +
*Env:* `+KC_HTTPS_MANAGEMENT_KEY_STORE_FILE+`
--



|

|
[.options-key]#`+https-management-key-store-password+`# 

[.options-description]#The password of the key store file for the management server.#

[role="options-extended"]
--
[.options-description-extended]#If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details.#

*CLI:* `+--https-management-key-store-password+` +
*Env:* `+KC_HTTPS_MANAGEMENT_KEY_STORE_PASSWORD+`
--



|[.options-default]#`+password+`# (default)


|===



