FEDURUS

Shibboleth Identity Provider Certificate Rollover

This page describes the process of certificate rollover for Shibboleth Identity Providers. The procedure described below allows replacing certificates without any service disruptions.

Scope

Please note that the instructions are only applicable for a Shibboleth Identity Provider (IdP) configured according to the FEDURUS Shibboleth Identity Provider deployment guides!

Background Information

A Shibboleth Identity Provider (IdP) needs a certificate to sign SAML assertions. The certificate of an IdP is embedded in SAML metadata so that the Service Providers (SPs) know an IdP's certificate. Therefore, a new certificate has to be added to the federation metadata (via AAI Resource Registry).

Changes in metadata require at minimum 1 hour to propagate to all relying parties. Therefore, certificates cannot be replaced in one single step. While most relying parties downloaded metadata within two hours, this is not guaranteed for all entities. In particular, entities reachable via the interfederation service eduGAIN might need up to 24 hours to update metadata. Certificate rollover can however be performed without any service interruption for services using the Shibboleth or SimpleSAMLphp software. For this to work, the order and the timing of the following steps are crucial.

Setup

Identity Provider Certificate Rollover Instructions

An overview of the general procedure can be found in the following graphic. It explain how to perform the certificate rollover without any service disruption.

Step 0: Create new certificate

First, ensure that openssl is installed on the host as this is required for the following commands. If not availble yet, please install openssl (on Debian openssl can be installed as root with the command: apt-get install openssl).
FEDURUS recommends to use self-signed certificates for Shibboleth. If you already have a certificate that meets the FEDURUS certificates requirements continue with step 1.

To generate a new self-signed certificate for the IdP by running the following commands as root user:

# Use the temp directory to generate new key and certificate
cd /tmp

# Copy the current key file to the temp directory in order to preserve the file permissions
cp -p #oldKeyPath# idp.new.key

# Create configuration file
cat > idp-cert.cnf <<EOF

# OpenSSL configuration file for creating idp-cert.pem
[req]
prompt=no
default_bits=2048
encrypt_key=no
default_md=sha1
distinguished_name=dn
# PrintableStrings only
string_mask=MASK:0002
x509_extensions=ext
[dn]
CN=#hostName#
[ext]
subjectAltName=DNS:#hostName#,URI:#entityID#
subjectKeyIdentifier=hash
EOF

# Generate a new pair of certificate and key files (in the current directory)
openssl req -config idp-cert.cnf -new -x509 -days 1095 -keyout idp.new.key -out idp.new.crt 2> /dev/null

# Move new files
mv idp.new.key #oldKeyPath#
mv idp.new.crt #oldCertPath#

# Cleanup
rm idp-cert.cnf

# Output new IdP certificate
cat #oldCertPath#

With the above commands a new certificate and private key are generated and moved to the Shibboleth configuration directory.
Ensure that the key file #oldKeyPath# is readable by the user that executes the Servlet container (Tomcat).

Step 0: Create new certificate

To generate a new self-signed certificate for the IdP, run the following commands as root user:

cd /opt/shibboleth-idp/credentials

sudo java -cp "../webapp/WEB-INF/lib/*:../bin/lib/*" \
  net.shibboleth.utilities.java.support.security.SelfSignedCertificateGenerator \
  --lifetime 3 \
  --certfile idp.crt.new \
  --keyfile idp.key.new \
  --hostname #hostName# \
  --uriAltName #entityID#

sudo chmod 600 idp.key.new
sudo chown --reference idp.key idp.key.new

With the above commands a new certificate and private key are generated inside the /opt/shibboleth-idp/credentials/ directory.

Step 1: Add new certificate to metadata

This step can be done immediately after or at the same time as step 1. Now that the IdP has the new certificate configured as standby certificate, the certificate also must be propagated to the SPs in the federation. To achieve that, the new certificate has to be included in the federation metadata.
Go to the Federation Registry and add the content of the new IdP certificate #newCertPath# to the corresponding Home Organisation Description. Add the certificate as additional SSO and AA certificate. The order of the certificates doesn't matter.
Then apply the change.
For most SPs in the FEDURUS or AAI Test federations it will take at most 2 hours until they will have downloaded the new federation metadata file. However, eduGAIN SPs need longer. To be on the safe side, one should therefore not proceed with the next step before 24 hours have elapsed.
SPs that downloaded new metadata will use all available certificates to verify the assertions signed by the IdP or to verify the IdP's SSL certificate.

Step 2: Configure IdP to use new certificate

After at least 24 hours, every SP should have downloaded the latest metadata file, which includes the new certificate. Subsequently, the Identity Provider can now be configured to use the new certificate. One usually has to configure the new certificate in two places: The Apache or Tomcat configuration and the Shibboleth configuration. The metadata which the IdP generated about itself should be updated as well.

Backup the file #metadataFilePath#.

# Backup metadata file
cp #metadataFilePath# #backupMetadataFilePath#

