DiscoJuice is a very flexible User Interface library for implementing an IdP Discovery Service.

Important warning on using DiscoJuice in production!

As of April 2014 DiscoJuice is not yet established in a production ready environment. There is a huge interest in DiscoJuice and we use it ourself as well, and we are looking into the possibilities of establishing DiscoJuice in a very reliable hosting serivce.

If you have input with regards to requirements, ideas or suggestions with regards to using DiscoJuice, you may contact Andreas directly.

Stay tuned, and join the mailinglist!

What is DiscoJuice

As a service provider, connected to a large number of Identity Providers, you would need to ask the user in advance of the authentication process to select its Identity Provider.

DiscoJuice is super simple to deploy at a Service Provider. Is is as easy as copy and pasting a small javascript refernece into the HTML source of your application.

Features

Some of the features DiscoJuice supports includes:

  • Local Memory (cookie)
  • Remote Memory (DiscoReadWrite protocol + IdP Discovery)
  • Javascript only, super simple to deploy
  • DiscoJuiceJSON compact UI-focused Metadata format (MDUI friendly)
  • Presents logos, searchable keywords, name, descr, country...
  • Automatically discovery of country
  • HTML5 Geo-location API
  • Gracefull non-javascript fallback
  • Inline incremental search
  • Flexible integration API using JS callbacks.
  • Protocol agnostics, demoed with alternative protocols.
  • Multi-lingual both provider list (from metadata) and UI is translated into 15 languages

Deployment options

There are at least three ways to deploy DiscoJuice that you should be aware of.

  1. DiscoJuice embedded IdP Selector Popup in Application
  2. Service Provider IdP Discovery Service
  3. Identity Federation Central IdP Discovery Service
  4. Global IdP Discovery Service

If your application has a login-button, this button can be connected to the Embedded DiscoJuice Discovery Service.

Screenshot of DiscoJuice embedded

By installing DiscoJuice, the login button will result in a DiscoJuice popup discovery service that allows the user to select Identity Provider, and then redirects the user in the correct way.

Prepare to add some HTML template of the pages where you would connect DiscoJuice to the login button. You probably will have a login link or button similar to this:

<a href="/login" class="login-btn">Login</a>

Next, in the <head>-section of your HTML page you will need to setup DiscoJuice.

<!-- JQuery hosted by Google -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js" type="text/javascript"></script>

<!-- DiscoJuice hosted by UNINETT at discojuice.org -->
<script type="text/javascript" src="https://cdn.discojuice.org/discojuice-stable.min.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.discojuice.org/css/discojuice.css" />
<script type="text/javascript">
	DiscoJuice.Hosted.setup(
		{
			"target": "a.signin",
			"title": "Example showcase service",
			"spentityid": "https://bridge.uninett.no/saml2/entityid",
			"responseurl": "http://bridge.uninett.no/response.html",
			"redirectURL": "http://bridge.uninett.no/login?idp=",
			"feeds": ["edugain", "kalmar", "feide"]
		}
	);
</script>

Notice that if you already have jQuery referenced on your site, DiscoJuice may reuse this jQuery, and you should not refer jQuery twice. DiscoJuice does not require any specific version of jQuery.

The DiscoJuice.Hosted.setup() function takes a configuration object as a parameter. The configuration object, may contain the following properties:

target

Optional The JQuery selector, pointing to the login button discussed above. In example a.login-btn will refer to a login link like this: <a href="" class="login-btn">Login</a>.

If you leave out this parameter, it does attach to "body" instead, and will open on page load instead of being invoked by a button click.

title
Optional The name of the service. Using the header of the DiscoJuice popup.
feeds
Required 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. See a list of available metadata feeds
redirectURL
Required 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.
spentityid
Reccomended The Service Provider EntityID, used in the IdP Discovery Protocol.
responseurl
Reccomended The IdP Discovery Response URL, point to a special HTML page that you need to host on your site; more on this below.

The two properties spentityid and responseurl is required in order to enable the central IdP Discovery protocol that allows users of the

Protected pages without a login button

If your application includes pages that would require immediate redirect to the identity provider, there is no login button to connect to DiscoJuice. Instead you can combine these protected pages to any of the standalone DiscoJuice discovery options:

Setting up the IdP Discovery Response HTML page

There is a static HTML page that you need to setup on your own host, and you need to configure the URL of this page

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.

Beeing a trusted client

DiscoJuice.org hosts a passice central discovery service, and to get this to work, your hostname needs to be trusted by DiscoJuice.org. 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.

Setup a preconfigured discovery service for your local Service Provider that implements the IdP Discovery Protocol.

