I’m looking for some insights on how I might be able to customize Keycloak’s X509 authentication.
I have a requirement to authenticate users with government issued PIV/CAC cards. Based on the information I’ve gathered, it seems like the authentication certificates on these cards may not always include email address of the user which is what we need to identify users on our system. Given that this identifying information can vary, what customization options do I have with Keycloak to map the certificate’s Subject information to a user account. It seems like Keycloak requests the client certificates only during the authentication flow. Is there some provision where I can define a flow to request the browser to send the client certificate, so that the informaton can be extracted and saved as custom attributes on a user profile. Essentially I’m looking to capture and extract the certificate information (Subject) one time and compare against the saved information for future logins with the card.
I don’t know if I’m approaching this problem the right way. Any advice from those who have successfully implemented PIV card login with Keycloak is greatly appreciated.
If you are doing x509 authentication in Keycloak, it’s quite straightforward. You didn’t mention any specific standard while describing the use case, so I will assume some common ground based on the fact that you are using Keycloak as the Identity Provider.
It’s all about authentication. Since Keycloak is the Identity Provider, I assume you are handling the authentication scenario with OpenID Connect.
Once you enable x509 authentication, you have several ways to identify the user’s identity source and also work with regular expressions. You then need to match the identity in Keycloak based on some attribute.
Lastly, just a reminder: You are in an mTLS setup, so Keycloak or the proxy/load balancer (plus Keycloak with a custom SPI to extract the user certificate from a header) will request the certificate selection.
All the mentioned points are 100% OOTB. However, you always have the option to extend Keycloak’s functionality with custom SPIs.
Thanks, I appreciate the quick response. And yes to your points #1 and #2. Also, I did get the mTLS authentication part to work by adding the X509 Username form as an Alternate execution step and using self-signed client certificates. I had the regular expression set to extract the email address from the certificate and the login worked well. All is well with my own self-signed certs.
What I’m struggling with is using client certificates found in PIV/CAC cards that government employees use. Apparently the Subject field on the cards does not always include an email address. So I do not know how to map that to a user in Keycloak.
Could you expand more on #3? I don’t know if I’m on the wrong track. But I’m thinking that I have to provide a separate page (which is not a login page) where the user can send the certificate information that our application can extract and save first. This would be one time step. Can this be customized with Keycloak or should it be managed outside of Keycloak?
I hope I was able to add some clarity to my use case.
Curious if you ever managed to get this working. PIV card authentication, especially in the world of federated trust to other CAs, should always match on at least Issuer+Subject if it’s not explicit binding.
Emails or UPNs carried in alternate names shouldn’t be used by themselves unless you’re only accepting certificates from a singular, or singular set of, CAs that you know impersonation won’t be possible.
If you follow the Microsoft altSecurityIdentities mapping it’s a combination of like “X509:</I/>{someIssuerString}</S/>{subjectString}.”
But across federal PIV/CAC cards accepting multiple issuers and combing Issuer+Subject is generally the standard - more info can be found here Configure Smart Card Logon on Windows Domains (although it calls out “domain account” the concept really applies everywhere for all log ins).
Anyhow, just looking at it now for Keycloak and also struggling with how the UX will be, what needs to be setup to work right (i.e., the root Keycloak domain should NOT require mTLS at all, needs to be path based or another domain to present log in form with button).