Here are some notes about constructing metadata for Shibboleth entities, particularly for the new SAML 2.0-based metadata format.

You need to read the following in order to have a reasonable understanding of the new metadata format:

  • The SAML 2.0 metadata specification (saml-metadata-2.0-os.pdf).
  • The SAML 1.x profile of the SAML 2.0 metadata specification (currrently draft-saml1x-metadata-05.pdf).
  • Shibboleth Architecture: Protocols and Profiles (draft-mace-shibboleth-arch-protocols-latest.pdf, currently working draft 09, 28-Feb-2005).

In the 1.1/1.2 metadata format, it was possible to have an OriginSite and a DestinationSite with the same @Name. If you want to do this with the new format, you make a single EntityDescriptor with the appropriate roles for both an identity provider and for a service provider.

A 1.1/1.2 identity provider needs to have:

  • An IDPSSODescriptor with
    • A @protocolSupportEnumeration including both urn:oasis:names:tc:SAML:1.1:protocol and urn:mace:shibboleth:1.0.
    • A SingleSignOnService with
      • a @Binding of urn:mace:shibboleth:1.0:profiles:AuthnRequest.
      • a @Location which will normally be an https URL. Often the path in that URL will be /shibboleth/HS.
      • See Shibboleth Architecture: Protocols and Profiles for a definition of urn:mace:shibboleth:1.0:profiles:AuthnRequest.
  • An AttributeAuthorityDescriptor with
    • An AttributeService with
      • a @Binding of urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding
      • a @Location which MUST be an https URL in order to meet the requirement in <em>Shibboleth Architecture: Protocols and Profiles</em> section 2.2.2 that the attribute authority have the ability to authenticate requests. Often the path in that URL will be /shibboleth/AA.

The standard 1.1/1.2 to 1.1/1.2 sequence goes like this:

  • User visits the SP.
  • SP sends a urn:mace:shibboleth:1.0:profiles:AuthnRequest somewhere, perhaps a WAYF or a known good IdP endpoint.
  • WAYF allows the user to pick from entities:
    • that have IDPSSODescriptors
      • that have @protocolSupportEnumeration including urn:mace:shibboleth:1.0
  • WAYF sends the user to the URL contained in the chosen entity's SingleSignOnService with a @Binding of urn:mace:shibboleth:1.0:profiles:AuthnRequest. Such a binding MUST be present.
  • IdP verifies that the request shire parameter is valid for the given providerId: the entity must have an SPSSODescriptor with a @protocolSupportEnumeration containing urn:oasis:names:tc:SAML:1.1:protocol, which in turn contains an AssertionConsumerService with a @Binding of urn:oasis:names:tc:SAML:1.0:profiles:browser-post and the given @Location. [Not sure all these checks are made in fact; but they should be.]
  • IdP invokes the SAML 1.1 Browser/POST profile, which ends up with the user agent performing an HTTP POST to the URL passed as shire.

If a 1.3 IdP wants to be able to communicate with 1.1/1.2 SPs, it has to have the same metadata as a 1.1/1.2 IdP, at a minimum. There are a couple of potential differences:

  • The SingleSignOnService's @Location is more likely to have a path of /shibboleth-idp/SSO.
  • The AttributeService's @Location is more likely to have a path of /shibboleth-idp/AA.

If a 1.3 IdP only needs to be able to communicate with 1.3 SPs, it could in theory use "attribute push" (probably in conjunction with the artifact profile) and not have an AttributeAuthorityDescriptor at all. [Suggest disallowing this by policy.]

SAML 1.1 Browser/Artifact Profile

The 1.3 IdP supports the SAML 1.1 Browser/Artifact profile, which replaces the indirect POST response to the authentication request (and the JavaScript required to make this transparent) with an HTTP GET encoding a much smaller artifact. The artifact is then dereferenced by the SP to retrieve the much larger authentication assertion. Supporting this mode of operation requires that:

  • The IdP is V1.3 or better.
  • The IdP must have an IDPSSODescriptor with
    • An ArtifactResolutionService with
      • a @Binding of urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding
      • a @Location which will normally be an https URL in order to meet the requirement in <em>Shibboleth Architecture: Protocols and Profiles</em> section 2.2.5 that the service provide for mutual authentication. Often the path in that URL will be /shibboleth-idp/Artifact.
  • The SP is V1.3 or better.
  • The SP must have an SPSSODescriptor with
    • A @protocolSupportEnumeration including urn:mace:shibboleth:1.0
    • An AssertionConsumerService with
      • A @Binding of urn:oasis:names:tc:SAML:1.0:profiles:artifact-01

