IDP Discovery Service

Introduction

The IDP Discovery Service presents the identity providers configured for a SAML service provider and returns the selected provider to that service provider. Use it when one SAML application can authenticate through several identity providers and the user needs to choose one before authentication starts.

The service does not infer an identity provider from a user name or domain. It looks up the incoming service-provider entityID, displays that entity's configured providers, and returns the selected provider's providerId.

Configuration

Note

Module name: IDPDiscovery

The module also supports the common HTTP module configuration for its listener and static resources.

Properties

Name	Description	Default	Mandatory
http_context	HTTP context at which the discovery page and its API are published.	"/discovery"
webroot_dir	Directory containing the discovery user interface.	"web/idp_discovery"
support_url	Support link included in error responses and displayed by the user interface.	""
error_redirect	Returns errors to the service provider through a redirect instead of displaying them locally.	false
enable_precompression	Serves precompressed files from the main web root when available.	true
enable_precompression_overlay	Serves precompressed files from configured overlay directories when available.	false
entities	Service providers and the identity providers offered to each one. The list must not be empty.	[]
entities[].entityID	Service-provider entity ID. It must also exist in loaded SAML metadata.	""
entities[].providers	Identity providers offered for this service provider. The list must not be empty.	[]
entities[].providers[].id	Selection value used internally by the discovery page.	""
entities[].providers[].providerId	Identity-provider entity ID returned to the service provider.	""
entities[].providers[].label	Label displayed to the user.	""
entities[].providers[].logo	Optional image path used by the discovery user interface.	""

Example

{
  "name": "IDPDiscovery",
  "enabled": true,
  "config": {
    "http_context": "/discovery",
    "support_url": "https://example.com/support",
    "entities": [
      {
        "entityID": "https://sp.example.com/metadata",
        "providers": [
          {
            "id": "bankid",
            "providerId": "https://idp.example.com/bankid",
            "label": "BankID",
            "logo": "assets/svg/bankid.svg"
          },
          {
            "id": "entra",
            "providerId": "https://idp.example.com/entra",
            "label": "Microsoft Entra ID",
            "logo": "assets/svg/entra.svg"
          }
        ]
      }
    ]
  }
}

How discovery works

1. The service provider redirects the browser to the discovery URL with its entity ID and return URL.
2. The module verifies that the service provider and return URL are present in loaded SAML metadata.
3. The page displays the providers configured for that service provider.
4. The module appends the selected providerId to the return URL and redirects the browser back to the service provider.

Caution

The SAML module must have loaded metadata for the service provider. Its metadata must contain an idpdisc:DiscoveryResponse whose Location matches the return URL.

Request parameters

The service provider starts discovery with an HTTP GET request to the configured http_context.

Name	Description	Default	Mandatory
entityID	Entity ID of the service provider. The value must match both loaded SAML metadata and one configured entities[].entityID.	""
return	URL to which the selected provider is returned. Its base URL must match a metadata DiscoveryResponse location.	""
returnIDParam	Query-parameter name used to return the selected provider ID.	"entityID"
isPassive	When true, errors are returned by redirecting to the service provider.	false
policy	Discovery protocol policy. The value is accepted for protocol compatibility but does not change module behavior.	"urn:oasis:names:tc:SAML:profiles:SSO:idpdiscovery-protocol:single"

Example request:

https://access.example.com/discovery/?entityID=https%3A%2F%2Fsp.example.com%2Fmetadata&returnIDParam=idp&return=https%3A%2F%2Fsp.example.com%2Fsaml%2Fdiscovery

SAML metadata requirement

The service provider metadata must include at least one standard SAML IdP Discovery DiscoveryResponse element. The module compares the base URL of the incoming return parameter with the element's Location value.

<md:EntityDescriptor
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol"
    entityID="https://sp.example.com/metadata">
    <md:SPSSODescriptor
        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:Extensions>
            <idpdisc:DiscoveryResponse
                Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol"
                Location="https://sp.example.com/saml/discovery"
                index="0"/>
        </md:Extensions>
        <md:AssertionConsumerService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://sp.example.com/saml/acs"
            index="0"
            isDefault="true"/>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

The return URL must not already contain the parameter named by returnIDParam. The module adds that parameter after the user selects a provider.