EntityMatcher

The EntityMatcher plugin interface is used in various places inside other SP components that have to decide whether operate on an IdP based on its metadata.

For example, the <RelyingParty> element allows configuration options to be selectively applied to "matching" IdPs. This interface makes the evaluation process extensible instead of limiting it to specific criteria.

Unlike many of the plugin types supported by the SP, there is no specific XML element that is normally used to load an EntityMatcher. Rather, other plugin types rely on this mechanism and include the configuration content identified below based on the type of EntityMatcher plugin used. There is typically, but not always, a matcher attribute used to specify the type of plugin.

1 Name EntityMatcher
- 1.1 Attribute
- 1.2 Example
  - 1.2.1 Example use of Name EntityMatcher
2 EntityAttributes EntityMatcher
- 2.1 Attributes
- 2.2 Child Elements
- 2.3 Example - TBD
3 RegistrationAuthority EntityMatcher
- 3.1 Attributes
- 3.2 Child Elements
- 3.3 Example
  - 3.3.1 Example use of RegistrationAuthority EntityMatcher in a MetadataFilter

Name EntityMatcher

Matches an IdP based on its entityID or the name of an enclosing <md:EntitiesDescriptor> element in its metadata, informally referred to as a "group" name.

Be advised that relying on group names is often unreliable when including metadata from multiple, independent sources unless you have confidence that group names won't overlap. They are mostly designed for use with locally-prepared metadata.

Attribute

Name	Type	Default	Description

Name	Type	Default	Description
Name	string		Specifies the entityID or <md:EntitiesDescriptor>/@Name to match against. Matching is exact and case sensitive.

Example

Example use of Name EntityMatcher

<RelyingParty Name="https://idp.example.org/idp/shibboleth">

EntityAttributes EntityMatcher

Matches an IdP based on the presence of matching <saml:Attribute> elements inside a <md:EntityAttributes> extension in its metadata, or the metadata of its parent <md:EntitiesDescriptor> element(s). This plugin implements so-called "tag" matching, which is more flexible than a group-based approach that relies on hierarchical containment in a file.

The matching criteria for the plugin are expressed as a set of <saml:Attribute> elements (or a shorthand for specifiying a single attribute value to check for). Each element contains a set of values. All of the values specified must be found in an extension attribute in the metadata for a match to succeed, but a single such match is sufficient.

That is, the <saml:AttributeValue> elements within a <saml:Attribute> form an "AND" criterion, but separate <saml:Attribute> elements form an "OR" criterion.

Attributes

Name	Type	Default	Description

Name	Type	Default	Description
trimTags	boolean	false	When true, values found in the metadata are trimmed of leading or trailing whitespace before a direct comparison.
attributeName	string		Specifies the Name of a <saml:Attribute> tag to match on. Used as a shorthand syntax when matching against a single tag and value.
attributeNameFormat	string		Specifies the NameFormat of a <saml:Attribute> tag to match on. Used as a shorthand syntax when matching against a single tag and value. When absent, or set to the "unspecified" format, any NameFormat is considered a match if the Name matches the attributeName property.
attributeValue	string		Specifies a <saml:AttributeValue> to match on. Used as a shorthand syntax when matching against a single tag and value.
attributeValueRegex	regex		Specifies an expression to apply while searching <saml:AttributeValue> elements to match on. Used as a shorthand syntax when matching against a single tag and value.

Child Elements

Name	Cardinality		Description

Name	Cardinality		Description
<saml:Attribute>	1 or more (absent shorthand)		Identifies a <saml:Attribute> tag to match on. Contains one or more <saml:AttributeValue> elements containing values or regular expressions to match with. To use a regular expression, add a regex="true" XML attribute to the <saml:AttributeValue> element.

Example - TBD

RegistrationAuthority EntityMatcher

Matches an IdP based on the presence of a matching registrationAuthority attribute inside an <mdrpi:RegistrationInfo> extension in its metadata, or the metadata of its parent <md:EntitiesDescriptor>element(s).

Attributes

Name	Type	Default	Description

Name	Type	Default	Description
registrationAuthority	string		Specifies an authority to match. Used as a shorthand syntax when matching against a single value.

Child Elements

Name	Cardinality		Description

Name	Cardinality		Description
<registrationAuthority>	1 or more (absent shorthand)		Specifies an authority to match. Used as a shorthand syntax when matching against a single value.

Example

Example use of RegistrationAuthority EntityMatcher in a MetadataFilter

Load only metadata entities published by the registration authorities of the DFN-AAI or ACOnet federations . All others get ignored.

<MetadataFilter type="Include" matcher="RegistrationAuthority">
  <registrationAuthority>https://www.aai.dfn.de</registrationAuthority>
  <registrationAuthority>http://eduid.at</registrationAuthority>
</MetadataFilter>