How to Build a Federation

Shibboleth federations provide a scaleable infrastructure to help providers discover each other, identify each other, and understand the information they share. They are not necessary to run Shibboleth in a production environment, but they can simplify things greatly. This document provides some advice on how to move from a skeletal deployment to a full-fledged federation.

Before you start, check that there is no pre-existing federation that meets your needs. If there is, it would be simpler to join that federation and leverage the work they've already done.

This guide could be used to make an intra-campus SSO system, to provide federated access amongst a community, or both. Shibboleth generalizes these into the same problem.

Create the Metadata
The Discovery Problem & WAYF
Configure the Providers
Create the Policy
Create the Attributes

1. Create the Metadata

Metadata provides the basis for all trust between providers in Shibboleth. The metadata doesn't configure the provider itself, but is used instead to identify and describe counterparties. When an SP or an IdP receives a request from another provider, it needs to be able to verify that the remote provider is who it claims to be. This is done by comparing the declared name in the SAML request to the names the provider knows from the metadata. When there's a match, the remote provider must then present the credentials that are in that provider's metadata. Now that the remote provider has been positively identified, they can communicate. If there is no match, or the credentials presented are wrong, no attributes will be sent.

The metadata file is either signed, hosted using https://, or both, and frequently downloaded by all providers in the federation. It's stored in an XML file, conventionally named federationName-metadata.xml. The distribution of Shibboleth includes example-metadata.xml as a template from which we'll work.

Every provider in your new federation must have its own EntityDescriptor element within the main EntitiesDescriptor element. Each EntityDescriptor element must have a uniquely identifying URI(which includes both URLs and URNs), which needs to be assigned on a conceptual basis. In general, these entity names are nothing but unique identifiers. However, we recommend using URLs, which may be beneficial in anticipation of future use of dynamically resolved metadata. The EntityDescriptor's entityID is currently referred to by the Shibboleth providers as providerIds, but this language should be unified in Shibboleth 2.0 as entityID.

Metadata for Intra-Realm SSO

In situations where there will only be one or two IdPs that are used by a federation, such as in an intra-realm SSO deployment, it's suggested that the federation use two separate metadata files. The IdP metadata is placed into an metadata.xml file, which can be distributed to all SPs that rely on it. The SP metadata is then placed in a separate metadata.xml file which is only needed by the IdP. This approach simplifies metadata distribution and can be easier to understand for the deployers and maintainers of the SPs.

Entity Naming

The first name to assign is for the main EntitiesDescriptor element. The urn:mace:shibboleth:examples value must be replaced with one appropriate for your federation. This could be the location where your federation policy will be hosted, such as https://www.supervillain.edu/evil-federation/policy.html. Make sure to use a legal namespace you control. This EntitiesDescriptor element is filled with one or more EntityDescriptor element with unique names for each provider.

IdP naming is generally straightforward. One EntityDescriptor will suffice for most IdPs, with additional entries only necessary if it's acting with two or more materially different policies. The EntityDescriptor name should follow a pattern similar to https://idp.supervillain.edu/shibboleth/federation-name/idp. In cases where the provider is acting under the same policy in multiple federations, the federation-name can be omitted and the same entity name used in all transactions.

SP naming is a little more tricky. Shibboleth SPs will often host multiple applications and distinct trust realms behind a single provider, and an application could span multiple providers. As far as the IdP is concerned, the actual machine and URL of the resource are not important. The entityID (providerId) is the unit by which relying parties and applications are measured. It provides the basis for trust and attribute release. This means each individual SP will usually operate as multiple distinct entities: one entity name (providerId) for each logically distinct application it protects. An EntityDescriptor element must be created for each. A general-purpose application protecting a large, common webspace might be named https://sp.supervillain.edu/shibboleth/federation-name/sp , whereas the super-secret shrink ray research division might have its own policies and entity name https://sp.supervillain.edu/shibboleth/federation-name/shrinkray . IdPs will treat them as entirely discrete and separate entities, sending different attributes and information to each, even though they're protected by the same SP.

