The main DiscoJuice script is invoked like this:

$(target).DiscoJuice(options);

Here options are a javascript object including several options related to how DiscoJuice looks and behaves.

All these options are well documented here:

When you are using the hosted version of DiscoJuice from discojuice.org, you probably want to use the DiscoJuice.Hosted helper functions to automatically create the options object.

The DiscoJuice.Hosted object contains two helper functions:

  • DiscoJuice.Hosted.getConfig() - that automatically generates a options object and returns it.
  • DiscoJuice.Hosted.setup() - that automatically generates a options object, and then invokes DiscoJuice automatically with it.

DiscoJuice.Hosted.setup()

DiscoJuice.Hosted.setup(
	"a.signon", "Example Showcase service",
	"https://service.org/saml2/entityid",
	"http://service.org/response.html", ["edugain", "kalmar", "feide"], 
	"http://service.org/login?idp="
);

This function takes 5 parameters:

  • The JQuery selector, pointing to the login button discussed above. In example a.signon will refer to a login link like this: <a href="..." class="signon">...</a>
  • The name of the service. Using the header of the DiscoJuice popup.
  • The Service Provider EntityID, used in the IdP Discovery Protocol.
  • The IdP Discovery Response URL, point to a special HTML page that you need to host on your site; more on this below.
  • A list of metadata feeds that you would like to use. A metadata feed is basically a list of providers with additional metadata, like keywords and logos.
  • A URL prefix that the user will be redirected to after the user has selected a provider. The user will then be redirected to this URL but with the identifier of the provider added as a suffix.

DiscoJuice.Hosted.getConfig()

This function takes 4 parameters. They are identical to the parameters of DiscoJuice.Hosted.setup() except the first parameter target that is omitted.

Here is an example of a generated options object:

{
	"title": "Sign in to &lt;strong&gt;Example Showcase Service&lt;/strong&gt;",
	"subtitle": "Select your Provider",
	"disco": {
		"spentityid": "https://service.org/saml2/entityid",
		"url": "http://service.org/response.html",
		"stores": ["https://store.discojuice.org/"],
		"writableStore": "https://store.discojuice.org/"
	},
	"cookie": true,
	"country": true,
	"location": true,
	"countryAPI": "https://store.discojuice.org/country",
	"discoPath": "https://static.discojuice.org/",
	"callback": function (e, djc) {
		var returnto = window.location.href;
		window.location = "http://service.org/login?idp=" + escape(e.entityID);
	},
	"metadata": 
		[
			"https://static.discojuice.org/feeds/edugain",
			"https://static.discojuice.org/feeds/kalmar",
			"https://static.discojuice.org/feeds/feide"
		]
}

	

Overriding the generated options object

A good approach to add more advanced options, would be to first generate the options object using DiscoJuice.Hosted.getConfig, and then perform adjustments to the options, before invoking DiscoJuice.

Here is an example of disabling communication with DiscoJuice.org for setting preferences on selected providers, as well as turning on the always option to always popup the DiscoJuice window:

var djc = DiscoJuice.Hosted.getConfig(
	 "Example Showcase service",
	 "https://service.org/saml2/entityid",
	 "http://service.org/response.html", ["edugain", "kalmar", "feide"], "http://service.org/login?idp="
);
delete djc.disco;
djc.always = true;
$("a.signin").DiscoJuice(djc);

To debug the options, open the Javascript console / web developer inspector in your browser, and add this line:

console.log(djc);

to output the options object as provider to DiscoJuice.

Adding entities from other sources

If you would like to combined the metadata feeds from http://cdn.discojuice.org/feeds/ with some additional entries, such as in example Feide OpenIdP, you may do that in a few alternative ways.

If you have only a few entries, the simplest approach is to include the metadata inline in the configuration of DiscoJuice. You may then use the inlinemetadata options from the DiscoJuice Configuration Reference.

var djc = DiscoJuice.Hosted.getConfig(
	 "Example Showcase service",
	 "https://service.org/saml2/entityid",
	 "http://service.org/response.html", ["edugain", "kalmar", "feide"], "http://service.org/login?idp="
);
djc.inlinemetadata = [
	 {
		  'entityID': 'https://openidp.feide.no',
		  'title': 'OpenIdP',
		  'icon': 'openidp.png',
		  'descr':'If you do not have an institutional account, register here.',
		  'country':'_all_',
		  'geo':null,
		  'weight':-5,
		  'keywords': ['Guest', 'OpenIdP', 'Orphanage', 'Homeless', 'Create Account', 'Register']
	 }
];
$(document).ready(function() {
	 $("a.signon").DiscoJuice(djc);      
});

