Getting Started with DiscoJuice
The most common way to setup DiscoJuice would be to integrate DiscoJuice into the Service as a popup box that is activated when the user clicks on a login button. The use then selects which provider to login with. DiscoJuice is configured to run a callback function when the user selects a provider, which allows you to configure how to start the real login process, depending on how the authentication software works. The most common callback will be to redirect the user to a specific URL with the identifier of the provider as a parameter.
This Getting Started Guide helps you through setting up DiscoJuice making use of the
discojuice.org hosted environment. This means you do not need to host DiscoJuice yourself, but can instead just point to hosted version. You may also host DiscoJuice locally, but it is reccomended that you start with getting things work with the hosted version first
To get started, you would need to add a login button (when the user is not already logged in). DiscoJuice does not care how the login button is, as long as it is a HTML element. Here is an example:
<a href="/traditional/discovery" class="signon">Login</a>
Now, we need to add some code in the HTML
DiscoJuice.Hosted.setup() function takes the following parameters:
- The JQuery selector, pointing to the login button discussed above. In example
a.signonwill 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.
The IdP Discovery Response page is a simple HTML page that you should install on your service provider. You can download this file here.
The URL to this response page is required in the configuration above. It must be hosted on your own server, to fulfil the same-origin policy.
DiscoJuice.org also hosts a passice central discovery service, and to get this to work, your hostname needs to be accepted by DiscoJuice. If your metadata cotains a DiscoveryResponse element, and is present in eduGAIN, InCommon, Kalmar or UK Access Federation, it should be trusted already. If you want to add additional hosts without joining these federations, ask on the DiscoJuice mailinglist.
The instructions above on setting up DiscoJuice includes the most basic required options, but DiscoJuice have a lot of configuration options to meet your requirements.
There is a specific guide on how to setup a local authentication inside DiscoJuice:
DiscoJuice.org is hosting a set of automatically generated metadata feeds from the metadata of various Identity Federations.
Here you can see a list of the provided feeds here:
You may also setup your own metadata feeds.
If your Service Provider supports that you go to a specific URL with the entityID of the Identity PRovider as a parameter, you can make use of that.
TODO: Document in more detail on how this can be setup with Shibboleth and SimpleSAMLphp.
Go to a page containing the login button, and click on it. The DiscoJuice popup should then appear, and you may choose a provider.
Instead of having an embedded version of DiscoJuice, you may setup a separate page implementing the IdP Discovery Protocol, and using DiscoJuice as a user interface.
DiscoJuice is a GÉANT3 project, developed by UNINETT. Currently the focus is on providing a centralized hosted version of DiscoJuice, at
DiscoJuice is currently hosted by UNINETT, providing a best effort uptime. If DiscoJuice becomes used a lot in our federations, there probably should be a more formal agreement on the
discojuice.org hosting, with a Service Level Agreement, and funding from the biggest players. One solution could be that the GÉANT projects funds and hosts the service in the future.
Comments or questions regarding this may be sent on the mailinglist.
The DiscoJuice UI is now translated into 15 different languages. We wish more translations welcome, if you're interested in translating DiscoJuice, please visit this page:
and request a new translation team for your language, and after I have accepted the team, you'll be granted access. When your translation is complete, notice us through the DiscoJuice mailinglist, and we'll include the new translation in the DiscoJuice hosted at
The metadata feeds at
discojuice.org will interpret multi-lingual names of providers from SAML metadata, and will serve the user the preferred translation based upon the Accept language header sent from tbe browser. Currently, it fallbacks to the english translation if the preferred language was not available.
If you operate a Identity Federation, you may contact firstname.lastname@example.org about offering a automatically generated feed at
To improve the quality of your generated metadata feed, please read this guide to improve the metadata:
You may also choose to offer your own
DiscoJuiceJSON feed and host that yourself. Or you may want to add support for
DiscoJuiceJSON format in your software exporting metadata.
If you would like to setup your own passive discovery storage, to store preferences of the user (and not use
Discojuice.org) you may implement support for the DiscoReadWrite protocol:
If you are using simpleSAMLphp, you can enable the
discojuice module to get started very quickly. This module makes use of the hosted DiscoJuice script on
DiscoJuice is completely independent from SimpleSAMLphp, and there is no need to install SimpleSAMLphp just to use DiscoJuice.
- DiscoJuice Changelog
- Reference on DiscoJuice options object
- Guide for Federations
- Guide for SimpleSAMLphp as Service Provider
- DiscoPoints and Weighting Login Providers
- Reference on DiscoJuiceJSON
- Specification on DiscoReadWrite protocol
If you have questions about using DiscoJuice, please join the mailinglist.