Skip to content

How to configure mTLS

mTLS is a robust way of authenticated the client.

In order to configure the mTLS for client authentication, you need to upload the Certificate Authority used to issue the client certificate. This certificate chain will be used to validate client certificate compliance. This can be done through the third-party-resources upload

This will automatically enable the mTLS at the load balancer level and the client certificate, if valid, will be transmitted to Keycloak.

At this point, most of the job has already been handled by Cloud-IAM. Now you need to configure a new Authentication flow based on the browser flow for instance.

Duplicate the browser flow
Duplicate the browser flow

Then, simply add a new step of type X509/Validate Username Form.

X509/Validate Username Form
X509/Validate Username Form

Finally, select the field to extract from the certificate to authenticate the user. The most convenient field is usually the Subject's email.

Then select against which value / attribute of the Keycloak users to check the value from the certificate. This is used to define a proper mapping between the client certificate information and the actual Keycloak user.

Configure X509 step
Configure X509 step

Once setup, we advise you to test this new authentication flow at the level of one client (the account-console for instance).

When you will access the login page, if you have multiple possible certificate or if the CA cannot be identified, you might be asked by the browser to select which certificate to send.

mTLS send certificate
mTLS send certificate

Then, Keycloak ask tor confirmation that you want to be authenticated as the user defined in the certificate.

mTLS login
mTLS login

TIP

To ensure the mTLS is properly enabled, you can run the following command that will return the client certificate authority expected by the server

shell
echo "" |\
openssl s_client -connect $NAME.cloud-iam.com:443 -state 2>/dev/null |\
grep -A 1 "Acceptable client certificate CA names"
echo "" |\
openssl s_client -connect $NAME.cloud-iam.com:443 -state 2>/dev/null |\
grep -A 1 "Acceptable client certificate CA names"