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 4 Next »

The following instructions are specifically intended for InCommon Federation participants who need to replace a certificate currently in Federation metadata with a new certificate. This migration process is required, for example, in the case of expired certificates.

Note: General information about key rollover will be found elsewhere.

Propagating Metadata Throughout the Federation

The certificate migration processes documented below require any changes to metadata to propagate throughout the Federation before the next step in the process can safely occur. Since metadata is pulled by each Federation participant, the actual time required to propagate new metadata 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.

If all software implementations fully supported key rollover, the actual waiting time would be of little concern. Some applications, however, have limitations that need to be factored into this decision. 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 a certificate in SP metadata will "break" interoperability with that IdP. In such a situation, the wait time becomes a strategic decision left to the deployer's discretion.

Migrating a Certificate in IdP 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 an 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 the SSL/TLS key.
  4. Remove the old <md:KeyDescriptor use="signing"> element from IdP metadata.

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.

Migrating a Certificate used by the Shibboleth IdP

Although SAML metadata expresses a single key for both signing and SSL/TLS, the Shibboleth IdP has separate configurations for each. In Shibboleth 2.0, for example, a signing credential is configured in relying-party.xml and then that credential is associated with specific protocols as desired. The latter is beyond the scope of this key rollover process, so all you need to do is configure the new signing credential in relying-party.xml. Even that may not be necessary if the new credential physically replaces the location of the old credential.

The next step is to configure the key for SSL/TLS as well (assuming the IdP supports artifact resolution or attribute query, both of which likely require SSL/TLS server authentication). If Apache is used in front of the Java container (usually Tomcat), the configuration of the SSL/TLS credential occurs in the Apache configuration file. If, on the other hand, Tomcat is used as a stand alone server, the new SSL/TLS credential is added to both Tomcat's keystore and its configuration file (server.xml). In either case (Apache or Tomcat), the server is restarted to complete the configuration.

Migrating a Certificate in SP 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, as an SSL/TLS key, and/or as a decryption key.

Procedure:

  1. Configure the SP software as follows:
    1. Continue to use the old key as a signing key, as an SSL/TLS key, and/or as 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, as an SSL/TLS key, and/or as 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, as an SSL/TLS key, and/or as a decryption key

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 a 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.

Migrating a Certificate used by the Shibboleth SP

The key rollover process for a Shibboleth 2.0 SP is fully documented in the Shib wiki.

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