3 Metadata Usage and Extensions

The UK federation publishes metadata describing participating entities. This metadata provides the information required for entities to know how to communicate with each other securely, and establishes a trust fabric permitting entities to verify each other’s identities.

The metadata published by the UK federation uses the SAML 2.0 metadata format defined in [SAML2Meta]. This standard leaves the meaning of some constructs undefined to allow flexibility, and allows extensions to the format to be defined to meet new requirements. This document specifies the UK federation’s particular uses of the standardised constructs, and documents the extensions to the standards which are used in the federation’s published metadata.

3.1 Local and Imported Metadata

Entity metadata published by the UK federation may have been acquired through the following routes:

• Entities registered with the UK federation operator acting as a metadata registrar are referred to here as local entities, and the metadata describing them as local metadata. Only federation members are eligible to register entities in this way.

• Entities whose metadata has been registered by some other originating registrar and acquired by the UK federation operator in other ways, such as through inter-federation metadata exchange agreements with federation partners, are referred to here as imported entities; the metadata describing them is imported metadata.

Different processing is applied to local and imported metadata, resulting in different guarantees to metadata consumers in each case. These differences will be highlighted where appropriate in subsequent sections.

The selection process for federation partners, along with the agreements reached with those partners and the processing performed before imported metadata is published to UK federation consumers, is intended to provide a comparable level of technical trust in imported metadata as for local metadata. Note, however, that in general the owners of the entities represented by imported metadata are bound only by the behavioural agreements they have made with the originating registrar, and not by the UK federation Rules of Membership. As a result, presence in the federation metadata alone should not be taken to imply particular behavioural guarantees.

3.2 Registration and Publication Extension

The SAML V2.0 Metadata Extensions for Registration and Publication Information are defined in [SAML-Metadata-RPI-V1.0], and consist of elements in a namespace given the conventional namespace prefix of “mdrpi”.

3.2.1 <mdrpi:PublicationInfo> Element

Every metadata aggregate published by the UK federation (see section 4, “Metadata Publication Service”, below) has a document element with a child <Extensions> element which in turn contains an <mdrpi:PublicationInfo> element with the following attributes:

• A creationInstant attribute containing a timestamp indicating when the document was constructed ready for signature and publication.

• A publisher attribute with the value “http://ukfederation.org.uk”, the “federation URI”.

For example:

<mdrpi:PublicationInfo creationInstant="2013-03-15T17:10:03Z"
     publisher="http://ukfederation.org.uk"/>

3.2.2 <mdrpi:RegistrationInfo> Element

Every <EntityDescriptor> in metadata published by the UK federation contains a child <Extensions> element which in turn contains an <mdrpi:RegistrationInfo> element.

For local entities, the <mdrpi:RegistrationInfo> element will always possess a registrationAuthority attribute with the value “http://ukfederation.org.uk”. It MAY also possess a registrationInstant attribute containing a timestamp indicating when the metadata for the entity was registered with the UK federation. Note that particularly significant changes to an already registered entity’s metadata may result in a fresh registrationInstant timestamp being recorded.

For example:

<mdrpi:RegistrationInfo
    registrationAuthority="http://ukfederation.org.uk"
    registrationInstant="2012-11-16T10:06:35Z"/>

For imported entities, the <mdrpi:RegistrationInfo> element will always possess a registrationAuthority attribute with a value other than that used for local entities. This value will always be a reliable indicator of the originating registrar, such as the entity’s home federation. This reliability will be achieved by mechanisms such as validating imported registrationAuthority attribute values against the source of imported metadata.

For registrars representing eduGAIN participant federations, the registrationAuthority value used will normally be that listed on the eduGAIN technical status page.

Note that the registrationAuthority values used will usually be the same as the value chosen by a registrar to refer to itself, but may be different in exceptional circumstances. For example:

• Some registrars have not yet chosen a registrationAuthority value by which to identify themselves in metadata; in this case, a provisional value may be selected by the UK federation.

