Page tree

Previous Stable Release

Please note that the V3 release branch is now the previous stable release, with the current stable releases from the V4 branch.
Support for V3 will end on Dec 31, 2020.

Skip to end of metadata
Go to start of metadata

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

Compare with Current View Page History

« Previous Version 12 Next »

This is preliminary documentation regarding an unreleased feature and the details may change prior to availability.


One of the challenges of dealing with interoperability issues with SPs is maintaining all the custom configuration rules needed to drive the IdP's behavior in all kinds of different ways. Traditionally most of these kinds of settings are concentrated in the relying-party.xml file and involve defining "overrides" for SPs or groups of SPs, often through manually maintained lists of entityIDs.

As discussed in the RelyingPartyConfiguration topic in the section on dynamically-driven configuration, V3.3 introduced an advanced capability to produce these settings on the fly at runtime, which creates opportunities for more flexible configuration, at some cost in complexity. One of the techniques currently described in that section involves the use of metadata "tags" (a shorthand name for the <mdattr:EntityAttributes> extension feature) to embed signals in metadata that can drive configuration. In the longer term, any hope for a simplified approach to configuration or even a GUI probably rests on a strategy of this general type.

V3.4 introduces a built-in layer of code and Spring wiring to enable the use of the metadata-driven approach to configuration in a systematic way that provides a set of conventions for tag names and values to use to drive a significant range of configuration settings. With a small amount of up-front adjustment to the relying-party.xml file, it's possible to enable comprehensive support for metadata-driven configuration that can be freely intermixed in most cases with more static settings as required.

Bear in mind that enabling this feature requires a total degree of trust and control over one's sources of metadata, because the information in the metadata can have a wide-ranging degree of impact on the behavior of the IdP, by design. It essentially off-loads pieces of your configuration to the metadata, with all that that entails.

All of these new features are optional and are essentially a "working example" of how to use the already-available features provided with V3.3 to do something useful. It is expected at the time of writing that an unofficial plugin may be available prior to the release of V3.4 to enable the same example features in the V3.3 release.


Support for this feature has been added to the runtime environment in a way that avoids overhead (and risk) if not used but allows for straightforward enablement on a per-profile basis. The existing parent beans used for defining relying party defaults, overrides, and profile configurations all have analogs with a ".MDDriven" suffix in their names. Changing the existing parent bean name by adding the suffix and reloading the configuration will cause the runtime to evaluate most of the commonly-used configuration settings by checking for appropriately-named "tags" in the SP's metadata before falling back to the default, or statically configured, value if no tag is found.

For example, if you would like to enable tag-driven configuration for SAML 2.0 Browser SSO, you can replace any reference to the SAML2.SSO bean with SAML2.SSO.MDDriven, as in this example:

Enable tag-driven features in relying-party.xml
<bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
	<property name="profileConfigurations">
			<ref bean="Shibboleth.SSO" />
			<ref bean="SAML1.AttributeQuery" />
			<ref bean="SAML1.ArtifactResolution" />
			<ref bean="SAML2.SSO.MDDriven" />
			<ref bean="SAML2.ECP" />
			<ref bean="SAML2.Logout" />
			<ref bean="SAML2.AttributeQuery" />
			<ref bean="SAML2.ArtifactResolution" />

Attribute / Property Convention

The "bridge" between the metadata and this feature is the naming and syntax of the tags used to control the configuration properties in the IdP. As an implementation strategy this could be "brute forced" with arbitrary mapping dictionaries, but the supplied implementation takes the approach of automating a mapping between the names of settings, the identifiers used internally for the various profiles, and the names of the corresponding SAML Attributes in metadata for those profile/setting combinations.

Each setting has a "base" name matching its Java bean property name as would be used if the setting were explicitly configured in Spring. For example, the property set via p:defaultAuthenticationMethods is named "defaultAuthenticationMethods".

The corresponding SAML Attribute for a setting is named by suffixing the "base" name of the setting to a profile URL that is defined by the Shibboleth software for each of the supported profiles.

The URLs are as follows:

ProfileProfile URL

It follows that the includeAttributeStatement property of the "Shibboleth.SSO" profile configuration can be set via a metadata Attribute named "".

As an additional convention, a setting can be configured for all profiles simultaneously by prefixing it with the URL "".

Type Conversion

The supplied implementations support various built-in type conversions supporting a natural mapping between simple XML syntax and Java data types. The only XML syntaxes supported are "simple content" models involving an <AttributeValue> containing only text content, but it is possible to apply specific xsi:type designations that trigger more precise handling (such as enforcing numeric or boolean data). Different kinds of settings support particular XML syntaxes as described below.

