> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/idp-discovery-service/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/idp-discovery-service/idp-discovery-service.md). # 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 example configuration as an example request: {% code title="SP1 GET request " fullWidth="false" %} ```html 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 ``` {% endcode %} {% code title="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 ``` {% endcode %} ## Configuration: Module and HTTP The IDP Discovery service is a standalone module that supports all standard configurations for a HTTP-Server. Please see [Configuration](https://docs.fortifiedid.se/modules/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](https://docs.fortifiedid.se/samlmodule/). ## 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. \ ## Configuration: Properties {% hint style="info" %} **Module name:** `IDPDiscovery` {% endhint %} {% tabs %} {% tab title="Properties" %}
NameDescriptionDefault valueMandatory
http_contextModule context path. Endpoint for the initial GET to the service./discoverytrue
support_urlOptional URL linking to a dedicated support page, displayed alongside error messages for additional assistance.false
entitiesArray of SP entities with their list of providerstrue
entities.entityIDSP entity IDtrue
entities.providersArray of providerstrue
entities.providers.idPosition in view listtrue
entities.providers.providerIdThe providerId for the IDPtrue
entities.providers.labelThe name of the provider in the view.true
entities.providers.logoIcon for the providertrue
{% endtab %} {% tab title="Example" %} ```json { "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" } ] } ] } } ] } ``` {% endtab %} {% endtabs %} ### DiscoveryResponse MUST be present in SP metadata For IdP Discovery to function correctly, the Service Provider’s SAML metadata MUST include at least one element. The Discovery Service relies on this element to determine where the user is returned after selecting an Identity Provider.\ If no DiscoveryResponse is present in the metadata, the Discovery Service cannot reliably complete the discovery flow and IdP discovery MUST be considered unsupported for that Service Provider. The Location attribute of the DiscoveryResponse element MUST reference an endpoint implemented by the Service Provider that can receive:\ • the selected IdP entityID\ • the associated RelayState and continue the authentication flow by initiating a SAML authentication request to the chosen Identity Provider. ```xml https://sp.example.com/app/continue ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.fortifiedid.se/idp-discovery-service/idp-discovery-service.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.