• If a registrar makes an abrupt change to its selected registrationAuthority value, the UK federation may choose to map this to the old value temporarily in order to provide adequate notice to UK federation metadata consumers.

The <mdrpi:RegistrationInfo> element for an imported entity MAY contain additional attributes and elements included by the originating registrar as a result of their own registration practices.

3.3 Login and Discovery User Interface Extensions

The SAML V2.0 Metadata Extensions for Login and Discovery User Interface are defined in [SAML-Metadata-UI-V1.0], and consist of elements in a namespace given the conventional namespace prefix of “mdui”.

Entities registered with the UK federation may be given <mdui:UIInfo> and <mdui:DiscoHints> elements by agreement between the registrar and the entity owner. Because of the relationship between <mdui:DisplayName> and <OrganizationDisplayName> highlighted in [SAML-Metadata-UI-V1.0] section 2.4.1, particular care is given to consistency between the different mechanisms.

At present, registration of <mdui:Keywords> elements is NOT RECOMMENDED by the UK federation. This situation may change should a controlled vocabulary for this element’s values be standardised.

Imported metadata may contain elements in the mdui namespace as determined by the originating registrar’s registration practices. In particular, note that:

• Imported entities are not guaranteed to have mdui metadata at all.

• Several of the mdui elements are tagged with a language. English is normal within local metadata, but imported metadata may include other languages, and an English variant is not guaranteed.

3.4 SAML 1 Support

UK federation metadata supports entities supporting any combination of SAML 2.0 and SAML 1 profiles. Entities supporting SAML 1 are described in metadata based on [SAML1Meta-xsd] and [SAML1Meta], with additions defined in [ShibProt] section 3.4.

3.5 SAML 2.0 Metadata Extensions for Shibboleth

The SAML V2.0 Metadata Extensions for Shibboleth are defined in [ShibMetaExt], and consist of elements in a namespace given the conventional namespace prefix of “shibmd”.

3.5.1 <shibmd:KeyAuthority> Element

The UK federation’s production, test and fallback aggregates originally included <shibmd:KeyAuthority> elements within an <Extension> element child of each document’s <EntitiesDescriptor> element to support credential validation using a PKIX-based scheme.

Support for PKIX-based credential validation was removed from UK federation metadata during June 2014, and the corresponding <shibmd:KeyAuthority> elements were removed from the last aggregate during February 2015.

3.5.2 <shibmd:Scope> Element

To allow for the automatic validation of the scope portion of scoped attribute values (see [eduPerson20] section 1.3), UK federation metadata supports the inclusion of <shibmd:Scope> elements in the metadata for identity provider entities. It is RECOMMENDED that service providers validate the scope portion of any scoped attribute values sent to them (in particular, values of eduPersonScopedAffiliation and eduPersonPrincipalName) against the scopes present in the issuing identity provider’s metadata. Scoped attribute values containing scopes not included in the identity provider’s metadata SHOULD be discarded.

<shibmd:Scope> elements may appear in three locations:

• Within the <Extensions> element of an <IDPSSODescriptor>, in which case they should be regarded as valid scopes for attributes sent by the identity provider through front-channel bindings or using the Browser/Artifact profile,

• Within the <Extensions> element of an <AttributeAuthorityDescriptor>, in which case they should be regarded as valid scopes for attributes returned as the result of attribute queries,

• Within the <Extensions> element of the <EntityDescriptor>, in which case they should be regarded as valid scopes for attributes sent to the service provider through either of the above mechanisms. This use of <shibmd:Scope> is deprecated, see below.

All identity providers registered with the UK federation MUST possess at least one valid scope. The federation’s registration and publication procedures ensure that an identical collection of <shibmd:Scope> elements will be present in the <Extensions> elements of a local identity provider’s <EntityDescriptor>, <IDPSSODescriptor> and, where present, <AttributeAuthorityDescriptor>.

