Participation in eduGAIN

The eduGAIN service enables SAML metadata exchange between partner federations. The UK federation joined eduGAIN in 2013, and you can find federations participating in the eduGAIN system listed here.

The UK federation implements a policy of exporting all entities to eduGAIN (with some exceptions). This document explains the implications for UK federation members, and gives instructions for how to opt-out of eduGAIN participation.

We RECOMMEND that you follow good practice for your entity's registered metadata. Please take time to review our recommendations listed below, or contact the helpdesk team for assistance.

Metadata exchange

For two SAML entities to communicate, each needs to have access to trustworthy metadata about the other. From the perspective of each entity, this involves providing metadata about itself to its partner and receiving equivalent metadata about its partner in exchange.

Direct bilateral metadata exchanges are the most obvious way in which two entities can exchange metadata, but this scales badly because it means you have to give your metadata to each and every partner you are interested in communicating with. Large-scale federation is therefore based on mediated exchange of metadata between entities, in which federation operators act as brokers.

In the UK federation, for example, each entity's metadata is registered once with the federation operator. Aggregated metadata for all registered entities is published by the federation operator so that it can be consumed by all participating entities. This means that each entity only exchanges metadata with the federation operator, but gains the same benefit as if it had exchanged metadata with each participant. This is obviously a much more effective approach at the scale of groups such as the UK federation, which involve hundreds or thousands of entities.

Interfederation metadata exchange

One of the limitations of simple metadata exchange brokered by federations, as described above, is that it only works for two entities registered in the same federation. Pre-eduGAIN, the most common approach to communication across federation boundaries had been for an entity owner to join each of the individual federations involved, in order to be able to register the entity's metadata with each. It is also normally necessary for the entity to be configured to consume multiple metadata sources (one from each federation), in order to receive all of the required partners' metadata.

This approach again raises the cost and effort of making connections to new partners: multiple federation agreements may need to be signed (in many cases, in more than one legal jurisdiction); multiple metadata registrations need to be made and kept up to date as entity metadata changes; and configuration complexity is increased.

How eduGAIN works

Interfederation metadata exchange is an approach which avoids the overhead of operating in a multi-federation environment. Instead of requiring each entity to be separately registered with each federation, an entity is registered with a single "home federation". A home federation may be one that makes the most sense geographically, one you are already a member of, or one that best meets your requirements in terms of ease of membership. (For most readers of this document, the home federation is the UK federation.)

The partner federations then exchange metadata between themselves and re-publish that metadata to their own members. The eduGAIN service is the mechanism by which this is achieved:

  • Each participating federation produces an "export metadata aggregate", comprising the metadata of entities chosen to be exported.
  • The export metadata aggregates produced by the participating federations are all consumed by eduGAIN, which from them generates an "eduGAIN aggregate"—the aggregate of all the federation export aggregates.
  • The eduGAIN aggregate is made available for consumption by each participating federation.

Each federation decides which entities to "export", and which entities within the eduGAIN aggregate to accept as "imports" from its partners. With respect to the UK federation:

  • entities being considered for inclusion in the export aggregate are required to meet some basic conditions.
  • entities imported, via the eduGAIN aggregate, into the UK federation are checked for conformance to federation standards and if satisfactory are re-published in the UK federation's aggregate, which is consumed by UK federation entities.

The result is that, once again, an entity only exchanges metadata with its home federation operator but gains the same benefit as it would from exchanging metadata with every participating entity, whether from its own home federation or received by its home federation, via eduGAIN, from one of its federation partners.

This combination of import and export—referred to as interfederation metadata exchange—means that participating entities can obtain trustworthy metadata for their partners in other federations without having to join those federations and configure multiple sources of metadata. Another way of looking at this is that, by exchanging metadata, partner federations are expanding the pool of trusted metadata available to members of each federation. Although this is unlikely ever to become a truly universal system, it is expected to grow into a global pool of entity metadata available to members of all participating federations: registration with a single federation should be sufficient for many entities.

UK federation entity participation in eduGAIN

Since the UK federation moved to full participation as part of the eduGAIN system in December 2013, we have operated on an "opt out" basis: entities registered with the UK federation are exported to other eduGAIN participants by default, but can be explicitly opted out by their owners.

