Shibboleth at NC State » Technical Documentation » Notes on SP Certificates

Notes on SP Certificates

In Shibboleth, IdPs and SPs exchange information using SAML messages passed through the user's browser connections. The SP uses a public/private key pair to sign its messages sent to the IdP, and to decode messages sent to it from the IdP. The IdP uses its own public/private key pair to sign its messages sent to the SP, so the SP can verify the message is genuine.

In each case, SPs and IdPs need to be able to verify the certificate offered by the other. This is managed through the exchange of metadata through the federation. The certificates of all the IdPs and SPs in the federation are collected together and signed by the federation's key.

The standard SP install creates a suitable key and self-signed certificate (in the same directory as shibboleth2.xml) called sp-key.pem and sp-cert.pem and configures shibboleth2.xml to use them.

Note that everything in the certificate apart from the public key itself (so expiry date, hostname, etc.) is ignored by the Shibboleth software - the certificate is just a convenient standard container for transporting the key in the metadata. Shibboleth IdP and SP software will quietly ignore expired certificates when found in metadata that is correctly and currently signed by the federation.

However, other SAML providers have proven to be less accepting of expired certificates. We have run into cases where other SAML IdPs will refuse to send attributes to our SPs if their certificate is expired. When this happens, we have to update the certificate on the SP and in the registered metadata.

Updating an expired certificate

The goal of this section is to keep the existing public/private key pair for the SP in place, and to issue a new certificate using this existing public key. We do not want to re-run the keygen.sh script, because that would create an entirely new key pair. Instead, we will modify some of the code found in the script to make sure we just generate a new cert from the existing keys.

First, we need to make a config file for openssl. This will tell the openssl program how to label the certificate when it creates it. This code is exactly the same as the code generated by the keygen.sh script. Unfortunately, that script deletes this file after it uses it, so we have to make a copy for ourselves.

cd /etc/shibboleth
cat > sp-cert.cnf <<END
# OpenSSL configuration file for creating sp-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=YOUR.HOST.ncsu.edu
[ext]
subjectAltName=DNS:YOUR.HOST.ncsu.edu
subjectKeyIdentifier=hash
END
vi sp-cert.cnf
    # now edit the two "YOUR.HOST" entries above

Next, we make a backup of the current sp-cert.pem file, and then use openssl to generate the new certificate. This code assumes you want your self-signed certificate to last for 3652 days = 10 years.

cp sp-cert.pem sp-cert.old.pem
openssl req -new -x509 -days 3652 -key sp-key.pem \
        -config sp-cert.cnf > sp-cert.new.pem

Next, install the new certificate on your server and restart the services.

cp sp-cert.new.pem sp-cert.pem
service shibd restart
service httpd restart

Finally, send an email to shibboleth-help@ncsu.edu requesting that we re-download your SP metadata to register the updated certificate. Something like this will work:

To: shibboleth-help@ncsu.edu
Subject: Update metadata for https://your.host.ncsu.edu/sp/shibboleth

We have recently updated the certificate on our SP. Please download
the updated metadata from:
    https://your.host.ncsu.edu/Shibboleth.sso/Metadata
and update our entry in the NCSU Federation.

Problems with changing certificates

As mentioned above, the Shibboleth SP and IdP softwares will ignore the expiration dates on your certificates. There should be no loss of service between these providers during a certificate update. Other SAML providers may be affected during the time between the change of the certificate on the SP, and the update of the certificate in the published metadata.

Consider these situations:

  1. The SP is using an expired certificate, and the metadata also contains that expired certificate.

    • Shibboleth SP and IdP - will function normally.
    • Non-Shibboleth SAML IdP - may refuse to send messages to the SP while it has an expired certificate.

  2. The SP has updated its certificate to one that is not expired. The metadata still contains the old, expired certificate.

    • Shibboleth SP and IdP - will function normally.
    • Non-Shibboleth SAML IdP - may refuse to accept messages from the SP because the SAML message contains a copy of the SP certificate and that does not match the certificate in the metadata.

  3. The metadata has been updated with the new certificate, and the remote IdP has downloaded the latest metadata.

    • Shibboleth SP and IdP - will function normally.
    • Non-Shibboleth SAML IdP - should accept messages and function normally.

Issuing a new key and certificate

This process describes how to completely replace the key and certificate pair used by an SP without causing a loss of service. These instructions are based on a guide provided by SWITCH.

In order to avoid the problems outlined in the previous section, we need to temporarily use two key/cert pairs on the SP during the switch. This process will take at least a day or two to complete.

