Shibboleth Service Provider Certificate Rollover

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

Note

Background Information

A Shibboleth Service Provider (SP) needs a certificate to sign authentication requests and decrypt SAML assertions. The certificate of an SP is embedded in SAML metadata so that the Identity Providers (IdPs) know a SP's certificate. Therefore, a new certificate has to be added to:

After approval of a change in the Resource Registry, Switch edu-ID Federation Metadata requires at least one hour to propagate to all relying parties. Therefore, a certificate of a new keypair cannot be replaced in one single step.
While most relying parties will have downloaded metadata within two hours, this is not guaranteed for all entities. However, certificate rollover can be performed without any service interruption. For this to work, the order and the timing of the following steps are crucial.

Setup

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

Hostname of the SP:
Operating system of the host that runs the SP:
Path of old certificate file:
Path of old key file:

Service Provider Certificate Rollover Instructions

The following instructions explain how to perform the certificate rollover without any service disruption. An overview of the general procedure can be found in the following graphic.
Recommended timeline for Service Provider certificate rollover

Step 0: Create new certificate

Switch recommends to use self-signed certificates for the SAML communication. If you already have a new certificate (e.g. provided by a SAML SP tenant in a cloud) that meets the SWITCHaai certificates requirements continue with step 1.

If the size of your current keypair is already 3072 bits, you can reuse the keypair and only generate a new self-signed certificate.
Display the keysize of your current certificate with this openssl command:

a) Reuse existing 3072 bit keypair

To reuse a 3072 bit keypair and only generate a new self-signed certificate for the SP, run the following commands as root user:

If, and ony if, you could reuse the existing 3072 bit keypair, you get the big advantage of not having to wait for propagation via metadata.
Since the SP's keypair hasn't changed, the SP can decrypt assertions generated by IdPs that encrypted it with either the old or the new certificate they find in their local copy of the SP's metadata.
Therefore,
b) Generate a new 3072 keypair
To generate a new self-signed certificate, run the following commands:
With the above commands a new certificate and private key are generated and moved to the Shibboleth IdP credentials directory.
Ensure that the key file #newKeyPath# is readable by the user that executes the Shibboleth daemon process shibd.

Step 1: Configure new certificate as 'additional new certificate'

Before adding the new certificate to the federation metadata, the certificate must first be added to the SP configuration (shibboleth2.xml). This way the SP knows about the new certificate before it receives assertions encrypted with the new certificate. On the other side it must be prevented that the SP already uses the new certificate actively for attribute queries. Therefore, the certificate should be configured as 'additional new certificate'.
In the Shibboleth configuration file shibboleth2.xml replace your current CredentialResolver element with the following one:

        <!-- 
        Certificate/Private key pairs are read in sequence.
        Unless specificially defined only the first 
        CredentialResolver is used for attribute requests.
        More information:
        https://wiki.shibboleth.net/confluence/display/SP3/CredentialResolver
        -->
        <CredentialResolver type="Chaining">
             <!-- Active certificate -->
             <CredentialResolver type="File"
                                 key="#oldKeyPath#" 
                                 certificate="#oldCertPath#"/>
             <!-- Additional new certificate -->
             <CredentialResolver type="File"
                                 key="#newKeyPath#" 
                                 certificate="#newCertPath#"/>
        </CredentialResolver>
    
It is important that the new certificate is added after the old certificate because they are used in the order of their declaration!

After adding the new certificate as 'additional new certificate', it is recommended to check the configuration (as administrator or root) with the command:
It should say that the overall configuration is loadable without error or critical messages.
Next, restart the Shibboleth daemon with: As result of this configuration change, the SP can decrypt assertions that were encrypted by the old or the new certificate. The SP will still use the old certificate for attribute queries.

Step 2: Add new certificate to metadata

This step can be done immediately after or at the same time as step 1. Now that the SP has the new certificate configured as 'additional new certificate', the certificate also must be propagated to the IdPs in the federation. Therefore, the new certificate has to be included in the federation metadata.
Show the new certificate with: Then go to the Resource Registry and add the new certificate to the corresponding Resource Description of the SP. The order of the certificates doesn't matter.
Then submit the change for approval and wait until a Resource Registration Authority (RRA) administrator has approved the change.

Resource Registry screenshot
After the changes for the Resource Description were approved, it will take at most 2 hours until every IdP in the Switch edu-ID Federation will have downloaded the new federation metadata file.
IdPs that downloaded the metadata will choose randomly which certificate they use to encrypt assertions for this SP. Therefore, the SP by this time already must have the new certificate configured in order to be able to decrypt assertions with both, the old and the new certificate.
To be on the safe side, one should not proceed with the next step before this time has elapsed.

Step 3: Configure SP to use new certificate

After at least 2 hours, every IdP in the Switch edu-ID Federation should have downloaded the latest metadata file, which includes the new certificate. Subsequently, the Service Provider can now be configured to use of the new certificate as active certificate and keep the old one as 'additional old certificate'. To make the new certificate the active one it must be configured before the old certificate.
To achieve this, change the order of the CredentialResolver elements in the Shibboleth configuration file shibboleth2.xml as shown below:

        <!-- 
        Certificate/Private key pairs are read in sequence.
        Unless specificially defined only the first 
        CredentialResolver is used for attribute requests.
        More information:
        https://wiki.shibboleth.net/confluence/display/SP3/CredentialResolver
        -->
        <CredentialResolver type="Chaining">
             <!-- Active certificate -->
             <CredentialResolver type="File"
                                 key="#newKeyPath#" 
                                 certificate="#newCertPath#"/>
             <!-- Additional old certificate -->
             <CredentialResolver type="File"
                                 key="#oldKeyPath#" 
                                 certificate="#oldCertPath#"/>
             
        </CredentialResolver>
    
Again, check the configuration and restart the Shibboleth daemon after applying this change: And then:

Step 4: Remove old certificate from metadata

This step can be performed immediately after step 3.
Go to the Resource Registry and remove the old certificate from the corresponding Resource Description of the SP. After this change was approved by an RRA administrator, it will take again at most 2 hours until the change has propagated to all IdPs in the Switch edu-ID Federation.

Step 5: Remove old certificate from Service Provider configuration

For security reasons, it is recommended to remove the old certificate from the configuration. This step is recommended even if the certificate expired.
Before continuing, it is important you have waited for two hours after the change of Step 4 was approved. Only then one can be sure that all IdPs in the Switch edu-ID Federation have downloaded the new metadata.
Instead of removing the old certificate, is is recommended to comment it out in the Shibboleth configuration file shibboleth2.xml like shown below:

        <!-- 
        Certificate/Private key pairs are read in sequence.
        Unless specificially defined only the first 
        CredentialResolver is used for attribute requests.
        More information:
        https://wiki.shibboleth.net/confluence/display/SP3/CredentialResolver
        -->
        <CredentialResolver type="Chaining">
             <!-- Active certificate -->
             <CredentialResolver type="File"
                                 key="#newKeyPath#" 
                                 certificate="#newCertPath#"/>
             <!-- Additional old certificate -->
        <!--
             <CredentialResolver type="File"
                                 key="#oldKeyPath#" 
                                 certificate="#oldCertPath#"/>
        -->
        </CredentialResolver>
    
Again, check the configuration and restart the Shibboleth daemon after applying this change: And then:

References

Additional information on certificates in Metadata