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

# Set up single sign-on with Microsoft Entra ID

> Admin guide to connecting BenefitFlow single sign-on with Microsoft Entra ID (SAML). About 15 minutes.

Single sign-on lets your team sign in to BenefitFlow with their existing company login,
so there's no separate BenefitFlow sign-in to manage. This guide is for your IT or identity
administrator. It walks through creating a BenefitFlow application in Microsoft Entra ID and
sending us two things to finish the connection. For how single sign-on works overall, see
[Single sign-on](https://docs.benefitflow.com/knowledge-base/sso.md).

It takes about 15 minutes. You'll need permission to create enterprise applications in Entra,
which means the **Application Administrator** or **Cloud Application Administrator** role.

## Before you begin

> [!WARNING]
>
> **The email address Entra sends us is what identifies each person.** BenefitFlow accounts are
> keyed on email, so the address in Step 4 has to be the work email your people actually use. Get
> it wrong and sign-in fails. Step 4 is the one to read carefully.

We'll have sent you two values to paste into Entra in Step 3:

| What we call it | What Entra calls it | Value |
| - | - | - |
| Entity ID | Identifier | `urn:amazon:cognito:sp:us-east-1_hH6QJvQla` |
| ACS URL | Reply URL | `https://benefit-flow-prod.auth.us-east-1.amazoncognito.com/saml2/idpresponse` |

Neither value is secret, and nothing you send back to us is secret either. Single sign-on
metadata is made up of public endpoints and a public certificate, so email is a fine way to
exchange all of it.

## Set up the application in Entra

**1. Create the application**

In the Entra admin center, go to **Enterprise applications**, then **New application**.

Choose **Create your own application**, then select **Integrate any other application you
don't find in the gallery (Non-gallery)**. Name it **BenefitFlow** and click **Create**.

![Create your own application panel in Entra, with BenefitFlow entered as the name and the Non-gallery option selected](https://mintcdn.com/benefitflow/lVQT3d-6nwhEERh-/images/entra-create-app.png?fit=max\&auto=format\&n=lVQT3d-6nwhEERh-\&q=85\&s=2f7caf02f5bf8a0f36779ace1fbd2046)

**2. Start SAML setup**

Open the new application, go to **Single sign-on**, and choose **SAML** as the method.

![Select a single sign-on method screen in Entra, with SAML highlighted](https://mintcdn.com/benefitflow/lVQT3d-6nwhEERh-/images/entra-select-saml.png?fit=max\&auto=format\&n=lVQT3d-6nwhEERh-\&q=85\&s=12289214a82d2d0d822e6e5613ef0d75)

**3. Enter the two connection values**

In the **Basic SAML Configuration** panel, click **Edit** and fill in:

* **Identifier (Entity ID):** `urn:amazon:cognito:sp:us-east-1_hH6QJvQla`
* **Reply URL (Assertion Consumer Service URL):** `https://benefit-flow-prod.auth.us-east-1.amazoncognito.com/saml2/idpresponse`

Leave the other fields blank. Click **Save**.

![Basic SAML Configuration panel in Entra with the Identifier and Reply URL filled in](https://mintcdn.com/benefitflow/lVQT3d-6nwhEERh-/images/entra-basic-saml-config.png?fit=max\&auto=format\&n=lVQT3d-6nwhEERh-\&q=85\&s=9f58dc2bb8768de4d82124bca7554e59)

**4. Add the email claim**

This is the step that matters most. BenefitFlow matches each sign-in to an account by email
address, so Entra has to send us that address under a claim named exactly `email`.

Open **Attributes & Claims**, click **Edit**, then **Add new claim**:

* **Name:** `email`
* **Namespace:** leave blank
* **Source:** Attribute
* **Source attribute:** the attribute that holds each person's work email, the same address
  they were invited to BenefitFlow with

In most organizations that's `user.userprincipalname`, because people sign in with their email.
If your people sign in with something else (for example `jsmith@corp.example.com` while their
email is `jane.smith@example.com`), pick the attribute that holds the real address, usually
`user.mail`.

To check, open any user in Entra and compare **User principal name** to **Email**. If they
match, use `user.userprincipalname`. If they don't, use `user.mail`.

Click **Save**.

![Manage claim screen in Entra with Name set to email and Source attribute set to user.userprincipalname](https://mintcdn.com/benefitflow/lVQT3d-6nwhEERh-/images/entra-email-claim.png?fit=max\&auto=format\&n=lVQT3d-6nwhEERh-\&q=85\&s=b6481d233fa3b20f4691310457ff5d6a)

> [!WARNING]
>
> **Entra pre-fills a few claims of its own, and one of them looks like the right one but isn't.**
> If you see a claim whose name ends in `/emailaddress`, that is not the claim we need. Its name
> is a long schema URL rather than `email`, and it reads from `user.mail`. Add the `email` claim
> regardless of what's already listed. When you're done,
> your `email` claim sits alongside the pre-filled ones, which is what we expect to see.

![Attributes and Claims list in Entra showing the email claim sourced from user.userprincipalname alongside the default claims](https://mintcdn.com/benefitflow/lVQT3d-6nwhEERh-/images/entra-claims-list.png?fit=max\&auto=format\&n=lVQT3d-6nwhEERh-\&q=85\&s=f8b9e01db0d99cd5b8e46863188ba20b)

> [accordion] Which attribute to choose
>
> We match the `email` claim to the address each person was invited under, so the claim has to
> carry exactly that address.
>
> * **`user.userprincipalname`** is the name people sign in with. Every Entra account has one,
>   and in most organizations it's the work email. If it isn't (sign-in names on a different
>   domain, short usernames, `onmicrosoft.com` names, guest accounts), it won't match and
>   sign-in is refused.
> * **`user.mail`** is filled in from Exchange. It's blank for anyone without a mailbox, such as
>   service accounts and contractors, and a blank value means that person can't sign in.
>   Nothing in Entra warns you it's empty.
>
> Pick whichever one holds the real work address for the people who'll use BenefitFlow. If
> you're unsure, check with your BenefitFlow contact before you roll it out.

**5. Assign your users**

Go to **Users and groups** and assign the people who should have BenefitFlow access. Only
assigned users can sign in through this application.

![Users and groups page for the BenefitFlow application in Entra, with the Add user/group button highlighted](https://mintcdn.com/benefitflow/lVQT3d-6nwhEERh-/images/entra-assign-users.png?fit=max\&auto=format\&n=lVQT3d-6nwhEERh-\&q=85\&s=5d570bf991e1eb3cd6c3e832db5c0370)

**6. Copy the metadata URL**

Return to the **Single sign-on** page. Under **SAML Certificates**, copy the
**App Federation Metadata Url**. It's a link ending in `.xml`.

![SAML Certificates section in Entra with the App Federation Metadata Url highlighted](https://mintcdn.com/benefitflow/lVQT3d-6nwhEERh-/images/entra-metadata-url.png?fit=max\&auto=format\&n=lVQT3d-6nwhEERh-\&q=85\&s=be721f596ad93e66ff4ee99036c47652)

**7. Send us two things**

Email these to your BenefitFlow contact:

1. **The metadata URL** from Step 6.
2. **The email domain or domains your employees use** (for example, `yourcompany.com`). Include
   every domain in use if there's more than one.

That's everything we need to finish the setup on our side. See
[what happens next](https://docs.benefitflow.com/knowledge-base/sso.md#what-happens-next).

## If sign-in doesn't work

> [accordion] Someone signs in to Entra, then BenefitFlow says they have no account
>
> This is the common one, and it's almost never what it looks like. The sign-in worked. The email
> address Entra sent didn't match any BenefitFlow account. Two things to check:
>
> * **Did you complete Step 4?** Without the `email` claim, we receive no address at all.
> * **Is the address the `email` claim sends the same one that person was invited under?**
>   Someone invited as `jane@yourcompany.com` who signs in to Entra as
>   `jane.smith@yourcompany.com` won't match.
>
> Send us the name of the affected person and we can tell you exactly which address we received.

More fixes, plus how to add and remove people, are in [Single sign-on](https://docs.benefitflow.com/knowledge-base/sso.md).

## Related

> [card] [Single sign-on](https://docs.benefitflow.com/knowledge-base/sso.md)

> [card] [Team Management for Admins](https://docs.benefitflow.com/knowledge-base/team-management.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.