Step 1: Make a new key/cert pair for the SP. Do this in a separate directory from the shibboleth configs, so we don't accidentally overwrite the current key/cert pair.

cd /tmp
/etc/shibboleth/keygen.sh -y 10 \
  -h your.host.ncsu.edu \
  -e https://your.host.ncsu.edu/sp/shibboleth
        # h is the hostname 
        # e is the entityID
ls /tmp/sp-*
    /tmp/sp-cert.pem  /tmp/sp-key.pem

Step 2: Configure your SP to expect either key/cert pair. Copy the new key and cert into your shibboleth directory under a new name. Make sure the file permissions are correct.

cd /tmp
cp sp-cert.pem /etc/shibboleth/sp-cert-2017.pem
cp sp-key.pem /etc/shibboleth/sp-key-2017.pem
cd /etc/shibboleth
chown shibd.shibd sp-cert-2017.pem sp-key-2017.pem
ls -l sp*
    -rw-r--r-- 1 shibd shibd 1159 Jul 16  2014 sp-cert.pem
    -rw-r--r-- 1 shibd shibd 1505 May 31 09:48 sp-cert-2017.pem
    -rw------- 1 shibd shibd 1675 Oct  9  2009 sp-key.pem
    -rw------- 1 shibd shibd 2484 May 31 09:48 sp-key-2017.pem

Next add the new key/cert to the SP configuration as a secondary credential in parallel with the current pair.

vi /etc/shibboleth/shibboleth2.xml
    # find the CredentialResolver tag with the old certs
    # duplicate it, and change the names for the second cert.
    # then wrap both entries in a Chaining CredentialResolver tag

    # like this:
    <CredentialResolver type="Chaining">
        <!-- current cert expired 2014 -->
        <CredentialResolver type="File" key="sp-key.pem"
            certificate="sp-cert.pem"/>
        <!-- new cert expires 2027 -->
        <CredentialResolver type="File" key="sp-key-2017.pem"
            certificate="sp-cert-2017.pem"/>
    </CredentialResolver>

Now restart shibd to reload the configuration.

service shibd restart
less /var/log/shibboleth/shibd.log
    # should see load lines for both key/cert pairs

Step 3: Notify the federation that your SP has two certificates. Send an email to shibboleth-help@ncsu.edu requesting that we re-download your SP metadata to register the extra certificate. Something like this will work:

To: shibboleth-help@ncsu.edu
Subject: Update metadata for https://your.host.ncsu.edu/sp/shibboleth

We are replacing the key/certificate on our SP. Please download
the updated metadata from:
    https://your.host.ncsu.edu/Shibboleth.sso/Metadata
and update our entry in the NCSU Federation.

This will start a ServiceNow ticket that we will use for the remaining conversations. We will let you know when the Federation has been updated. Then you have to wait a few hours for the IdP login servers to receive the updated metadata. After that, both sides (SP and IdP) are prepared to use either of the certificate pairs.

Step 4: Update your SP to make the new key/certificate pair the primary credential. 

cd /etc/shibboleth
vi shibboleth2.xml
    # switch the order of the two certs, putting the 2017 cert first
    <CredentialResolver type="Chaining">
        <!-- current cert expires 2027 -->
        <CredentialResolver type="File" key="sp-key-2017.pem"
            certificate="sp-cert-2017.pem"/>
        <!-- old cert expired 2014 -->
        <CredentialResolver type="File" key="sp-key.pem"
            certificate="sp-cert.pem"/>
    </CredentialResolver>

service shibd restart
less /var/log/shibboleth/shibd.log
    # should see load lines for both key/cert pairs

Step 5: Update the Federation to remove the old certificate. You can reply to the ServiceNow ticket started in step 3. We will remove the old certificate entry from your metadata and republish the Federation. Then we wait another few hours for the updates to propagate.

Step 6: Remove the old key/certificate pair from your SP. You can comment out the old entry, or remove it entirely, as you prefer. You may also want to delete the old key/certificate files.

cd /etc/shibboleth
vi shibboleth2.xml
    <CredentialResolver type="Chaining">
        <!-- current cert expires 2027 -->
        <CredentialResolver type="File" key="sp-key-2017.pem"
            certificate="sp-cert-2017.pem"/>
        <!-- old cert expired 2014 -->
        <!--
          <CredentialResolver type="File" key="sp-key.pem"
              certificate="sp-cert.pem"/>
        -->
    </CredentialResolver>

service shibd restart
less /var/log/shibboleth/shibd.log
    # should see load lines for just the current key/cert pair

# once you are sure you won't need these again    
rm sp-key.pem sp-cert.pem