The metadata exported to federation partners for an identity provider registered with the UK federation does not include <shibmd:Scope> elements in the <Extensions> elements of the entity’s <EntityDescriptor>.

The presence and location of <shibmd:Scope> elements in the metadata for an imported identity provider is dependent on the originating registrar’s registration practices. In particular, note that:

• Although unusual, it is possible that an imported identity provider’s metadata will not include any <shibmd:Scope> elements. As a consequence of the general rule given above that scoped attribute values containing scopes not included in the identity provider’s metadata SHOULD be discarded, such an entity will be unable to assert any scoped attributes.

• Registrars other than the UK federation do not provide <shibmd:Scope> elements at the <EntityDescriptor> level.

All <shibmd:Scope> elements in metadata published by the UK federation will include an explicit regexp attribute, to avoid digital signature verification issues. Most entities are expected to use scopes with regexp="false". However, both local and imported metadata MAY use regexp="true", with the restriction that any regular expression scope must (alongside other rules):

• end with an escaped literal dot ('\.'),
• followed by a “literal tail”, which must:
  • consist of at least two domain labels (e.g., “example”, “edu”) separated by escaped literal dots ('\.'),
  • which when the encoded dots are decoded represents a domain name under a “public suffix” such as ac.uk or com listed in the public suffix list,
• followed by a '$' anchor.

This allows regular expressions of the general form “.*\.example\.ac\.uk$” to be accepted; this regular expression will match either of the following:

• a.example.ac.uk
• a.b.example.ac.uk

The example regular expression will not, however, match example.ac.uk alone.

The following regular expression scopes would not be accepted either for local or imported metadata:

• .*.example.ac.uk$: literal dots are not escaped
• .*\.example\.ac\.uk: trailing anchor missing
• .*\.ac\.uk$: ac.uk is not below a public suffix; i.e., is not a registrable domain
• .*\.example\.local$: local is not a public suffix

The UK federation’s convention is that scopes are named by DNS domain names, expressed in lower case. Entity owners registering metadata containing <shibmd:Scope> elements MUST demonstrate that each domain used is either owned by them, or that specific permission has been given to them to use the domain for the purpose of registering the entity. Federation partners are required to have broadly similar registration practices around the domain names registrants are permitted to use in <shibmd:Scope> elements.

3.6 UK Federation Label Namespace

The following XML namespace is defined for use in UK federation metadata:

http://ukfederation.org.uk/2006/11/label

The conventional prefix used for this namespace is “ukfedlabel”.

All elements defined in this namespace will take the form of simple labels which are either present or absent in a particular context. Labels may be either XML elements (with or without attributes) or simple attributes.

An XML Schema document describing the label namespace is available through the federation helpdesk. Only those elements of this namespace which appear in metadata published by the UK federation are described here.

Note that although the identifier for the label namespace contains its date of definition, additional elements may be added to this namespace at any time.

3.6.1 UK Federation Member Label

If an entity is owned by a member in good standing of the UK federation, the following element will be added to the <Extensions> element of the entity’s <EntityDescriptor> element:

<ukfedlabel:UKFederationMember/>

The presence of this element indicates that the owner of the entity has agreed to be bound by the UK federation’s Rules of Membership [UKROM].

The <ukfedlabel:UKFederationMember> extension will only ever appear on local metadata; it will never appear in the metadata for imported entities. It is not included in the metadata exported to federation partners.

3.6.2 Accountable Users Label

The UK federation’s Rules of Membership allow for a member to assert to the federation operator that a given identity provider entity provides for user accountability (see [UKROM] section 6.1). A member making such an assertion must comply with all the requirements of section 6 of the Rules.

If such an assertion has been made to the federation operator in respect of an entity, the following element will be added to the <Extensions> element of that entity’s <EntityDescriptor> element:

<ukfedlabel:AccountableUsers/>

Note that the assertion of user accountability is made by the federation member alone; it is not verified by the federation operator.