Setting Data TypeSupported XML ConversionsNotes
StringUntyped, string, boolean, integer, dateTime, base64binary

Booleans are mapped to "0" or "1".

Dates are mapped to the Unix epoch, converted to String.

BooleanUntyped, string, boolean, integer

Strings are processed as a valid XML boolean value (0, 1, true, false) or treated as false.

Non-zero integers are true, zero is false.

IntegerUntyped, string, boolean, integer

Strings are decoded via Integer.decode() method.

Booleans are mapped to 0 or 1.

LongUntyped, string, boolean, integer, dateTime

Strings are decoded via Long.decode() method.

Booleans are mapped to 0 or 1.

Dates are mapped to the Unix epoch, converted to a Long.

DoubleUntyped, string, boolean, integer

Strings are decoded via Double.valueOf() method.

Booleans are mapped to 0.0 or 1.0.

DurationUntyped, string, integer

Strings are converted from the ISO Duration notation used throughout the software.

Integers are treated as a millisecond duration.

List<?>Untyped, string, boolean, integer, dateTime, base64binarySupports multiple values and each value is converted to a String and then used to construct an object of the type specified for the property via a String-based single-argument constructor.
Set<?>Untyped, string, boolean, integer, dateTime, base64binarySupports multiple values and each value is converted to a String and then used to construct an object of the type specified for the property via a String-based single-argument constructor.
BeanUntyped, stringConverted to a String used as a name of a Spring bean to build or access

Applying Tags

There are two ways to apply tags to metadata: directly and indirectly.

The direct method applies to cases in which you control the metadata or when the source of the metadata supports the inclusion of the necessary extensions. The tags simply appear within the metadata being loaded into the IdP using an <mdattr:EntityAttributes> extension element:

Direct embedding of configuration tags
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" 
            <saml:Attribute Name=""
            <saml:Attribute Name=""
                <saml:AttributeValue xsi:type="xsd:boolean">false</saml:AttributeValue>
    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
	<!-- Content omitted -->        

The indirect method relies on a metadata filter to attach the tags at runtime after loading and verifying the metadata. This is useful for cases in which you want to rely on externally supplied metadata but still organize parts of your configuration around the metadata. One use for this is simply consistency: if you have both external and local metadata, you can drive the configuration with both.

Indirect example of applying tags using a filter
<MetadataProvider id="InCommonMD" xsi:type="FileBackedHTTPMetadataProvider"
	<MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P14D" />
	<MetadataFilter xsi:type="SignatureValidation"
		certificateFile="%{idp.home}/credentials/incommon.pem" />
	<MetadataFilter xsi:type="EntityRoleWhiteList">
	<MetadataFilter xsi:type="EntityAttributes">
		<saml:Attribute Name=""
		<saml:Attribute Name=""
			<saml:AttributeValue xsi:type="xsd:boolean">false</saml:AttributeValue>


Bean ID
RelyingParty.MDDrivenRelyingPartyConfigurationA template bean for use in defining metadata-driven RelyingParty overrides by hand
RelyingPartyByName.MDDrivenRelyingPartyConfigurationA template bean for defining metadata-driven RelyingParty overrides based on matching by name
RelyingPartyByGroup.MDDrivenRelyingPartyConfigurationA template bean for defining metadata-driven RelyingParty overrides based on matching by <EntitiesDescriptor> groups
RelyingPartyByTag.MDDrivenRelyingPartyConfigurationA template bean for defining metadata-driven RelyingParty overrides based on matching <EntityAttributes> extension content