These names must match the values of the providerId specified in shibboleth.xml and idp.xml.

Trust

Shibboleth relies on public-key cryptography certificates to allow providers to identify one another through both signed assertions and SSL/TLS. The certificates used by your providers in these transactions must match the corresponding data in their metadata entries. This can be achieved two ways:

embedding the certificates used by a provider directly in its metadata;
placing the CN of the key in the metadata, and relying on PKI for verification.

Embedding certificates directly in the metadata is strongly recommended for several reasons. Future versions of Shibboleth will allow assertions to be encrypted and pushed directly to providers, simplifying flows and enabling new deployment scenarios. This is only possible if the public key of the relying party is available. Many of the hassles that accompany PKI deployment, such as revocation, can be handled using the metadata more easily – simply replace the certificate with a new one. Additionally, any signer can be used as long as the private key is sufficiently well-guarded. This does not preclude the use of a common root.

If the machine running a provider already has a certificate, it can be used as long as it's being embedded or its root is in the metadata file. If you need to generate certificates, make sure to generate the public/private keypair securely, such as on the machine itself. Centrally generating keys is insecure and only used in TestShib for convenience. Once the keys are generated, either self-sign them on the machine, or sign them with one of the trusted roots included in the metadata.

Shibboleth allows distinct certificates to be used when the provider is operating in different capacities, such as one for the SSO service and another for the AA. This will rarely be encountered, and the same certificate should be present in both parts of the metadata.

Endpoints

EntityDescriptor elements will include several endpoint definitions, each of which describes where and how to contact a provider for a specific kind of interaction. These are defined using the various _Function_Service elements. The entries in example-metadata.xml are a good demonstration to work from, and the major modification should only be the server names and the handlerURL paths for additional applications in the Location fields.

Scope

Identity Providers have an extra extension in their metadata to handle attribute scope. This extension limits the attribute scopes that a provider is allowed to be authoritative for; for example, Supervillain University couldn't send an eduPersonScopedAffiliation of member@brown.edu (unless the federation decided it wanted to allow Supervillain University to express that someone was a member of Brown). This has important policy implications since the scope of an attribute is often used for trust decisions. For Supervillain University's IdP, this would only be <shibmd:Scope>supervillain.edu</shibmd:Scope>.

Signing

While hosting the metadata behind SSL/TLS provides some degree of integrity and authentication, metadata may additionally be signed by the central authority to ensure it hasn't been tampered with. This is done using metadatatool, followed by download and verification by use of siterefresh and metadatatool on the individual providers using distributed Java keystores containing the certificate of the central authority. Providers themselves never check the signature, so it's important to store the metadata securely once received.

2. The Discovery Problem & WAYF

One of the hardest problems in federated identity is the determination of the Identity Provider for a user. While there's a number of promising technologies on the way, such as Cardspace and SDSS' Multi-WAYF work, the problem of creating a palatable user experience is challenging today. The essential goal is to redirect the user's browser to the location of the SSO endpoint with the SP information encoded in the URL. All these approaches do nothing more than construct this request. These are some suggestions about how to handle it.

If an application will generally only allow users from a single IdP to access it, its SessionInitiator can point directly at the SSO service, sidestepping discovery entirely.

The traditional approach is for the federation to stand up a central WAYF service through which users at all service providers are funneled. There are a few WAYFs available. This has the unfortunate effect of requiring users to select their home from a list of providers, but the advantage that this must only be done once for all service providers sharing the WAYF. Configuration and setup information is available along with each WAYF.

Portals may also be constructed both at the IdP and the SP. The SP could display a set of links or buttons, each corresponding to the IdP of a community that it will be hosting using LazySessions. These buttons would be assigned their own SessionInitiator elements, one for each IdP pointing directly at the SSO handler, which would then be added to shibboleth.xml. A few links and associated shibboleth.xml configuration elements might look like:

