bin/kc.[sh|bat] start --truststore-paths=/opt/truststore/myTrustStore.pfx,/opt/other-truststore/myOtherTrustStore.pemWhen Keycloak 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.
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, .pfx, or .pkcs12. 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 Keycloak, 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 Keycloak.
For example:
bin/kc.[sh|bat] start --truststore-paths=/opt/truststore/myTrustStore.pfx,/opt/other-truststore/myOtherTrustStore.pemIt is still possible to directly set your own javax.net.ssl truststore System properties, but it’s recommended to use the --truststore-paths instead.
When running Keycloak on Kubernetes or OpenShift, the server will automatically include well-known cluster certificate authorities in the system truststore if they are present on the filesystem:
Kubernetes service account CA: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
OpenShift service CA: /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt
This behavior is enabled by default and does not require the Operator. It can be controlled with the following option:
--truststore-kubernetes-enabled=true|false (default: true)
To disable automatically trusting the cluster CAs entirely:
bin/kc.[sh|bat] start --truststore-kubernetes-enabled=falseNote that if the corresponding files are not mounted into the container, they will not be included regardless of the option values.
When https-client-auth is set to required or request without an explicit https-trust-store-file, mTLS client certificate validation falls back to the system truststore. With truststore-kubernetes-enabled=true, this means certificates signed by the Kubernetes cluster CA will be accepted as valid client certificates. If this is not desired, either set https-trust-store-file explicitly or disable truststore-kubernetes-enabled.
|
You may refine how hostnames are verified by TLS connections with the tls-hostname-verifier property.
DEFAULT (the default) allows wildcards in subdomain names (e.g. *.foo.com) to match names with the same number of levels (e.g. a.foo.com, but not a.b.foo.com) - with rules and exclusions for public suffixes based upon https://publicsuffix.org/list/
ANY means that the hostname is not verified - this mode should not be used in production.
WILDCARD (deprecated) allows wildcards in subdomain names (e.g. *.foo.com) to match anything, including multiple levels (e.g. a.b.foo.com). Use DEFAULT instead.
STRICT (deprecated) allows wildcards in subdomain names (e.g. *.foo.com) to match names with the same number of levels (e.g. a.foo.com, but not a.b.foo.com) - with some limited exclusions. Use DEFAULT instead.
Please note that this setting does not apply to LDAP secure connections, which require strict hostname checking.