SAMLMetadataApproaches

Overview

The hub’s SAML 2.0 support, like all Shiibboleth software before, fundamentally operates directly via SAML Metadatato provision connections, and is specifically designed around the use of third-party signed metadata issued by SAML trust federations to provision basic connectivity and trust to thousands of systems at once, and not by manually connecting to them one at a time. When you don’t have a source of metadata like that, then you have to do additional work to supply what the hub expects and solve some fairly difficult problems. Basically, there aren’t any approaches that have proven effective except the one nobody seems to appreciate. Life is funny.

Notably, the degenerate case of needing to trust a very small number of IdPs (or one) is not unusual and is discussed below; in such cases, there are still fundamental exposures created by the sort of practices one sees frequently; IdPs can get away to some extent with treating SP metadata as though it’s not terribly important. SPs cannot do the same when it comes to IdP metadata. Your whole reason for using a SAML SP to protect anything meaningful is dependent on that metadata being accurate and trustworthy or you’re wasting your time.

Absent metadata, the hub will be unable to do much with an agent asking it to issue a SAML request or process a response. Technically what happens is that the request falls into a state we call “unverified” but, unlike some cases with OpenID, it’s not really practical to do anything other than fail. The agent will get a response back indicating the hub couldn’t fulfil the request and end up generically reporting an error. Notably, you would see the same any time there’s an accidental mistake causing the entityID the hub is trying to interact with to diverge from what the metadata contains, as the lookup is performed by the entityID.

Providing Metadata to the Hub

The hub, by virtue of operating within the IdP software, relies on the existing IdP Metadata Resolver service and configuration (that is thus the “full documentation/reference” on configuring metadata sources). The existing metadata service delivered with the IdP out of the box is automatically plumbed into every agent bean for you. The only difference is that just as the IdP (mostly) ignores any metadata for systems acting as an IdP and only expects to look for SP metadata, the hub ignores any SP metadata and only cares about IdP metadata As a result, wisdom aside, it’s perfectly possible to supply piles of both IdP and SP metadata to the software at the same time without any interference with either use case.

With all the options and approaches we support, what are the best choices? This depends on your use case, which broadly speaking is likely going to overlap with one of about three general cases.

Enterprise Scenarios

The most common enterprise scenario for an SP is that only a single IdP is in use (the enterprise one). There might be a few more in certain cases, but it devolves to “very few strongly trusted options”.

In this scenario, the IdP(s) should if possible provide a source of XML-signed, short-lived (days? maybe weeks?) metadata that the hub will refresh for you dynamically from the source. We do not recommend the use of unsigned metadata sources under a commercial TLS key but this is of course supported.

This approach is addressed using the FileBackedHTTPMetadataProvider combined with appropriate filters to check the signature and enforce an upper bound on validity.

Example TBD

Configuring a local copy of the metadata statically (typically with the FilesystemMetadataProvider) is a common, but not ideal, fallback choice. While not automatically handling changes to the IdP’s metadata is a problem, the risk of accepting a compromised key before knowing about it is catastrophic. The problem with remote, but untrustworthy, sources of metadata is that while it might prevent the general problem of prompt revocation, it exposes the hub to a more constant risk of bad metadata being introduced.

Federated Scenarios

The term “federated” as an adjective is heavily misused, but it really means what others sometimes call multi-lateral federation, the ability to leverage a large number of external IdPs operated by other organizations in a relatively loosely coupled relationship. Large is relative, but let’s say at least dozens but usually more on the order of hundreds.

MDQ

The best solution for this when possible is a so-called MDQ service, which is a simple HTTP service providing signed metadata lookup that we support natively. Most viable SAML federations now operate such services and will document how to use them. The DynamicHTTPMetadataProviderprovides native and automatic support for this protocol.

There are links to some federations' MDQ service documentation on the SAMLBasics page.

At minimum, what you need to configure an MDQ source is:

• the MDQ location

• the proper signing key, which essentially secures your entire system by signing all the IdP metadata and their keys

• the policy regarding how long the metadata can be valid to prevent stale but “valid” metadata from being re-injected

The location is obvously placed into the metadata provider’s <MetadataQueryProtocol> element. The signing key (in a local file) is referenced in the SignatureValidationFilterand the upper bound on validity referenced in the RequiredValidUntilFilterattached to the provider.

Remote Aggregates

Prior to MDQ, most federations operated by providing large (and growing) aggregates of SAML metadata collected together in one file and provided over HTTP. You certainly can support that today with the FileBackedHTTPMetadataProvider, with the same basic requirements, a signing key and a validity limit.

The problem with this at scale is memory usage and to a lesser extent processing time, and we do not expect that consuming large files this way will ever be viable anymore. Ultimately you will have to judge how much overhead you can live with.

Locally Maintained Metadata