https://www.supervillain.edu/shrinkray/Shibboleth.sso/WAYF/Supervillain?target=https://www.supervillain.edu/shrinkray/index.html
https://www.supervillain.edu/shrinkray/Shibboleth.sso/WAYF/EvilCoalition?target=https://www.supervillain.edu/shrinkray/index.html

<SessionInitiator id="supervillain" Location="/Supervillain"
	Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
	wayfURL="https://idp.supervillain.edu/shibboleth-idp/SSO"
	wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>

<SessionInitiator id="evilcoalition" Location="/EvilCoalition"
	Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
	wayfURL="https://idp.evil.edu/shibboleth-idp/SSO"
	wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>

Users can also access their home site first, which can have special links constructed that allow an IdP-first flow, also sidestepping the problem. A link might resemble:

https://idp.supervillain.edu/shibboleth-idp/SSO?
	target=https://www.supervillain.edu/shrinkray/index.html
	&shire=https://www.supervillain.edu/shrinkray/Shibboleth.sso/SAML/POST
	&providerId=https://www.supervillain.edu/shibboleth/evilfederation/shrinkray

3. Configure the Providers

We assume you already have operational providers installed and tested against a service such as TestShib.

The configuration of all your providers needs to match the information contained in the metadata. Configuration of the providers is covered in-depth in the ConfiguringShibboleth and ConfigurationHowTos sections of the Wiki, and there are a few specific examples for discovery configuration above. Frequently, the only change will be the providerId, which will match the EntityDescriptor names you created, and SessionInitiator information on the SPs. On the IdPs, attribute release should be enabled as desired using the newly generated providerIds.

The other major change is adding the metadata from your new federation to each provider, which all need local copies. The metadata should be repeatedly refreshed, either using curl/wget or preferably metadatatool/siterefresh, by placing it on a cron job that runs every 5 minutes or so. Every idp.xml and shibboleth.xml file needs a MetadataProvider element pointing to the locally stored version.

4. Create the Policy

Every federation should establish and publish a document that describes its policies, practices, and operation. This is analogous to the Certificate Policy (CP) maintained by certificate authorities, but it needs to contain a different set of information. This document will be important in establishing the LevelOfAssurance (LOA) of your federation, governing the behavior of providers in your federation, and transacting with providers outside your federation.

A policy for federations that require only basic trust and a low level of assurance should still discuss basic policies and procedures, focusing in particular on signing key, certificate authority, and attribute information. Any federation that seeks to establish a higher LOA and level of trust should consider the following as well.

5. Create the Attributes

The final part of an exchange between providers that may be facilitated by a federation is the definition of attributes that would be of common interest to federation members. This provides a common language for expressing and interpreting data about users so that access is properly controlled.

Attribute names in SAML, and by extension Shibboleth, are generally expressed as URIs. Section 8.2 of SAML 2.0 Profiles recommends that all LDAP attributes be expressed as URIs through transformation of the OID identifier, e.g. urn:oid:1.3.6.1.4.1.5923.1.1.1.5. Attributes may also be named through other URN namespaces, or by using URLs, which could be resolved to yield a controlled vocabulary, synonyms, and other information. It's very important that proper attribute naming etiquette be followed and that you don't define attributes in namespaces you don't control.

Proliferation in attributes and misappropriation of attributes are two countervailing forces that need to be balanced as you decide which attributes to use. A large number of attributes has already been defined and named (e.g. eduPerson and x.520), and in any situation where a pre-existing attribute meets your needs, it should be used. However, controlled vocabularies and specific definitions must be followed. Use your best judgment in deciding whether to create a new attribute definition.

Attribute definitions should be written in appropriately normative language and assigned at least a SAML-based name. This information should be made available to all providers in your federation and referenced by or included in your federation's policy statement.