Sign in Subscribe
Concepts

Configuring TLS in Keycloak

Andrios Robert

• 1 min read

The login page loaded, but the browser warned the connection was not secure. That’s how you know your Keycloak TLS configuration is wrong. Fixing it is not optional—without TLS, credentials and tokens can leak, and attackers can hijack sessions.

What is TLS in Keycloak

Transport Layer Security (TLS) encrypts traffic between Keycloak and its clients. Configuring TLS ensures that authentication requests, admin sessions, and token exchanges cannot be intercepted. Keycloak supports TLS both for its public endpoints and for internal communication between nodes in a cluster.

Generating Certificates

Use a trusted Certificate Authority (CA) or create a self-signed certificate for testing. Generate a key pair and certificate using openssl or an external service like Let’s Encrypt. Store the .crt and .key files in a secure location on the host where Keycloak runs.

Configuring TLS in Keycloak

When running Keycloak in standalone mode:

  1. Place the certificate and private key in the server’s filesystem.
  2. Edit standalone.xml or standalone-ha.xml. In the HTTPS listener, set:
<ssl name="HTTPS" key-alias="server" password="changeit" certificate-key-file="/etc/x509/https/tls.key" certificate-file="/etc/x509/https/tls.crt"/>
  1. Reload or restart Keycloak to apply changes.

For Docker:

  • Bind mount the certificates into the container.
  • Set environment variables:
KC_HTTPS_CERTIFICATE_FILE=/etc/x509/https/tls.crt
KC_HTTPS_CERTIFICATE_KEY_FILE=/etc/x509/https/tls.key
  • Run the container with -e KC_HTTPS_PORT=8443 and expose that port.

Verifying TLS

Open the admin console over https://. Use a certificate inspector to verify the chain and expiration date. Check the browser lock icon and confirm there are no mixed-content warnings. For production, ensure the certificate comes from a trusted CA and supports modern cipher suites.

Advanced Keycloak TLS Settings

  • Configure mutual TLS by enabling client certificate authentication.
  • Harden the TLS configuration by disabling weak protocols like TLS 1.0 and 1.1.
  • Use automated certificate renewal scripts when using Let’s Encrypt.
  • In clustered setups, ensure TLS is enabled on both frontend and backend interfaces.

Common Issues

  • Misconfigured certificate paths or permissions.
  • Using a certificate not matching the hostname.
  • Forgetting to open the secure port in the firewall.

Securing Keycloak with TLS is a baseline standard, not an enhancement. It protects authentication flows and API calls without slowing the system.

See how a secure Keycloak TLS configuration works in minutes—run it live now on hoop.dev.