Inhaltsverzeichnis

Zertifikate

Zertifikate für die SAML-basierte Kommunikation

Bei der SAML-basierten Kommunikation zwischen IdP und SP werden Zertifikate zur Signatur-Validierung sowie zum Verschlüsseln eingesetzt. Diese Zertifikate müssen für die betreffende Entity in der Metadatenverwaltung eingetragen werden.

Zertifikate müssen gültig sein

Generell gilt: Entities mit ungültigen, d.h. abgelaufenen oder zurückgezogenen Zertifikaten werden automatisch aus der DFN-AAI Produktivföderation entfernt!


Informationen für Identity Provider / Attribute Authorities

Siehe unter Vorbereitung: Zertifikate


Informationen für Service Provider

Unabhängig davon, welche der u.g. Varianten zum Einsatz kommen, müssen das für die SAML-basierte Kommunikation verwendete Zertifikat und der zugehörige Private Key in der SP-Konfiguration hinterlegt werden. Beim Shibboleth SP ist dies das Element CredentialResolver in /etc/shibboleth/shibboleth2.xml, s.u. Shibboleth SP


Zertifikate der DFN-PKI bzw. DFN-Verein Community PKI

Für die SAML-basierte Kommunikation empfehlen sich 39 Monate gültige Zertifikate aus der DFN-Verein Community PKI (genauer: max. 1170 Tage). Wenn Sie berechtigt sind, Zertifikate von der DFN-PKI zu beantragen, wählen Sie bei der Beantragung bitte das Profil „Shibboleth IdP SP“ aus. Dieses Zertifikat laden Sie in der Metadatenverwaltung hoch.


Eigene/lokale CA

Für Zertifikate aus einer eigenen/lokalen CA gelten die selben Regeln wie für selbst-signierte Zertifikate, siehe unten.


Selbst-signierte Zertifikate

Die dritte Möglichkeit ist die Verwendung von selbst-signierten Zertifikaten mit einer Gültigkeitsdauer von maximal 39 Monaten. Wir empfehlen zur korrekten Erstellung die Dokumentation ​der SWITCHaai. Hierbei ist darauf zu achten, dass die Laufzeit auf 3 Jahre bzw. max. 39 Monate zu setzen ist (keygen Tool: -y 3, openssl: -days 1170). Die Schlüssellänge muss mindestens 3072 Bit betragen.


Zertifikate gängiger Zertifizierungsstellen

Alternativ können Zertifikate aus CAs genutzt werden, die in den gängigen Standardbrowsern (Google Chrome, Firefox, Microsoft Edge) vorinstalliert sind.

Ausnahmen

Eine Ausnahme von den o.g. Regeln gilt bei SPs, die bereits in anderen Föderationen (mit anderen Zertifikats-Policies) registriert sind. In diesem Fall können die dort verwendeten Zertifikate auch für die DFN-AAI genutzt werden, auch wenn diese länger gültig sind.


Vorsicht bei der Verwendung von Wildcard-Zertifikaten!

Da Wildcard-Zertifikate für eine ganze Subdomain gelten und daher für mehrere Entities gleichzeitig verwendet werden können, ist der potentielle Schaden bei einer Kompromittierung des privaten Schlüssels deutlich höher als bei Zertifikaten für genau spezifizierte FQDNs. Daher sollten Wildcard-Zertifikate in der DFN-AAI nur verwendet werden, wenn das Einsatzszenario dies technisch erzwingt. Beispielsweise existieren insbesondere im Bibliotheksumfeld Softwaresysteme, die dynamisch Host-Names erzeugen und die mit herkömmlichen Zertifikaten nicht funktionieren. Beispiele für solche Software: EZProxy, Netman/HAN.
Ein und dasselbe Wildcard-Zertifikat sollte nicht auf verschiedenen Servern mit unterschiedlichen Diensten, Einsatzzwecken oder Schutzklassen verwendet werden. Aufgrund des höheren Schadenspotentials bei Kompromittierung sind Wildcard-Zertifikate kein probates Mittel der Arbeitsersparnis bei der Beantragung und dem Deployment von Zertifikaten.
Wildcard-Zertifikat werden in der DFN-AAI daher nur unterhalb von Sub-Domains oder Second-Level-Domains akzeptiert, die ausschließlich für einen klar abgegrenzten Zweck genutzt werden, also beispielsweise entweder für „*.ub.uni-example.de“ oder für „*.medizin.uni-example.de“, nicht aber für „*.uni-example.de“.


Keine Letsencrypt-Zertifikate

