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

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

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.

Single sign-on

Team Management for Admins

Last modified on October 29, 2026