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

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

If sign-in doesn’t work

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.

Single sign-on

Team Management for Admins

Last modified on November 20, 2026