The <ukfedlabel:AccountableUsers> extension will only ever appear on local metadata; it will never appear in the metadata for imported entities. It is not currently included in the metadata exported to federation partners.

3.7 SDSS Federation WAYF Namespace

Until November 2015, UK federation metadata made use of the following XML namespace originally defined by the SDSS federation:

http://sdss.ac.uk/2006/06/WAYF

The conventional prefix used for this namespace was “wayf”.

This namespace was used solely to label identity provider entities in order to hide them from the normal (filtered) federation central discovery service, previously the “Where Are You From” (WAYF) service. This was done by adding the following element to the <EntityDescriptor>’s <Extensions> element:

<wayf:HideFromWAYF/>

The use of this element has been replaced by an entity category, using the mechanism described in [RFC8409] and [MetaAttr].

3.8 <EntityDescriptor> Element

3.8.1 entityID Attribute

Values of the entityID attribute for entities registered with the UK federation MUST be an absolute URI using either the http, https or urn schemes. https-scheme URIs are RECOMMENDED.

http-scheme and https-scheme URIs used for entityID values MUST contain a host part whose value is a DNS domain. The registrant MUST demonstrate that the domain used is either owned by them, or that specific permission has been given to them to use the domain for the purpose of registering the entity.

The use of urn-scheme URIs for entityID values is NOT RECOMMENDED but will be permitted in exceptional circumstances. When permitted, such values MUST be part of a properly delegated registry under the urn:mace namespace, as described in [RFC3613]. The registrant MUST also demonstrate that the urn:mace URI value in question has been issued for their use.

The entityID attributes of an imported entity MUST be an absolute URI using either the http, https or urn scheme. urn-scheme URIs are further constrained to the urn:mace namespace as described in [RFC3613]. Federation partners are required to have broadly similar registration practices around the domain names registrants are permitted to use in http-scheme and https-scheme URIs used as entityID values.

When a particular entityID value has been registered with the UK federation, the local metadata will always take precedence over metadata from any other source. When an entityID value has not been locally registered, but has been registered with more than one federation partner, the conflict will be resolved at the UK federation operator’s discretion.

No attempt will be made to resolve conflicts of this kind by merging metadata for a particular entityID value from more than one source; this preserves the integrity of the registrationAuthority attribute included in the published entity’s <mdrpi:RegistrationInfo> element.

3.8.2 ID Attribute

Each <EntityDescriptor> element registered with the UK federation is given a unique ID attribute, formed by concatenating the two letters “uk” and six decimal digits, such as “uk000123”. This attribute value is used as a name for the individual <EntityDescriptor> by the federation operator as part of the operational procedures of the federation metadata registrar.

During the transition from the SDSS federation to the UK federation, it was always the case that:

• Entities which appeared in both the SDSS federation metadata and the UK federation metadata had ID attribute values of uk000199 or lower.

• Entities which only appeared in the UK federation metadata had ID attribute values of uk000200 or higher.

This numerical convention will not necessarily be observed in the future, although present practice is to give all new entities ID attribute values of uk000200 or higher.

Imported metadata will never include an ID attribute; any ID attribute assigned to an entity by its originating registrar is removed before re-publication in UK federation metadata. This action prevents collisions between entity metadata acquired from multiple sources from rendering the resulting XML invalid.

3.9 <Organization> Element

The contents of the <Organization> element in metadata for imported entities is entirely determined by the originating registrar’s registration practices. In particular, note that:

• Imported entities are not guaranteed to have an <Organization> element at all.

• Several of the elements within <Organization> are tagged with a language. English is normal within local metadata, but imported metadata may include other languages, and an English variant is not guaranteed.

The remainder of this section discusses the <Organization> element conventions in metadata for local entities.

The SAML 2.0 Metadata specification defines the <Organization> element as specifying “basic information about an organization responsible for a SAML entity or role” ([SAML2Meta], section 2.3.2.1). Its mandatory child elements are:

• <OrganizationName>, containing a name that “may or may not be suitable for human consumption”

