51 lines
3 KiB
Text
51 lines
3 KiB
Text
|
<#import "/templates/guide.adoc" as tmpl>
|
||
|
|
<#import "/templates/kc.adoc" as kc>
|
||
|
|
<#import "/templates/links.adoc" as links>
|
||
|
|
|
||
|
|
<@tmpl.guide
|
||
|
|
title="Configuring trusted certificates for mTLS"
|
||
|
|
summary="Learn how to configure Mutual TLS to verify clients that are connecting to {project_name}."
|
||
|
|
includedOptions="https-trust-store-* https-client-auth https-management-client-auth">
|
||
|
|
|
||
|
|
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:
|
||
|
|
|
||
|
|
<@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.
|
||
|
|
|
||
|
|
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 <@links.server id="keycloak-truststore"/> 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:
|
||
|
|
<@kc.start parameters="--https-trust-store-file=/path/to/file --https-trust-store-password=<value>"/>
|
||
|
|
|
||
|
|
== 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 <@links.server id="outgoinghttp"/>.
|
||
|
|
|
||
|
|
=== 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].
|
||
|
|
|
||
|
|
</@tmpl.guide>
|