You use an EZproxy SP? Check out the EZproxy config.txt documentation and adapt the steps below accordingly. Since version 6.2.2, EZproxy supports proper certficate rollover.

To avoid service interruptions, make sure to carry out every of the numbered steps completely.

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

Some of the configuration snippets contain values that are custom-tailored for the Service Provider. The guide will use "#hostName#" as hostname, "#entityID#" as entityID, "#oldCertPath#" as path for the old certificate, "#oldKeyPath#" as path for the old key file and "#os#" as operating system.If you want to choose different values, fill out the form again.

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.

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:

It should say that the overall configuration is loadable without error or critical messages.
Next, restart the Shibboleth daemon with:

service shibd restart

service shibd restart

net stop shibd_Default
net start shibd_Default

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:

cat #newCertPath#

cat #newCertPath#

type #newCertPath#

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.

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:

openssl x509 -fingerprint -sha1 -noout -in #newCertPath#

openssl x509 -fingerprint -sha1 -noout -in #newCertPath#

openssl.exe x509 -fingerprint -sha1 -noout -in #newCertPath#

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:

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: