Technical details on how DiscoJuice works

There are several roles of the play of DiscoJuice, each falls into separate same-origin policies. (not all the domain names are not real, but used as an example)

  • The web service provider, that needs to know which provider to login the user; service.example.org.
  • The DiscoJuice static content, including the script, some UI elements, such as images and css; provided from static.discojuice.org.
  • DiscoJuice JSON Metadata feeds, a compact optimized metadata document for federations using JSON; metadata.federation.org
  • An IP to geo JSONP lookup service; running on geo.discojuice.org.
  • One or more existing discovery services; wayf.swtich.ch
  • A new central passive discovery service; store.discojuice.org

Installing DiscoJuice

The web service, includes in the web template of the service at service.example.org a script element referring to the static DiscoJuice javascript running at static.discojuice.org.

Also the web service includes a response.html page at service.example.org. This is used to receive responses from IdP Discovery Services.

DiscoJuice Operations

When a user clicks a login button or otherwise invokes DiscoJuice. The browser loads the script from static.discojuice.org, but runs in the context of service.example.org. The script draws the core UI of DiscoJuice on the screen, embedded in the web page running on service.example.org. The CSS and images are loaded from static.discojuice.org.

Now, DiscoJuice loads one or more metadata feeds using JSONP from metadata.federation.org. metadata.federation.org also caches provider logos adjusted to an appropriate size (approx 40x60px). On metadata.federation.org an engine runs to generate JSON metadata from SAML 2.0 Metadata, and postprocessing logos etc.

In parallell, the uses the JSONP interface of geo.discojuice.org to get the estimated geo-location of the current user, based upon lookup of IP address. This is used to preselect the country in the UI, and as a fallback geo-location of the user used to sort the entities based upon distance.

Then DiscoJuice if configured make passive IdP Discovery Requests to a set of configured Discovery Services. These requests is compatible with all existing WAYFs or Discovery Services, by using the IdP Discovery Protocol. The user is not redirected, instead the scripts load a hidden iframe within the body of the web service. The iframe’s src points to the IdP Discovery endpoint at the discovery service endpoint of a remote discovery service. The return parameter to these iframe URLs are pointing back to the response.html running on service.example.org. These requests are made to check if the user has preselected any provider in any of the remote discovery services. Obviously these requests are made passive and does not always return any result, but never involves UI. The iframe content is redirected back to the response.html page with the selected provider as a query string parameter. The response.html page has a inline script that parses the response from the IdP Discovery protocol, and sends this to the parent frame (this run in the same-origin), DiscoJuice main script receives this and adjust the list of providers.

When the user has selected a provider, DiscoJuice can store use a simple addition to the IdP Discovery Protocol to be able to set the value of the selected provider on a remote domain; such as store.discojuice.org. DiscoJuice includes a hidden iframe similar to the approach above, but with a providerID set in the request. DiscoJuice has two implementation of an extended version of the Discovery Protocol, a server-side and a client-side implementation. The servier-side implementation typically uses cookies to store the selected provided in the context of store.discojuice.org. A client side implementation can use cookies or localStorage. store.discojuice.org uses access control to only leak preferred providers to clients registered in metadata, using the already established elements for that in SAML 2.0 metadata.

As a result the preferred provider is always shown on top of the list, even when the user moves between service providers running in completely separate domains. DiscoJuice achieve this even though the DiscoJuice script runs in the local context of the service provider.

Leave a Reply