keycloak: 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
About this issue
- Original URL
- State: closed
- Created 2 years ago
- Comments: 16 (4 by maintainers)
Correct
keycloak.confoptions for defining a JKS trust store for outbound SSL connections arespi-truststore-file-fileandspi-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.
This did the trick for me:
KC_SPI_TRUSTSTORE_FILE_FILEworks for me with JKS store (with custom CA) +KC_SPI_TRUSTSTORE_FILE_PASSWORD=changeit(system-global cacerts on RHEL8-like) for LDAP user federation (onlyldaps://, StartTLS still doesn’t work).