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:

1. User Initiation: A user attempts to access a protected resource, triggering the discovery service.

2. Discovery: The service identifies the user's organisation or domain, either through input or domain mapping.

3. IDP Selection: Based on the discovery data, the service references a pre-configured policy to select the appropriate IDP.

4. Redirection: The user is redirected to their IDP for authentication.

5. Authentication: The user logs in using their IDP credentials.

6. Assertion: Upon successful authentication, the IDP sends an assertion back to the service, confirming the user's identity.

7. 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 Fortified Demo setup as an example:

SP GET request

https://localhost:8443/discovery/?entityID=SomeSP&returnIDParam=providerid&return=https%3A%2F%2Fwww.example.com

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

In this section, we configure the associations between service providers (SPs) and their respective identity providers (IDPs). This is done by using metadata that is loaded when the module starts.

Metadata is referenced by:

• path: A local file containing the metadata

• url: URL to the file containing the metadata.

The metadata is mandatory so one of the references needs to be configured.

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

Properties

Name	Description	Default value	Mandatory
http_context	Module context path. Endpoint for the initial GET to the service.	/discovery
internal_http_destination	The name of the HttpClient module that should be used to fetch the metadata.	default
metadata	Array[] of metadata locations.
metadata.path	Local path to a metadata file.
metadata.url	URL to the metadata file

Example

{
      "name": "IDPDiscovery",
      "config": {
        "http_context": "/discovery",
        "http_port": "${globals.ports.http_port}",
        "http_use_ssl": true,
        "http_keystore_ref": "${globals.keystores.https.ref}",
        "http_keystore_type": "${globals.keystores.https.type}",
        "http_key_alias": "${globals.keystores.https.http_key_alias}",
        "http_key_password": "${globals.keystores.https.http_key_password}",
        "internal_http_destination": "metadata_client",
        "metadata": [
          {
            "url": "https://eid.litsec.se/svelegtest-sp/metadata/2/metadata.xml"
          },
          {
            "path": "/config/eid_litsec_se_sp_1.xml"
          }
        ]
      }
    },