IDP Discovery Service

Introduction

This document details the setup and management of the IDP Discovery Service, which directs users to their respective Identity Providers (IDPs) for efficient single sign-on (SSO) processes. It targets system administrators, security architects, and developers involved in SSO implementations, assuming familiarity with authentication protocols like SAML and OAuth.

Technical Overview

The IDP Discovery Service facilitates a user's connection to the correct Identity Provider (IDP) by following a standardised flow:

User Initiation: A user attempts to access a protected resource, triggering the discovery service.
Discovery: The service identifies the user's organisation or domain, either through input or domain mapping.
IDP Selection: Based on the discovery data, the service references a pre-configured policy to select the appropriate IDP.
Redirection: The user is redirected to their IDP for authentication.
Authentication: The user logs in using their IDP credentials.
Assertion: Upon successful authentication, the IDP sends an assertion back to the service, confirming the user's identity.
Access Granted: The service processes the assertion and grants access to the resource.

This flow ensures that users are authenticated through their respective IDPs efficiently, maintaining a secure and streamlined access protocol.

Connecting to an IDP Discovery Service

To initiate user sign-on, the service provider sends the user's browser to the discovery service using an HTTP GET request with these key parameters:

entityID (required): Identifies the service provider the user is trying to access.
return (required): Specifies where to send the user after IDP selection.
policy (optional): Influences the discovery service's processing. It defaults to a standard policy if not specified. Not supported.
returnIDParam (optional): Determines the name of the parameter for returning the IDP's unique identifier. Defaults to "entityID".
isPassive (optional): Set to "true" or "false" to decide if user interaction is allowed during discovery. Defaults to "false". Not supported.

The service provider must ensure the correct entityID is provided.

Using the example configuration as an example request:

SP1 GET request

https://localhost:8443/discovery/?entityID=https://eid.litsec.se/sp/1&returnIDParam=providerid&return=https%3A%2F%2Feid.litsec.se%2Fsvelegtest-sp%2Fauthnrequest%2Fdisco%2F1

SP2 GET request

https://localhost:8443/discovery/?entityID=https://eid.litsec.se/sp/2&returnIDParam=providerid&return=https%3A%2F%2Feid.litsec.se%2Fsvelegtest-sp%2Fauthnrequest%2Fdisco%2F2

Configuration: Module and HTTP

The IDP Discovery service is a standalone module that supports all standard configurations for a HTTP-Server. Please see Configuration for more details.

Configuration: Metadata

The associations between this module and the service providers (SPs) is done by using metadata that is configured using the SAML-module.

Configuration: Look and feel

Basic changes

Add basic look and feel changes to the ui_config_overrides.json. (see language section how to use ui_config_overrides.json. Here you can changes logo, browser tab name and link to logo.

Advanced changes

More extended information of how overlay work can be found in the Integrity WEB documentation. https://docs.fortifiedid.se/fortified-integrity/authenticators/ui/overriding-ui-elements

Configuration: Properties

Module name: IDPDiscovery

Name

Description

Default value

Mandatory

http_context

Module context path. Endpoint for the initial GET to the service.

/discovery

support_url

Optional URL linking to a dedicated support page, displayed alongside error messages for additional assistance.

entities

Array of SP entities with their list of providers

entities.entityID

SP entity ID

entities.providers

Array of providers

entities.providers.id

Position in view list

entities.providers.providerId

The providerId for the IDP

entities.providers.label

The name of the provider in the view.

entities.providers.logo

Icon for the provider

{
  "modules": [
    {
      "name": "SAML",
      "config": {
        "internal_http_destination": "http_saml",
        "metadata": [
          {
            "url": "https://eid.litsec.se/svelegtest-sp/metadata/1/metadata.xml"
          },
          {
            "url": "https://eid.litsec.se/svelegtest-sp/metadata/2/metadata.xml"
          }
        ]
      }
    },
    {
      "name": "HttpClient",
      "config": {
        "name": "http_saml",
        "idle_timeout_ms": 5000,
        "connect_timeout_ms": 5000,
        "request_timeout_ms": 6000,
        "circuit_breaker": {
          "enabled": true,
          "default_config": {
            "maxFailures": 5,
            "timeout": 10000,
            "resetTimeout": 10000
          }
        }
      }
    },
    {
      "name": "IDPDiscovery",
      "config": {
        "http_context": "/discovery",
        "support_url": "https://example.com/support",
        "entities": [
          {
            "entityID": "https://eid.litsec.se/sp/1",
            "providers": [
              {
                "id": "1",
                "providerId": "https://www.bankid.com/",
                "label": "BankID",
                "logo": "assets/svg/bankid.svg"
              },
              {
                "id": "2",
                "providerId": "https://eidas.ec.europa.eu/",
                "label": "Foreign eID",
                "logo": "assets/svg/eidas.svg"
              }
            ]
          },
          {
            "entityID": "https://eid.litsec.se/sp/2",
            "providers": [
              {
                "id": "1",
                "providerId": "https://app.klarna.com/login",
                "label": "Klarna",
                "logo": "assets/svg/efos.svg"
              },
              {
                "id": "2",
                "providerId": "https://www.google.com",
                "label": "Google",
                "logo": "assets/svg/google.svg"
              },
              {
                "id": "3",
                "providerId": "https://www.bankid.com/",
                "label": "BankID",
                "logo": "assets/svg/bankid.svg"
              },
              {
                "id": "4",
                "providerId": "https://eidas.ec.europa.eu/",
                "label": "Foreign eID",
                "logo": "assets/svg/eidas.svg"
              }
            ]
          }
        ]
      }
    }
  ]
}