The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.


This usually only needs editing for complex deployments

A single discovery service implementation can have multiple handlers. Each handler can have a different look and feel (as described inDSUIEdit) and can display the relevant data in different ways. This is all controlled by making changes to the wayfconfig.xml file. This file consists of the following parts:

Default Configuration

The default behavior is defined in the <Default> element. The following attributes or elements can be changed:

  • jspFile and errorJspFile - control the display. They are described further in DSUIEdit.
  • provideList - controls whether a single list of all possible IdPs is presented. The default wayfs.jsp works best if this is false when provideListofList is set to be true.
  • provideListOfList - controls whether multiple lists are presented (one for each MetadataProvider).
  • showUnusableIdPs - controls the contents of the above lists. The single list (provideList=true) is trimmed by excluding IdPs which do not share a metadata file with the SP. The multiple lists (provideListOfList=true) is trimmed by excluding all lists which do not specify the SP.
  • <SearchIgnore> - contains a list of words to be ignored while performing a search.

Metadata sources

A metadata source is often a description of a federation. The details on how to do add <MetadataProvider> elements are given in DSAddMetadata.

Plugins and the Cookie Plugin.

The general mechanism for defining plugins is described in DsPlugIn.

One plugin is defined in the distribution. This plugin controls the cookie that is used to remember previous selections. The name and value format of the _saml_idp cookie conforms to the Identity Provider Discovery Profile.

The <Plugin> element has the following attributes:

  • identifier - (required) A unique name by which this version of the plugin is known. This is used when defining the precise behavior of each discovery handler.
  • type - (required) This attribute must be set to edu.internet2.middleware.shibboleth.wayf.plugins.provider.SamlCookiePlugin
  • alwaysFollow - (optional) If this is true, and if the Discovery Service locates a cookie with valid data, then this value is immediately used with no user intervention. The precise results depend upon which protocol is being used. (Default: true)
  • deleteCookie - (optional) This is usually set to "FALSE". If it is set to "TRUE" then the plugin will delete any cookie it discovers. If this is set, it is usually done in within a second <Plugin>, which allows the deployment of a handler which deletes any memory the user may have. (Default: false)
  • cacheExpiration - (optional) This specifies the lifetime (in seconds) of the persistent cookie. Set to 0 to expire when the user closes the browser. (Default: 6048000)
  • cacheDomain - (optional) The domain attribute of the cookie. This can be uuseful in deploying the SAML common domain cookie. Note that as per RFC 2965 this should be of the form "". (Default: none)

Discovery Service Handler.

Each handler is defined via a <DiscoveryServiceHandler> element. As well as the attributes and elements described for the Default configuration (and which, if specified override the default), each DiscoveryServiceHandler MUST have a location attribute.

The default web.xml specifies that "/WAYF" and "/*.wayf" are the possibilities for DiscoveryServices. If a URL matches the above, but does not match any location in a DiscoveryServiceHandler, then the first handler for which the default attribute is set true is invoked. The web.xml built into into the war file should not be changed unless you have to change the end points that it uses.

In addition the <DiscoveryServiceHandler> may contain the following subelements:

  • <Federation identifier="id"> - These elements define which <MetadataProvider> elements provide metadata to to this handler. If no <Federation> elements are present, then all of the <MetadataProvider> elements are used.
  • <PluginInstance identifier="id"> - These elements define which <Plugin> elements are associated with this handler.