1. Next activate the new certificate and keys:

   # Backup the old files
   sudo mv #oldKeyPath# #backupKeyPath#
   sudo mv #oldCertPath# #backupCertPath#
   
   # Activate the new files
   sudo mv #newKeyPath# #oldKeyPath#
   sudo mv #newCertPath# #oldCertPath#
   

In the idp-metadata.xml, replace the two PEM-formatted blocks in the <ds:X509Certificate> elements with the content of the new PEM certificate #oldCertPath#.
Omit the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. Do this two times, once in the IDPSSODescriptor and once in the AttributeAuthorityDescriptor element.

<!-- IDPSSODescriptor / AttributeAuthorityDescriptor -->
<!-- ... -->
<KeyDescriptor>
     <ds:KeyInfo>
         <ds:X509Data>
             <ds:X509Certificate>
MIIDFDCCAfygAwIBAgIJAOVA31cn9tCxMA0GCSqGSIb3DQEBBQUAMBkxFzAVBgNV
BAMTDnNwLmV4YW1wbGUub3JnMB4XDTA4MDMwNzE2MTAxNVoXDTExMDMwODE2MTAx
NVowGTEXMBUGA1UEAxMOc3AuZXhhbXBsZS5vcmcwggEiMA0GCSqGSIb3DQEBAQUA
A4IBDwAwggEKAoIBAQDNhGHf6eeZF14sJduvDBG1MyMxjHWN5UorfLXPDAYZhr5W
D9biVzyfq9FCbP4ndDkBSVdu5rgXKLxyzod1MkDeN+4idr9EZiAVbhJaLDir5YwB
agStiCC65QLsrAGrTKbGn7HoXOfO5o4+l4a62mMgMFMAUp9W/JQ0k4fWmbnWcXHo
UzEeN/XukiD4jgUFnf9/dB/9P93ViAnkSUoEHeHIz7Oiw1c/9pCJktiU2ns9exUw
wRGaagLXdPBxAdvUx1o1MG+Uajfg85EwhVzlO2kBClq3k9koJi01eTam4XxsBGSQ
TmvsKf8aPES0nrhSJjOtceGOuyxAQ9UXSRi+0rrXAgMBAAGjXzBdMDwGA1UdEQQ1
MDOCDnNwLmV4YW1wbGUub3JnhiFodHRwczovL3NwLmV4YW1wbGUub3JnL3NoaWJi
b2xldGgwHQYDVR0OBBYEFEJItQ8/IYfolzHeMZ3aNEzisC44MA0GCSqGSIb3DQEB
BQUAA4IBAQBPJi0wFTrqfATuhuA1h91efgYqE6WIC99Go4i6UFnsjwl3k9ZCF2xs
9T1uZ22nOFmAnAPbUS3cMiqFWGwlpC4w0KaXIeeUuh51g5+nKnqRE0XkCmm+5515
66L6PR+RMN9kx2h4HCuwvyFN02Y+Iz49oSOBW9exV1BmP0mhWF1j6lPoDkRDLZnG
eLtJhzirb37BEk0fJkIg8OM1SPZ1mdB/5qhkWj4RRp47e03zeVE2YQMNhn6sE9hj
xTdeeVyguekdSeLaF89jXvW6XBJR9NsZ+NswXIFN6nIYIRQha8+w2p1Saq0fvf8g
wf2JYThoxNmfL8cHfoPqJAikP1gwuRjt
             </ds:X509Certificate>
         </ds:X509Data>
     </ds:KeyInfo>
</KeyDescriptor>
<!-- ... -->

Then restart the servlet container (e.g. Tomcat). In the case of tomcat the command to be executed as root user is:

# Restart servlet container
/etc/init.d/tomcat* restart
		

Then restart the servlet container (e.g. Tomcat). In the case of Tomcat the command to be executed as root user is:
For ubuntu:

# Restart servlet container
sudo service tomcat7 restart

For Red Hat Enterprise Linux 7 / CentOS 7:

# Restart servlet container
sudo systemctl restart tomcat.service

2. According to the the IdP deployment guides, Apache is used as front-end web server. Therefore, the configuration for the VirtualHost serving port 8443 might have to be adapted to use the new certificate as well.
   Please ensure that the certificate configuration for that VirtualHost uses the new certificate as well. It should look similar to:
   

   <VirtualHost #hostName#:8443>
       [...]
       SSLCertificateFile      #oldCertPath#
       # In case of a certificate issued by a well-known CA
       # make sure to configure the certificate chain
       # This is not necessary for self-signed certificates
       #SSLCertificateChainFile /etc/ssl/certs/qvsslica.crt.pem
       SSLCertificateKeyFile   #oldKeyPath#
       [...]
   <VirtualHost>
   

   After applying this change to the configuration, restart Apache:

   /etc/init.d/apache2 restart

Step 3: Remove the old certificate from metadata

This step can be performed immediately after step 2.
Go to the Federation Registry and remove the old certificate from the corresponding Home Organization Description of the IdP. It will take again up to 24 hours until the change has propagated to all Service Providers.

References

Additional information on certificates in Metadata