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.


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.

Warning regarding SPs based on implementations other than Shibboleth or SimpleSAMLphp!

Be aware that many SP implementations other than Shibboleth or SimpleSAMLphp are not properly capable of dealing with certificate rollover at the IdP!

  1. The SP either ignores additional certificates in metadata and only uses the first or last certificate.
  2. The SP is not able to regularly load metadata and will therefore never learn about a new IdP certificate.

In both cases, such SPs will fail to verify the IdP's signature on the SAML assertion and interoperation with that IdP will fail.

In case a) it will work again once the rollover is complete and the expiring certificate is removed from metadata in step 3).

In case b) it will only work again once the SP's configuration gets manually updated with the new IdP certificate after step 2).

  • Interfederated IdPs should wait more than 24h before applying step 2).
  • However, if you have important SPs using an implementation other than Shibboleth or SimpleSAMLphp, do not wait longer than 2h before applying step 2) and best apply the certificate rollover outside of office hours when only few users are expected to access such SPs!


Before starting the certificate roll-over, please complete the following form and click on "Update". This generates custom-tailored configuration snippets in the sections below.


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.

Recommended timeline for Identity Provider certificate rollover
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#

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

# OpenSSL configuration file for creating idp-cert.pem
# PrintableStrings only

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

# Move new files
mv #oldKeyPath#
mv #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/*" \ \
  --lifetime 3 \
  --certfile \
  --keyfile \
  --hostname #hostName# \
  --uriAltName #entityID#

sudo chmod 600
sudo chown --reference idp.key

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.
  1. Backup the file #metadataFilePath#.
    # Backup metadata file
    cp #metadataFilePath# #backupMetadataFilePath#
  2. 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#
  3. 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 -->
    <!-- ... -->
    <!-- ... -->
  4. 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
  5. 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
  6. 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#
    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.


Additional information on certificates in Metadata

Последние изменения страницы [an error occurred while processing the directive]