> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Microsoft Entra ID SSO with Serval (SAML)

> Configure SAML 2.0 single sign-on between Microsoft Entra ID and Serval, including prerequisites, supported features, enterprise-app setup, and the SAML attributes Serval expects.

This guide walks a Microsoft Entra ID administrator through connecting Entra ID (formerly Azure AD) to Serval for SAML 2.0 single sign-on, so your users sign in to Serval with their Entra credentials. Serval brokers SAML through [WorkOS](https://workos.com/); the in-product setup gives you the exact values to paste into Entra.

## Prerequisites

Before you begin, make sure you have:

* **A Serval administrator account**: an account with the **Admin** organization role in the Serval organization you're configuring. Sign-in URL: `https://app.serval.com`.
* **Entra administrative permissions**: a role that can create enterprise applications, configure SAML single sign-on, and assign users (for example **Cloud Application Administrator** or **Application Administrator**).
* **A verified domain in Serval**: verify the email domain your users sign in with under **Organization → Security** in Serval before you enable SSO. SAML sign-in is rejected for users whose email domain isn't verified on your organization.

## Supported features

| Feature                         | Supported                                                                                                   |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| SP-initiated SSO                | Yes                                                                                                         |
| IdP-initiated SSO               | Yes                                                                                                         |
| Just-In-Time (JIT) provisioning | No                                                                                                          |
| User provisioning (SCIM)        | Yes, via [SCIM directory sync](/sections/documentation/platform/org-settings#security-sso-scim-and-domains) |
| Single Logout (SLO)             | No                                                                                                          |
| Force authentication            | Yes                                                                                                         |

<Note>
  Serval doesn't create accounts through SAML JIT provisioning. To provision and deprovision users automatically, configure **SCIM** alongside SSO from **Organization → Security**.
</Note>

## Add a Serval enterprise application in Entra

Serval isn't listed in the Entra application gallery. Create a non-gallery enterprise application, then configure SAML on that app.

1. In the [Entra admin center](https://entra.microsoft.com), go to **Identity → Applications → Enterprise applications**.
2. Select **New application**.
3. Select **Create your own application**.
4. Enter a name (for example, `Serval`).
5. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
6. Select **Create**.

## Configure SAML SSO

Serval generates a unique Service Provider (SP) configuration for your organization. Retrieve those values from Serval, then enter them in the **enterprise application you created** above.

<Note>
  When you select **Configure SSO** in Serval, the guided setup shows generic "create a new SAML app" instructions. For Entra, skip creating a second app; you only need to copy your **ACS URL**, **Entity ID**, and **IdP metadata** from that screen into the non-gallery application you already created.
</Note>

<Steps>
  <Step title="Start SSO setup in Serval">
    In Serval, switch to the **Organization** workspace, open **Settings → Security**, and select **Configure SSO**. This launches a guided setup that displays your organization's **Reply URL (ACS URL)** and **Identifier (SP Entity ID)**.
  </Step>

  <Step title="Enter the SP values in Entra">
    In the Serval enterprise application, open **Single sign-on**, select **SAML**, then edit **Basic SAML Configuration**:

    * **Identifier (Entity ID)**: the SP Entity ID from Serval.
    * **Reply URL (Assertion Consumer Service URL)**: the ACS URL from Serval.

    Leave **Sign on URL** blank unless the guided setup asks you to set one. Save your changes.
  </Step>

  <Step title="Send the Entra metadata to Serval">
    On the same **Single sign-on** page, under **SAML Signing Certificate**, copy the **App Federation Metadata URL**. Provide it in the Serval guided setup so Serval can trust assertions signed by your Entra tenant.
  </Step>

  <Step title="Assign users and test">
    Assign the Serval app to the users or groups who should have access (**Users and groups**). Then sign in from the Entra **My Apps** portal (IdP-initiated) or from Serval's sign-in page (SP-initiated) to confirm access.
  </Step>
</Steps>

## SAML attribute statements

Confirm these mappings under **Attributes & Claims** in the Entra app's SAML settings. Entra's default claims already use XML URIs. Leave those defaults. The guided setup maps them. Don't add extra claims named `id`, `email`, `firstName`, or `lastName`.

| Source                   | Default claim  |
| ------------------------ | -------------- |
| `user.mail`              | `emailaddress` |
| `user.givenname`         | `givenname`    |
| `user.surname`           | `surname`      |
| `user.userprincipalname` | `name`         |

<Note>
  Email identifies the user. WorkOS takes a stable identifier from NameID, so you don't need a separate `id` claim. Sign-in fails if email is missing.
</Note>

Entra only populates `user.mail` when the user's **mail** attribute is set. For accounts without a mailbox, set **Entra → Users → the user → Contact information → Email**, or map the email claim to `user.userprincipalname` if that value is an address on your verified domain.

## SP-initiated sign-in

Users can start sign-in from Serval directly:

1. Go to `https://app.serval.com`.
2. Enter your work email. Serval detects your organization's SSO domain and redirects you to Entra.
3. Complete authentication in Entra. Serval returns you to the app, signed in.

This SAML enterprise application isn't the **Continue with Microsoft** button on the login card, the [Microsoft Graph](/sections/integrations/microsoft-graph) integration, or the <a href="/sections/documentation/helpdesk/embedded-widget/entra-oidc">employee portal widget</a>.

## Troubleshooting

* **`Profile domain does not belong to the target Organization`**: the signed-in user's email domain isn't verified on your Serval organization. Verify the domain under **Organization → Security**.
* **"Invalid SAML Response"**: the Entra metadata registered in Serval doesn't match the app sending the assertion (for example, after recreating the enterprise application). Re-send the current **App Federation Metadata URL** to Serval.
* **User not assigned**: Entra denies sign-in for anyone who isn't assigned to the enterprise application. Open **Users and groups** and assign the user or a group they belong to.
* **Locked out after enabling Require SSO**: enabling **Require SSO** makes SSO the only sign-in method for members on a verified domain. If Entra sign-in is unavailable, an administrator can restore access through magic-link sign-in for guest accounts, or contact your Serval representative.

<Warning>
  Turning on **Require SSO** disables password and magic-link sign-in for members on your verified domains. Confirm SSO works end to end for at least one administrator before enforcing it.
</Warning>

If sign-in still fails after these checks, reach out to your Serval representative or Serval support with the time of the attempt and the error message shown.