====== X509-Authentifizierung in Shibboleth ======
Dieser Artikel ist ein Beitrag für Shibboleth IdP 3.x. Es ist unklar, ob er für Shibboleth IdP 4.x so noch gilt.
Ein Login-Vorgang am Shibboleth-IdP besteht im Allgemeinen aus verschiedenen //Flows//. Nachdem eine Anfrage von einem Service Provider (SP) empfangen wurde, geht der IdP in einen der verfügbaren Flows zur Authentifizierung über. Dabei handelt es sich beispielsweise um den Password-Flow authn/Password, wobei sich der Nutzer durch die Eingabe von Nutzername und Passwort authentifizieren kann. Diese Daten werden dann gegen eine angeschlossene Datenquelle (häufig LDAP-Server) geprüft. Am Ende dieses Flows steht die //Subject-Canonicalization//, die das Erzeugen eines Benutzernamens (auch //Principal// genannt) für den Nutzer, der sich gerade erfolgreich authentifiziert hat, beschreibt. Unter diesem Benutzernamen ist der Nutzer im weiteren Verlauf im IdP bekannt. Normalerweise entspricht dieser Name schlichtweg dem Nutzernamen.
Neben dem authn/Password-Flow stellt der Shibboleth-IdP auch den sogenannten authn/X509-Flow zur Verfügung, der die Verwendung von X509-Client-Zertifikaten als Authentifizierungsmethode erlaubt. Die Logik auf Seiten des IdP ist dabei vergleichsweise simpel: Im Servlet-Container wird die Umgebungsvariable „javax.servlet.request.X509Certificate“ verwendet, um zu prüfen, ob die Authentifizierung erfolgreich ist. Wie diese Variable befüllt wird, spielt für den IdP dabei keine Rolle (siehe [[https://wiki.shibboleth.net/confluence/display/IDP30/X509AuthnConfiguration|Dokumentation im Shibboleth Wiki]]).
Jeder Login-Flow wird über einen dedizierten Endpunkt am IdP zur Verfügung gestellt. Bei authn/X509 handelt es sich dabei um den Pfad /Authn/X509. Ein naheliegender Weg besteht nun darin, diesen Endpunkt über den Apache-Webserver zu schützen. Sobald der IdP dann in seinem Ablauf in den authn/X509-Flow springt (wodurch der User auf den geschützten Pfad auf dem Webserver weitergeleitet wird), greift die Zugriffskontrolle von Apache. Da in diesem Fall als Authentifizierungsmethode X509-Zertifikate eingesetzt werden sollen, kann hierfür das [[https://httpd.apache.org/docs/2.4/mod/mod_ssl.html|Apache-Modul „mod_ssl“ entsprechend konfiguriert]] und das Client-Zertifikat validiert werden. Ist diese Validierung erfolgreich, kann der Nutzer den Endpunkt des IdP aufrufen. Dort ist „javax.servlet.request.X509Certificate“ nun korrekt befüllt und stellt Informationen über das verwendete Zertifikat bereit. Wenn die Zugriffskontrolle von Apache den Nutzer nicht durchlässt (also die Validierung des Zertifikats nicht erfolgreich war), kommt der Nutzer gar nicht erst zum X509-Endpunkt.
Im Gegensatz zum authn/Password-Flow, wo die //Subject-Canonicalization// im Allgemeinen sehr simpel ist, muss beim authn/X509-Flow unter Umständen mehr konfiguriert werden. Normalerweise lässt sich der zu verwendende Name aber aus dem //Subject-DN// des Client-Zertifikats extrahieren.
===== Anleitung für Apache, Tomcat und Shibboleth =====
Hier soll nun die beschriebene Kombination von Apache-Webserver (Apache 2), Tomcat Java-Servlet-Container (Tomcat 7 bzw. 8) und Shibboleth IdP V3.X beschrieben werden. In der Anleitung wird davon ausgegangen, dass die prinzipielle Infrastruktur bereits aufgebaut und lauffähig ist.
In diesem Beispiel werden zwei Client-Zertifikate verwendet:
- emailAddress=mustermann@dfn-cert.de, CN=Erika Mustermann, OU=Test, O=Organisation 1, C=DE
- emailAddress=mustermann@dfn-cert.de, CN=Erika Mustermann, OU=Test, O=Organisation 2, C=DE
Die Zertifikate sind durch folgende Zertifikat-Hierarchie ausgestellt:
- C=DE,O=Test,CN=Test Eins CA
- C=DE,O=Test,CN=Test Intermediate
- C=DE,O=Test,CN=Test Root (Root CA)
Die beiden Zertifikate unterscheiden sich also nur durch die Zugehörigkeit zu Organisation 1 bzw. Organisation 2. Beide Zertifikate wurden als Client-Zertifikate in den Browser importiert.
===== Konfiguration der Authentifizierung in Shibboleth =====
Die Konfiguration des X509-Flows zur Authentifizierung im Shibboleth-IdP erfordert lediglich eine Anpassung in der Konfigurationsdatei ''{idp.home}/conf/idp.properties''. Hier lässt sich der Login-Flow mit ''idp.authn.flows = X509'' aktivieren.
Weiterhin werden laut [[https://wiki.shibboleth.net/confluence/display/IDP30/X509AuthnConfiguration|Shibboleth Wiki]] noch drei optionale Konfigurationsmöglichkeiten des Flows in ''{idp.home}/conf/authn/x509-authn-config.xml'' angeboten. In der Praxis dürfte in den meisten Fällen jedoch nur einer davon relevant sein:
''shibboleth.authn.X509.externalAuthnPath'' erlaubt das Festlegen des Pfads, auf den weitergeleitet werden soll, sobald der Login-Flow aufgerufen wird. Standardmäßig werden die Nutzer*innen dabei auf eine vorgeschaltete Seite weitergeleitet (siehe Abbildung). Dort müssen sie explizit bestätigen, dass sie einen Login per X509-Zertifikat wünschen. Dann werden sie auf den Endpunkt /Authn/X509 weitergeleitet. Wenn dieses Verhalten nicht gewünscht ist, kann dieser Parameter direkt auf den Endpunkt gesetzt werden.
{{:de:screenshot_x509-login.png|Standardmäßig konfigurierte Hinweis-Seite vor der Weiterleitung auf den geschützten Endpunkt}}
===== Validierung der Zertifikate in Apache =====
Nachdem nun im IdP der authn/X509-Flow aktiviert und ggf. konfiguriert wurde, muss Apache so konfiguriert werden, dass der IdP-Endpunkt /Authn/X509 nur nach erfolgreicher Prüfung des Client-Zertifikats aufgerufen werden darf.
==== Einbinden der CA zur Validierung des Zertifikats ====
Zunächst muss das Zertifikat zur Validierung des Root-Zertifikats in der Hierarchie angegeben werden:
SSLCACertificateFile /etc/pki/tls/certs/dfn-test-root.crt
Die Direktive muss direkt im VirtualHost stehen, nicht innerhalb einer Location-Angabe.
==== Schutz des X509-Endpunkts des IdP ====
Der eigentliche Schutz des authn/X509-Endpunkts am IdP erfolgt dann über den Schutz der entsprechenden Location auch innerhalb der Virtual-Host-Definition, etwa wie folgt:
SSLVerifyClient require
SSLVerifyDepth 3
SSLOptions StdEnvVars ExportCertData
Require expr (%{SSL_CLIENT_S_DN_O} == 'Organisation 1')
Während hier prinzipiell die in [[https://httpd.apache.org/docs/2.4/mod/mod_ssl.html|Apache-mod-ssl]] aufgeführten Parameter gesetzt werden können, sind insbesondere die folgenden Direktiven interessant:
''SSLVerifyClient'' ermöglicht erst die Authentifizierung per Client-Zertifikat. Zudem macht im hier betrachteten Anwendungsfall auch nur ''Require'' Sinn, da nur damit sichergestellt wird, dass der Client ein valides Zertifikat präsentieren muss.
''SSLVerifyDepth'' drückt die maximale Anzahl an Intermediate-CAs aus, die von Apache verfolgt werden, bis das Zertifikat abgewiesen wird. Im vorliegenden Beispiel ist hier der Wert 3 ausreichend. In anderen Szenarien muss ggf. angepasst werden.
''SSLOptions'' ermöglicht das Festlegen von weiteren Parametern, insbesondere welche Daten aus dem Zertifikat als Umgebungsvariablen zur Verfügung gestellt werden.
''Require'' erlaubt die Konfiguration von Bedingungen, die erfüllt sein müssen, damit der Zugriff gestattet wird und ermöglicht damit die Einschränkung der Authentifizierung auf bestimmte Nutzergruppen. Im folgenden wird diese Direktive genauer betrachtet. ''Require expr'' ersetzt im Allgemeinen die veraltete ''SSLRequire''-Direktive.
==== Konfigurationsmöglichkeiten Require ====
Die Verwendung von ''Require'' ist in der [[https://httpd.apache.org/docs/2.4/mod/mod_authz_core.html#reqexpr|Apache Online-Dokumentation]] vollständig dokumentiert. Weitere Informationen zur Syntax der alten Direktive ''SSLRequire'' finden sich [[https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslrequire|hier]]. Die Syntax ist mit einigen Ausnahmen identisch.
In dem Beispiel oben wird beispielsweise die Einschränkung ''(%{SSL_CLIENT_S_DN_O} == 'Organisation 1')'' verwendet. Dabei wird mit ''%{SSL_CLIENT_S_DN_O}'' zunächst auf eine Umgebungsvariable zugegriffen (in diesem Fall, der O-Komponente des Subject-DN des Client-Zertifikats) welche dann auf Übereinstimmung mit einem bestimmten String verglichen wird. Eine Übersicht über die nutzbaren Umgebungsvariablen findet sich in der [[https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#envvars|Apache Online-Dokumentation]]. In diesem Beispiel würde also Zertifikat 1 (O=Organisation 1) Zugriff erhalten, während Zertifikat 2 (O=Organisation 2) nicht akzeptiert werden würde.
Diese Einschränkungen können nun nach Belieben kombiniert werden, etwa wie im folgenden Beispiel:
Require expr ( (%{SSL_CLIENT_S_DN_O} == 'Organisation 1') \
&& (%{SSL_CLIENT_I_DN_CN} == 'Test Zwei CA') )
Hier wird mit ''%{SSL_CLIENT_I_DN_CN}'' der CN des Issuer des Client-Zertifikats überprüft. Da beide Zertifikate von „Test Eins CA“ ausgestellt wurden, werden beide Zertifikate nicht akzeptiert.
===== Weiterverarbeitung des Ergebnisses in Shibboleth =====
Nachdem nun in Apache die Validierung des Client-Zertifikats vorgenommen und dieses akzeptiert wurde, kann der User auf den authn/x509-Endpunkt am IdP zugreifen. Dort steht dem IdP über die Umgebungsvariable ''javax.servlet.request.X509Certificat'' der Inhalt des Client-Zertifikats zur Verfügung.
Im Folgenden werden einige Punkte beschrieben, die nun üblicherweise am IdP nach der eigentlichen Authentifizierung zu beachten sind:
==== Extrahieren des „Principal“ aus dem Zertifikat ====
Zunächst muss über die //Subject-Canonicalization//ein Name für den Nutzer erstellt werden. Dies kann in ''{idp.home}/conf/c14n/x500-subject-c14n-config.xml'' konfiguriert werden. Hierbei stehen standardmäßig zwei Möglichkeiten zur Verfügung:
Zunächst kann über eine Prioritätenliste auf etwaige Attribute im SubjectAltName des Zertifikats zugegriffen werden. Hier ist die Angabe von Werten zwischen 0 und 8 möglich, welche in [[https://tools.ietf.org/html/rfc5280#section-4.1.2.6|RFC-5280]] definiert werden. 1 steht hier beispielsweise für E-Mail.
Alternativ kann über eine zweite Prioritätenliste auf die einzelnen Komponenten im Subject-DN des Client-Zertifikats zugegriffen werden, wobei in der IdP-Konfiguration die jeweiligen OIDs angegeben werden müssen. Um also beispielsweise in den vorliegenden Zertifikaten die ''emailAddress'' – und wenn diese nicht im Subject-DN ist, alternativ den CN zu verwenden – könnte die folgende Regel definiert werden:
1.2.840.113549.1.9.1
2.5.4.3
Weiterhin ist es auch möglich, einige vorgegebene Transformationen anzuwenden (z. B. den Namen in Kleinbuchstaben transformieren) oder eigene Transformationen zu formulieren.
Generell muss hier eine passende Strategie gefunden werden, mit der anhand des erzeugten Namens weitergearbeitet werden kann. Wenn also beispielsweise weitere Attribute aus einem LDAP-Server abgefragt werden sollen, muss hier bereits darauf geachtet werden, einen geeigneten Namen für den Suchfilter zu generieren.
==== Abfrage von Attributen aus einem LDAP-Server ====
Schließlich kann nun der wie oben beschrieben erzeugte //Principal// dazu verwendet werden, weitere Attribute aus einem LDAP-Server abzufragen. In ''{idp.home}/conf/ldap.properties'' wird ein Suchfilter für den Attribute Resolver definiert:
idp.attribute.resolver.LDAP.searchFilter = (uid=$resolutionContext.principal)
Hierbei bezieht sich ''$resolutionContext.principal'' auf den wie oben beschrieben erzeugten Namen. Dieser Filter wird dann normalerweise in den Data Connectors im Attribute Resolver verwendet, um über eine LDAP-Schnittstelle Informationen aus einem Nutzerverzeichnis abzufragen. Die weitere Konfiguration unterscheidet sich dann nicht weiter von einer herkömmlichen Attribut-Abfrage.
Eine weitere mögliche Verwendung des Principal ist eine Attribut Definition in ''{idp.home}/conf/attribute-resolver.xml'', die direkt auf diesen Wert zugreift:
Hier wird der wie oben beschrieben erzeugte Principal als Eingangswert für das Attribut ''uid'' verwendet.
{{tag>fixme}}