8c3df19722
closes #24148 Co-authored-by: Václav Muzikář <vaclav@muzikari.cz> Co-authored-by: Martin Bartoš <mabartos@redhat.com>
37 lines
2.5 KiB
Text
37 lines
2.5 KiB
Text
<#import "/templates/guide.adoc" as tmpl>
|
|
<#import "/templates/kc.adoc" as kc>
|
|
|
|
<@tmpl.guide
|
|
title="Configuring trusted certificates"
|
|
summary="How to configure the {project_name} Truststore to communicate through TLS."
|
|
includedOptions="truststore-paths tls-hostname-verifier">
|
|
|
|
When {project_name} communicates with external services or has an incoming connection through TLS, it has to validate the remote certificate in order to ensure it is connecting to a trusted server. This is necessary in order to prevent man-in-the-middle attacks.
|
|
|
|
The certificates of these clients or servers, or the CA that signed these certificates, must be put in a truststore. This truststore is then configured for use by Keycloak.
|
|
|
|
== Configuring the System Truststore
|
|
|
|
The existing Java default truststore certs will always be trusted. If you need additional certificates, which will be the case if you have self-signed or internal certificate authorities that are not recognized by the JRE, they can be included in the `conf/truststores` directory or subdirectories. The certs may be in PEM files, or PKCS12 files with extension `.p12` or `.pfx`. If in PKCS12, the certs must be unencrypted - meaning no password is expected.
|
|
|
|
If you need an alternative path, use the `--truststore-paths` option to specify additional files or directories where PEM or PKCS12 files are located. Paths are relative to where you launched {project_name}, so absolute paths are recommended instead. If a directory is specified, it will be recursively scanned for truststore files.
|
|
|
|
After all applicable certs are included, the truststore will be used as the system default truststore via the `javax.net.ssl` properties, and as the default for internal usage within {project_name}.
|
|
|
|
For example:
|
|
|
|
<@kc.start parameters="--truststore-paths=/opt/truststore/myTrustStore.pfx,/opt/other-truststore/myOtherTrustStore.pem" />
|
|
|
|
It is still possible to directly set your own `javax.net.ssl` truststore System properties, but it's recommended to use the `--truststore-paths` instead.
|
|
|
|
== Hostname Verification Policy
|
|
|
|
You may refine how hostnames are verified by TLS connections with the `tls-hostname-verifier` property.
|
|
|
|
* `WILDCARD` (the default) allows wildcards in subdomain names, such as *.foo.com.
|
|
* `ANY` means that the hostname is not verified.
|
|
* When using `STRICT`, the Common Name (CN) must match the hostname exactly.
|
|
+
|
|
Please note that this setting does not apply to LDAP secure connections, which require strict hostname checking.
|
|
|
|
</@tmpl.guide>
|