> For the complete documentation index, see [llms.txt](https://help.enterprise.ledger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.enterprise.ledger.com/help-center-v2/administration/users/single-sign-on.md).

# Single sign-on (SSO)

How an organization sets up SAML 2.0 single sign-on for a Ledger Enterprise Workspace with Ledger support, what the IT team configures in the identity provider, and how SSO controls access.

Single sign-on (SSO) lets the PSD users of a Workspace sign in through the identity provider (IdP) of their organization.

**Role: the IT team that administers your IdP, and the Master Administrators of the Workspace.**

## How SSO works

* Ledger Enterprise supports SAML 2.0 only.
* Ledger support enables SSO for a Workspace, and changes it. The interface has no setting for SSO, and the change is not a Request.
* SSO applies to PSD users. API users authenticate over the API. See [**API users**](https://help.enterprise.ledger.com/help-center-v2/start-here/get-started/api-users.md).
* SSO changes how users sign in. Users still approve Requests on their Ledger device.
* At the first SSO sign-in, each PSD user pairs their Ledger device with their SSO identity. After the pairing, the user does not confirm on the device to sign in. See [**Pairing**](#pairing).
* One SSO identity pairs with one PSD user only. Some persons have more than one PSD user, for example one for each Ledger device. Such a person can sign in with SSO as one of them only.

> **Important:** Ledger Enterprise does not recommend more than one user for each person. With more than one user, the same person can act as more than one user in the same approval chain. This weakens the separation of duties. See [**Separation of duties**](https://help.enterprise.ledger.com/help-center-v2/concepts/the-security-model.md#separation-of-duties).

## Access control

* In a Workspace with SSO, a PSD user cannot sign in with the Ledger device alone. The sign-in always goes through the IdP.
* An SSO identity alone does not give access. It must be paired with an active PSD user, and the pairing needs the Ledger device of that user.
* A suspended or revoked PSD user cannot sign in, even when the IdP accepts the identity.
* When you disable a person in the IdP, they cannot sign in again. An open session stays open until it ends, 15 minutes after the last request. See [**When your session ends**](https://help.enterprise.ledger.com/help-center-v2/start-here/get-started/signing-in.md#when-your-session-ends).

> **Important:** To remove access to the Workspace, revoke the PSD user. Disabling the person in the IdP is not enough: the user stays in the Workspace and in its approval steps. See [**Revoking**](https://help.enterprise.ledger.com/help-center-v2/administration/users.md#revoking).

## Before you start

* An IdP that can create a SAML 2.0 client.
* If the IdP sends the attribute `deviceUserId`, the device ID of each PSD user. See [**The device ID in the IdP**](#the-device-id-in-the-idp).
* One PSD user for each person who signs in with SSO. Find the persons who have more than one PSD user, and decide which PSD user each person keeps. See [**How SSO works**](#how-sso-works).
* Active PSD users. A user must finish registration, and the activation Request must be approved, before the user can pair. See [**Creating a PSD user**](https://help.enterprise.ledger.com/help-center-v2/administration/users.md#creating-a-psd-user).

## Set up SSO

1. Contact Ledger support in the support portal. Ask to enable SSO, and name the Workspace. See [**Contacting Ledger support**](https://help.enterprise.ledger.com/help-center-v2/contacting-support.md).
2. Ledger support sends you the SSO endpoint URL of your Workspace.
3. In your IdP, create a SAML 2.0 client. Use the values in [**Values for the SAML client**](#values-for-the-saml-client).
4. Send the following to Ledger support:
   * the SAML metadata of the IdP, as a URL or an XML file;
   * the client ID;
   * whether Ledger Enterprise must sign the authentication request (`AuthnRequest`);
   * whether Ledger Enterprise must validate signatures;
   * any specific configuration of the IdP that Ledger must know.
5. Ledger support completes the configuration, and tells you when SSO is ready.
6. Ask one PSD user to sign in with SSO and to pair their device. Make sure that the Workspace opens. See [**Sign in with single sign-on**](https://help.enterprise.ledger.com/help-center-v2/start-here/get-started/signing-in.md#sign-in-with-single-sign-on).
7. Tell the other PSD users that their next sign-in uses SSO, and that the first one includes the pairing.

### Values for the SAML client

| Setting                             | Value                                                                                                         |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Master SAML Processing URL          | The SSO endpoint URL                                                                                          |
| Valid redirect URIs                 | The SSO endpoint URL, and the SSO endpoint URL followed by `/*`                                               |
| Home URL                            | The SSO endpoint URL                                                                                          |
| Name ID format                      | `persistent`                                                                                                  |
| Force Name ID format                | On (`true`)                                                                                                   |
| Attribute `deviceUserId` (optional) | The device ID of the Ledger device of the user. See [**The device ID in the IdP**](#the-device-id-in-the-idp) |

These names are the Keycloak names. In other IdPs:

* The SSO endpoint URL is the Assertion Consumer Service (ACS) URL. Some IdPs call it the single sign-on URL or the reply URL.
* The client ID is the entity ID of the client. Some IdPs call it the audience URI.
* **Valid redirect URIs** and **Home URL** can have no equivalent. Leave them out.

> **Important:** If Ledger support changes the SSO endpoint URL, update the URLs of the client in your IdP.

### The device ID in the IdP

The attribute `deviceUserId` is optional.

* When the IdP sends it, Ledger Enterprise compares it with the device ID of the connected Ledger device when the user pairs. A different value stops the pairing with **PSD does not match your SSO session**.
* When the IdP does not send it, Ledger Enterprise does not compare. The SSO identity pairs with the PSD user of the connected Ledger device.

> **Important:** Without the attribute `deviceUserId`, the pairing does not confirm that the SSO identity and the Ledger device belong to the same person. Send the attribute to add this check.

Send the device ID as 16 hexadecimal characters, in uppercase, with no hyphens: `0123A123B123C123`. Ledger Enterprise compares the values character by character.

To get this value, open the user page and copy the **Identifier** with its copy action. The copy action gives the device ID with no hyphens. The page shows the same device ID with hyphens, in groups of four: `0123-A123-B123-C123`. If you type the value from the screen, remove the hyphens. See [**The user page**](https://help.enterprise.ledger.com/help-center-v2/administration/users.md#the-user-page).

## Pairing

At the first SSO sign-in, a PSD user pairs their Ledger device with their SSO identity. Each SSO identity pairs with one PSD user, and each PSD user with one SSO identity.

When the IdP sends the attribute `deviceUserId`, Ledger Enterprise checks it at the pairing only. It does not check it again at later sign-ins.

No action in the interface or the API removes the pairing. Revoking the PSD user does not remove it either: the SSO identity cannot pair with another PSD user. A new identity for a user who is already paired cannot pair again.

> **Warning:** Do not change the Name ID of a paired user, for example during a migration to another IdP. The user then cannot sign in. Contact Ledger support before the change.

## What can go wrong

| What you see                                                    | Cause                                                                                                                                                                                       | What to do                                                                                                                                                                |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PSD does not match your SSO session**                         | The attribute `deviceUserId` from the IdP is not the device ID of the connected Ledger device. A device ID with hyphens or in lowercase also causes it                                      | Correct the device ID in the IdP. See [**The device ID in the IdP**](#the-device-id-in-the-idp). Then the user signs in again                                             |
| **PSD already linked to another user**                          | The SSO identity, or the PSD user, is already paired. A changed Name ID causes it. It also shows when a person who has more than one PSD user pairs a second one with the same SSO identity | Make sure the Name ID of the user is persistent and did not change. If it changed, contact Ledger support. For a second PSD user, see [**How SSO works**](#how-sso-works) |
| **Pair your Ledger device** shows for a user who already paired | The PSD user is suspended or revoked, or the Name ID of the user changed                                                                                                                    | Make sure the user is active in **Users**. If the user is active, see the row above                                                                                       |
| The **Sign in** page shows again after the IdP                  | The sign-in did not complete                                                                                                                                                                | The user selects **Continue with SSO** again. If the problem continues, check the client in the IdP, then contact Ledger support                                          |

For all the sign-in messages, see [**Sign-in and device messages**](https://help.enterprise.ledger.com/help-center-v2/reference/statuses-and-errors.md#sign-in-and-device-messages).

## Related

* [**Signing in and out**](https://help.enterprise.ledger.com/help-center-v2/start-here/get-started/signing-in.md)
* [**Users**](https://help.enterprise.ledger.com/help-center-v2/administration/users.md)
* [**Contacting Ledger support**](https://help.enterprise.ledger.com/help-center-v2/contacting-support.md)
* [**Statuses and errors**](https://help.enterprise.ledger.com/help-center-v2/reference/statuses-and-errors.md)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.enterprise.ledger.com/help-center-v2/administration/users/single-sign-on.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
