Discovery API

Discovery API can be used to fetch information in JSON format about a specific application and a template, such as available authentication methods. This information is usable, for example, when the initial login menu screen showing all the available authentication methods is being built externally.

The discovery API is callable by Web Agent ID (ie. entityID) and template name:

/uas/discovery(/<method>)?entityID=<entityID>&template=<template>&locale=<locale>&callback=<jsonp>

If the URL parameter callback is defined, the returned JSON–object will be wrapped inside the function call defined in <jsonp>.

Optionally, discovery API can also be called by conversationID:

/uas/discovery?id=<conversation-id>

 The return message is formed of following elements:

idp → EntityID of the identity provider.

sp → EntityID of the service provider.

template → Contains information about the selected template. Composite of the following elements.

name → Name of the template.

defaultLocale → Default locale of the template.

locales → List of all locales in the template.

localeNames → Map of localized names for the locales.

locale → Current locale.

settings → Contains map of settings specific to the selected template. Composite of the following elements.

showlogin → Corresponds to the showlogin parameter in the template.

showmenustepup → Corresponds to the showmenustepup parameter in the template.

usemethodlogoimages → Corresponds to the usemethodlogoimages parameter in the template.

usemethodtextlink → Corresponds to the usemethodtextlink parameter in the template.

usemethodgroups → Corresponds to the usemethodgroups parameter in the template.

methods → Map of authentication methods available to the agent and information about each method.

title → Name of the authentication method.

type → Type of the authentication method. One of {password, stepup, proxy, unregistered, discovery}.

password → Name of the password method related to this stepup method. Used only if type is stepup.

stepUp → Type of the stepup method. One of {otp, sms, mpki}.

groups → List of method groups as defined in the method grouping of the current template.

title → Name of the method group.

methods → List of authentication methods in the group.

Example of Discovery API message for request:

https://idp.example.com:8443/uas/discovery?entityID=urn%3Auuid%3A2aca7e7e-7a00-4149-8126-65536cdfcb7d&template=default&locale=en

{
  "idp": "https://idp.example.com:8443/sso-ui",
  "sp": "urn:uuid:2aca7e7e-7a00-4149-8126-65536cdfcb7d",
  "template": {
    "name": "template5",
    "defaultLocale": "fi",
    "locales": [
      "fi",
      "en",
      "sv"
    ],
    "localeNames": {
      "fi": "Suomeksi",
      "sv": "På Svenska",
      "en": "In English"
    }
  },
  "locale": "en",
  "settings": {
    "showlogin": false,
    "showmenustepup": true,
    "usemethodlogoimages": true,
    "usemethodtextlink": true,
    "usemethodgroups": true
  },
  "methods": {
    "password.1": {
      "title": "Password One",
      "type": "password"
    },
    "otp.1": {
      "title": "OTP One",
      "type": "stepup",
      "password": "password.1",
      "stepUp": "otp"
    },
    "sms.1": {
      "title": "SMS OTP One",
      "type": "stepup",
      "password": "password.1",
      "stepUp": "sms"
    },
    "mpki.1": {
      "title": "MPKI One",
      "type": "stepup",
      "password": "password.1",
      "stepUp": "mpki"
    },
    "password.2": {
      "title": "Password Two",
      "type": "password"
    },
    "otp.2": {
      "title": "OTP Two",
      "type": "stepup",
      "password": "password.2",
      "stepUp": "otp"
    },
    "proxy.1": {
      "title": "Proxy One",
      "type": "proxy"
    },
    "proxy.2": {
      "title": "Proxy Two",
      "type": "proxy"
    },
    "proxy.4": {
      "title": "Proxy Directory",
      "type": "proxy"
    },
    "tupas.nordea.1": {
      "title": "Nordea",
      "type": "proxy"
    },
    "tupas.danske.1": {
      "title": "Danske",
      "type": "proxy"
    },
    "tupas.op.1": {
      "title": "OP",
      "type": "proxy"
    },
    "mpki.2": {
      "title": "MPKI Two",
      "type": "unregistered",
      "unregistered": "mpki"
    },
    "active.1": {
      "title": "WAYF",
      "type": "discovery"
    }
  },
  "groups": [
    {
      "title": "Pankit",
      "methods": [
        "tupas.op.1",
        "tupas.danske.1",
        "password.1"
      ]
    },
    {
      "title": "Testi",
      "methods": [
        "tupas.nordea.1"
      ]
    },
    {
      "title": "Muut",
      "methods": [
        "otp.1",
        "sms.1",
        "mpki.1",
        "password.2",
        "otp.2",
        "proxy.1",
        "proxy.2",
        "proxy.4",
        "mpki.2",
        "active.1"
      ]
    }
  ]
}