X.509 client

certificate

authentication

X.509 auth - overview

  • Keycloak supports authentication with client certificates
  • There must be certificate authority (CA), which issues client certificates to users
  • CA needs to be trusted by Keycloak server (entry in truststore on KC server side)

X.509 - authentication workflow

  • User has X509 certificate, signed by trusted CA
  • User adds X509 in PKCS12 format to his browser
  • User wants to authenticate against Keycloak
  • User sends initial request to OIDC/SAML endpoint. Must be HTTPS request
  • Keycloak (Undertow subsystem) does mutual SSL authentication. Client identity extracted from client certificate in HTTPS connection
  • Keycloak authenticator - more verifications of client certificate and map certificate identity to existing Keycloak user
  • User is automatically authenticated by Keycloak (no login form shown) and redirected back to the app

Required actions from admin

  • Have CA authority to create client certificates
  • Create client certificates and distribute somehow to users
  • Setup Keycloak

CA setup and manage certificates

Setup Keycloak

  • Create truststore file with CA entry
  • Eventually setup other things (CRL, OCSP responder)
  • Configure standalone.xml
  • Configure X509 authenticator in Keycloak admin console

Configuration in standalone.xml

  • Security realm
    • Points to truststore file, which need to have entry corresponding to CA used to sign client certificates
    • Keystore file - Identity of the server itself
  • Undertow subsystem - HTTPS listener pointing to security realm above

Configuration of authenticator

  • Done in Keycloak admin console
  • Configuration options
    • Check revocation status - optional support for CRL or OCSP
    • Check "key usage" or "extended key usage" from certificate - also optional
    • Extract identity from client certificate
    • Map extracted identity to Keycloak user - user must exists. Either map to username/email of existing user or some attribute of existing user

Extract identity from client certificate

  • Match SubjectDN using regular expression
  • X500 Subject’s e-mail attribute
  • X500 Subject’s Common Name attribute
  • Match IssuerDN using regular expression
  • X500 Issuer’s e-mail attribute
  • X500 Issuer’s Common Name attribute
  • Certificate Serial Number

X509 client certificate lookup

  • Specifies how exactly to lookup certificate from HTTP request
  • Provider configurable in keycloak subsystem in standalone.xml
  • Builtin options are:
    • DefaultClientCertificateLookup - Lookup from attribute of HTTP request standardized by servlet specification. Default option
    • ApacheProxySslClientCertificateLookup - Used when Keycloak behind Apache reverse proxy
    • HaProxySslClientCertificateLookup - Used when Keycloak behind HAProxy reverse proxy
  • Eventual possibility to add own provider (if none of builtin options matches). But SPI not supported

Direct grants support

  • Authentication with client certificates in directGrant requests (non-browser requests requesting KC authentication)
  • Separate authenticator implementation

Simple tutorial