3.2 EDS Configuration Options

1 All options
- 1.1 alwaysShow
- 1.2 autoFollowCookie 1.2
- 1.3 autoFollowCookieTTLs 1.2
- 1.4 autoFollowCookieProps 1.3
- 1.5 dataSource
- 1.6 defaultLanguage
- 1.7 defaultLogo
- 1.8 defaultLogoHeight, defaultLogoWidth
- 1.9 defaultReturn
- 1.10 defaultReturnIDParam
- 1.11 doNotCollapse 1.1
- 1.12 helpURL
- 1.13 ie6Hack
- 1.14 ignoreKeywords
- 1.15 ignoreURLParams 1.1
- 1.16 insertAtDiv
- 1.17 langBundles
- 1.18 maxResults
- 1.19 myEntityID
- 1.20 noWriteCookie 1.1
- 1.21 preferredIdP
- 1.22 hiddenIdPs
- 1.23 redirectAllow 1.3
- 1.24 samlIdPCookieTTL
- 1.25 samlIdPCookieProps 1.3
- 1.26 selectedLanguage 1.3
- 1.27 setFocusTextBox 1.1
- 1.28 showListFirst 1.1
- 1.29 testGUI
2 Details & Examples
- 2.1 Configuring Auto-Follow 1.2
- 2.2 Configuring selected language 1.3

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();
	.....
}