Shibboleth Identity Provider Certificate Rollover

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

Scope

Please note that the instructions are only applicable for a Shibboleth Identity Provider (IdP) configured according to the SWITCH Shibboleth Identity Provider deployment guides!

Background Information

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 up to 24 hours 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!

  1. The SP either ignores additional certificates in metadata and only uses the first or last certificate.
  2. 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!

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.

    

Identity Provider Certificate Rollover Instructions

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.

Recommended timeline for Identity Provider certificate rollover
Step 0: Create new certificate
First, ensure that openssl is installed on the host as this is required for the following commands. If not availble yet, please install openssl (on Debian openssl can be installed as root with the command: apt-get install openssl).
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 for the IdP by running the following commands as root user:

# Use the temp directory to generate new key and certificate
cd /tmp

# Copy the current key file to the temp directory in order to preserve the file permissions
cp -p #oldKeyPath# idp.new.key

# Create configuration file
cat > idp-cert.cnf <<EOF

# OpenSSL configuration file for creating idp-cert.pem
[req]
prompt=no
default_bits=2048
encrypt_key=no
default_md=sha1
distinguished_name=dn
# PrintableStrings only
string_mask=MASK:0002
x509_extensions=ext
[dn]
CN=#hostName#
[ext]
subjectAltName=DNS:#hostName#,URI:#entityID#
subjectKeyIdentifier=hash
EOF

# Generate a new pair of certificate and key files (in the current directory)
openssl req -config idp-cert.cnf -new -x509 -days 1095 -keyout idp.new.key -out idp.new.crt 2> /dev/null

# Move new files
mv idp.new.key #oldKeyPath#
mv idp.new.crt #oldCertPath#

# Cleanup
rm idp-cert.cnf

# Output new IdP certificate
cat #oldCertPath#
With the above commands a new certificate and private key are generated and moved to the Shibboleth configuration directory.
Ensure that the key file #oldKeyPath# is readable by the user that executes the Servlet container (Tomcat).
Step 0: Create new certificate
To generate a new self-signed certificate for the IdP, run the following commands as root user:

cd /opt/shibboleth-idp/credentials

sudo java -cp "../webapp/WEB-INF/lib/*:../bin/lib/*" \
  net.shibboleth.utilities.java.support.security.SelfSignedCertificateGenerator \
  --lifetime 3 \
  --certfile idp.crt.new \
  --keyfile idp.key.new \
  --hostname #hostName# \
  --uriAltName #entityID#

sudo chmod 600 idp.key.new
sudo chown --reference idp.key idp.key.new

With the above commands a new certificate and private key are generated inside the /opt/shibboleth-idp/credentials/ directory.
Step 1: Add new certificate to metadata
This step can be applyed immediately after or at the same time as step 1. Now that the IdP has the new certificate configured as standby certificate, the certificate must also be propagated to the SPs in the federation. 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.

