DiscoveryService API Reference

Functions

json_mdq_get(id, mdq_url, entity_id, trustProfile)

An MDQ client using fetch (https://fetch.spec.whatwg.org/). The function returns a Promise which must be resolved before the object can be accessed.

Arguments:

  • id (string) – an entityID (must be urlencoded) or sha1 id

  • mdq_url (string) – a URL of an MDQ service incl trailing slash - eg https://md.thiss.io/entities/

  • entity_id (string) – entityID of the SP using the discovery service, in case there is a trust profile

  • trustProfile (string) – trustProfile selected by the SP using the discovery service, in case there is a trust profile

Returns:

Promise – A promise that resolves to an object representing the resulting entity

parse_qs(paramsArray)

Parse an array of querystring components into an Object

Returns:

an object with each k,v-pair as properties.

ds_response_url(entity, params)

Create a SAML discovery service protocol response URL from the entity_id property of the entity object and the return and returnIDParam (if present) of the params object. Combine with a base URL to form a full discovery service response.

When specifying a ‘shib’ initiator type, the shibboleth SP session initiator should be configured with property entityIDParam=”IDPEntityID”.

Arguments:

  • entity (Object) – a discojson entity

  • params (Object) – an object object from which ‘return’ (required) and ‘returnIDParams’ (optional) will be used

Returns:

string – a query string

Classes

class DiscoveryService(mdq, persistence, context, opts)

A DiscoveryService class representing the business logic of a SAML disocvery service.

To obtain cross-site persistence, using the browser’s Storage Access API, an integrator must expose a checkbox from the persistence service, so that when the user clicks on it, they will be prompted for permission to share persisted entities across different sites using the persistence service. This exposed checkbox can be labelled “remember me” or something of the sort.

The constructor takes 4 parameters:

Arguments:

  • mdq (function|string) – a callable or a URL to be used for MDQ-style lookups of entity objects.

  • persistence (string|PersistenceService) – the URL of a persistence service or an instance of the PersistanceService

  • context (string) – the default context identifier

  • opts (Object) – An optional object containing options. Supported keys:

DiscoveryService.DiscoveryService

The constructor takes 4 parameters:

DiscoveryService.do_saml_discovery_response(entity_id, persist=true)

The main entrypoint of the class. Performs the following actions in a Promise-chain: 1. fetches the entity from the persistence service 2. performs an MDQ lookup if the entity was not found 3. returns an item (entity+last_used timestamp)

Arguments:

  • entity_id (string) – the entityID of the SAML identity provider

  • persist (boolean) – set to true (default) to persist the discovery metadata

DiscoveryService.pin(entity_id)

Shorthand for do_saml_discovery_response. Convenience method for the case when you want to pre-populate (aka pin) an identity provider choice. The idea is to call this function, resolve the Promise but not redirect the user.

Arguments:

  • entity_id (string) – the entityID of the SAML identity provider

DiscoveryService.remove(entity_id)

Removes an entity by calling the remove function of the underlying PersistenceService instance.

Arguments:

  • entity_id (string) – the entityID of the SAML identity provider to be removed

DiscoveryService.saml_discovery_response(entity_id, persist=true)

Call do_saml_discovery_response and then set window.top.location.href to the discovery response URL This assumes that the code is running on the discovery service URL so the relative redirect works.

Arguments:

  • entity_id (string) – an entityID of the chosen SAML identity provider.

  • persist (boolean) – whether to persist the choice

DiscoveryService.with_items(callback)

Preform callback on all entities in the persistence-service.

Arguments:

  • callback (function) – a callable taking a single entity parameter