Für die Signierung und Verschlüsselung der SAML-Komunikation raten wir dringend von Letsenycrpt-Zertifikaten ab, da diese nur eine Gültigkeit von 90 Tagen haben. Ein Zertifikats-Rollover müsste jedes Mal manuell in der Metadatenverwaltung erfolgen. Auch die SP-Konfiguration muss beim Rollover 2x geändert werden. Wir empfehlen daher den Einsatz selbst-signierter Zertifikate oder solcher aus der DFN-Verein Community PKI (siehe oben).


Nächster Schritt: Funktionstests

Zertifikatstausch am IdP

Vielen Dank an die Schweizer Kolleg*innen für die ausführliche englischsprachige Dokumentation zur SWITCHaai, die uns beim Erstellen als Vorlage gedient hat!

Wenn Sie ablaufende Zertifikate auf Ihren AAI-Systemen austauschen müssen, gehen Sie wie folgt vor:

1. Was muss getauscht werden?

Stellen Sie fest, ob es um die Webserver-Zertifikate oder um die Zertifikate für die SAML-basierte Kommunikation geht. Das kann, muss aber nicht dasselbe Zertifikat sein.

2. Beschaffung eines neuen Zertifikates

siehe oben

3. Ggf. Zertifikat am Webserver tauschen

4. Zertifikatswechsel auf dem IdP

5. zweites Zertifikat für SAML-Kommunikation eintragen

6. Zertifikat für SAML-Kommunikation in Metadatenverwaltung eintragen

24 Stunden Wartezeit

Veröffentlichen Sie das neue Zertifikat mindestens 24 Stunden vor dem nächsten Schritt zusätzlich zu dem alten Zertifikat in den Föderationsmetadaten!

7. Alt und neu in der Konfiguration vertauschen

24 Stunden Wartezeit

Nach diesem Schritt warten Sie bitte erneut mindestens 24 Stunden, bevor Sie weitermachen.

8. Alte Zertifikate für SAML-Kommunikation aus Konfiguration entfernen

9. zweites Bean auskommentieren

Zertifikatstausch am SP

1. Was muss getauscht werden?

Stellen Sie fest, ob es um die Webserver-Zertifikate oder um die Zertifikate für die SAML-basierte Kommunikation geht. Das kann, muss aber nicht dasselbe Zertifikat sein.

2. Beschaffung eines neuen Zertifikates

siehe oben

3. Ggf. Zertifikat am Webserver tauschen

4. Zertifikate für SAML-Kommunikation tauschen

Der SP benötigt vorübergehend beide Zertifikate bzw. Schlüssel, alt und neu, denn er muss in der Lage sein, Authentication Requests zu signieren und SAML Assertions zu entschlüsseln.

24 Stunden Wartezeit

Veröffentlichen Sie das neue Zertifikat zusätzlich zu dem alten Zertifikat in den Föderationsmetadaten und warten Sie 24 Stunden mit dem nächsten Schritt.

5. Zertifikate für SAML-Kommunikation tauschen

24 Stunden Wartezeit

Entfernen Sie jetzt das alte Zertifikat aus den Föderationsmetadaten und warten Sie 24 Stunden mit dem nächsten Schritt.

6. Altes Zertifikat aus der SP-Konfiguration entfernen

Direkt verdrahtete IdPs/SPs

Wenn Sie SPs an der DFN-AAI vorbei direkt mit Ihrem IdP verbunden haben, haben Sie die Metadaten von IdP und SP manuell im jeweils anderen hinterlegt. Diese Metadatensätze müssen sie prüfen und ggf. manuell aktualisieren, wenn Sie auf einem oder beiden Systemen das Zertifikat getauscht haben.

Die SSL-Zertifikatskette auf Ihrem Webserver