While worth mentioning for completeness, this isn’t really a practical option at any real scale, just as it’s not a real solution for IdPs to manually maintain metadata for SPs that are not effectively an extension of their own business. IdPs today can manually connect to SPs when the SPs are locally operated or a SAAS solution that one is contracting for, and of course that is by far the dominant use case for SAML in the world. Once you get beyond those cases, there is no practical way for an IdP to be expected to know about random services in the world, and it’s equally untenable for an SP to manually track and on-board lots of IdPs for which no clear business incentive exists to do so.

In effect, the line between this scenario and the following one is that business incentive and whether the costs of having to solve this problem badly are justified to whoever pays the bills.

SasS or Tenant Scenarios

The middle ground between the first and second scenario is a matter of perspective, because a SaaS deployment may well have dozens or hundreds of IdPs or more, certainly at a large commercial scale. What is different from a federated case is the process by which an IdP would be added and why. With a tenant-based model or one in which there are heavyweight processes or contracts involved to add a new IdP to the mix, there is at least the possibility that any manual process for this is dwarfed by all the rest of the work involved (including customizing behavior around the data being received, a whole other topic).

In practice, the best option for this whenever possible is to rely on an MDQ service (see the previous scenario), many of which will be publically accessible (to their own detriment) even for non-members of the relevant federation. Any IdP metadata available in that form is going to solve your problem for all those cases in one step, and better than you could possibly manage any other way, so if you have that option for any of your customers, it should be employed for them.

For everybody else, the fact is you have no good options, but one decent one that takes some work.

Often, SaaS operators tend to manually collect and statically deploy metadata by hand (or break it apart) and have no means of dealing with IdP key revocation, rollover, or endpoint changes. If this is you, do better.

Our perspective would be that providing a secure and authorizable means by which customers can supply the information to you on demand and generate SAML metadata that the hub can consume from the filesystem is probably your best bet for any customers that cannot point you at an MDQ-sourced metadata service. For the love of all that is good and pure…do not compromise the operational advantages those organizations are paying for by forcing them to manually get you the information if it changes. If you’re using this software, you would be throwing out its best feature.

For everyone else, though, this suggestion is fairly similar to the most common “less terrible” strategy one sees in which IdP information is supplied by customers in an application’s configuration. This can work in a similar fashion with our software if the “back-end” produces the necessary metadata for the hub to consume. (It may one day even be a feature we add to the IdP.)

The best solution for this at the point of hub consumption is the LocalDynamicMetadataProvider, by virtue of the fact that with a single configuration you can consume metadata from individual, isolated files created for each IdP (the filename being the hash of the entityID). The files will be checked for changes per your chosen policy, allowing updates to be visible automatically if the files change.

Example TBD

Another, more complex option is to implement the MDQ “back-end” yourself (reasonably simple to do with Apache in fact) and manage the metadata some other way you see fit, and use the MDQ support to get it into the hub.

Traps to Avoid

Regardless of the scenario, there are some traps to be aware of and avoid/mitigate.

Non-Expiring Metadata

Metadata that is used to provide a trusted key absent any other constraints (which is how Shibboleth works and how the only standardized SAML trust model is defined) relies solely on the metadata’s expiration to “bound” the risk of an old or compromised key being accepted if an old (even if signed) metadata document were to be fed in. The validUntil attribute (and the signature over the document) limits that window precisely, just as a CRL does, and is the only means by which reliable key revocation and replacement become possible.

Shibboleth provides the RequiredValidUntilFilterfeature for this purpose, which acts to prevent any metadata without an expiration (or too long a validity window) from being accepted.

Thus, you should never configure a remote metadata source without such a filter (and a SignatureValidationFilter) in place and if you can’t do so, then you should not under any circumstances accept it. Period.

Metadata Impersonation Attacks

An often overlooked issue with remote metadata sources is that you can’t allow overlap between metadata from a remote source with metadata from any other source, local or remote. That is, if you have dedicated sources of metadata for particular IdPs, you must ensure that no sources of metadata can supply metadata for any of the same entityIDs. (One assumes local metadata sources are under your control enough that it would be remote sources to worry about.)

In practice, this means it’s not generally viable to rely on more than one “large scale” remote metadata source. You might just believe that the remote source is trusted enough not to supply metadata source in some other way, but assuming the set of “other” IdPs is small enough, adding a PredicateMetadataFilteris a useful step to exclude the specific entityIDs that you should not allow the remote source to supply.

While ordering your metadata sources can also help with this (e.g., putting local sources first before failing over to a remote option), the possibility of errors being introduced into local sources is never zero and so the risk exists that the system could query the remote source for one of the “locally sourced” entityIDs.

This issue is best illustrated if one considers the sort of poor practice that might involve connecting to every IdP’s metadata from the source, remotely, by hand, each one intended to supply only that IdP’s metadata. This is a terrible approach for all kinds of reasons (there being a background refresh thread for every single one being one example), but in particular it becomes possible for any of those remote sources to supply metadata for any IdP that any of them were meant to supply, and it also means that a breach of any of them effectively compromises the whole hub.

Thus, in any scenario involving multiple remote sources, you need to consider, and possibly implement filters to prevent, metadata for the “wrong” entityID from being supplied by any of them. Either inclusion or exclusion rules may be needed.