MetadataDrivenConfigurationExamples

The IdP includes a very important feature that allows much of the per-SP configuration typically found in relying-party.xml or attribute-filter.xml to be offloaded to extension Attribute “tags” in SP metadata. This has a number of advantages, though sometimes this is situational or a matter of preference/style. It can become very unwieldy to maintain long lists of overrides or filter rules, and the performance of the IdP can suffer if the number truly gets out of hand. Metadata is more standardized, can be much more easily scripted when the metadata is not sourced from a federation, and there are a variety of filters supported for adding to federation metadata on the fly.

With any of the examples below, there are a couple of different ways one can go about supporting tags for specific use cases. The main one documented by the MetadataDrivenConfiguration topic is the “global” one: altering the profile configuration beans active for a relying party definition to add the “.MDDriven" suffix automatically wires up support for most of the possible properties in a standard way to allow tag-based control.

This is both good and bad. It’s good because it’s simple and a single step for control over a lot of different options. It’s bad because it is somewhat slower due to the need to constantly access the metadata to look up virtually every setting, though the recent releases do this much more efficiently through caching of the decoded tags into a hash table.

It’s also something of a risk when remote sources of metadata are used because those sources could in theory slip the same tags into the metadata to influence the behavior of your IdP. This is why you should never trust any remote source other than a federation providing appropriately signed metadata (and NEVER rely on a vendor’s own source of metadata, which are almost always incorrect anyway). Having said that, the EntityAttributes filter has a means of stripping existing tags from a source before adding back others, so that is an important tool for safety.

The other option, which will be noted in the examples here, is to wire up by hand specific support for a particular tag doing a specific thing. This isn’t obvious, but it follows a basic pattern and the specific wiring needed is shown in the examples. Note that this doesn’t obviate the risk of specific tags being injected by metadata sources, but in some cases this risk is further mitigated by a lack of benefit in doing so by that source. Some settings just don’t gain somebody anything to manipulate.

Signing Key Selection

It is not generally useful practice to use more than one signing key at a time (consider where they’re all stored, and the probability that if one were compromised that the rest would somehow not be?). However, this occasionally becomes necessary either during a transition to a new key, or an adjustment that becomes necessary due to constraints imposed by a particular SP regarding size or changes to security policy, for example, the transition away from SHA-1 certificates though SAML itself isn’t affected by that issue at all when implemented compliantly.

The goal of this example is to default the system to signing with a particular “current” key/certificate, but tag specific SPs that require the use of a different key or certificate.

Security Configuration Beans

Because this has never been a common thing for a Shibboleth IdP to do, there isn’t a clean/simple way to control the key. It’s part of a much larger set of objects that make up the so-called Security Configuration setting, which includes not only keys but also algorithm controls.

Signing Credentials

First you need to actually define beans in credentials.xml that load the relevant key and certificate to make up each individual signing credential. In this real world example, the “first” credential has been replaced at some point and in its place two new keys were deployed using properties to locate the files and password. The most important points are that you need to be sure to alias shibboleth.DefaultSigningCredential to the one to use by default, and the shibboleth.SigningCredentials bean needs to reference all of them.

Security Configurations

Second, you define a separate security configuration in relying-party.xml making use of the non-default key. In this example, several built-in beans are used to simplify the definitions. Only the signing key is overridden.

Adding Tag Support

As described in the introduction, you can do this either globally as documented with the .MDDriven profile bean suffix or just add support for this specific tag:

Of course you would need to do similar overrides of other profiles that make use of the keys.

In English, what the strategy bean says is “Look in the metadata for a standardized cross-profile tag named “http://shibboleth.net/ns/profiles/securityConfiguration” whose value is the name of a bean of type org.opensaml.security.config.SecurityConfiguration. In other words, the tag can’t really be the configuration in the same way as a boolean or string valued setting but is the name of the bean supplying the configuration.

Metadata

Local Metadata

When you control the metadata (or script it, etc.), then you would tag an SP to trigger use of the non-default key like so:

Remote Metadata

For a remote metadata source, you will typically want two filters, one to strip anthing undesired from the feed and another to add the tag you want. In this example, anything other than so-called “entity category” tags are removed before adding the exception tag.