This page describes the process of certificate rollover for Shibboleth Identity Providers. The procedure described below allows replacing certificates without any service disruptions.
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 24 hours or more 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!
The SP either ignores additional certificates in metadata and only uses the first or last certificate.
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).
Note:
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!
An overview of the general procedure can be found in the following diagram. It explains how to perform the certificate rollover without any service disruption for Shibboleth and SimpleSAMLphp SPs.
Step 0: Create new certificate
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:
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 IdP's keypair hasn't changed, the IdP still uses the same private key to sign assertions, all SPs can verify the signature based on the old as well as the new certificate they find in their local copy of the IdP's metadata.
Therefore,
in step 1) below you do not need to add the new certificate, you directly replace the exisitng one in the fields for Identity Provider (SSO) Signing Certificate and Attribute Authority (AA) Certificate,
in step 2) below you backup and activate only the self-signed certificate and leave the private key untouched,
safely ignore step 3) below since you directly replaced the self-signed certificate in step 1).
b) Generate a new 3072 keypair
To generate a new keypair and self-signed certificate for the IdP, run the following commands as root user:
With the above commands a new certificate and private key are generated inside the /opt/shibboleth-idp/credentials/ directory.
In case the JAVA_HOME environment variable is not set, you can set it for the keygen.sh command like this JAVA_HOME=/usr/lib/jvm/jre /opt/shibboleth-idp/bin/keygen.sh ...
Step 1: Add new certificate to metadata
The SPs in the federation must now learn about the new IdP certificate. To achieve that, the new certificate has to be included into the federation metadata.
Go to the Resource 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 Switch edu-ID Federation or the AAI Test Federation it will take at most 2 hours until they will have downloaded the new federation metadata file. However, eduGAIN SPs need much longer. To be on the safe side, one should therefore not proceed with the next step before 24 hours have elapsed. Note: Carefully read the warning regarding non Shibboleth or SimpleSAMLphp SPs above!
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.
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#
To trigger the IdP to start using the changed credentials, reload the RelyingParty service that also reloads the conf/credentials.xml file and its referenced credential files:
This step can be performed immediately after step 2.
Go to the Resource 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. Make use of the browser's 'tool-tip' feature to identify the expiring certificate.
