This page introduces some important policy considerations associated with InCommon metadata. Other pages discuss the availability of multiple metadata aggregates and provide guidance with respect to metadata configuration, including client configuration and the configuration of outbound firewalls.
InCommon expects participants to refresh metadata daily to ensure that SAML endpoints have access to the most up-to-date keys and other registered information. Some software implementations (such as Shibboleth) handle metadata easily, but regardless of your software, please read this entire page to understand the requirements and pitfalls associated with metadata consumption.
It is strongly recommended that InCommon SPs and IdPs refresh and verify metadata at least daily. An optimal configuration would attempt to refresh metadata every hour, assuming your client supports HTTP Conditional GET.
Participants are strongly encouraged to use SAML software that properly handles metadata; failure to do so can have profound effects on the successful use of the Federation. In addition to maintaining the security of your own deployment, proper metadata use is critical to ensure that other participants can depend on your system behaving correctly when they make changes.
The security implications of metadata refresh!
Regular metadata refresh protects users against spoofing and phishing, and is a necessary precaution in the event of key compromise. Failure to refresh metadata exposes you, your users, and other Federation participants to unnecessary risk.
In addition, if you don't refresh your metadata regularly, it is likely that a software implementation will fail at some point since the XML document carries an expiration date (
validUntil) that causes the metadata to expire in two weeks. InCommon strongly recommends that you do not rely on the actual length of this validity interval in any way, and in fact, we reserve the right to shorten the validity interval with little or no notice.
The mechanics of metadata refresh:
- Choose the right metadata aggregate for your particular deployment
- Deploy an automated metadata refresh process
- Configure your metadata process:
- Configure your metadata client
- Configure your outbound firewall rules (if necessary)
- Verify the XML signature on downloaded metadata
- Validate the expiration date on downloaded metadata
Federation metadata is signed for integrity and authenticity. Participants are strongly encouraged to verify the XML signature on the metadata file before use; failure to do so will seriously compromise the security of your SAML deployment.
The InCommon Federation is based on the Explicit Key Trust Model, one of several possible metadata trust models. To bootstrap the trust fabric of the Federation, participants are required to download and configure the metadata verification certificate into their metadata refresh process:
The certificate must be obtained securely since all subsequent operations depend on it. You may check the integrity of the downloaded certificate in a variety of ways. For example, you could use
openssl after the fact as follows:
$ curl --silent --remote-name
$ openssl x509 -sha1 -in incommon.pem -noout -fingerprint
Once the certificate file is locally installed, you can use it to verify the signature on the metadata file. For example, you could use the XmlSecTool (or some similar 3rd-party tool) to verify the signature:
You may also want to schema validate the metadata:
For convenience, we provide a set of (suitably modified) schema files that permit offline schema validation.
Federation metadata has an expiration date, much like an X.509 certificate. It is important that expired metadata not be accepted, otherwise an attacker would be able to substitute expired metadata in conjunction with a metadata refresh. In particular, a metadata file should not be accepted if either of the following conditions are true:
- If the metadata file does not have a
validUntilattribute on the root element.
- If the
validUntilattribute on the root element is expired.
A metadata reload process should check each of the above conditions before accepting the metadata; alternatively if your SAML implementation is known to ignore/reject expired metadata (a basic correctness requirement), it may be sufficient to ensure that a
validUntil attribute exists and is not unexpectedly far into the future.
Verify the expiration date independently!
Verifying the signature on a SAML metadata file does not verify the presence or value of an expiration date. The only way to verify the expiration date is to parse the XML.