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.



You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 18 Next »

This is one of a series of documents regarding the use of X.509 certificates in Federation metadata. The following instructions are intended for InCommon Federation participants wishing to replace an old certificate with a new certificate in metadata. Such a migration process (or key rollover, as it is sometimes called) is required, for example, in the case of expired certificates.

Contents

Getting Started

Start by reading the sections on terminology, metadata propagation, and implementation support, which set the stage for certificate migration. If you're an IdP site administrator, continue by reading the section on Migrating a Certificate in IdP Metadata. SP site administrators, on the other hand, should read the section on Migrating a Certificate in SP Metadata instead. For general information about certificate migration strategies, see the comprehensive (but optional) document on key rollover.

Terminology

Key Descriptors

We will use the following terminology:

  • A signing key refers to a key pair used in XML Signature. A private key is used to sign an XML blob while the corresponding public key is used to verify the signature.
  • An SSL/TLS key is a key pair used during a back-channel exchange, usually a SOAP exchange (such as artifact resolution or attribute query). Such a key may be used for SSL/TLS client-server authentication.
  • An encryption key refers to a key pair used in XML Encryption. A public key is used to encrypt an XML blob while the corresponding private key is used to decrypt the ciphertext. (That's an over-simplification of XML Encryption, but it will suffice in what follows.)

Recall that there are three types of key descriptors in SAML metadata:

  1. <md:KeyDescriptor use="signing">
  2. <md:KeyDescriptor use="encryption">
  3. <md:KeyDescriptor>

A type 1 key is used for both signing and SSL/TLS. That is, the key is used to provide authenticity and integrity but not necessarily confidentiality.

A type 2 key is used for encryption only, that is, the key is used to provide confidentiality.

Since the use XML attribute is missing on a type 3 key descriptor, such a key is used for signing, SSL/TLS, and encryption. Such a key is used to provide authenticity, integrity, and confidentiality.

As you might guess, the latter type of key is most difficult to migrate away from. On the other hand, redundantly including the same key in two key descriptors in the same role descriptor leads to bloated metadata files. In the case of large metadata files distributed by federations, this bloat can be significant. Thus there's a natural tension between type 3 keys and the more explicit key descriptors (i.e., types 1 and 2).

Role Descriptors

A role descriptor is a metadata element whose type is based on the SAML md:RoleDescriptorType type. Examples include <md:IDPSSODescriptor>, <md:SPSSODescriptor>, and so forth. This term will be useful when discussing the features of conforming implementations in the section on implementation support.

Metadata Propagation

The certificate migration processes outlined below require all changes to metadata to be propagated to your federation partners before the next step in the process can safely occur. How this happens depends on who your federation partners actually are. If your partners are members of the InCommon Federation, metadata propagation is fairly well understood (as long as your partners follow InCommon recommendations with respect to metadata consumption) but if you have partners that are not InCommon participants, then it is up to you to make sure those partners receive critical metadata updates.

For InCommon participants, metadata is pulled at various times so the actual time required to propagate new metadata throughout the Federation is variable. Deployers are encouraged to communicate directly with Federation partners to ensure that critical metadata updates are received in a timely manner.

Since InCommon participants are strongly encouraged to update their metadata daily, you should wait at least a day for your new metadata to propagate. You may want to wait longer, however. We recommend you wait three (3) weeks for the metadata to propagate, since any given Federation metadata file has an explicit 3-week lifetime. Since SP operators have to update metadata twice (see below), SPs are advised to begin the migration process early, at least six (6) weeks prior to the certificate's expiration date.

Implementation Support

In general, SAML implementations have varying degrees of support for X.509 certificates in metadata, which leads to known interoperability issues. Thus software limitations need to be factored into the certificate migration decision-making process.

To fully support key rollover, implementations MUST support the following features:

  1. An implementation MUST be able to consume and utilize two signing keys bound to a single role descriptor. There are two cases that MUST be supported:
    1. <md:KeyDescriptor use="signing"> and <md:KeyDescriptor use="signing"> in a single role descriptor
    2. <md:KeyDescriptor use="signing"> and <md:KeyDescriptor> in a single role descriptor
  2. If an implementation supports inbound encryption, it MUST be configurable with up to two decryption keys.
  3. An implementation MAY support (i.e., consume and utilize) multiple encryption keys per role descriptor in metadata. In particular, the implementation MAY support two <md:KeyDescriptor> elements (with no use XML attribute) in a single role descriptor, but this is not strictly required since it can usually be avoided in practice.

It is known, for instance, that some IdP implementations will not consume SP metadata containing more than one encryption key descriptor. Thus there will be a period of time where the migration of an encryption certificate in SP metadata will "break" interoperability with IdP deployments based on that implementation. In such a situation, the wait time for propagating metadata (e.g.) becomes a strategic decision left to the deployer's discretion.

Consult your software documentation to better understand its capabilities. Indeed, evaluate software capabilities before you deploy, if at all possible.

Migrating a Certificate in IdP Metadata

This section and its subsections are meant for IdP site administrators wishing to replace an old certificate with a new certificate in metadata.

In Federation metadata, all certificates in IdP metadata are contained in an <md:KeyDescriptor use="signing"> element. Such a certificate may be used for signing and/or SSL/TLS. Usually there are identical key descriptors contained in the <md:IDPSSODescriptor> and <md:AttributeAuthorityDescriptor> elements, in which case both certificates are migrated out of metadata at the same time.

Regardless of the IdP implementation used, the general migration process is as follows.

Preconditions:

  • There is an <md:KeyDescriptor use="signing"> element in IdP metadata.
  • The IdP software is configured to use the corresponding private key as a signing key and/or SSL/TLS key.

Procedure:

  1. Add a new <md:KeyDescriptor use="signing"> element to IdP metadata.
  2. Wait for the newly updated metadata to propagate.
  3. Configure the IdP software to use the new key (instead of the old key) as the signing key and/or SSL/TLS key.
  4. Remove the old <md:KeyDescriptor use="signing"> element from IdP metadata.

Procedural details:

At step 1, login to the administrative web interface, upload a new certificate, and bind that certificate to your metadata. Be sure to bind the certificate to each of the <md:IDPSSODescriptor> and <md:AttributeAuthorityDescriptor> elements. After doing so, your IdP's metadata will contain four (4) key descriptors, two of which are new.

The configuration at step 3 depends on your particular IdP software implementation and how the key is used. Some implementations require separate configurations for signing and SSL/TLS. In particular, if your IdP supports artifact resolution or attribute query, it may require a separate SSL/TLS key configuration. Consult your software documentation for further instructions. (If you're using the Shibboleth IdP, refer to the next section.)

Finally, at step 4, remove the old key descriptors from metadata but leave the two new key descriptors in the metadata. This completes the migration process.

Implementation-specific Details for IdP Deployers

The key rollover process for a Shibboleth 2.x IdP is fully documented in the Shib wiki.

Migrating a Certificate in SP Metadata

This section and its subsections are meant for SP site administrators wishing to replace an old certificate with a new certificate in metadata.

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.

Regardless of the SP implementation used, the general migration process is as follows.

Preconditions:

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

Procedure:

  1. Configure the SP software as follows:
    1. Continue to use the old key as a signing key, an SSL/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 to metadata
    2. Leave the old <md:KeyDescriptor> element in metadata
  3. Wait for the newly updated metadata to propagate
  4. Configure the SP software as follows:
    1. Use the old key as a decryption key only (i.e., discontinue the use of the old key as a signing key and/or SSL/TLS key)
    2. Use the new key as a signing key, an SSL/TLS key, and/or a decryption key
  5. Remove the old <md:KeyDescriptor> element from SP metadata
  6. Wait for the newly updated metadata to propagate
  7. Configure the SP software as follows:
    1. Discontinue the use of the old key as a decryption key
    2. Continue the use of the new key as a signing key, an SSL/TLS key, and/or a decryption key

Procedural details:

Step 1 requires the new key to be configured as an encryption key only. In particular, the new key must not be configured as a signing key or SSL/TLS key at this step (but see step 4). Note that some software implementations do not permit multiple encryption keys to be configured (which is an implementation bug). Check your software documentation for further instructions.

At step 2, login to the administrative web interface, upload a new certificate, and bind that certificate to the <md:SPSSODescriptor> element in your metadata. After doing so, your SP's metadata will contain two (2) key descriptors, one of which is new.

At the end of step 4, the old and new keys will have precisely the opposite capabilities that they had at the end of step 1. Thus if your software supports the configuration at step 1, then it will also support the configuration at step 4.

At step 5, login to the administrative web interface and remove the old key descriptor from the metadata. This is done by removing the old certificate from the list of certificates uploaded to the web application.

Finally, completely remove the old key from the configuration at step 7. 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.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels