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:

Changes in SWITCHaai 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 will have downloaded metadata within two hours, this is not guaranteed for all entities. Certificate rollover can however 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:
entityID 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 Shibboleth. If you already have a certificate that meets the SWITCHaai certificates requirements continue with step 1.
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/SHIB2/NativeSPCredentialResolver
        -->
        <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 the 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
In order to approve the new certificate, the RRA administrator might ask you for the fingerprint of the certificate. The fingerprint can be shown with the command: After the changes for the Resource Description were approved, it will take at most 2 hours until every IdP in the SWITCHaai 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 SWITCHaai 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/SHIB2/NativeSPCredentialResolver
        -->
        <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 SWITCHaai 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 SWITCHaai 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/SHIB2/NativeSPCredentialResolver
        -->
        <CredentialResolver type="Chaining">
             <!-- Active certificate -->
             <CredentialResolver type="File"
                                 key="#newKeyPath#" 
                                 certificate="#newCertPath#"/>
             <!-- Additional old certificate -->
        <!--
             <CredentialResolver type="File"
                                 key="#oldKeyPath#" 
                                 certificate="#oldCertPath#"/>
        -->
        </CredentialResolver>
    

References

Additional information on certificates in Metadata