Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revisionBoth sides next revision
en:certificates [2017/12/04 15:43] – [Common Trusted CA Certificates] Silke Meyeren:certificates [2019/09/12 11:16] Silke Meyer
Line 1: Line 1:
-====== Certificates for SAML-based communication ======+~~NOTOC~~ 
 +====== Certificates ====== 
 +{{INLINETOC 2}} 
 +===== Certificates for SAML-based communication =====
 In the context of SAML-based communication between IdP and SP, certificates are used for purposes of signature validation and encryption. Those certificates must be registered for the respective entity using the [[en:metadata_admin_tool|metadata administration tool]]. In the context of SAML-based communication between IdP and SP, certificates are used for purposes of signature validation and encryption. Those certificates must be registered for the respective entity using the [[en:metadata_admin_tool|metadata administration tool]].
  
-**The general rule is:** Entities with invalid (that is expired or revoked) certificates are automatically removed from the productive DFN-AAI federation! +**The general rule is:** Entities with invalid (i.e. expired or revoked) certificates are automatically removed from the productive DFN-AAI federation! 
-===== Information for Identity Providers / Attribute Authorities =====+==== Information for Identity Providers / Attribute Authorities ====
 Cf. [[de:shibidp3prepare-zert#dfn-pki-zertifikate|Vorbereitung: Zertifikate]] Cf. [[de:shibidp3prepare-zert#dfn-pki-zertifikate|Vorbereitung: Zertifikate]]
  
-===== Information for Service Providers ===== +==== Information for Service Providers ==== 
-All certificates and the respective private keys used for SAML-based communication have to be add to your SP's configuration, no matter which of the options mentioned below you choose. With Shibboleth SP this is the ''CredentialResolver'' element in /etc/shibboleth/shibboleth2.xml (see [[https://wiki.aai.dfn.de/de:shibsp|Shibboleth SP (de)]]).+All certificates and the respective private keys used for SAML-based communication have to be added to your SP's configuration, no matter which of the options mentioned below you choose. With Shibboleth SP this is the ''CredentialResolver'' element in /etc/shibboleth/shibboleth2.xml (see [[de:shibsp|Shibboleth SP (de)]]).
  
-==== DFN-PKI Certificates ====+=== DFN-PKI Certificates === 
 +For general information, please refer to https://www.pki.dfn.de/dfn-aai-zertifikate/ \\
 If you are entitled to request certificates issued by DFN-PKI, please select the "Shibboleth IdP SP" profile when submitting your CSR. Upload the server certificate in the metadata administration tool. If you are entitled to request certificates issued by DFN-PKI, please select the "Shibboleth IdP SP" profile when submitting your CSR. Upload the server certificate in the metadata administration tool.
  
-==== Common Trusted CA Certificates ==== +=== Common Trusted CA Certificates === 
-You can use certificates issued by common Certification Authorities (CAs) that are preinstalled in the most common web browsers (Google Chrome, Firefox, Microsoft Edge). They must not exceed a validity of 39 months. If you get an "Issuer not found" warning for such a certificate please contact our [[mailto:hotline@aai.dfn.de|helpdesk]]. +You can use certificates issued by common Certification Authorities (CAs) that are preinstalled in the most common web browsers (Google Chrome, Firefox, Microsoft Edge). They must not exceed a validity of 39 months. If you get an "Issuer not found" warning for such a certificate please contact our [[hotline@aai.dfn.de|helpdesk]]. 
-**Service Providers that are already registered with another federation, the same certificate (i.e. the one registered with the other federation) may be used even if the aforementioned requirements are not met.** In this case, please drop a note to the DFN-AAI [[mailto:hotline@aai.dfn.de|helpdesk]].+
  
-==== Self-signed Certificates ==== +=== Self-signed Certificates === 
-Self-signed certificates may be used as well if they are not valid for longer than 39 months. As for the technical aspects, please refer to the online documentation of [[https://www.switch.ch/aai/guides/sp/configuration/#4|SWITCHaai]]. Before joining the DFN-AAI production federation, self-signed certificates have to be verified by the DFN-AAI operations team. For this purpose, the following options are available after you uploaded your certificate in the metadata administration tool:+Self-signed certificates may be used as well if they are not valid for longer than 39 months. For production, the CN (or the subject alternative names) of the certificate must at least contain the domain name of the SP. Ideally it should contain the complete host name. As for the technical details, please refer to the online documentation of [[https://www.switch.ch/aai/guides/sp/configuration/#4|SWITCHaai]]. Before joining the DFN-AAI production federation, self-signed certificates have to be verified by the DFN-AAI operations team. For this purpose, the following options are available after you uploaded your certificate in the metadata administration tool:
   * Please offer us a possibility to download the certificate via https (e.g. via your SPs metadata handler or a download link to the file on your webserver). The SSL connection to the webserver has to be secured by a trusted CA certificate.   * Please offer us a possibility to download the certificate via https (e.g. via your SPs metadata handler or a download link to the file on your webserver). The SSL connection to the webserver has to be secured by a trusted CA certificate.
   * If you do not have the possibility to send us a download link, we can compare the certificate's fingerprint via fax to +49-711-63314-133 (caller-ID must be transmitted!) or telephone (we'll call you on a publicly known number). Here is how you find out the fingerprints:   * If you do not have the possibility to send us a download link, we can compare the certificate's fingerprint via fax to +49-711-63314-133 (caller-ID must be transmitted!) or telephone (we'll call you on a publicly known number). Here is how you find out the fingerprints:
Line 24: Line 27:
 $ openssl x509 -noout -fingerprint -sha256 -in self-signed-server-cert.pem $ openssl x509 -noout -fingerprint -sha256 -in self-signed-server-cert.pem
 </code> </code>
-  * As a third option, you can send us the certificate in an S/MIME-signed (signing cert form a well known CA) email to [[mailto:hotline@aai.dfn.de|hotline@aai.dfn.de]]+  * As a third option, you can send us the certificate in an S/MIME-signed (signing cert form a well known CA) email to [[hotline@aai.dfn.de|hotline@aai.dfn.de]].
-  * For production, the CN (or the subject alternative names) of the certificate must at least contain the domain name of the SP. Ideally it should contain the complete host name.+
  
-==== Please avoid the following certificates ==== +<callout type="danger" title="Exceptions"> 
-=== Wildcard certificates ===+**As for Service Providers that are already registered with another federation, the same certificate (i.e. the one registered with the other federation) may be used even if the aforementioned requirements are not met.** In this case, please drop a note to the DFN-AAI [[hotline@aai.dfn.de|helpdesk]]. 
 +</callout> 
 + 
 +=== Please avoid the following certificates === 
 +== Wildcard certificates ==
 The use of wildcard certificates is only permitted in duly justified cases. The use of wildcard certificates is only permitted in duly justified cases.
  
-=== Letsencrypt === +== Letsencrypt == 
-We strongly advise against the use of Letsencrypt certificates for SAML-based communication as they expire after 90 days. Every time, you would have to do a manual certificate rollover in the metadata administration tool. The SP configuration has to be adapted twice for a rollover, too. That is why we recommend self-signed certificates with a validity of 3 year+We strongly advise against the use of Letsencrypt certificates for SAML-based communication as they expire after 90 days. Every time, you would have to do a manual certificate rollover in the metadata administration tool. The SP configuration has to be adapted twice for a rollover, too. That is why we recommend self-signed certificates with a validity of 3 years. (If you are securing your webserver with Letsencrypt certificates, that is obviously no problem.
  
 **Next step:** [[en:functionaltest|Functional Tests]] **Next step:** [[en:functionaltest|Functional Tests]]
  
-==== Certificate rollover ==== +==== Certificate / Key Rollover (SP) ==== 
-Whenever you switch to a new certificate, both the old and the new one are temporarily part of the federation's metadata. We recommend the documentation of [[https://www.switch.ch/aai/support/certificates/certificate-migration/|SWITCHaai]]. (When their documentation tells you to wait two hours, you should wait a whole day as the distribution of metadata to all DFN-AAI participants can take that long. If you have a DFN-PKI certificate, replace their referrals to self-signed certificates with the DFN-PKI certificate.)+ 
 +Whenever you switch to a new certificate, both the old and the new one are temporarily part of the federation's metadata. We recommend the documentation of [[https://www.switch.ch/aai/support/certificates/certificate-migration/|SWITCHaai]]. (When their documentation tells you to wait two hours, you should wait a whole day as the distribution of metadata to all DFN-AAI participants can take that long. If you have a DFN-PKI certificate, replace their referrals to self-signed certificates with the DFN-PKI certificate.) There is also some documentation in the [[https://wiki.shibboleth.net/confluence/display/SP3/Multiple+Credentials#MultipleCredentials-KeyRollover|Shibboleth Wiki]].
  
-====== The SSL certificate chain on your webserver ======+===== The SSL certificate chain on your webserver =====
 Your webserver's SSL configuration is not directly affected by the configuration of SAML-based communication in DFN-AAI. That said, the webserver still has to deliver a valid certificate chain: The binding URLs are secured by SSL/TLS as well as the IdP/SP websites. If end users' devices validate the certificate chain they will encounter errors on your site. Android devices, for example, will not trust the connection. With Shibboleth IdPs, you can verify it by calling the status page (https://idp.domain.tld/idp/status). With Shibboleth SPs, we recommend to check the Session Handler (https://sp.domain.tld/Shibboleth.sso/Session). Your webserver's SSL configuration is not directly affected by the configuration of SAML-based communication in DFN-AAI. That said, the webserver still has to deliver a valid certificate chain: The binding URLs are secured by SSL/TLS as well as the IdP/SP websites. If end users' devices validate the certificate chain they will encounter errors on your site. Android devices, for example, will not trust the connection. With Shibboleth IdPs, you can verify it by calling the status page (https://idp.domain.tld/idp/status). With Shibboleth SPs, we recommend to check the Session Handler (https://sp.domain.tld/Shibboleth.sso/Session).
  
Line 45: Line 52:
   * You need a file containing the private key. On a linux machine, it should be something like /etc/ssl/private/idp.domain.tld.key. You also need the respective server certificate which you could put in /etc/ssl/localcerts/idp.domain.tld.pem.   * You need a file containing the private key. On a linux machine, it should be something like /etc/ssl/private/idp.domain.tld.key. You also need the respective server certificate which you could put in /etc/ssl/localcerts/idp.domain.tld.pem.
   * Create a third file containing the complete chain, e.g. /etc/ssl/certs/idp.domain.tld.pem. Add this file to your webserver's configuration. It contains:   * Create a third file containing the complete chain, e.g. /etc/ssl/certs/idp.domain.tld.pem. Add this file to your webserver's configuration. It contains:
-   * the server certificate +    * the server certificate 
-   * one or more matching intermediate certificates +    * one or more matching intermediate certificates 
-   * the CA's root certificate+    * the CA's root certificate
 These certificates are appended to the file in this order. You may add comments in between (beginning with a "#"). The chains must not contain any additional certificates. Below you can find the full certificate chain for dfn.de as an example. These certificates are appended to the file in this order. You may add comments in between (beginning with a "#"). The chains must not contain any additional certificates. Below you can find the full certificate chain for dfn.de as an example.
  
Line 56: Line 63:
 6ded7378 6ded7378
 </code> </code>
-  * Check the hash of the first intermediate certificate. it should match the server certificate's issuer hash.+  * Check the hash of the first intermediate certificate. It should match the server certificate's issuer hash.
 <code> <code>
 $ openssl x509 -in intermediate1.pem -noout -hash $ openssl x509 -in intermediate1.pem -noout -hash
Line 68: Line 75:
 If there is another intermediate certificate, compare the above issuer hash with its hash and so on. Like this, you crawl up to the root certificate step by step. If there is another intermediate certificate, compare the above issuer hash with its hash and so on. Like this, you crawl up to the root certificate step by step.
  
-If you use the Apache webserver, point the SSLCACertificateFile directive to your chain file. (See the example configuration on [[de:shibidp3prepare-http#konfiguration|IdP Preparations: HTTPServer]] resp. [[de:shibsp#konfigurationsbeispiel|Shibboleth SP configuration example]].+If you use the Apache webserver, point the SSLCACertificateFile directive to your chain file. (See the example configuration on [[de:shibidp3prepare-http#konfiguration|IdP Preparations: HTTPServer]] resp. [[de:shibsp#konfigurationsbeispiel|Shibboleth SP configuration example]]).
  
 Once you have added you certificate chain, adapted your configuration and activated it you can verify it with OpenSSL: Once you have added you certificate chain, adapted your configuration and activated it you can verify it with OpenSSL:
Line 74: Line 81:
 $ openssl s_client -connect idp.domain.tld:443 $ openssl s_client -connect idp.domain.tld:443
 </code> </code>
-Below you can the answer of dfn.de's webserver as an example. As an alternative you can use external services, e.g. the  [[https://www.ssllabs.com/ssltest/|SSLLabs]] website.+Below you can see the answer of dfn.de's webserver as an example. As an alternative you can use external services, e.g. the [[https://www.ssllabs.com/ssltest/|SSLLabs]] website.
  
 **Next step:** [[en:functionaltest|Functional Tests]] **Next step:** [[en:functionaltest|Functional Tests]]
  • Last modified: 14 months ago