Resource Registry screenshot
For most SPs in the SWITCHaai or AAI Test federations it will take at most 2 hours until they will have downloaded the new federation metadata file. However, eduGAIN SPs need 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.
  1. Backup the file #metadataFilePath#.
    # Backup metadata file
    cp #metadataFilePath# #backupMetadataFilePath#
    
  2. 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#
    
  3. In the idp-metadata.xml, replace the two PEM-formatted blocks in the <ds:X509Certificate> elements with the content of the new PEM certificate #oldCertPath#.
    Omit the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. Apply this twice, once in the IDPSSODescriptor and once in the AttributeAuthorityDescriptor element.
    <!-- IDPSSODescriptor / AttributeAuthorityDescriptor -->
    <!-- ... -->
    <KeyDescriptor>
         <ds:KeyInfo>
             <ds:X509Data>
                 <ds:X509Certificate>
    MIIDFDCCAfygAwIBAgIJAOVA31cn9tCxMA0GCSqGSIb3DQEBBQUAMBkxFzAVBgNV
    BAMTDnNwLmV4YW1wbGUub3JnMB4XDTA4MDMwNzE2MTAxNVoXDTExMDMwODE2MTAx
    NVowGTEXMBUGA1UEAxMOc3AuZXhhbXBsZS5vcmcwggEiMA0GCSqGSIb3DQEBAQUA
    A4IBDwAwggEKAoIBAQDNhGHf6eeZF14sJduvDBG1MyMxjHWN5UorfLXPDAYZhr5W
    D9biVzyfq9FCbP4ndDkBSVdu5rgXKLxyzod1MkDeN+4idr9EZiAVbhJaLDir5YwB
    agStiCC65QLsrAGrTKbGn7HoXOfO5o4+l4a62mMgMFMAUp9W/JQ0k4fWmbnWcXHo
    UzEeN/XukiD4jgUFnf9/dB/9P93ViAnkSUoEHeHIz7Oiw1c/9pCJktiU2ns9exUw
    wRGaagLXdPBxAdvUx1o1MG+Uajfg85EwhVzlO2kBClq3k9koJi01eTam4XxsBGSQ
    TmvsKf8aPES0nrhSJjOtceGOuyxAQ9UXSRi+0rrXAgMBAAGjXzBdMDwGA1UdEQQ1
    MDOCDnNwLmV4YW1wbGUub3JnhiFodHRwczovL3NwLmV4YW1wbGUub3JnL3NoaWJi
    b2xldGgwHQYDVR0OBBYEFEJItQ8/IYfolzHeMZ3aNEzisC44MA0GCSqGSIb3DQEB
    BQUAA4IBAQBPJi0wFTrqfATuhuA1h91efgYqE6WIC99Go4i6UFnsjwl3k9ZCF2xs
    9T1uZ22nOFmAnAPbUS3cMiqFWGwlpC4w0KaXIeeUuh51g5+nKnqRE0XkCmm+5515
    66L6PR+RMN9kx2h4HCuwvyFN02Y+Iz49oSOBW9exV1BmP0mhWF1j6lPoDkRDLZnG
    eLtJhzirb37BEk0fJkIg8OM1SPZ1mdB/5qhkWj4RRp47e03zeVE2YQMNhn6sE9hj
    xTdeeVyguekdSeLaF89jXvW6XBJR9NsZ+NswXIFN6nIYIRQha8+w2p1Saq0fvf8g
    wf2JYThoxNmfL8cHfoPqJAikP1gwuRjt
                 </ds:X509Certificate>
             </ds:X509Data>
         </ds:KeyInfo>
    </KeyDescriptor>
    <!-- ... -->
    
  4. Then restart the servlet container (e.g. Tomcat). In the case of tomcat the command to be executed as root user is:
    # Restart servlet container
    /etc/init.d/tomcat* restart
  5. Then restart the servlet container (e.g. Tomcat). In the case of Tomcat the command to be executed as root user is:
    For ubuntu:
    # Restart servlet container
    sudo service tomcat7 restart
    
    For Red Hat Enterprise Linux 7 / CentOS 7:
    # Restart servlet container
    sudo systemctl restart tomcat.service
    
  6. According to the the IdP deployment guides, Apache is used as front-end web server. Therefore, the configuration for the VirtualHost serving port 8443 might have to be adapted to use the new certificate as well.
    Please ensure that the certificate configuration for that VirtualHost uses the new certificate as well. It should look similar to:
    <VirtualHost #hostName#:8443>
        [...]
        SSLCertificateFile      #oldCertPath#
        # In case of a certificate issued by a well-known CA
        # make sure to configure the certificate chain
        # This is not necessary for self-signed certificates
        #SSLCertificateChainFile /etc/ssl/certs/qvsslica.crt.pem
        SSLCertificateKeyFile   #oldKeyPath#
        [...]
    <VirtualHost>
    
    After applying this change to the configuration, restart Apache:
    /etc/init.d/apache2 restart
Step 3: Remove the old certificate from metadata
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.

References

Additional information on certificates in Metadata