This page describes the process of certificate rollover for Shibboleth Service Providers. The procedure described below allows replacing certificates without any service disruptions.
Note
Please note that the instructions are only applicable to a Shibboleth 2.x or 3.x Service Provider (SP) configured according to the Switch Shibboleth Service Provider deployment guides!
- You do not use a Shibboleth SP?
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 with multiple EZproxyCertNumber values.
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:
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
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 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:
openssl x509 -noout -text -in #oldCertPath#
openssl x509 -noout -text -in #oldCertPath#
openssl.exe x509 -noout -text -in #oldCertPath#
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:
openssl.exe req \
-new \
-x509 -days 3650 \
-key #oldKeyPath# \
-subj "/CN=#hostName#" \
-out #newCertPath#
REM Make sure that file permissions for #newCertPath#
REM are the same as for #oldCertPath#
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,
in step 1) below you do not need to add the new certificate, you directly replace the path for the active certificate with #newCertPath# and leave the private key path untouched
If you have an Additional old certificate, disable it by commenting it out (see step 5) below),
in step 2) below you do not need to add the new certificate, you directly replace the existing certificate in the Certificates field,
in step 3) below you do not have to wait, you can check the configuration and restart the SP immediately,
safely ignore step 4) below since you directly replaced the self-signed certificate in step 2).
safely ignore step 5) below since you already commented it out above.
b) Generate a new 3072 keypair
To generate a new self-signed certificate, run the following commands:
# Use the temp directory to generate new key and certificate
cd /tmp
# Copy the current key file to the temp directory preserving the file permissions
cp -p #oldKeyPath# sp-key-temp.pem
# Generate a new pair of certificate and key files (in the current directory)
/etc/shibboleth/keygen.sh -y 10 -h #hostName#
# Copy the content to the temporary key file with the correct file permissions
cat sp-key.pem > sp-key-temp.pem
# Move the temporary key file to the correct path
mv sp-key-temp.pem #newKeyPath#
# Cleanup
rm sp-key.pem
# Copy the certificate to the correct location
mv sp-cert.pem #newCertPath#
# Use the shibboleth directory to generate new key and certificate
cd /etc/shibboleth
# Move existing certificate files to temporary location if they exist
[ -e sp-cert.pem ] && mv sp-cert.pem /tmp/
[ -e sp-key.pem ] && mv sp-key.pem /tmp/
# Generate a new pair of certificate and key files
shib-keygen -y 10 -h #hostName#
# Copy the certificate to the correct location
mv sp-cert.pem #newCertPath#
# Move the key file to the correct path
mv sp-key.pem #newKeyPath#
# Move back the old certificate to the correct place
[ -e /tmp/sp-cert.pem ] && mv /tmp/sp-cert.pem /etc/shibboleth/
[ -e /tmp/sp-key.pem ] && mv /tmp/sp-key.pem /etc/shibboleth/
cd C:\Temp
C:\opt\shibboleth-sp\etc\shibboleth\keygen.bat -h #hostName# -y 10 -o C:\Temp
REM In older versions of the Shibboleth SP the -o option is not supported yet
REM For those versions, just omit -o option and change to C:\opt\shibboleth-sp\etc\shibboleth\ for the next steps
move sp-cert.pem #newCertPath#
move sp-key.pem #newKeyPath#
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:
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.
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:
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: