3. Configuration

The EDS functions in conjunction with a suitably configured Service Provider. Both Shibboleth and non Shibboleth SPs can be used, but at the present time, we don't know of any other implementations that directly support the JSON feed format used in the software.

Configuration of Shibboleth SPs, which MUST be running V2.4 or later, is detailed below. For non-Shibboleth SPs, consult the appropriate documentation.

The precise configuration of the SP depends on when it was first installed, since certain mechanisms changed in version 2.4.

3.1.1 SPs installed since Version 2.4 and later

This section describes the requirements when using configuration files that were installed along with recent versions of the SP software.

Perform the following steps to configure the Service Provider, by editing the /etc/shibboleth/shibboleth2.xml:

1. Edit the <MetadataProvider> tag, setting the legacyOrgNames attribute to true. (See NativeSPMetadataProvider for more information). We do this because at this time almost no federation metadata includes the discovery UI extensions. (See section 4. Metadata Considerations for more information).

   <MetadataProvider type="XML" uri="http://federation/metadata.xml"
       backingFilePath="federation.xml" legacyOrgNames="true" reloadInterval="7200">

2. Edit the SSO tag (see NativeSPServiceSSO for details), removing the entityID attribute and adding a discoveryProtocol of "SAMLDS" and setting the discoveryURL attribute to the URL of the web page that will contain the EDS.

   <SSO discoveryProtocol="SAMLDS" discoveryURL="https://yoursp/path/to/EDS">
      SAML2 SAML1
   </SSO>
   

3.1.2 SP installed prior to version 2.4

This section describes the requirements when using configuration files that were installed along with older versions of the SP software and have been carried forward into V2.4 or later. In no case can you use a version prior to V2.4.

Perform the following steps to configure the Service Provider, by editing the /etc/shibboleth/shibboleth2.xml:

1. Edit the <MetadataProvider> tag, setting the legacyOrgNames attribute to true. (See NativeSPMetadataProvider for more information.) We do this because at this time almost no federation metadata includes the discovery UI extensions. (See section 4. Metadata Considerations for more information).

   <MetadataProvider type="XML" uri="http://federation/metadata.xml"
       backingFilePath="federation.xml" legacyOrgNames="true" reloadInterval="7200">
   

2. Edit the Sessions tag to add a discovery service feed.

   <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
   

3. Modify the <SessionInitiator> chain used by your deployment and make sure the last <SessionInitiator> element in the chain is of type="SAMLDS" and that it points to the web page containing the EDS. If an existing element of type="WAYF"is present you will need to remove it or comment it out.

   <!-- This is an example, it may not match yours exactly. -->
   <SessionInitiator type="Chaining" Location="/Login">
       ... earlier elements ...
       <SessionInitiator type="SAMLDS" URL="https://yoursp/path/to/EDS"/>
   </SessionInitiator>
   

3.1.3 Testing

To test that everything is operational, open a browser and attempt to access an SP protected page. The SP should redirect you to the embedded discovery service and, if you select your Identity Provider (IdP) you should be able to log in to the SP as normal. On the first visit to the embedded discovery service there will be no history (obviously) but if you close out the browser and try to log in to the SP again you should now see your previously chosen IdP listed as a preferred IdP.

The precise behavior of the EDS is controlled by various configuration options which are set in the IdPSelectUIParms class defined in the idpselect_config.js file. This is the only file you should need to edit to configure the EDS.

A complete list of user-changeable configuration options is presented below. For a production installation, at least the dataSource, defaultLogo, defaultLogoHeight, defaultLogoWidth, and helpURL options should be set.

Parameters with a superscript^{like this} indicate that the parameter is only available starting at the release whose number figures in the superscript..

All options

alwaysShow

default value: true
This controls whether the search box always shows results as soon as you start typing in it. If false, results will only be shown when there are fewer than maxResults of them.

autoFollowCookie ^1.2

If present this indicated the name of the cookie to be used to signal "auto follow"; see below.

autoFollowCookieTTLs ^1.2

Specifies the potential lifetime (in days) for the cookie use to signal "auto follow".  This should be specified as an array for instance

 this.autoFollowCookieTTLs = [ 1, 60, 270 ];

See below for more details

autoFollowCookieProps ^1.3

This provides a string (potentially containing multiple semi-colon separated properties) which is appended when setting the 'autoFollowCookie' described above. For example '; Secure; SameSite=Lax';

dataSource

