Skip to main content
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; 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

Serval doesn’t create accounts through SAML JIT provisioning. To provision and deprovision users automatically, configure SCIM alongside SSO from Organization → Security.

​
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, 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.
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.
1

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).
2

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

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

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.

​
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.
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.
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 integration, or the employee portal widget.

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