BrowserSSOProfileConfigurationDefault metadata-driven configuration for SAML 1.1 SSO profile
SAML1.AttributeQuery.MDDrivenAttributeQueryProfileConfigurationDefault metadata-driven configuration for SAML 1.1 Attribute Query profile
SAML1.ArtifactResolution.MDDrivenArtifactResolutionProfileConfigurationDefault metadata-driven configuration for SAML 1.1 Artifact Resolution profile
SAML2.SSO.MDDrivenBrowserSSOProfileConfigurationDefault metadata-driven configuration for SAML 2.0 SSO profile
SAML2.ECP.MDDrivenECPProfileConfigurationDefault metadata-driven configuration for SAML 2.0 Enhanced Client/Proxy profile
SAML2.Logout.MDDrivenDefault metadata-driven configuration for SAML 2.0 Single Logout profile
SAML2.AttributeQuery.MDDrivenAttributeQueryProfileConfigurationDefault metadata-driven configuration for SAML 2.0 Attribute Query profile
SAML2.ArtifactResolution.MDDrivenArtifactResolutionProfileConfigurationDefault metadata-driven configuration for SAML 2.0 Artifact Resolution profile
Liberty.SSOS.MDDrivenSSOSProfileConfigurationDefault metadata-driven configuration for Liberty ID-WSF Delegated SSO profile
CAS.LoginConfiguration.MDDrivenLoginConfigurationDefault metadata-driven configuration for CAS login prototol
CAS.ProxyConfiguration.MDDrivenProxyConfigurationDefault metadata-driven configuration for CAS proxy login protocol
CAS.ValidateConfiguration.MDDrivenValidateConfigurationDefault metadata-driven configuration for CAS ticket validation protocol
shibboleth.DefaultMDProfileAliasesList<String>A built-in list of alternate URL "prefixes" to property names, this is used to automate the generation of property tag names that apply to all profiles at the same time.
shibboleth.MDProfileAliasesList<String>An optional user-supplied list of additional URL prefixes to support custom property tag names
shibboleth.MDDrivenStringPropertyStringConfigurationLookupStrategyParent bean for defining new lookup strategies for string settings
shibboleth.MDDrivenBoolPropertyBooleanConfigurationLookupStrategyParent bean for defining new lookup strategies for boolean settings
shibboleth.MDDrivenIntPropertyIntegerConfigurationLookupStrategyParent bean for defining new lookup strategies for integer settings
shibboleth.MDDrivenLongPropertyLongConfigurationLookupStrategyParent bean for defining new lookup strategies for long integer settings
shibboleth.MDDrivenDoublePropertyDoubleConfigurationLookupStrategyParent bean for defining new lookup strategies for double settings
shibboleth.MDDrivenDurationPropertyDurationConfigurationLookupStrategyParent bean for defining new lookup strategies for Duration settings
shibboleth.MDDrivenListPropertyListConfigurationLookupStrategyParent bean for defining new lookup strategies for List settings
shibboleth.MDDrivenSetPropertySetConfigurationLookupStrategyParent bean for defining new lookup strategies for Set settings
shibboleth.MDDrivenBeanPropertyBeanConfigurationLookupStrategyParent bean for defining new lookup strategies for arbitrary Spring bean settings

Examples (In Progress)

Signed Assertions vs. Responses

Enabling signed assertions is advisedly handled by turning on WantAssertionsSigned in metadata, but isn't always possible and sometimes has to be combined with disabling signed responses (or just for efficiency).

Disabling Encryption

Setting idp.encryption.optional is usually a workaround for handling the majority of SPs without encryption support, but there are a couple of scenarios in which it's useful to be able to manually disable it. Some federations (InCommon for one) have limitations such that SPs without encryption support are stuck registering keys they don't support. Some SPs support encryption but build in time-bombs by forcing flag day key rotations on all IdPs that cause outages or manual work.


There are metadata extensions that are meant to be used to signal algorithm support, but they're not widely used at this point. The most common scenario is to force SHA-1 for older systems.

Legacy Profiles

A common use case is enabling SAML 1 for legacy systems, often combined with either enabling queries or attribute push (to eliminate the queries).

NameID Format Exceptions

Using <NameIDFormat> elements in metadata (which can also be added at runtime with a filter) is the normal way to trigger them, but the "unspecified" Format has to be triggered with a profile setting. That's not common, but it's easy to define a tag for just in case. The problem is that any two SPs using it are only coincidentally going to want the same data, so this isn't solely a matter of format selection.

Bug Workarounds

Some of the other profile settings are workarounds for bugs, e.g., omitting the NotBefore attribute. Likely not very common but easily tag-driven. We could also supply basic scripts for driving things like additional Audience values so the script would run based on a tag but the values would still be local to the script.

Forcing MFA

Handling SPs that require MFA but can't request it requires IdP-side configuration.

Attribute Release Consent

Triggering consent based on the SP is pretty common.


The authorization checking flow is another case, though the checking condition would probably to be extended for each different service/scenario.

Not relying-party-driven, but a canonical case for using metadata tagging is to drive attribute release, occasionally via bundles a la R&S and also piecemeal. FIltering is ultimately going to perform proportional to the number of policies times their individual overhead, so if tag-based rules are sufficiently fast, a policy per attribute would ultimately match or exceed the approach of defining policies per service.

  • No labels