mTLS Certificates and CRL Agent on Keycloak

What are mTLS and CRL in Keycloak?

mTLS (Mutual TLS) is a security protocol where both the client and the server authenticate using certificates. Unlike standard TLS—where only the server proves its identity—mTLS ensures that only trusted applications, services, or devices can reach Keycloak. This adds a strong validation layer before any authentication flow begins.

CRL (Certificate Revocation List) is a list of certificates that should no longer be trusted because they were compromised, disabled, or removed from use. Keycloak’s CRL Agent regularly retrieves and updates these lists from your PKI. During the mTLS handshake, it checks whether the presented certificate is valid or revoked. If the certificate appears in the CRL, Keycloak immediately blocks the connection.

Together, mTLS + CRL ensure that only verified and non-revoked clients can communicate with Keycloak.

Usage and Use Cases of mTLS in Keycloak

mTLS adds a strong security layer to Keycloak by validating the client certificate before any access is allowed. By enforcing the “Something You Have” factor through a device-bound certificate, mTLS can even replace username/password login entirely when configured in strict mode.

Beyond stronger security, mTLS also simplifies onboarding new applications or APIs: instead of configuring passwords or shared secrets, access is granted through certificate-based trust, offering a safer and more scalable alternative.

IAM Use Cases

CIAM (Customer IAM)

Restrict access to trusted customer applications
Block spoofed or malicious apps early
Reduce fraud and protect customer accounts

WIAM (Workforce IAM)

Allow access only from managed corporate devices
Protect internal and administrative applications
Reduce insider risks and unauthorized surface exposure

Identity Provider Brokering

Authenticate external IdPs using certificates
Prevent spoofed IdPs and man-in-the-middle attacks
Strengthen cross-domain trust relationships

Technical Use Cases

Microservices / M2M: Secure internal API and service-to-service calls
Admin Tools & Automation: Authenticate scripts or admin tools without passwords

Security considerations and user impact of mTLS

While mTLS significantly improves security, it also introduces friction for end users and client applications (e.g.: losing a certificate means losing access, users cannot authenticate from unmanaged devices, IT teams must generate and distribute certificates, etc.).

These constraints reflect the usual balance between stronger security and operational convenience, the appropriate level depends on each organization’s context and security requirements.

How to upload your mTLS certificates in the Cloud-IAM Console

In this article, we will assume that you already created your certificate .crt .cer.

Open Cloud-IAM console
Select the Keycloak deployment you want to configure.
Click on Customisation
Then select mTLS to start the configuration
Click Upload
Select the file containing your certificate (for example: acme-v1.0.crt)
Toggle the option to either apply now and trigger a restart or don't and upload now and restart later.
Then click Upload to confirm

After 5–10 minutes, while your Keycloak deployment redeploys via the rolling upgrade process, the changes will be applied. Your mTLS certificates are now uploaded to your deployment.

Cloud-IAM Console - Upload mTLS certificates

How to configure Strict mTLS for Keycloak

Introduction

This tutorial explains how to configure strict mTLS for your Keycloak deployment. In a strict mTLS setup, every client must present a valid X.509 certificate before accessing Keycloak.

This mode is useful when:

You want to enforce strong authentication for all clients
Your environment requires strict verification of device or application identity
You must block all unauthenticated connections at the network edge
You want to prevent access from unmanaged or unknown devices entirely

Identity Mapping Assumption

For this tutorial, we assume that your client certificate contains an email field (either in the Subject or in the Subject Alternative Name – SAN). This email allows Keycloak to map the incoming certificate to the correct user account during authentication.

If the client does not send a certificate, or if the certificate is invalid, the connection is blocked directly at the load balancer, before it reaches Keycloak. If the certificate is valid, the load balancer approves the connection and forwards the request to Keycloak for identity mapping and authentication. For more details on how a Managed Keycloak deployment architecture with Load Balancer and Keycloak, see the architecture insight.

This guide assumes

You have already uploaded your mTLS certificate in the Cloud-IAM Console.
→ See: How to upload your mTLS certificates
You are using a custom domain, which is required to enable mTLS on managed deployments.
→ See: How to configure your custom domain
Your Keycloak deployment is fully operational and shows the Running status.
→ See: Deployment lifecycle – Running

Scope of This Tutorial

This tutorial focuses on how to configure optional mTLS within Keycloak and the Cloud-IAM Console. This tutorial does not cover all the necessary security best practices for a complete configuration, it's a build to guide you through one specific process.

Step 1 - How to set a custom domain with mTLS as Strict

In this step, you configure your custom domain so it enforces strict mTLS at the load balancer level. This ensures Keycloak only receives requests from clients presenting a valid certificate.

Open Cloud-IAM console
Select the Keycloak deployment you want to configure.
Click on Configuration
Select the ✎ Edit icon next to the custom domain you want to secure with strict mTLS.
Enable the mTLS toggle.
Select Strict, then click Save to confirm.

Cloud-IAM Console - Set mTLS Custom Domains as Strict

Step 2 - How to duplicate your browser flow on Keycloak

Keycloak does not allow editing the default Browser flow, so you must duplicate the browser flow before making changes.

Log in to your Keycloak as an admin
Select the realm where you want to apply mTLS certifications
Navigate to Authentication
Select ... from the Browserline
Click on Duplicate (3.)
Name the new browser flow (e.g. browser-mtls)

Keycloak Console - Duplicate browser flow mTLS — Keycloak Console - Duplicate browser flow for mTLS

Step 3 - How to add steps mTLS on Keycloak authentication flow

In this step, you add the X.509 authenticator so Keycloak can extract the email from the certificate and identify the user.

Open the newly created Browser flow (e.g. browser-mtls)
Select Add Execution
Search from the list X509/Validate Username Form, select it, and click Add
Reorder the executions so X509/Validate Username Form is placed just below the Cookie and above Kerberos step
Set the execution requirement to Required

Keycloak Console - Strict Browser flow mTLS expected

Step 4 - How to configure mTLS x509 on Keycloak authentication flow as strict

In this step, you configure Keycloak to extract the email from the certificate and map it to the correct Keycloak user.

Select the ⚙️ next to X509/Validate Username Form to open the control panel
Name X509/Validate Username Form config on Alias (e.g. mtls-email)
From User Identity Source list click on Subject's e-mail
From User mapping method list click on Username or Email
Optional: if you don't want confirmation screen toggle On Bypass identity confirmation line
Verify the toggle is ON that Check certificate validity
Then click Save to validate this new execution

Keycloak Console - Configure mTLS x509 settings on Keycloak

Step 5 - How to bind the new mTLS browser flow

In this step, you activate your new authentication flow so it becomes the default browser flow for the realm.

Navigate to Authentication
Select ... from the browser-mtls line
Click on Bind flow
Then select Browser flow and click on Save

Your Keycloak realm now uses the mTLS-enabled flow.

Keycloak Console - Bind the new mTLS browser flow

Conclusion

You have now successfully enabled strict mTLS authentication for Keycloak on your realm. All incoming connections must now present a valid certificate, and Keycloak will authenticate users based on the email contained in that certificate.