Zertifikatsbasierte Authentifizierung in Keycloak eignet sich besonders für Szenarien, in denen Benutzer oder Geräte eindeutig und sicher identifiziert werden sollen – etwa mit klassischen Smartcards, virtuellen Smartcards oder auch Softzertifikaten, die zentral auf Clients ausgerollt werden. Wenn du dich zuerst darüber informieren möchtest, welche dieser Zertifikatslösungen überhaupt zu deinem Unternehmen passt, empfehlen wir dir unseren ergänzenden Überblicksartikel: Smartcard, TPM & Softwarezertifikat – welche Zertifikatslösung passt zu meinem Unternehmen? In diesem Beitrag hier zeige ich dir konkret, wie du eine zertifikatsbasierte Authentifizierung in Keycloak technisch umsetzt – inklusive Truststore-Konfiguration, Authentifizierungs-Flow und TLS-Offloading mit NGINX.
1. Truststore einrichten
Damit Keycloak Client-Zertifikaten vertraut, musst du die ausstellende CA der Zertifikate, die später für die Anmeldung herangezogen werden sollen, in einen Truststore importieren. Das Ganze läuft über eine Java-Keystore-Datei (JKS).
Beispiel für den Import einer CA:
keytool -importcert \
-trustcacerts \
-file myCA.pem \
-alias myCA \
-keystore /opt/keycloak/conf/keycloak_truststore.jks \
-storepass changeit \
-nopromptDann in deiner keycloak.conf:
https-trust-store-file=/opt/keycloak/conf/keycloak_truststore.jks
https-trust-store-password=changeit
https-client-auth=requestMit https-client-auth=request sagst du dem Server: „Frag freundlich nach einem Zertifikat, aber akzeptiere auch Verbindungen ohne eins.“
2. Auth-Flow konfigurieren
Jetzt brauchst du einen passenden Authentifizierungs-Flow:
- Im Keycloak Admin UI unter Authentication > Flows einen neuen Flow erstellen (z. B.
X.509 Browser Auth) - Füge dort den X.509 Certificate Authenticator hinzu
Damit Keycloak das Zertifikat nicht nur entgegennimmt, sondern auch einem Benutzerkonto zuordnen kann, musst du in diesem Flow den Schritt „X509/Validate Username“ (oder „Form“, siehe unten) korrekt konfigurieren.
In diesem Schritt legst du fest, wo im Zertifikat die Benutzerinformationen stecken, wie sie extrahiert und mit einem Benutzer in Keycloak abgeglichen werden.
Wichtigste Felder und ihre Bedeutung:
- User Identity Source
Gibt an, wo im Zertifikat die Benutzeridentität gesucht werden soll – z. B. im Subject (Common Name, Distinguished Name etc.) oder im Subject Alternative Name (SAN), etwa als E-Mail-Adresse. - Regular Expression
Ermöglicht es, gezielt Teile des ausgewählten Felds herauszufiltern (z. B. die E-Mail-Adresse). Ein einfaches^(.+)$übernimmt den gesamten Wert. - User Mapping Method
Definiert, wie der extrahierte Wert mit einem Benutzer in Keycloak abgeglichen wird – meist überUsername,Emailoder beides. - A name of user attribute (optional)
Wenn du den extrahierten Wert zusätzlich als Attribut beim Benutzer speichern möchtest, gib hier den Attributnamen an – nützlich für Debugging oder Reporting.
Beispiel-Szenario: Mapping über E-Mail im SAN
Angenommen, du möchtest die E-Mail-Adresse aus dem SAN-Feld des Zertifikats verwenden und mit einem Benutzer in Keycloak abgleichen.
Dann wählst du in der Konfiguration:
- User Identity Source:
Subject's Alternative Name E-mail - Regular Expression:
^(.+)$ - User Mapping Method:
Username or Email - A name of user attribute: z. B.
usercertificate(optional)
Wenn das Zertifikat z. B. email=alice@example.com im SAN enthält, extrahiert Keycloak die E-Mail-Adresse und sucht nach einem Benutzer mit username oder email = alice@example.com. Bei einem Treffer: Auth erfolgreich – komplett ohne Passwort.
Wichtig: Der Browser muss dabei Zugriff auf das Client-Zertifikat haben – unabhängig davon, ob es auf einer Smartcard, virtuellen Smartcard oder als Software-Token vorliegt. Für den Browser ist das Trägermedium dabei transparent – er präsentiert dem Server einfach das Zertifikat, wenn er darum gebeten wird. Wie genau der Zugriff auf das Zertifikat erfolgt, hängt stark von der eingesetzten Infrastruktur, dem Browser und dem Zertifikatstyp ab – es gibt hier nicht den einen Weg, weshalb wir in diesem Beitrag nicht weiter darauf eingehen.
3. Das Problem mit dem Browser-Popup
Sobald https-client-auth=request gesetzt ist, bekommst du beim Öffnen der Keycloak-Seite ein Zertifikatsauswahl-Popup – selbst wenn der Flow kein Zertifikat erfordert.
Warum? Weil der Browser das Zertifikat direkt beim TLS-Handshake anbietet – also vor der eigentlichen Authentifizierung in Keycloak. Sobald Keycloak sagt „Ich hätte gern ein Zertifikat“, fragt der Browser nach. Ob’s danach überhaupt verwendet wird, ist ihm egal.
4. Die Lösung: TLS-Offloading via Reverse Proxy
Statt Keycloak direkt TLS machen zu lassen, setzt du einen Reverse Proxy wie NGINX davor. Der übernimmt die TLS-Verbindung inkl. Client-Zertifikaten – und leitet die relevanten Daten per Header an Keycloak weiter.
Beispiel: NGINX mit Client-Zertifikatsweitergabe
server {
listen 443 ssl;
server_name keycloak.example.com;
ssl_certificate /etc/nginx/certs/server.crt;
ssl_certificate_key /etc/nginx/certs/server.key;
ssl_client_certificate /etc/nginx/certs/ca.crt;
ssl_verify_client optional;
location / {
proxy_pass http://localhost:8080;
proxy_set_header X-SSL-Client-Cert $ssl_client_escaped_cert;
}
}Jetzt kommt das Zertifikat im Header X-SSL-Client-Cert bei Keycloak an.
5. Keycloak so konfigurieren, dass er den Header auswertet
Damit Keycloak den Zertifikat-Header verarbeitet, musst du den richtigen Lookup-Provider aktivieren:
bin/kc.sh start \
--spi-x509cert-lookup-provider=nginx \
--spi-x509cert-lookup-nginx-ssl-client-cert=X-SSL-Client-CertOder alternativ in keycloak.conf:
spi-x509cert-lookup-provider=nginx
spi-x509cert-lookup-nginx-ssl-client-cert=X-SSL-Client-Cert6. Optional: Zertifikatsprüfung dem Proxy überlassen
Wenn dein NGINX bereits eine vollständige Prüfung des Client-Zertifikats übernimmt (z. B. Gültigkeit, CA, Revocation etc.), kannst du Keycloak mitteilen, dass er dem Proxy vertraut und die Zertifikatsprüfung nicht selbst noch einmal durchführen soll:
trust-proxy-verification=trueDas reduziert die Last auf Keycloak und vermeidet doppelte Validierung. Wenn du das nicht setzt, wird Keycloak das Zertifikat aus dem Header entgegennehmen und trotzdem selbst nochmal gegen den Truststore prüfen.
7. Kein Popup mehr: https-client-auth=none
Wenn der Proxy die Zertifikate übernimmt, brauchst du keine Client-Zertifikatsanfrage auf TLS-Ebene mehr. Also:
https-client-auth=noneDadurch verschwindet das Browser-Popup vollständig. Das Zertifikat wird trotzdem geprüft – aber im Flow, durch den Proxy geliefert, im Header übergeben.
Fazit
Zertifikatsbasierte Auth in Keycloak ist nicht schwer, wenn man weiß, worauf man achten muss:
- Truststore für die ausstellende CA konfigurieren
- Auth-Flow mit X.509 Authenticator bauen
- TLS-Offloading über Reverse Proxy einrichten
- Zertifikat per HTTP-Header an Keycloak weitergeben
spi-x509cert-lookupkorrekt konfigurieren- Optionale Prüfung mit
trust-proxy-verification=true - Popup umgehen mit
https-client-auth=none