Setting up a discovery service using DiscoJuice typically involves two main steps:

  1. Configure an ACL list of hostnames that are allowed to communicate and get respones from the Discovery Service
  2. Setup the discovery page it self containing static HTML

Setting up the HTML Discovery page

The page will be presented on a URL of your choice. This URL will be the endpoint where you point the service provider to send IdP Discovery requsts.

Below is an example of such a page.

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8" />
	<title>Select your login provider – DiscoJuice</title>
	
	<script type="text/javascript" 
		src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

	<script type="text/javascript" language="javascript" 
		src="//cdn.discojuice.org/engine/discojuice-stable.min.js"></script>
	<script type="text/javascript" language="javascript" 
		src="//cdn.discojuice.org/engine/idpdiscovery.js"></script>

	<link rel="stylesheet" type="text/css" 
		href="//cdn.discojuice.org/css/discojuice.css" />


	<style type="text/css">
		body {
			text-align: center;
		}
		div.discojuice {
			text-align: left;
			position: relative;
			width: 600px;
			margin-right: auto;
			margin-left: auto;
		}
	</style>

	
	<script type="text/javascript">


		$("document").ready(function() {

			$.getJSON('/data/acl.json', function(acl) {

				var options = {
					"title": "DiscoJuice",
					"feeds": ["edugain", "kalmar", "feide"]
				};
				var djc = DiscoJuice.Hosted.getConfig(options);

				djc.always = true;
				djc.callback = IdPDiscovery.setup(djc, acl);

				$("body").DiscoJuice(djc);
			});

		});


	</script>
	
	
	
</head>
<body style="background: #e8e8e8">
</body>
</html>

The code above will load a JSON file with an ACL list of hostnames from the location /data/acl.json.

Alternatively, you may configure a list of hosts without any separate JSON request, like this:

var acl = ['sp.example.org', 'sp2.example.org'];
var options = {
	"title": "DiscoJuice",
	"feeds": ["edugain", "kalmar", "feide"]
};

var djc = DiscoJuice.Hosted.getConfig(options);
djc.always = true;
djc.callback = IdPDiscovery.setup(djc, acl);

$("body").DiscoJuice(djc);

Setup a preconfigured discovery service for your local federation that implements the IdP Discovery Protocol.

Setting up a discovery service using DiscoJuice typically involves two main steps:

  1. Configure an ACL list of hostnames that are allowed to communicate and get respones from the Discovery Service
  2. Setup the discovery page it self containing static HTML

Setting up the HTML Discovery page

The page will be presented on a URL of your choice. This URL will be the endpoint where you point the service provider to send IdP Discovery requsts.

Below is an example of such a page.

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8" />
	<title>Select your login provider – DiscoJuice</title>
	
	<script type="text/javascript" 
		src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

	<script type="text/javascript" language="javascript" 
		src="//cdn.discojuice.org/engine/discojuice-stable.min.js"></script>
	<script type="text/javascript" language="javascript" 
		src="//cdn.discojuice.org/engine/idpdiscovery.js"></script>

	<link rel="stylesheet" type="text/css" 
		href="//cdn.discojuice.org/css/discojuice.css" />



	<style type="text/css">
		body {
			text-align: center;
		}
		div.discojuice {
			text-align: left;
			position: relative;
			width: 600px;
			margin-right: auto;
			margin-left: auto;
		}
	</style>

	
	<script type="text/javascript">

		$("document").ready(function() {

			$.getJSON('/data/acl.json', function(acl) {

				var options = {
					"title": "DiscoJuice",
					"feeds": ["edugain", "kalmar", "feide"]
				};
				var djc = DiscoJuice.Hosted.getConfig(options);

				djc.always = true;
				djc.callback = IdPDiscovery.setup(djc, acl);

				$("body").DiscoJuice(djc);
			});

		});

	</script>
	
	
	
</head>
<body style="background: #e8e8e8">
</body>
</html>

The simplest choice of them all.

There is a central DiscoJuice discovery page running at

http://cdn.discojuice.org/discovery

This discovery page accepts to return responses to all Service Provieders registered properly in all member metadata feeds.

You may perform a limited configuration of the Discovery service, that will be part of the URL. You may create a configuration JSON object containing two properties, title and feeds, like this:

{
	"title": "Feide Discovery",
	"feeds": ["feide"]
}

This configuration object may be JSON encoded, and URLencoded, and added to the query string of the discovery endpoint as a parameter b.

The resulting URL may be something like:

https://cdn.discojuice.org/discovery?b=%7B%22title%22%3A%22Feide%20Discovery%22%2C%22feeds%22%3A%5B%22feide%22%5D%7D

The customize page will aid you in creating a URL containing a configuration object.