
:guide-id: mutual-tls
:guide-title: Configuring trusted certificates for mTLS
:guide-summary: Configure Mutual TLS to verify clients that are connecting to {project_name}.
:guide-priority: 999
:guide-tile-visible: true
:version: 26.3.0

include::../attributes.adoc[]

[[mutual-tls]]
= Configuring trusted certificates for mTLS

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::[]


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 and X.509 Authentication.

== Enabling mTLS

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 a truststore and use the following
command to enable mTLS:

[source,bash]
----
bin/kc.[sh|bat] start --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.

WARNING: The mTLS configuration and the truststore is shared by all Realms. It is not possible to configure different truststores for different Realms.

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.

== Using a dedicated truststore for mTLS

By default, {project_name} uses the System Truststore to validate certificates. See link:{links_server_keycloak-truststore_url}[{links_server_keycloak-truststore_name}] for details.

If you need to use a dedicated truststore for mTLS, you can configure the location of this truststore by running the following command:
[source,bash]
----
bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file --https-trust-store-password=<value>
----

Recognized file extensions for a truststore:

* `.p12`, `.pkcs12`, and `.pfx` for a pkcs12 file
* `.jks`, and `.truststore` for a jks file
* `.ca`, `.crt`, and `.pem` for a pem file

If your truststore does not have an extension matching its file type, you will also need to set the `https-key-store-type` option.

== Additional resources

=== Using mTLS for outgoing HTTP requests

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 link:{links_server_outgoinghttp_url}[{links_server_outgoinghttp_name}].

=== Configuring X.509 Authentication

For more information on how to configure X.509 Authentication, see link:{adminguide_link}#_x509[X.509 Client Certificate User Authentication section].


== Relevant options

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

|
[.options-key]#`+https-client-auth+`# [.none]#icon:tools[role=options-build]#

[.options-description]#Configures the server to require/request client authentication.#

[role="options-extended"]
--


*CLI:* `+--https-client-auth+` +
*Env:* `+KC_HTTPS_CLIENT_AUTH+`
--



|
`+none+` (default), `+request+`, `+required+`

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

[.options-description]#The trust store which holds the certificate information of the certificates to trust.#

[role="options-extended"]
--


*CLI:* `+--https-trust-store-file+` +
*Env:* `+KC_HTTPS_TRUST_STORE_FILE+`
--



|

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

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

[role="options-extended"]
--


*CLI:* `+--https-trust-store-password+` +
*Env:* `+KC_HTTPS_TRUST_STORE_PASSWORD+`
--



|

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

[.options-description]#The type of the trust 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-trust-store-type+` +
*Env:* `+KC_HTTPS_TRUST_STORE_TYPE+`
--



|

|
[.options-key]#`+https-management-client-auth+`# [.none]#icon:tools[role=options-build]#

[.options-description]#Configures the management interface to require/request client authentication.#

[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-client-auth+` +
*Env:* `+KC_HTTPS_MANAGEMENT_CLIENT_AUTH+`
--



|
`+none+` (default), `+request+`, `+required+`


|===
