As of today, the Federation Manager does not support "Signing Only" certificates in SP metadata. Instead of the procedure below, use the key rollover process for a Shibboleth 2.x SP documented in the Shib wiki, even if you don't use Shibboleth. See also Case 3c on the Key Rollover wiki page.
Migrating a Certificate in SP Metadata
This article is for SP site administrators wishing to replace an old certificate with a new certificate in metadata. Please read the overview of Certificate Migration before continuing.
In Federation metadata, a certificate in SP metadata is contained in an <md:KeyDescriptor> element. Such a certificate may be used for signing, SSL/TLS, and/or encryption. Invariably there is a single key descriptor contained in the <md:SPSSODescriptor> element.
This procedure requires two decryption keys to be configured in the SP software at one time. Some software implementations do not permit multiple decryption keys to be configured (which is an implementation bug). Check your software documentation for further instructions.
Regardless of the SP implementation used, the general migration process is as follows.
Preconditions:
- There is an
<md:KeyDescriptor>element (with nouseXML attribute) in SP metadata. - The software is configured to use a single private key as a signing key, as an SSL/TLS key, and/or as a decryption key.
Procedure:
- Configure the SP software as follows:
- Continue to use the old key as a signing key, an SSL/TLS key, and/or a decryption key
- In addition, use the new key as a decryption key only
- Update the SP metadata as follows:
- Add a new
<md:KeyDescriptor>element (with nouseXML attribute) - Change the old
<md:KeyDescriptor>element to an<md:KeyDescriptor use="signing">element
- Add a new
- Wait for the newly updated metadata to propagate throughout the Federation.
- Configure the SP software as follows:
- Use the new key (instead of the old key) as the signing key and/or SSL/TLS key
- Use the new decryption key only (i.e., discontinue use of the old decryption key)
- Remove the old
<md:KeyDescriptor use="signing">element from SP metadata.
Procedural details:
Step 1 requires the new key to be configured as a decryption key only. In particular, the new key must not be configured as a signing key or SSL/TLS key at this time (but see step 4). At the end of step 1, your software will have two decryption keys configured. Which one gets used depends on what metadata the IdP has available when the assertion is encrypted.
At step 2, login to the Federation Manager and bind a new certificate to the <md:SPSSODescriptor> element by adding a new <md:KeyDescriptor> element with no use XML attribute. That is, bind the new key to metadata as a "Signing and Encryption" key. Simultaneously change the old <md:KeyDescriptor> element to an <md:KeyDescriptor use="signing"> element by selecting "Signing Only" from the drop-down menu next to the certificate in the interface. After doing so, your SP's metadata will contain two (2) key descriptors, one of which is new.
Key Order in the Configuration
The new decryption key should be configured first in the SP implementation. This is because the new key is the only encryption key listed in SP metadata. By listing the new key first in the configuration, fewer failed decryption attempts will occur.
Completely remove the old key from the configuration at step 4. At the end of this step, only the new key will be configured in the software, as a signing key, an SSL/TLS key, and/or a decryption key. The old key will no longer be configured.
Finally, at step 5, log into the Federation Manager and remove the old key descriptor—the one with the use="signing" XML attribute—from the metadata. This is done by removing the old certificate from the list of certificates uploaded to the web application.
This completes the migration process.
Implementation-Specific Details for SP Deployers
The key rollover process for a Shibboleth 2.x SP is fully documented in the Shib wiki. If you have questions about Shibboleth, please consult the Shib mailing lists.