Acceptance in eduGAIN means that your entity's metadata is included in the UK federation's export aggregate. This export aggregate is described in the UK federation Federation Technical Specifications.

The UK federation operates an "opt out" regime. This means that all entities registered with the UK federation will be exported to other eduGAIN participants by default, with the following exceptions:

  • Identity provider entities that do not support the SAML 2.0 protocol,
  • Schools sector aggregated identity provider entities,
  • Identity provider entities using "wildcard" scopes.

If your entity will be excluded from participation in eduGAIN for one of the above reasons, but you want it to be included, please contact the federation helpdesk at service@ukfederation.org.uk and request that the entity be "explicitly opted in" to interfederation.

How to opt-out of participation in eduGAIN

We believe that it is in the long term interests of the owners of all other entities that they are included in the eduGAIN system. However, this may not apply in the short term for a limited number of entities. If you believe that one of your entities should *not* be exported to eduGAIN, either now or in the future, the administrative contact for the entity (or management contact for the organization) must contact the federation helpdesk to request that the entity be "explicitly opted out" from interfederation. You can opt-out at any time.

Please note that your entity will still consume metadata from imported entities through the UK federation aggregate.

Metadata considerations

Acceptance in eduGAIN does not necessarily mean that your metadata will be available to members of other federations, as those federations may have particular technical requirements. For example, the Edugate federation is based solely on the SAML 2.0 protocol, so that entities running old SAML 1.1-only software (such as Shibboleth 1.3) will not be compatible.

Once your UK federation entity is included in the export aggregate, if the entity already consumes metadata from multiple federations you need to ensure that you will be testing against the imported version of an entity's metadata rather than a version collected from its home federation directly. The simplest way to do this is to remove all metadata sources other than the standard UK federation aggregate. If you can't do that, one approach is to re-order metadata sources in your entity's configuration such that the UK federation aggregate comes first. Another approach is to apply blacklisting to selected entities in the other metadata sources, to ensure that the correct version of the metadata takes precedence.

Next, you need to locate specific partner entities with which to test. You can look in the aggregate document to see an up-to-date list of the available imported entities.

If you are already in contact with the owner of the test target, you should make use of that to get things working. If you don't already have such a relationship, the UK federation helpdesk may be able to assist by arranging an introduction.

We note that even metadata exchange is not the only consideration for interoperation. It requires agreement over attributes exchanged and in many cases a contractual relationship as well.

Attribute release to imported entities

The UK federation integrates with eduGAIN by importing entities directly into the UK federation metadata aggregate. Each entity has a registrationAuthority value to indicate which federation it was originally registered in; the UK federation's is http://ukfederation.org.uk/.

The Registration Authority Configuration page, under Attribute Filter Policy configuration on the Shibboleth Wiki, describes how an IdP operator can configure attribute release based on the registrationAuthority value.

A list of the federations participating in eduGAIN and their registrationAuthority values is maintained on the eduGAIN technical status page.

How does Discovery work with multiple federations?

If your entity is a service provider, you need to extend your discovery strategy to handle identity providers from multiple federations. If you already have a custom local discovery service or WAYF, this should be straightforward.

If you are running a supported version of the Shibboleth service provider software, we recommend that you consider deploying its Embedded Discovery Service (EDS) capability. This provides a local discovery service which will automatically present any identity providers for which metadata is available, and which therefore works equally well in single-federation and multi-federation cases.

Another facility available to Shibboleth deployers that can be particularly useful in testing is to make use of a Session Initiator at the service provider: passing an entityID parameter when invoking a session initiator is a simple way of establishing a session with a particular identity provider without requiring a full discovery user interface.

If you are currently offloading discovery to a third party, your users will be able to select the imported IdPs directly from that Service. However, we recommend that you look into performing local discovery instead as that will give your users the best experience in the long term.

If you need advice about your approach to discovery, please contact the UK federation helpdesk.

Good practices in entity metadata

Much good practice is already enforced by the UK federation metadata registration procedure. However there are a few areas where we recommend practices but do not enforce them. In an interfederated operating environment, these practices are more important since you will not usually have access to the remote federation operator or entity operator.

The good practices are:

Assistance

Please contact the UK federation helpdesk if you need more information or assistance.