default value: /Shibboleth.sso/DiscoFeed
This is the URL of the source of the data feed of IdPs to the DS. This feed must be at the same location as the DS itself and so it is usual for the protocol and host part of the URL (https://example.org) to be dropped.

The data source is a JSON file. The schema of this file is defined in EDSDetails

defaultLanguage

default value: 'en'
This is the language to be used for display if it cannot be determined from the browser. See also section 3.3 Internationalization below.

defaultLogo

default value: null
This is the URL of the logo which is displayed if a previously selected IdP has no logo declared for it (see 4. Metadata Considerations below). It is recommended that this be a transparent box of size 80x60 pixels.

defaultLogoHeight, defaultLogoWidth

default value: null
The dimensions of the default logo.

defaultReturn

default value: null
If this is set it allows the EDS to be set up in a such a way that it does not need to be approached via the Discovery Service protocol. The defaultReturn and defaultReturnIDParam parameters supply the values which would normally be supplied via the protocol.

Note that the values will be URL-encoded prior to being sent back. That is, this value could be constructed by URL-decoding the value to the "return" parameter in a standard Discovery Service protocol request.

defaultReturnIDParam

default value: null
If specified, this supplies the same value that the returnIDParam would in a DS protocol request.

Note that, according to the specification, if the value of defaultReturn is non-null and the value of defaultReturnIDParam is null, then the protocol default of entityID is used.

doNotCollapse ^1.1

default value: true
If set to false, then if none of the preferred IdPs have an associated logo, then the height of the EDS is collapsed appropriately

helpURL

default value: null
This is the URL to which users are dispatched when they click on the help link.

ie6Hack

default value: false
This can be used to ease some issues with IE6 and z-axis. IE6 is not supported by the EDS.

ignoreKeywords

default value: false
If this value is set to true then the contents of any <mdui:Keywords/> will not be used to find suggested names.

ignoreURLParams ^1.1

default value: false
If this value is set to true then the EDS entirely ignores all parameterization to the URL (including any DS protocol parameterization) and instead always relies on the defaultReturn configuration parameter.

insertAtDiv

default value: 'idpSelect'
This is the id of the <div> inside which the EDS will be constructed.

langBundles

See the section 3.3 Internationalization

maxResults

default value: 10
This controls how many results to display in response to typing in the search box. If alwaysShow is true, then the first maxResults values are shown. If it is false then nothing is shown until there are no more than maxResults values.

myEntityID

default value: null
If this is supplied, then the entityID supplied via the DS protocol is checked against this string.

noWriteCookie ^1.1

default value: false
If this is set to true, then the EDS does not save the selected IdP as a cookie.  If the EDS shares a domain with a Shibboleth SP, then this setting might be combined with enabling the SP's IdP history can be enabled via the idpHistory attribute on the SP's <Sessions> element.  This has the advantage that only successfully authenticated IdPs are store, whereas the EDS would otherwise save all selected IdPs.

preferredIdP

default value: null
If this is supplied, then it must be an array of entityIDs of IdPs which are considered preferred by this SP. Preferred IdPs are always displayed regardless of whether the user has previously selected them.

hiddenIdPs

default value: null
If this is supplied then it must be an array of entityIDs of IdPs which are not to be displayed by the EDS.

redirectAllow ^1.3

This setting prevents the use of the EDS as an open redirector by enforcing one or more regular expressions against the requested return parameter. The EDS doesn't have any dynamic awareness of the host(s) it's being deployed for, so it can't automatically guess an appropriate default. Upgraded systems will not have this setting, and continue to operate as before, but new installs get a default value that will cause an error until an appropriate rule is added.

The original name of this filter type prior to V1.3 was "returnWhiteList", support for which will be removed in a future release.

samlIdPCookieTTL

default value: 730
This is the lifetime (in days) of the cookie which is used to store the list of previously visited sites. This cookie is in the standard _saml_idp format as described in the SAML profiles specification.

samlIdPCookieProps ^1.3

This provides a string (potentially containing multiple semi-colon separated properties) which is appended when setting the cookie which is used to store the list of previously visited sites. For example '; Secure; SameSite=Lax';

selectedLanguage ^1.3

default value: null

If this is specified then it is the language which the EDS is to be displayed in.  The language (which may contain a localization) should be available in a language bundle.  An example is  given below

The default is to use the default localization of the browser.

setFocusTextBox ^1.1

default value: true
By default the text box is always given focus after the EDS has been drawn. Web sites may wish to leave the focus somewhere else; in that case they should set this value to false.

showListFirst ^1.1

default value: false
If set to true then the dropdown box of IdPs is initially shown. If the value is absent or set to false then the free text "search as you type" box is displayed.

testGUI

default value: false
It is usually a configuration error to browse to the EDS page, rather than be redirected to it by SP when you visit a secured page. If this value is set to true, then none of the DS parameters are checked. This allows the GUI to be tested without the full DS parameter string (and without dispatching the browser to the selected IdP).

Details & Examples

Configuring Auto-Follow ^1.2

In certain constrained environments, it may be useful to make the user's decision "sticky", that is to say that once the selection is made it will stay in force for a certain amount of time.  

To do this you need to provide the name of a cookie as the parameter autoFollowCookie.  The presence of this cookie will indicate that the user should not be prompted for IdP selection for the lifeltime of the cookie, and the previous selection used.  In addition, you should configure autoFollowCookieTTLs as an array containing the number of days that the cookie should be valid for.  The size of the array specifies how many options the user will be given (in addition to "Never follow the selection").

You also need to ensure that your languages file contains the following extra lines (which will not be present in all locales, or in any version which was installed prior to 1.2)

'autoFollow.message' : 'Always follows this selection',
'autoFollow.never' : 'Never',
'autoFollow.time0' : 'One day',
'autoFollow.time1' : '3 months',
'autoFollow.time2' : '9 months',

You need a line autoFollow.timeX for every entry in the autoFollowCookieTTLs array you specified.

It is your responsibility to provide a mechanism to clear the autoFollow cookie to handle the case when the user specifies auto-follow and then makes the wrong decision.

Configuring selected language ^1.3

The selected language configuration parameter specifies the  language to use.  This can be dynamic with the value being recalculated each time the EDS is loaded.  For example if you wanted to detect the value from a parameter passed on the URL (a nonstandard thing to do 

function getLang() {
    var win = window;
    while (null !== win.parent && win !== win.parent) {
        win = win.parent;
    }
    var loc = win.location;
    var parmlist = loc.search;
    parmlist = parmlist.substring(1);

    parms = parmlist.split('&');
    if (parms.length === 0) {
	return null;
    }
    for (i = 0; i < parms.length; i++) {
        parmPair = parms[i].split('=');
        if (parmPair.length != 2) {
            continue;
        }
        if (parmPair[0] == 'lang') {
            return parmPair[1];
	}
    }
    return null;
}
.....
function IdPSelectUIParms(){
	.....
    this.selectedLanguage = getLang();
	.....
}

Localizing the EDS

The EDS is entirely globalized. This means that in usual operations all text that is displayed to the user can be controlled via the configuration of the DS. Precisely which text is displayed is adjusted as a function of the language and locale of the browser as determined by the EDS.

It is important to understand that the technical underpinnings do not allow the EDS access to the most useful setting (the language setting of the browser itself).

The EDS therefore tries a series of common (but non-standard) techniques to determine the locale of the browser, which is often the locale with which the operating system was installed. From this locale the language can be determined. However this may not be the same as the browser's currently selected preferred language.

If the browser does not respond to any of these techniques, then the default language configured into the EDS is used.

The net result of this is that a user may not see the localization they expected, but will see a localization that is useful to them. See also the Technical Details below.

The messages which can be displayed are defined in the configuration file idpselect_config.js and (from V1.1 onwards idpselect_languages.js which is combined into the minimised source)  as a series of bundles. V1.1 ships with bundles for English, German, Japanese and Brazilian Portuguese.

To extend the EDS for an additional language add the language to the langBundles variable in idpselect_config.js by adding an entry for the appropriate language (for instance "gd" or "fr-ca").   You can modify the language bundle that is shipped with the EDS in the same way.

Note that the EDS will use your language bundles in preference to the shipped language bundles and the most specific language possible. For instance, if the browser reports "en-gb" then the EDS would use a "en-gb" bundle in preference to an "en" bundle. Equally if only a "en-us" bundle is specified then there will be no match and the default language will be used.

IdPs

The DisplayNames of the IdPs are localized and their logos may be localized. Again, the EDS will select according to the browser locale's language, if available, falling back to the default language if the browser language is not available or if no DisplayName for the browser locale's language exists.

Technical Details

When the EDS is initialized, it attempts to determine the locale and language of the browser by consulting navigator.language. If this doesn't exist it then consults navigator.userLanguage. If either of these exist, then they are used as the language of choice.

If this language contains a hyphen (for example "fr-ca" or "en-gb") then the first part is taken as the 'major language'.

From then on all language lookup is done

1. First from the entire supplied language. (e.g. "fr-ca").  The search is done first in your configured bundles and then the provided bundles.
   
   

2. Then from the 'major language' ("fr")
   
   

3. Then from the default language as configured into the EDS.

This mechanism is used:

• For the language bundle which describes the static text displayed in the browser. If a required message doesn't exist having followed all three of these options then an error is displayed; this is a configuration error since the language bundles must contain all the messages for the default language.
  
  

• For the IdP Display Name. If an IdP does not have a display name in any of these languages then its entityID is used.
  
  

• For the IdP Logo. If an IdP does not have a logo in the browser language or 'major language' then a logo with no language is chosen. If none of these is present then a logo with the default language is chosen. If there is still no logo, then the defaultLogo is used. Note that the size of the logo is used to determine choice, but this is secondary to the language-driven choice.