Child pages
  • SP Cert Migration

The Incommon Federation wiki has moved.

Please visit the new InCommon Federation Library wiki for updated content. Remember to update your bookmarks.

Click in the link above if you are not automatically redirected in 15 seconds.

Skip to end of metadata
Go to start of metadata

Migrating a Certificate in SP Metadata

This article is for site administrators and delegated administrators wishing to migrate an old certificate out of SP metadata. Please read the more general topic on Certificate Migration before continuing.

Handle the New Private Key Carefully!

Before generating a new key pair, take a moment to consider how best to handle the all-important private key.

In Federation metadata, a certificate in SP metadata is contained in an <md:KeyDescriptor> element (with no use XML attribute). Such a certificate may be used for signing, TLS, and/or encryption. Thus there is a single key descriptor contained in the <md:SPSSODescriptor> element (except during migration).

Implementation Requirements

This procedure ultimately 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.


  • There is a single <md:KeyDescriptor> element (with no use XML attribute) in SP metadata.
  • The software is configured to use a single private key as a signing key, as an TLS key, and/or as a decryption key.


  1. Configure the SP software as follows:
    1. Continue to use the old key as a signing key, an TLS key, and/or a decryption key
    2. In addition, use the new key as a decryption key only
  2. Update the SP metadata as follows:
    1. Add a new <md:KeyDescriptor> element (with no use XML attribute)
    2. Change the old <md:KeyDescriptor> element to an <md:KeyDescriptor use="signing"> element
  3. Wait for the newly updated metadata to propagate throughout the Federation. Two weeks is safe, although longer times may be needed, depending on the operational practices of your partners.
  4. Configure the SP software as follows:
    1. Use the new key as a signing key, an TLS key, and/or a decryption key
    2. Discontinue use of the old key
  5. 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 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.

Key Order in the Configuration

The new decryption key should be listed 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.

At step 2, log into 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, that is, a "Signing Only" key. (Click the image on the right to see how this is done in the Federation Manager.) After doing so, your SP's metadata will contain two (2) key descriptors, one of which is new.

After waiting sufficiently long, 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 TLS key, and/or a decryption key. The old key will no longer be configured.

Finally, in conjunction with step 4, log into the Federation Manager at step 5 and remove the old key descriptor—the one with the use="signing" XML attribute—from the metadata. Leave the new <md:KeyDescriptor> element—the one with no use XML attribute—in the metadata.

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.

The migration process documented in the Shib wiki is different than the above process. The latter avoids having two encryption certificates in metadata at the same time, which is known to have interoperability issues with some IdP software (such as Microsoft AD FS 2.0).

If you have questions about Shibboleth, please consult the Shib mailing lists.


  • No labels