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:

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:

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.1

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:

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 supported 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:

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 include a <shibmd:KeyAuthority> element within an <Extension> element child of the document <EntitiesDescriptor> element. Although no longer required to support credential validation using the PKIX scheme, a dummy trust root is included to cover an implementation error in certain legacy software; we expect to remove the <shibmd:KeyAuthority> elements by the end of 2014.

The export and export preview aggregates do not include a <shibmd:KeyAuthority> element.

3.5.2 <shibmd:Scope> Element

To allow for the automatic validation of the scope portion of scoped attribute values (see [eduPerson12] 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:

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:

All <shibmd:Scope> elements in metadata published by the UK federation will include an explicit regexp attribute,to avoid digital signature verification issues. Entities registered with the UK federation will only be permitted to use regexp="true" in exceptional circumstances. Imported metadata MUST NOT use regexp="true".

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 currently 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

UK federation metadata currently makes use of an XML namespace originally defined by the SDSS federation:

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

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

This namespace is 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 is done by adding the following element to the <EntityDescriptor>’s <Extensions> element:

<wayf:HideFromWAYF/>

The different central discovery services are described in section 5, below.

The <wayf:HideFromWAYF> extension is included in metadata for local entities by agreement between the federation operator and the entity owner. In general, this treatment is appropriate for identity providers used for testing, or not yet ready for production use.

The <wayf:HideFromWAYF> extension is currently included in metadata for all imported entities. It is not currently included in the metadata exported to federation partners.

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:

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:

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:

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:

For a service provider 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):

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.2

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:

3.11 Future Directions

3.11.1 SDSS Federation WAYF Namespace

The use of the SDSS federation WAYF namespace will be discontinued at some point. The SDSS-defined <wayf:HideFromWAYF> marker element will be replaced by an entity category, using the mechanism described in [EntityCat] and [MetaAttr].

3.11.2 <shibmd:KeyAuthority> Element

Now that the transition to a non-PKIX trust fabric has been completed, the inclusion of a <shibmd:KeyAuthority> element in published aggregates is no longer required. This element is therefore expected to be removed from all aggregates before the end of calendar year 2014.

3.11.3 <shibmd:Scope> Element

Use of the regexp="true" attribute is under consideration for aggregated identity providers such as those used in the UK schools sector. Initial experiments will be restricted to aggregation of the so-called “synthetic” scopes allocated by the UK federation operator to local authorities on behalf of their schools. If successful, this would result in a reduction in the size of UK federation metadata aggregates and in the amount of maintenance required for the metadata associated with schools sector identity providers.

More general use of regexp="true" is not expected to be viable due to concerns about its potential misuse, whether intentional or accidental.

  1. See http://www.edugain.org/technical/status.php 

  2. Keys with a modulus longer than 2048 bits are not believed to provide any additional practical security over 2048-bit keys, while making cryptographic operations using the longer keys more expensive for both parties.