You may also provide your own feed of metadata, and refer to that. Add the url of your own feed to the metadata array like this:

var djc = DiscoJuice.Hosted.getConfig(
	 "Example Showcase service",
	 "https://service.org/saml2/entityid",
	 "http://service.org/response.html", ["edugain", "kalmar", "feide"], "http://service.org/login?idp="
);
djc.metadata.push('https://example.org/additional-metadata.js');
$(document).ready(function() {
	 $("a.signon").DiscoJuice(djc);      
});

In the current version of DiscoJuice the feed URL MUST support the JSONP protocol, even if it is served on the same domain. (We'll remove this requirement, follow issue 42).

When invoking DiscoJuice you provide a configuration object as a parameter, allowing for several options for customizing DiscoJuice.

Basic configuration

title
The title bar in DiscoJuice contains two rows, including a title and subtitle.
subtitle
The title bar in DiscoJuice contains two rows, including a title and subtitle.

Navigation

cookie
When the user has made his/her choice on a provider, should DiscoJuice store the result in a persistent local cookie? Then DiscoJuice will remember the choice until next
country

Boolean value. Default: true

Enable UI widget for selecting country.

countryAPI
If you enter an URL supporting the DiscoJuice country lookup API, DiscoJuice will automatically discovery the country of the current user based upon IP address lookup, and then preselect the current country based upon that.
location

Boolean value. Default: false

Enables a widget for supporting HTML5 Geo-location

Metadata

metadata
The URLs of the JSON metadata feeds. This could be a string of a single URL, or an array of multiple URLs.
inlinemetadata
An array of DiscoJuice JSON Metadata entities to be merged with the external feeds.
discoPath
The path for the DiscoJuice installation relative to the current page. In example, it could be set to discojuice/.

User interface customization

always

Boolean value. Default: false

Should the DiscoJuice be shown by default, not requiring the user to invoke the UI by clicking on some button? Enable this if running DiscoJuice standalone and not embedded popup.

overlay

Boolean value. Default: true

Enable this if you run DiscoJuice embedded, and want to fadeout the background when DiscoJuice is enabled.

Callback

callback
A javascript function callback that will be called when the user has made his/her choice on a provider. The callback functions may take one parameter, which will be the entity configuration object of the selected entity. The entityID may be fetched through the entityID property.

Communicating with remote Discovery Services

Here is an example configuration of the disco option as deployed on the Foodle service:

"disco": {
	"spentityid": "https://foodl.org/simplesaml/module.php/saml/sp/metadata.php/saml",
	"url": "https://foodl.org/res/discojuice/discojuiceDiscoveryResponse.html?",
	"stores": [
		'https://disco.uninett.no/',
		'https://foodle.feide.no/simplesaml/module.php/discopower/disco.php',
		'https://kalmar2.org/simplesaml/module.php/discopower/disco.php'
	],
	'writableStore': 'https://disco.uninett.no/'
},

DiscoJuice supports to be configured to read from a number of external IdP Discovery Services. The protocol that DiscoJuice is using to communicate with these services is the IdP Discovery Protocol. The request will be sent using a hidden iFrame, with the IsPassive parameter set to true.

spentityid
The IdP Discovery Protocol requires that the request is including the Service Provider EntityID of the service that the Discovery service represents.
url
The URL that the response will be sent to. This must be the full URL of the discojuiceDiscoveryResponse.html file contained in the DiscoJuice package.
stores
An array of IdP Discovery Service endpoints to contact. You may safely include a short list of services, but you are reccomended to limit the number, because all these services are contacted by all users when DiscoJuice is used.
writableStore
You may configure one IdP Discovery Service endpoint that supports DiscoJuiceReadWrite, which is an extension to the IdP Discovery Protocol, that allows you to write the result of the user selection to a central discovery service. DiscoJuice deployed standalone supports this protocol.

DiscoJuice is multi-lingual, and depending on your browser language preferences, DiscoJuice will adapt to your preferred language.

If you would like to contribute with translation to another language, please contact Andreas.

Translation of feeds

The names of the Identity Providers are extracted in multiple languages from the SAML 2.0 Metadata files. To add support for additional languages, metadata from the origin source must be updated.