• <OrganizationDisplayName>, containing a name “suitable for human consumption”

• <OrganizationURL>, containing a URL specifying “a location to which to direct a user for additional information”.

Many SAML federations make use of <OrganizationDisplayName> as a convenient location from which to draw a string identifying a particular identity provider. This string is used when selection from a list of identity providers is required: for example this might be done at a central discovery service, often known as a WAYF (“Where Are You From”) service.

This convention is unremarkable in an environment where a one-to-one mapping exists between organisations and identity providers, so that the organisation “responsible for” the SAML entity is the same (singular) organisation for which the identity provider speaks. Because the UK federation allows both outsourcing and aggregated identity provision, different conventions are adopted for entities registered with the UK federation.

Firstly, all local entities are provided with an <Organization> element in which the <OrganizationName> contains a string representing the UK federation’s canonical name for the member organisation responsible for the entity. This will normally be the organisation’s legal name, as taken for example from the organisation’s constitution or from Companies House records.

Secondly, the <OrganizationDisplayName> contains a string describing the function of the particular entity, and the <OrganizationURL> contains a URL leading to more information as appropriate to the entity’s function.

For an identity provider entity:

• The <OrganizationDisplayName> contains the string by which the identity provider is to be known by discovery services.

  • In the case of identity providers representing a single member organisation, this will normally be a simplified form of the canonical name of that member organisation, selected by the federation operator to provide users of discovery services with a coherent selection.

  • In the case of an aggregated identity provider representing multiple member organisations, the <OrganizationDisplayName> will be chosen by the federation operator to represent the combined identity community.

• The <OrganizationURL> contains a URL leading to either more information about the organisation responsible for the entity, or more information about the identity community served by the entity.

For a service provider entity:

• The <OrganizationDisplayName> will be descriptive of the particular service provided. This MAY include a component representing the organisation offering the particular service.

• The <OrganizationURL> contains a URL leading to either more information about the organisation responsible for the entity, or more information about the service provided by the entity.

In the case where member organisation A entrusts the operation of one of its entities to a second member organisation B (or, alternatively, where A purchases services from B):

• The <OrganizationName> will refer to member B.

• The <OrganizationDisplayName> will refer to member A.

• The <OrganizationURL> will refer to either A or B, as appropriate in the particular case.

3.10 <KeyDescriptor> Element

Each <IDPSSODescriptor>, <SPSSODescriptor> and <AttributeAuthorityDescriptor> role descriptor appearing in metadata published by the UK federation SHALL contain at least one <KeyDescriptor> element. These should be interpreted as described in section 2, “Trust Fabric”, above.

In roles which indicate support through their protocolSupportEnumeration values for SAML 2.0 or SAML 1.1 profiles, each <KeyDescriptor> MUST support the direct key verification scheme as described in section 2.1.1.

RSA public keys embedded in UK federation metadata MUST have a modulus whose length is at least 2048 bits. Public keys with a modulus whose length is more than 2048 bits are NOT RECOMMENDED.

The public exponent of an RSA public key embedded in UK federation metadata MUST be at least 5. A public exponent of 65537 is RECOMMENDED.

All <IDPSSODescriptor> and <AttributeAuthorityDescriptor> role descriptors MUST include at least one <KeyDescriptor> suitable for signing use (with use="signing" or absent).

All <SPSSODescriptor> role descriptors supporting SAML 2.0 profiles MUST include at least one <KeyDescriptor> suitable for encryption use (with use="encryption" or absent).

<ds:KeyName> elements SHALL NOT appear in metadata published by the UK federation:

• Any <ds:KeyName> elements in imported metadata are removed before republication, as they may refer to trust roots recognised by the originating registrar but not present in the UK federation trust fabric.

• <ds:KeyName> elements SHALL NOT be accepted in locally registered metadata.

Documents

• Current TRP (1.6)
• Current FTS (1.6)
• Current MDRPS (20130902)

Resources

• Federation Site
• About This Site