Incorrect documentation for setting truststore for mTLS

Describe the bug

Per https://www.keycloak.org/server/enabletls, I should be able to set a truststore for mTLS using KC_HTTPS_TRUST_STORE_FILE and KC_HTTPS_TRUST_STORE_PASSWORD; however, this doesn’t work and the truststore is null with the following warning among others:

2022-03-02 17:50:13,341 WARN  [org.keycloak.services.x509.NginxProxySslClientCertificateLookup] (executor-thread-2) Keycloak Truststore is null, but it is required !
2022-03-02 17:50:13,341 WARN  [org.keycloak.services.x509.NginxProxySslClientCertificateLookup] (executor-thread-2)   see https://www.keycloak.org/docs/latest/server_installation/index.html#_truststore

Instead if I use KC_SPI_TRUSTSTORE_FILE_FILE and KC_SPI_TRUSTSTORE_FILE_PASSWORD, things work as expected.

Also note that on https://www.keycloak.org/server/enabletls, there is also a typo in several places where https. and other dots are used for config keys instead of the -.

In the mTLS section of the reverse proxy docs (not yet released), it would also be good to mention that setting the truststore is required when using x509cert-lookup.

Version

17.0.0

Expected behavior

Configuration keys mentioned in TLS docs work as expected.

Actual behavior

Need to use other undocumented keys to get truststore to work.

How to Reproduce?

Entrypoint script:

#!/bin/bash

set -e

if [[ -n "${MTLS_CA}" ]]; then
    echo "mTLS is enabled"
    mtls_ca_path="/tmp/clientCertCA.pem"
    truststore_path="/tmp/truststore.jks"
    truststore_password="$(</dev/urandom tr -dc '[:alnum:]' | fold -w "${1:-20}" | head -n 1)"

    cat >"${mtls_ca_path}" <<EOF
${MTLS_CA}
EOF

    /usr/bin/keytool \
        -import \
        -noprompt \
        -keystore "${truststore_path}" \
        -file "${mtls_ca_path}" \
        -storetype jks \
        -storepass "${truststore_password}" \
        -alias "mTLS"

    # These don't seem to work, but the group below using SPI does.
    export KC_HTTPS_TRUST_STORE_FILE="${truststore_path}"
    export KC_HTTPS_TRUST_STORE_PASSWORD="${truststore_password}"
    export KC_HTTPS_TRUST_STORE_TYPE=jks

    export KC_SPI_TRUSTSTORE_FILE_FILE="${truststore_path}"
    export KC_SPI_TRUSTSTORE_FILE_PASSWORD="${truststore_password}"
else
    echo "mTLS is disabled"
fi

/opt/keycloak/bin/kc.sh start --auto-build

Relevant environment variables:

KC_HOSTNAME=myHostname
KC_PROXY=edge
KC_HTTP_ENABLED=true
KC_HTTP_RELATIVE_PATH=/auth
KC_SPI_X509CERT_LOOKUP_PROVIDER=nginx
KC_SPI_X509CERT_LOOKUP_NGINX_SSL_CLIENT_CERT="ssl-client-cert"
MTLS_CA=myCaContents

Anything else?

No response

[oranki]

Correct keycloak.conf options for defining a JKS trust store for outbound SSL connections are spi-truststore-file-file and spi-truststore-file-password. This was needed to configure LDAPS user federation source.

Documentation at https://www.keycloak.org/server/enabletls is either incorrect or incomplete, and the server admin guide links to old WildFly-based distro docs.

[fredericoschardong]

This did the trick for me:

USER root
RUN chmod 755 /opt/keycloak/conf/tls.key```