Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- de:certificates [2023/01/23 15:48] – [9. zweites Bean auskommentieren] + config snippet Silke Meyer
+++ de:certificates [2025/08/27 11:09] (aktuell) – [Informationen für Service Provider] Andreas Borm
@@ Zeile 5: / Zeile 5: @@
 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 [[de:metadata_admin_tool|Metadatenverwaltung]] eingetragen werden.
+Bei unseren Vorgaben bzgl. Signaturalgorithmus und Schlüssellänge richten wir uns nach dem Empfehlungen des BSI ([[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR03116/BSI-TR-03116-4.pdf?__blob=publicationFile&v|BSI TR-03116]], Kapitel 3).
 <callout color="#ff9900" title="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!
 </callout>
+\\
 ==== Informationen für Identity Provider / Attribute Authorities ====
 Siehe unter [[de:shibidp:prepare-zert|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. [[de:shibsp|Shibboleth SP]]
+\\
 === Zertifikate der DFN-PKI bzw. DFN-Verein Community PKI===
-Für die SAML-basierte Kommunikation empfehlen sich **3 Jahre gültige Zertifikate aus der [[https://www.pki.dfn.de/dfn-verein-community-pki|DFN-Verein Community PKI]]**.
+Für die SAML-basierte Kommunikation empfehlen sich **39 Monate gültige Zertifikate aus der [[de:dfnpki:dfnvereincommunitypki|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 [[https://www.switch.ch/aai/guides/sp/configuration/#4|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 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 [[https://help.switch.ch/aai/guides/sp/embedded-certificate/?hostname=yourhost.example.org|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 ===
@@ Zeile 32: / Zeile 44: @@
 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.
 </callout>
+\\
+=== 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 Wildcard-Zertifikate ===
+\\
-Die Nutzung von Wildcards in Zertifikaten ist nur in begründeten Ausnahmefällen gestattet.
 === 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:** [[de:functionaltest|Funktionstests]]
@@ Zeile 45: / Zeile 65: @@
 Vielen Dank an die Schweizer Kolleg*innen für die ausführliche englischsprachige [[https://www.switch.ch/aai/guides/sp/certificate-rollover/|Dokumentation]] zur SWITCHaai, die uns beim Erstellen als Vorlage gedient hat!
-Wenn Sie ablaufende Zertifikate auf Ihrem AAI-Systemen austauschen müssen, gehen Sie wie folgt vor:
+Wenn Sie ablaufende Zertifikate auf Ihren AAI-Systemen austauschen müssen, gehen Sie wie folgt vor:
 ==== 1. Was muss getauscht werden? ====
@@ Zeile 51: / Zeile 71: @@
 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/Generierung eines neuen Zertifikates ====
+==== 2. Beschaffung eines neuen Zertifikates ====
-=== DFN-PKI ===
+siehe oben
-Bei Fragen zur Erstellung von privaten Schlüsseln und Zertifikatsanträgen, schauen Sie bitte in die Dokumentation der Software, mit der Sie diese generieren. Die DFN-PKI bietet eine [[https://www.pki.dfn.de/fileadmin/PKI/anleitungen/Anleitung_Nutzung_OpenSSL.pdf|Zusammenfassung der wichtigsten OpenSSL-Befehle]] und ausführliche [[https://www.pki.dfn.de/faqpki/faqpki-allgemein/#c15083 | FAQ]] rund um Zertifikate. Das folgende Vorgehen müssen Sie möglicherweise an Ihre Umgebung anpassen.
-  * Sie können Ihren alten privaten Schlüssel weiterverwenden, wenn er nicht kompromittiert wurde. Oder Sie erstellen einen neuen privaten Schlüssel:<code>
-user@host:~$ openssl genrsa -out idp.example.org.key.pem 4096
-</code>
-  * Erstellen Sie einen Zertifikatsantrag (Certificate Signing Request, csr):<code>
-user@host:~$ openssl req -new -key idp.example.org.key.pem -out idp.example.org.csr.pem
-# Sie werden Folgendes abgefragt, evtl. befüllt mit Vorgaben aus Ihrer /etc/ssl/openssl.cnf
-Country Name (2 letter code) [DE]:
-State or Province Name (full name) []:            <== Bundesland
-Locality Name (eg, city) []:                      <== Stadt
-Organization Name (eg, company) []:               <== Einrichtung
-Organizational Unit Name (eg, section) []:        <== ggf. Abteilung o.ä.
-Common Name (eg, YOUR name) []:SERVERNAME         <== HIER DEN FQDN EINSETZEN!
-A challenge password []:
-An optional company name []:
-</code>
-  * Geben Sie diesen Zertifikatsantrag im .pem-Format bei der DFN-PKI ein. Wählen Sie das Profil "Shibboleth-IdP/-SP".
-  * Sie bekommen Ihr neues Zertifikat per E-Mail von der DFN-PKI.
-=== Sonstige Zertifizierungsstellen bzw. CAs ===
-Konsultieren Sie hierzu die Dokumentation des [[#zertifikate_gaengiger_zertifizierungsstellen|jeweiligen Anbieters]] bzw. dessen Kundensupport.
-=== Selbst-signierte Zertifikate ===
-Selbst-signierte Zertifikate sind ausschließlich für die SAML-basierte Kommunikation geeignet! Sowohl Shibboleth IdP als auch Shibboleth SP werden mit einem ''keygen'' Skript ausgeliefert, mit dessen Hilfe sich selbst-signierte Zertifikate erstellen lassen. Ansonsten ist dies z.B. auch mit OpenSSL möglich. Wichtig hierbei ist dass die Laufzeit 39 Monate nicht übersteigt und die Keylänge mindestens 3072 Bit beträgt (Voreinstellung bei Shibboleth). Siehe hierzu einstweilen die Dokumentation von SWITCH:
-  * [[https://www.switch.ch/aai/guides/idp/certificate-rollover/|Shibboleth IdP, Step 0]] (Wichtig: Tomcat User muss Leserecht auf den private Key haben.)
-  * [[https://www.switch.ch/aai/guides/sp/certificate-rollover/|Shibboleth SP, Step 0]]
-  * [[https://www.switch.ch/aai/support/certificates/embeddedcerts-requirements-appendix-a/|OpenSSL]]
 ==== 3. Ggf. Zertifikat am Webserver tauschen ====
   * Ersetzen Sie die alten, in der Webserverkonfiguration eingetragenen Dateien durch das neue Zertifikat, den privaten Schlüssel und die Zertifikatskette. (Unten auf dieser Seite ist erklärt, wie Sie die [[https://doku.tid.dfn.de/de:certificates#die_ssl-zertifikatskette_auf_ihrem_webserver|komplette Zertifikatskette]] ausliefern.)
   * Starten Sie den Webserver neu.
+  * Falls Sie für die SAML-Kommunikation ein anderes Zertifikat als für den Webserver verwenden (vgl. [[https://doku.tid.dfn.de/de:shibidp:prepare-zert#zertifikate_fuer_webserver_und_saml-basierte_kommunikation]]), tauschen Sie das Zertifikat für Port 8443 ([[https://doku.tid.dfn.de/de:shibidp:prepare-http#besonderheiten_bei_backchannel_requests]]) noch nicht jetzt, sondern erst nach dem letzten Schritt.
 ==== 4. Zertifikatswechsel auf dem IdP ====
   * Editieren Sie die Datei ''conf/credentials.xml'': Entfernen Sie dort die Kommentarzeichen um das zweite ''BasicX509CredentialFactoryBean''.<file xml>        <!--
@@ Zeile 97: / Zeile 90: @@
             p:entityId-ref="entityID" />
 </file>
+  * **ab IdP Version 4.3**: Editieren Sie die Datei ''conf/credentials.xml'': Entfernen Sie dort die Kommentarzeichen um das zweite ''BasicX509CredentialFactoryBean''.<file xml>        <!--
+        For key rollover, uncomment and point to your original keypair, and use the one above
+        to point to your new keypair. Once metadata has propagated, comment this one out again.
+        -->
+        <bean parent="shibboleth.BasicX509CredentialFactoryBean"
+            p:privateKeyResource="%{idp.encryption.key.2}"
+            p:certificateResource="%{idp.encryption.cert.2}"
+            p:entityId-ref="entityID" />
+</file>
 ==== 5. zweites Zertifikat für SAML-Kommunikation eintragen ====
@@ Zeile 111: / Zeile 113: @@
 ==== 6. Zertifikat für SAML-Kommunikation in Metadatenverwaltung eintragen ====
+  * Ein unterbrechungsfreier Betrieb ist nur möglich, wenn alle Service Provider weiterhin mit dem IdP kommunizieren können. Die SPs müssen sich vorab das neue Zertifikat aus den aktualisierten Föderationsmetadaten geholt haben. Besonders, wenn Sie an eduGAIN teilnehmen, müssen Sie davon ausgehen, dass manche SPs dies nur einmal pro Tag tun.
+  * Wenn Sie bei der Erstellung des Zertifikatsantrags denselben privaten Schlüssel verwendet haben, den Sie auch für das ablaufende Zertifikat verwendet haben, ist die Veröffentlichung des neuen Zertifikates in Metadaten nicht so zeitkritisch. Das können Sie machen, wenn der Schlüssel nicht kompromittiert ist und nach wie vor den aktuellen technischen Anforderung entspricht.
 <callout color="#ff9900" title="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!**
 </callout>
-  * Ein unterbrechungsfreier Betrieb ist nur möglich, wenn alle Service Provider weiterhin mit dem IdP kommunizieren können. Die SPs müssen sich vorab das neue Zertifikat aus den aktualisierten Föderationsmetadaten geholt haben. Besonders, wenn Sie an eduGAIN teilnehmen, müssen Sie davon ausgehen, dass manche SPs dies nur einmal pro Tag tun.
-  * Wenn Sie bei der Erstellung des Zertifikatsantrags denselben privaten Schlüssel verwendet haben, den Sie auch für das ablaufende Zertifikat verwendet haben, ist die Veröffentlichung des neuen Zertifikates in Metadaten nicht so zeitkritisch. Das können Sie machen, wenn der Schlüssel nicht kompromittiert ist und nach wie vor den aktuellen technischen Anforderung entspricht.
 ==== 7. Alt und neu in der Konfiguration vertauschen ====
-  * Nachdem das neue Zertifikat sich über die Metadaten herumgesprochen hat, tauschen Sie in ''conf/idp.properties'' alt und neu:<code>
+  * Nachdem das neue Zertifikat sich über die Metadaten herumgesprochen hat, entfernen Sie das alte Zertifikat aus den Föderationsmetadaten.
+  * In ''conf/idp.properties'' ersetzen Sie beim Signing-Key das alte durch das neue Zertifikat; beim Encryption-Key tauschen Sie alt und neu:<code>
 idp.signing.key= /etc/ssl/private/idp_neu.example.org.key.pem
 idp.signing.cert= /etc/ssl/localcerts/idp_neu.example.org.crt.pem
@@ Zeile 127: / Zeile 131: @@
 </code>
   * Starten Sie Tomcat neu.
-  * **Warten Sie erneut 24 Stunden!**
+<callout color="#ff9900" title="24 Stunden Wartezeit">
+**Nach diesem Schritt warten Sie bitte erneut mindestens 24 Stunden, bevor Sie weitermachen.**
+</callout>
 ==== 8. Alte Zertifikate für SAML-Kommunikation aus Konfiguration entfernen ====
   * Entfernen Sie das alte Zertifikat und den alten privaten Schlüssel aus der ''conf/idp.properties''.<code>
@@ Zeile 144: / Zeile 149: @@
         <!--
         <bean class="net.shibboleth.idp.profile.spring.factory.BasicX509CredentialFactoryBean"
+            p:privateKeyResource="%{idp.encryption.key.2}"
+            p:certificateResource="%{idp.encryption.cert.2}"
+            p:entityId-ref="entityID" />
+        -->
+</file>
+  * **Ab IdP Version 4.3**: Editieren Sie die Datei ''conf/credentials.xml'' erneut: Fügen Sie die Kommentarzeichen um das zweite ''BasicX509CredentialFactoryBean'' wieder ein.<file xml>        <!--
+        For key rollover, uncomment and point to your original keypair, and use the one above
+        to point to your new keypair. Once metadata has propagated, comment this one out again.
+        -->
+        <!--
+        <bean parent="shibboleth.BasicX509CredentialFactoryBean"
             p:privateKeyResource="%{idp.encryption.key.2}"
             p:certificateResource="%{idp.encryption.cert.2}"
@@ Zeile 150: / Zeile 167: @@
 </file>
   * Starten Sie Tomcat neu.
+  * Falls Sie für die SAML-Kommunikation ein anderes Zertifikat als für den Webserver verwenden, tauschen Sie jetzt auch das Zertifikat in der Konfiguration für Port 8443 (siehe [[https://doku.tid.dfn.de/de:shibidp:prepare-http#besonderheiten_bei_backchannel_requests]]).
 ===== Zertifikatstausch am SP =====
@@ Zeile 158: / Zeile 176: @@
 ==== 2. Beschaffung eines neuen Zertifikates ====
-=== DFN-PKI ===
+siehe oben
-Bei Fragen zur Erstellung von privaten Schlüsseln und Zertifikatsanträgen, schauen Sie bitte in die Dokumentation der Software, mit der Sie diese generieren. Die DFN-PKI bietet eine [[https://www.pki.dfn.de/fileadmin/PKI/anleitungen/Anleitung_Nutzung_OpenSSL.pdf|Zusammenfassung der wichtigsten OpenSSL-Befehle]] und ausführliche [[https://www.pki.dfn.de/faqpki/faqpki-allgemein/#c15083 | FAQ]] rund um Zertifikate. Das folgende Vorgehen müssen Sie möglicherweise an Ihre Umgebung anpassen.
-  * Sie können Ihren alten privaten Schlüssel weiterverwenden, wenn er nicht kompromittiert wurde. Oder Sie erstellen einen neuen privaten Schlüssel:<code>
-user@host:~$ openssl genrsa -out idp.example.org.key.pem 4096
-</code>
-  * Erstellen Sie einen Zertifikatsantrag (Certificate Signing Request, csr):<code>
-user@host:~$ openssl req -new -key idp.example.org.key.pem -out idp.example.org.csr.pem
-# Sie werden Folgendes abgefragt, evtl. befüllt mit Vorgaben aus Ihrer /etc/ssl/openssl.cnf
-Country Name (2 letter code) [DE]:
-State or Province Name (full name) []:            <== Bundesland
-Locality Name (eg, city) []:                      <== Stadt
-Organization Name (eg, company) []:               <== Einrichtung
-Organizational Unit Name (eg, section) []:        <== ggf. Abteilung o.ä.
-Common Name (eg, YOUR name) []:SERVERNAME         <== HIER DEN FQDN EINSETZEN!
-A challenge password []:
-An optional company name []:
-</code>
-  * Geben Sie diesen Zertifikatsantrag im .pem-Format bei der DFN-PKI ein. Wählen Sie das Profil "Shibboleth-IdP/-SP".
-  * Sie bekommen Ihr neues Zertifikat per E-Mail von der DFN-PKI.
-=== Sonstige Zertifizierungsstellen bzw. CAs ===
-Konsultieren Sie hierzu die Dokumentation des [[#zertifikate_gaengiger_zertifizierungsstellen|jeweiligen Anbieters]] bzw. dessen Kundensupport.
-=== Selbst-signierte Zertifikate ===
-Selbst-signierte Zertifikate sind ausschließlich für die SAML-basierte Kommunikation geeignet! Sowohl Shibboleth IdP als auch Shibboleth SP werden mit einem ''keygen'' Skript ausgeliefert, mit dessen Hilfe sich selbst-signierte Zertifikate erstellen lassen. Ansonsten ist dies z.B. auch mit OpenSSL möglich. Wichtig hierbei ist dass die Laufzeit 39 Monate nicht übersteigt und die Keylänge mindestens 3072 Bit beträgt (Voreinstellung bei Shibboleth). Siehe hierzu einstweilen die Dokumentation von SWITCH:
-  * [[https://www.switch.ch/aai/guides/idp/certificate-rollover/|Shibboleth IdP, Step 0]] (Wichtig: Tomcat User muss Leserecht auf den private Key haben.)
-  * [[https://www.switch.ch/aai/guides/sp/certificate-rollover/|Shibboleth SP, Step 0]]
-  * [[https://www.switch.ch/aai/support/certificates/embeddedcerts-requirements-appendix-a/|OpenSSL]]
 ==== 3. Ggf. Zertifikat am Webserver tauschen ====
   * Ersetzen Sie die alten, in der Webserverkonfiguration eingetragenen Dateien durch das neue Zertifikat, den privaten Schlüssel und die Zertifikatskette. (Unten auf dieser Seite ist erklärt, wie Sie die [[https://doku.tid.dfn.de/de:certificates#die_ssl-zertifikatskette_auf_ihrem_webserver|komplette Zertifikatskette]] ausliefern.)
@@ Zeile 193: / Zeile 182: @@
 ==== 4. Zertifikate für SAML-Kommunikation tauschen ====
-Im Gegensatz zum IdP ist beim SP zu beachten, dass der **SP vorübergehend beide Zertifikate bzw. Schlüssel benötigt**, alt und neu, denn er muss in der Lage sein, Authentication Requests zu signieren und SAML Assertions zu entschlüsseln.
+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.
   * Legen Sie das neue Zertifikat, den privaten Schlüssel und ggf. die Zertifikatskette auf den Server. Es ist wichtig, dass der Benutzer, mit dessen Kennung der ''shibd''-Prozess läuft, die Dateien lesen kann.<code bash>
 # Benutzerkennung feststellen:
@@ Zeile 244: / Zeile 233: @@
 </code>
   * Starten Sie den Dienst ''shibd'' neu:<code bash>root@sp:~ # systemctl restart shibd</code>
-  * Jetzt können Sie gleich das alte Zertifikat aus den Metadaten des SP herausnehmen. **Warten** Sie dann erneut bis zu 24 Stunden (sicher ist sicher), bis sich die Änderung in der DFN-AAI bzw. in eduGAIN herumgesprochen hat.
-==== 6. Zertifikate für SAML-Kommunikation tauschen ====
+<callout color="#ff9900" title="24 Stunden Wartezeit">
+**Entfernen Sie jetzt das alte Zertifikat aus den Föderationsmetadaten und warten Sie 24 Stunden mit dem nächsten Schritt.**
+</callout>
+==== 6. Altes Zertifikat aus der SP-Konfiguration entfernen ====
   * Entfernen Sie das alte Zertifikat aus der SP-Konfiguration, indem Sie es entweder löschen oder auskommentieren:<code xml>