Entity Selection Profile entity attribute

Motivation

Federation operators have rules for entity registration to ensure a good user experience within that federation. These rules are typically published in a Metadata Registration Practice Statement. When we look at a wider ecosystem where multiple federation operators register SPs and IdPs, we need prioritization and selection rules. The rule that many people know about is the metadata combination rule in eduGAIN metadata aggregation, which enforces unique entityIDs.

However, unique entityIDs are not sufficient to provide a good user experience in an ecosystem. Accurate and complete metadata (such as DisplayName and logos) will help people select the appropriate IdP when logging in, although this still requires an individual to make the correct choice at login time. What if there was also a mechanism in metadata for an SP to describe which IdPs it would prefer to interoperate with? This Entity Selection Profile aims to provide that.

Building on earlier work from SeamlessAccess, we are developing a profile that can allow SPs to identify a set of IdPs, either by entityID or generically by registrationAuthority or entity attribute. They coined the term “trustinfo” although we’re realising it’s actually an entity selection profile.

The first step is to define an entity attribute as a container for transporting selection rules and profiles. This step focusses on the current SAML environment.

There is supporting material in the REFEDS wiki on the Working Group page [WG]

XML namespaces and prefixes

Conventional namespace prefixes are used

Definitions

The Entity Selection Profile is an entity attribute which contains filtering rules. These filtering rules allow SP owners and others to define selection rules for which IdPs to display in a discovery service.

The entity attribute has Name="https://refeds.org/entity-selection-profile" and NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"

Syntax

• The entity attribute is found in md:EntityDescriptor/md:Extensions/mdattr:EntityAttributes. We recognise that the Entity Attributes specification allows md:EntitiesDescriptor/md:Extensions/md:EntityAttributes elements, but we rule them out for operational and conceptual reasons.
• There is only one instance of an Entity Selection Profile entity attribute in an entity. Behaviour when more than one is present is not defined by this profile.
• Composition with other sources of filtering is not defined by this profile
• The value of the entity attribute is a JSON data structure that has been Base64 encoded [Base64]
• Any whitespace before, after or internal to the value must be ignored

Semantics

• The expected consumer of the entity attribute is a discovery service. Federation operators and entity operators are not expected to decode the value.
  
• Semantics of the decoded value are defined by the metadata consumer. 
• We recommend that null values, incorrectly encoded values or other errors are treated as if there was no filtering. We do not recommend that the whole entity metadata is considered invalid.
• If the decoded value does not conform to the requirements of the consumer, we recommend that the consumer assumes there is no filtering. We do not recommend that the entity metadata is considered invalid.

Registration criteria

• Any entity that has a SP role can register this entity attribute

Examples

This example contains JSON which explicitly defines profiles for filtering in SeamlessAccess

<mdattr:EntityAttributes>
  <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
    Name="https://refeds.org/entity-selection-profile">
    <saml:AttributeValue>
eyJwcm9maWxlcyI6eyJzd2FtaWQtb25seSI6eyJzdHJpY3QiOnRydWUsImVudGl0aWVzIjpbeyJzZWxl
Y3QiOiJodHRwOi8vd3d3LnN3YW1pZC5zZS8iLCJtYXRjaCI6InJlZ2lzdHJhdGlvbkF1dGhvcml0eSIs
ImluY2x1ZGUiOnRydWV9XX0sImVkdWdhaW4iOnsiZW50aXRpZXMiOlt7ImluY2x1ZGUiOmZhbHNlLCJt
YXRjaCI6InJlZ2lzdHJhdGlvbkF1dGhvcml0eSIsInNlbGVjdCI6Imh0dHBzOi8vb3BlbmF0aGVucy5u
ZXQifV0sInN0cmljdCI6IHRydWV9fX0=
    </saml:AttributeValue>
  </saml:Attribute>
</mdattr:EntityAttributes>

The filtering rule is {"profiles":{"swamid-only":{"strict":true,"entities":[{"select":"http://www.swamid.se/","match":"registrationAuthority","include":true}]},"edugain":{"entities":[{"include":false,"match":"registrationAuthority","select":"https://openathens.net"}],"strict": true}}}

This non-functional example has an entity attribute with no value

The metadata consumer should ignore the attribute and perform no filtering.

<mdattr:EntityAttributes>
  <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
    Name="https://refeds.org/entity-selection-profile">
    <saml:AttributeValue />
  </saml:Attribute>
</mdattr:EntityAttributes>

This non-functional example contains a space

The metadata consumer should ignore the attribute and perform no filtering.

<mdattr:EntityAttributes>
  <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
    Name="https://refeds.org/entity-selection-profile">
    <saml:AttributeValue> </saml:AttributeValue>
  </saml:Attribute>
</mdattr:EntityAttributes>

This non-functional example contains an incorrectly encoded value

The metadata consumer should ignore the attribute and perform no filtering.

<mdattr:EntityAttributes>
  <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
    Name="https://refeds.org/entity-selection-profile">
    <saml:AttributeValue>*</saml:AttributeValue>
  </saml:Attribute>
</mdattr:EntityAttributes>

Security considerations

to be determined

References

• SAML2Meta: OASIS Standard, Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0. March 2005. http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf.
• MetaAttr: SAML V2.0 Metadata Extension for Entity Attributes Version 1.0. Edited by Scott Cantor. 4 August 2009. OASIS Committee Specification. http://docs.oasis-open.org/security/saml/Post2.0/sstc-metadata-attr-cs-01.pdf.
  
• Base64: The Base16, Base32, and Base64 Data Encodings. RFC 4648. https://datatracker.ietf.org/doc/html/rfc4648
• WG: REFEDS wiki page for the working group. https://wiki.refeds.org/display/GROUPS/SeamlessAccess+Trustinfo+Metadata+Working+Group