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

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

This guide is for your IT or identity administrator. It walks through creating a BenefitFlow
application in Okta 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 applications in the Okta Admin
Console, which means the **Super Administrator** or **Application Administrator** role.

## Before you begin

> [!WARNING]
>
> **The email address Okta 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 Okta in Step 3:

| What we call it | What Okta calls it | Value |
| - | - | - |
| ACS URL | Single sign-on URL | `https://benefit-flow-prod.auth.us-east-1.amazoncognito.com/saml2/idpresponse` |
| Entity ID | Audience URI (SP Entity ID) | `urn:amazon:cognito:sp:us-east-1_hH6QJvQla` |

Neither value is secret, and nothing you send back to us is secret either.

## Set up the application in Okta

**1. Create the application**

In the Okta Admin Console, go to **Applications and Resources**, then **Applications**, and
click **Create App Integration**.

Choose **SAML 2.0** and click **Next**. BenefitFlow connects over SAML, not OIDC.

![Create app integration dialog in Okta with SAML 2.0 selected](https://mintcdn.com/benefitflow/p1WB8gTh2DLv8LPI/images/okta-create-app-saml.png?fit=max\&auto=format\&n=p1WB8gTh2DLv8LPI\&q=85\&s=04bd2efa369d44ba8f8678b069b38afa)

**2. Name it**

On the **General Settings** page, set **App name** to `BenefitFlow` and click **Next**.

![General Settings page in Okta with BenefitFlow entered as the app name](https://mintcdn.com/benefitflow/p1WB8gTh2DLv8LPI/images/okta-general-settings.png?fit=max\&auto=format\&n=p1WB8gTh2DLv8LPI\&q=85\&s=57744ab06381a2735706dea9a38cc54d)

**3. Enter the two connection values**

On the **Configure SAML** page, fill in:

* **Single sign-on URL:** `https://benefit-flow-prod.auth.us-east-1.amazoncognito.com/saml2/idpresponse`.
  Leave **Use this for Recipient URL and Destination URL** checked.
* **Audience URI (SP Entity ID):** `urn:amazon:cognito:sp:us-east-1_hH6QJvQla`
* **Default RelayState:** leave blank.
* **Name ID format:** `EmailAddress`
* **Application username:** `Email`
* **Update application username on:** leave as is.

![Configure SAML page in Okta with the single sign-on URL, audience URI, EmailAddress name ID format, and Email application username filled in](https://mintcdn.com/benefitflow/p1WB8gTh2DLv8LPI/images/okta-configure-saml.png?fit=max\&auto=format\&n=p1WB8gTh2DLv8LPI\&q=85\&s=07d2ce24fed03627d749f2c1a1b19eda)

Click **Next**. The last page asks optional questions for Okta Support. Skip them and click
**Finish**.

**4. Add the email attribute**

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

Open the new application's **Sign On** tab, scroll to **Attribute statements**, and click
**Add expression**:

* **Name:** `email`
* **Expression:** `user.profile.email`

Click **Save**.

![Add expression dialog in Okta with Name set to email and Expression set to user.profile.email](https://mintcdn.com/benefitflow/p1WB8gTh2DLv8LPI/images/okta-add-email-expression.png?fit=max\&auto=format\&n=p1WB8gTh2DLv8LPI\&q=85\&s=44a43c83e0cbbb9f425b3bce86fa7634)

When you're done, Attribute statements should list the one `email` row.

![Attribute statements section in Okta listing one expression, email set to user.profile.email](https://mintcdn.com/benefitflow/p1WB8gTh2DLv8LPI/images/okta-attribute-statements.png?fit=max\&auto=format\&n=p1WB8gTh2DLv8LPI\&q=85\&s=c7b6425ed175ec885443a0d9506a4d16)

> [accordion] Why the email expression is user.profile.email
>
> `user.profile.email` is the primary email on each person's Okta profile. Okta requires it, so
> it's never blank. In most organizations it's the same address people use to sign in to Okta.
>
> **If that's not true in your org** (people's primary email in Okta differs from the address
> they use day to day), use whichever profile attribute holds the real work email instead. If
> you're unsure, send us a sample and we'll confirm it works before you roll it out.

**5. Assign your users**

Open the application's **Assignments** tab and assign the people who should have BenefitFlow
access. You can assign individuals or groups. Only assigned users can sign in through this
application.

![Assignments tab for the BenefitFlow application in Okta, with the Assign button](https://mintcdn.com/benefitflow/p1WB8gTh2DLv8LPI/images/okta-assign-users.png?fit=max\&auto=format\&n=p1WB8gTh2DLv8LPI\&q=85\&s=092efbe1d588afb4bd645c4c45b8f2a7)

**6. Copy the metadata URL**

Go back to the **Sign On** tab. Under **Metadata details**, copy the **Metadata URL**. It looks
like `https://yourcompany.okta.com/app/.../sso/saml/metadata`.

![Sign On tab of the BenefitFlow application in Okta, showing the Metadata URL with a Copy button](https://mintcdn.com/benefitflow/p1WB8gTh2DLv8LPI/images/okta-metadata-url.png?fit=max\&auto=format\&n=p1WB8gTh2DLv8LPI\&q=85\&s=07c7813fcda0fa4848cde419980d57e5)

**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 Okta, then BenefitFlow says they have no account
>
> The Okta sign-in worked, but the address Okta sent didn't match a BenefitFlow account. Check:
>
> * **Did you complete Step 4?** Without the `email` attribute, we receive no address at all.
> * **Is the primary email on that person's Okta profile the same one they were invited under?**
>   Someone invited as `jane@yourcompany.com` whose Okta primary email is
>   `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.