Version history

  • Draft 0.1

Supporting Material

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.

Approach

  • Draft 0.1 is our first working document.
  • Draft 0.2 will define the entity attribute as a Base64-encoded JSON data structure, and define semantics of a core set of names within that data structure. It is intended that this version will allow federation operators to test the entity attribute.
  • Subsequent 0.x drafts will add composition rules.
  • All draft versions of the specification will be hosted in the REFEDS wiki. The wiki has versioning enabled, which allows specific drafts to have stable references.
  • During community consultation, we will generate a PDF with line numbers to help people wishing to offer feedback. 
  • Version 1.0 is anticipated to be the first fully-specified profile. It will be produced as a PDF and recorded on zenodo.org. For easier access, a web friendly version will be published on the refeds website at https://refeds.org/entity-selection-profile.

XML namespaces and prefixes

Conventional namespace prefixes are used

PrefixXML NamespaceReferences
md:urn:oasis:names:tc:SAML:2.0:metadata SAML2Meta
mdattr:urn:oasis:names:tc:SAML:metadata:attributes MetaAttr



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 (such as SeamlessAccess button) is not defined by this profile
  • The value of the entity attribute is a JSON data structure that has been Base64 encoded
  • 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, not that the whole entity metadata is invalid.

If the decoded value does not conform to the requirements of the consumer, we recommend that the consumer assumes there is no filtering, not consider the entity metadata invalid.

Registration criteria

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

Examples

This example has an entity attribute with no value

<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 example contains a space

<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 example contains an incorrectly encoded value

<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 example contains JSON which explicitly defines the filtering rule

<mdattr:EntityAttributes>
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
Name="https://refeds.org/entity-selection-profile">
<saml:AttributeValue>eyJwcm9maWxlcyI6eyJzd2FtaWQtb25seSI6eyJzdHJpY3QiOnRydWUsImVudGl0aWVzIjpbeyJzZWxlY3QiOiJodHRwOi8vd3d3LnN3YW1pZC5zZS8iLCJtYXRjaCI6InJlZ2lzdHJhdGlvbkF1dGhvcml0eSIsImluY2x1ZGUiOnRydWV9XX0sInN3YW1pZC1lZHVnYWluIjp7InN0cmljdCI6dHJ1ZSwiZW50aXRpZXMiOlt7InNlbGVjdCI6ImZpbGU6Ly8vb3B0L3B5ZmYvbWV0YWRhdGEvb3BlbmF0aGVucy54bWwiLCJtYXRjaCI6Im1kX3NvdXJjZSIsImluY2x1ZGUiOmZhbHNlfV19fX0=</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}]},"swamid-edugain":{"strict":true,"entities":[{"select":"file:///opt/pyff/metadata/openathens.xml","match":"md_source","include":false}]}}}

Security considerations

to be determined

References

  • SAM2Meta: 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


  • No labels