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

# Single sign-on (SSO)

> How BenefitFlow single sign-on works, how to set it up with Okta or Microsoft Entra ID, and how to add and remove people once it's live.

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. BenefitFlow connects over SAML 2.0.

Setup takes your IT or identity administrator about 15 minutes. Pick the guide for your identity
provider:

> [card] [Okta](https://docs.benefitflow.com/knowledge-base/sso-okta.md)
>
> Create a SAML app in the Okta Admin Console.

> [card] [Microsoft Entra ID](https://docs.benefitflow.com/knowledge-base/sso-microsoft-entra.md)
>
> Create an enterprise application in the Entra admin center.

Using a different identity provider? Contact us before you start.

## How it works

> [!WARNING]
>
> **Email is what connects the two systems.** BenefitFlow matches each sign-in to an account by the
> email address your identity provider sends. That address has to be the same work email each person
> was invited under in BenefitFlow, or they'll be turned away.

Your identity provider sends us one attribute, `email`, when each person signs in. Their name and
everything else come from the BenefitFlow account they were invited under. Each provider guide
shows exactly where to set up `email`.

## What happens next

Once you've sent us your metadata URL and email domains, the rest runs in this order:

1. **We connect your identity provider** and switch single sign-on on for your organization.
2. **We set up your administrator account and test the sign-in ourselves.** If anything about the
   configuration is wrong, this is where it surfaces, and we'll come back to you.
3. **We confirm single sign-on is live** and hand over to your administrator.
4. **Your administrator adds the rest of your team.** Each new person is assigned in your identity
   provider and invited in BenefitFlow (see below).

From then on, your people go to `benefit-flow.com` and enter their work email. We recognize the
domain, send them to your company sign-in, and bring them back into BenefitFlow once they're signed
in.

## Adding and removing people

Single sign-on doesn't create BenefitFlow accounts on its own, and the two systems don't sync to
each other. Adding someone is a manual step in each one.

> [!WARNING]
>
> **A new person has to be added in both your identity provider and BenefitFlow.** Assign them to
> the BenefitFlow application in your identity provider, and invite them in BenefitFlow from **Team
> Management**. Do only one and they'll be turned away at sign-in. Assigned but not invited means
> there's no BenefitFlow account to land in. Invited but not assigned means your identity provider
> won't let them through. Use the same work email in both places.

1. **Assign them** to the BenefitFlow application in your identity provider.
2. **Invite them** in BenefitFlow, from **Team Management**, using the same work email.

![Invite teammates dialog in BenefitFlow with the full name, email, role, and user group fields](https://mintcdn.com/benefitflow/lVQT3d-6nwhEERh-/images/benefitflow-invite-user.png?fit=max\&auto=format\&n=lVQT3d-6nwhEERh-\&q=85\&s=2a0118f9d28cabe8c4e3054a883ad505)

To remove someone, unassign them from the BenefitFlow application or deactivate them in your
identity provider. Tell us as well if you want their BenefitFlow account fully deactivated.

## If sign-in doesn't work

> [accordion] Someone signs in at their company login, 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 your identity provider sent didn't match any BenefitFlow account. Two things to check:
>
> * **Is the `email` attribute set up?** Without it, we receive no address at all.
> * **Does the address match the invite?** Someone invited as `jane@yourcompany.com` whose identity
>   provider sends `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.

> [accordion] The person hasn't been invited to BenefitFlow yet
>
> Your BenefitFlow administrator can invite them from Team Management. Assigning someone in your
> identity provider isn't enough by itself.

> [accordion] Something else
>
> Contact us with the time of the attempt and the user's email address, and we'll trace it from
> our side.

## Common questions

> [accordion] Do our users still need a separate BenefitFlow login?
>
> No. Once single sign-on is live, their company login is the only credential they use for
> BenefitFlow.

> [accordion] What happens when someone leaves?
>
> Deactivate them in your identity provider, or unassign them from the BenefitFlow application,
> and they can no longer sign in. Tell us as well if you want their BenefitFlow account fully
> deactivated.

> [accordion] Is anything we exchange secret?
>
> No. 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.

## Related

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

> [card] [Signing in to BenefitFlow](https://docs.benefitflow.com/knowledge-base/signing-in.md)


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