Die SSL-Konfiguration Ihres Webservers hat direkt nichts mit der Zertifikat-Konfiguration für SAML-basierte Kommunikation in der DFN-AAI zu tun. Da aber sowohl die Binding URLs über SSL/TLS abgesichert werden (https), als auch der Aufruf der im Browser angezeigten IdP-/SP-Seiten, muss der Webserver in der Lage sein, eine vollständige Zertifikatskette ausliefern. Ist das nicht gegeben, wird Ihre Seite (IdP/SP) von Geräten, die die Kette validieren, nicht aufrufbar sein. Das bedeutet, dass etwa Android-Geräte die Login-Seite Ihres IdP nicht ohne Warnung besuchen können („Dieser Verbindung wird nicht vertraut“). Sie können dies beim Shibboleth IdP z.B. über den Aufruf der Statusseite prüfen (https://idp.domain.tld/idp/status), beim Shibboleth SP empfiehlt sich hierfür der Session Handler (https://sp.domain.tld/Shibboleth.sso/Session).

Einrichtung der vollständigen Zertifikatskette auf dem Webserver

Die Zertifikate werden in dieser Reihenfolge direkt untereinander gehängt. Dazwischen dürfen Kommentare eingefügt werden (mit „#“ beginnend). Die Kette darf keine zusätzlichen Zertifikate enthalten. Unten sehen Sie als Beispiel die Kette der Domain dfn.de.

Ob die einzelnen Zertifikate im chain file wirklich zusammenpassen, können Sie mit OpenSSL überprüfen:

Beim Apache Webserver wird der Pfad zu dieser Datei als SSLCACertificateFile hinterlegt, siehe hierzu unter IdP-Vorarbeiten: Webserver (IdP), bzw. Shibboleth SP > Konfigurationsbeispiel (SP).

Überprüfung der Zertifikatskette

Wenn Sie Ihre Zertifikatskette hinlegt, die Webserver-Konfiguration angepasst und aktiviert haben, können Sie sie mit OpenSSL zur Überprüfung abfragen:

$ openssl s_client -connect idp.domain.tld:443

Unten sehen als Beispiel die Antwort des Webservers von wayf.aai.dfn.de. Alternativ können Sie externe Dienste wie z.B. die Website von SSLLabs verwenden.

$ openssl s_client -connect wayf.aai.dfn.de:443
CONNECTED(00000003)
depth=3 C = DE, O = T-Systems Enterprise Services GmbH, OU = T-Systems Trust Center, CN = T-TeleSec GlobalRoot Class 2
verify return:1
depth=2 C = DE, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., OU = DFN-PKI, CN = DFN-Verein Certification Authority 2
verify return:1
depth=1 C = DE, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., OU = DFN-PKI, CN = DFN-Verein Global Issuing CA
verify return:1
depth=0 C = DE, ST = Berlin, L = Berlin, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., CN = wayf.aai.dfn.de
verify return:1
---
Certificate chain
 0 s:C = DE, ST = Berlin, L = Berlin, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., CN = wayf.aai.dfn.de
   i:C = DE, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., OU = DFN-PKI, CN = DFN-Verein Global Issuing CA
   a:PKEY: rsaEncryption, 4096 (bit); sigalg: RSA-SHA256
   v:NotBefore: Aug 17 09:11:20 2022 GMT; NotAfter: Sep 17 09:11:20 2023 GMT
 1 s:C = DE, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., OU = DFN-PKI, CN = DFN-Verein Global Issuing CA
   i:C = DE, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., OU = DFN-PKI, CN = DFN-Verein Certification Authority 2
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: May 24 11:38:40 2016 GMT; NotAfter: Feb 22 23:59:59 2031 GMT
 2 s:C = DE, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., OU = DFN-PKI, CN = DFN-Verein Certification Authority 2
   i:C = DE, O = T-Systems Enterprise Services GmbH, OU = T-Systems Trust Center, CN = T-TeleSec GlobalRoot Class 2
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Feb 22 13:38:22 2016 GMT; NotAfter: Feb 22 23:59:59 2031 GMT
---
Server certificate
-----BEGIN CERTIFICATE-----
MIII9jCCB96gAwIBAgIMJxwuQghQ6vPgo0CGMA0GCSqGSIb3DQEBCwUAMIGNMQsw
CQYDVQQGEwJERTFFMEMGA1UECgw8VmVyZWluIHp1ciBGb2VyZGVydW5nIGVpbmVz
IERldXRzY2hlbiBGb3JzY2h1bmdzbmV0emVzIGUuIFYuMRAwDgYDVQQLDAdERk4t
UEtJMSUwIwYDVQQDDBxERk4tVmVyZWluIEdsb2JhbCBJc3N1aW5nIENBMB4XDTIy
MDgxNzA5MTEyMFoXDTIzMDkxNzA5MTEyMFowgZAxCzAJBgNVBAYTAkRFMQ8wDQYD
VQQIDAZCZXJsaW4xDzANBgNVBAcMBkJlcmxpbjFFMEMGA1UECgw8VmVyZWluIHp1
ciBGb2VyZGVydW5nIGVpbmVzIERldXRzY2hlbiBGb3JzY2h1bmdzbmV0emVzIGUu
IFYuMRgwFgYDVQQDDA93YXlmLmFhaS5kZm4uZGUwggIiMA0GCSqGSIb3DQEBAQUA
A4ICDwAwggIKAoICAQDTgelyxRfx9V5DF5tNGrWEud9NAKFLJ6AtT2sH9k+9hIUb
LQq2JsX9u8FpxMb8aE/g8aFmDkqqYqHAfkSW5Z8KvV++YS+TvJppBOQnXKx8JbIM
OPi/PZblPerLXooBd30akjA3f+9PEX5Hb8ufl7p4JBPo1hJ8LE6tZi0aqoRElNJj
me0iiu7eboF6AVyH0vYSC9NQs1dbJ7GnS4dfagYjWMquqmJnwvYIWCtCkNypsXeZ
MbEYmDGuI+K2+74j4p8gr2Y9odOK/Tx544R0VeYaMyl9xdje2eT78PScMl/0uHKF
sR7rz9sVFOeCv5LxWAr+drzRMGZRaLPalJWGulhVgCO9y0/9FJ7+mw/Bx8fbIzWi
4R6Pie5Cj2Uo8LtMScCnFnj6kooZNTKetC+/zUeYxPpCpTJB3vtKuoImwY+BY9Fa
HAqlD30LbRc16ULxI67+NH/pFbKfwlNVYp5X/wSN1UuU02BRLHvAeEcxuNlG50Mj
OI4etFfkI443cXnTB9EGkdAS/P6aOoh3A2BhtXRFkQ5udbNYe2SCRXpZ+m+4XOIy
ZEzpvB0d3L+nKKjJ5qJVnCcOqWNb8wn2INtxSpFU7Vdcm16zeXsRh7SjcYQqdeh6
v761ePDMy3ERYyyrtKJh7Lp+YD1Jjw100X0axMwUb/oz41KjA8qTvRkn5YSIZwID
AQABo4IETzCCBEswVwYDVR0gBFAwTjAIBgZngQwBAgIwDQYLKwYBBAGBrSGCLB4w
DwYNKwYBBAGBrSGCLAEBBDAQBg4rBgEEAYGtIYIsAQEECjAQBg4rBgEEAYGtIYIs
AgEECjAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIFoDATBgNVHSUEDDAKBggrBgEF
BQcDATAdBgNVHQ4EFgQUrrmPRRWUYepArAkbkrf8yvHli9wwHwYDVR0jBBgwFoAU
azqYi/nyU4na4K2yMh4JH+iqO3QwGgYDVR0RBBMwEYIPd2F5Zi5hYWkuZGZuLmRl
MIGNBgNVHR8EgYUwgYIwP6A9oDuGOWh0dHA6Ly9jZHAxLnBjYS5kZm4uZGUvZGZu
LWNhLWdsb2JhbC1nMi9wdWIvY3JsL2NhY3JsLmNybDA/oD2gO4Y5aHR0cDovL2Nk
cDIucGNhLmRmbi5kZS9kZm4tY2EtZ2xvYmFsLWcyL3B1Yi9jcmwvY2FjcmwuY3Js
MIHbBggrBgEFBQcBAQSBzjCByzAzBggrBgEFBQcwAYYnaHR0cDovL29jc3AucGNh
LmRmbi5kZS9PQ1NQLVNlcnZlci9PQ1NQMEkGCCsGAQUFBzAChj1odHRwOi8vY2Rw
MS5wY2EuZGZuLmRlL2Rmbi1jYS1nbG9iYWwtZzIvcHViL2NhY2VydC9jYWNlcnQu
Y3J0MEkGCCsGAQUFBzAChj1odHRwOi8vY2RwMi5wY2EuZGZuLmRlL2Rmbi1jYS1n
bG9iYWwtZzIvcHViL2NhY2VydC9jYWNlcnQuY3J0MIIB9AYKKwYBBAHWeQIEAgSC
AeQEggHgAd4AdgCt9776fP8QyIudPZwePhhqtGcpXc+xDCTKhYY069yCigAAAYKr
EmbRAAAEAwBHMEUCIQDSmTwCWlCZATCfLURkGOxyR6pgKvj4d+TlKaMPXifttQIg
JOOE+3NXWghkYUJ36/Q+vSbxeRlS5FACic+kyzbAyQUAdQDoPtDaPvUGNTLnVyi8
iWvJA9PL0RFr7Otp4Xd9bQa9bgAAAYKrEmhKAAAEAwBGMEQCIDHPHuRKGYvrzd69
GBjuuuPfW3PGKOvY5yPd47ulHifCAiAfmBQHB5LIex3DO17m3aQlT+cgV01eLykK
EjF1mtq9qwB2AG9Tdqwx8DEZ2JkApFEV/3cVHBHZAsEAKQaNsgiaN9kTAAABgqsS
ZMUAAAQDAEcwRQIhAJ3/1gN+37V04DsHihKJH0Ireh04yaOHx3EWnqLXsaGMAiBy
8/C02kJgI5SLeFlJZghoIIT2rqy/iu8M8v+F0Cnq2wB1AFWB1MIWkDYBSuoLm1c8
U/DA5Dh4cCUIFy+jqh0HE9MMAAABgqsSZTQAAAQDAEYwRAIgDY0Wn4W8l8W7Jw8T
cy8rYjYCDc8j/opI+EsDK8+Q4OMCICGxPKaWwV04+7QOh5bdi0vNgm38V9RHP9F/
ps1wheNyMA0GCSqGSIb3DQEBCwUAA4IBAQBsn0WeEePbkHi0/RRCzFS8HDg4AIXV
nk7R3x0XsgnHFpMJEM2mRJlMJrjYNjYa/X6ynsXg78yGqRvPhdqRX1oqUI1lDaLa
Znj9+ZMfcfcTaDL74yE0jTbPGz4ayBA7dJJ9w2kSKwF0Mc0VLYNfuekSmqQJ1i4G
T1Z6ThTm3gNdv5tOnhImwOVYT62BwyzY6/wB4dPo32R9hdQjMETh9oREQ4NyKXPw
nrJ8a6vsyPKkyDjTh88AdxAdlozqXQrYC8/hGsbQcrdbSHxXuYAWF8ErW4HuZ+PZ
jiH9LG5qUw6EIvaYgiuxm8HVU4NOvF2cqwbtLfft1klxpqywN2jTIJEy
-----END CERTIFICATE-----
subject=C = DE, ST = Berlin, L = Berlin, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., CN = wayf.aai.dfn.de
issuer=C = DE, O = Verein zur Foerderung eines Deutschen Forschungsnetzes e. V., OU = DFN-PKI, CN = DFN-Verein Global Issuing CA
---
No client certificate CA names sent
Peer signing digest: SHA256
Peer signature type: RSA-PSS
Server Temp Key: X25519, 253 bits
---
SSL handshake has read 5882 bytes and written 397 bytes
Verification: OK
---
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
Server public key is 4096 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 0 (ok)
---
---
Post-Handshake New Session Ticket arrived:
SSL-Session:
    Protocol  : TLSv1.3
    Cipher    : TLS_AES_256_GCM_SHA384
    Session-ID: 284526F924E23FFDDA8286A63996DBB7EECBEBBCADAE3EAEB6DCD94A97ECCC64
    Session-ID-ctx: 
    Resumption PSK: 57A5B30716BB320C1D53CAF09D667C1D08AE179DB450063ED7305CBBD15B29C49AAFC7C8E381640717BA7FF6F3789F99
    PSK identity: None
    PSK identity hint: None
    SRP username: None
    TLS session ticket lifetime hint: 7200 (seconds)
    TLS session ticket:
    0000 - 83 6b 3a c5 50 ec c5 be-ab d4 49 ed 95 80 48 21   .k:.P.....I...H!
    0010 - 4d c7 ff 8f 8d 0c cb 63-a4 1d 11 9f 7b 86 0c 65   M......c....{..e

    Start Time: 1673270213
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)
    Extended master secret: no
    Max Early Data: 0
---
read R BLOCK
---
Post-Handshake New Session Ticket arrived:
SSL-Session:
    Protocol  : TLSv1.3
    Cipher    : TLS_AES_256_GCM_SHA384
    Session-ID: F0E581A89E7A0103398D4984082F5967E5B26079DD86D41499719A72237B3A2D
    Session-ID-ctx: 
    Resumption PSK: 0EED21E37A6873AC74CEE4F17DFD953850966D0AC73CD2B76FDA0C8995052DB66D489DCD07E464E492755BC8212ACD3B
    PSK identity: None
    PSK identity hint: None
    SRP username: None
    TLS session ticket lifetime hint: 7200 (seconds)
    TLS session ticket:
    0000 - a8 d0 1b 2e ca e6 70 cb-61 72 45 45 b7 e4 76 3e   ......p.arEE..v>
    0010 - f7 59 ad 02 e7 8a 50 39-11 a7 81 8a 78 36 6b d6   .Y....P9....x6k.

    Start Time: 1673270213
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)
    Extended master secret: no
    Max Early Data: 0
---
read R BLOCK