With Shibboleth 1.3, The Browser/Artifact profile will only be used if the Assertion Consumer Service location sent to the IdP as part of the authentication request has a @Binding of urn:oasis:names:tc:SAML:1.0:profiles:artifact-01. The IdP only has a choice of profiles to use if multiple profiles are bound to the same Assertion Consumer Service Location, which would be unusual.

Attribute Push

The 1.3 IdP supports "attribute push", where the authentication statement (whether passed directly or by reference through an artifact) includes attributes, rather than attributes being requested from an attribute authority later in the sequence. Use of attribute push is not explicit in the metadata, instead:

  • Attribute push is off by default for the Browser/POST profile.
  • Attribute push is on by default for the Browser/Artifact profile.
  • The default can be overridden for particular relying parties (entities or groups of entities) in the IdP configuration file.

NameIDFormat Elements

Each entity should declare the format or formats of NameIdentifier (SAML 1.x) or NameID (SAML 2.0) that it can handle. This is done by adding NameIDFormat elements to their metadata.

Multiple NameIDFormat elements can be provided, and are interpreted as being in order of preference with the earlier formats being preferred over the later ones. However, most entities will only describe one NameIDFormat.

Identity provider metadata should include NameIDFormat elements in both the IDPSSODescriptor and AttributeAuthorityDescriptor sections. Service provider metadata should include NameIDFOrmat elements in the SPSSODescriptor section.

The Shibboleth specification requires an implementation to have the ability to process a particular format called urn:mace:shibboleth:1.0:nameIdentifier. This is the so-called "handle" format with opaque, transient semantics. Actual deployments might in principle use other formats, but it is rare for a reference Shibboleth deployment to not make urn:mace:shibboleth:1.0:nameIdentifier available.

The AthensIM identity provider software is known to generate its own format (urn:mace:eduserv.org.uk:athens:uuid) with much the same semantics as the Shibboleth standard. Although this is not in compliance with the Shibboleth specification, errors do not at present arise because the current reference Shibboleth service provider implementation does not check that the format has a valid format URI.

Scope Extensions

When a SP receives a scoped attribute such as eduPersonScopedAffiliation, it filters the attribute values with respect to a list of scopes provided by the metadata.

In Shibboleth 1.1/1.2, attributes are returned from the attribute query issued by the SP to the IdP's AttributeAuthorityDescriptor role. The scope list is described by a series of shibmd:Scope elements in the Extensions element of the AttributeAuthorityDescriptor.

In Shibboleth 1.3, it is also possible to pass attribute values to the SP along with the authentication statement (so-called "attribute push", whether in conjunction with Browser/Artifact or not). Because these are considered to emanate from the IdP's IDPSSODescriptor role, in this case the SP filters the scoped attributes against a second series of shibmd:Scope elements in the Extensions to the IDPSSODescriptor. If there are no such elements, all scoped attributes will be unexpectedly filtered out.

Therefore, if an IdP might be a Shibboleth 1.3 entity, its valid scopes should be present on both the IDPSSODescriptor and the AttributeAuthorityDescriptor. These scopes should be identical; there is no reasonable use case for presenting different lists in these two contexts.

Future development will probably rationalise this by moving the location of the scope extensions from the role descriptors to the parent EntityDescriptor level. During a transition period, this means that the scope list should also appear at this location, for a total of three identical lists of scopes.

Requested and Required Attributes for SPs

Probably goes something like this: 

 <AssertionConsumerService index="3"
   Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"
   Location="https://wiki.it.ohio-state.edu/twiki/Shibboleth.sso/SAML/Artifact" />
 <AttributeConsumingService index="0" `isDefault="true">
   <ServiceName xml:lang="en">Internet2 Shibboleth Wiki</ServiceName>
   <RequestedAttribute Name="" isRequired="true" FriendlyName="" NameFormat="">
     <AttributeValue xmlns="urn:oasis:names:tc:SAML:2.0:assertion">foo</AttributeValue>
   </RequestedAttribute>
 </AttributeConsumingService>