> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/access/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/access/key-components/authenticators/protocol-managers/saml/idp-discovery-service.md).

# IdP Discovery Service

Configuration and usage guidance for IdP Discovery Service in Fortified ID Access.

## 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:

{% code title="SP GET request" fullWidth="false" %}

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

{% 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

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

{% hint style="info" %}
**Module name:** `IDPDiscovery`
{% endhint %}

{% tabs %}
{% tab title="Properties" %}

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th>Default value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td>http_context</td><td>Module context path. Endpoint for the initial GET to the service.</td><td><code>/discovery</code></td><td>true</td></tr><tr><td>internal_http_destination</td><td>The name of the HttpClient module that should be used to fetch the metadata.</td><td><code>default</code></td><td>false</td></tr><tr><td>metadata</td><td>Array[] of metadata locations.</td><td></td><td>true</td></tr><tr><td>metadata.path</td><td>Local path to a metadata file.</td><td></td><td>false</td></tr><tr><td>metadata.url</td><td>URL to the metadata file</td><td></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
      "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"
          }
        ]
      }
    },
```

{% endtab %}
{% endtabs %}


---

# 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/access/key-components/authenticators/protocol-managers/saml/idp-discovery-service.md?ask=<question>&goal=<endgoal>
```

`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.