Sign in Subscribe
Concepts

Keycloak TLS Configuration Guide

Andrios Robert

• 1 min read

The server refuses the connection. A browser stalls. The log spits an SSL handshake error. Your Keycloak instance is running, but without proper TLS configuration, it’s dead to the outside world.

Keycloak TLS configuration secures client connections, encrypts credentials, and blocks man-in-the-middle attacks. Whether you run Keycloak in production or staging, TLS should never be optional.

1. Generate or obtain a valid certificate
Use a trusted CA in production. For testing, create a self-signed certificate with openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem.

2. Import the certificate into a Java Keystore
Keycloak runs on Quarkus or WildFly, both requiring a keystore. Convert your certificate and private key into PKCS12 first:

openssl pkcs12 -export -in cert.pem -inkey key.pem -out keycloak.p12 -name keycloak

Then import into the JKS:

keytool -importkeystore -deststorepass password \
 -destkeypass password -destkeystore keycloak.jks \
 -srckeystore keycloak.p12 -srcstoretype PKCS12 -srcstorepass password \
 -alias keycloak

3. Configure Keycloak to use TLS
For Quarkus-based Keycloak (v17+), set environment variables or CLI options:

KC_HTTPS_CERTIFICATE_FILE=/opt/keycloak/conf/cert.pem
KC_HTTPS_CERTIFICATE_KEY_FILE=/opt/keycloak/conf/key.pem
KC_HTTPS_PORT=8443

For WildFly-based Keycloak, edit standalone.xml or standalone-ha.xml under the <server-identities> section and point to the keystore with your chosen password.

4. Enforce HTTPS in Keycloak
Open the Keycloak admin console, go to Realm Settings > Security Defenses > HTTPS. Set Require HTTPS to all requests. This forces all endpoints, including token and admin APIs, over TLS.

5. Update proxy and load balancer settings
If Keycloak sits behind a reverse proxy (NGINX, HAProxy, Traefik), ensure X-Forwarded-Proto headers are set, and configure Keycloak --proxy=edge option. Without this, redirects and cookies may fail.

6. Test your TLS setup
Use curl -vk https://your-keycloak-domain:8443/auth/ to verify certificate acceptance. Test with browsers and API clients. Check certificate chain validity on SSL Labs to confirm strong ciphers and protocols.

A correct Keycloak TLS configuration hardens your identity platform. It protects login flows, token exchange, and admin operations from interception. It’s not just a switch; it’s a baseline for trust in your authentication layer.

Want to see secure authentication in action without the setup grind? Try it on hoop.dev and have a fully functional, TLS-enabled Keycloak-like service live in minutes.