Skip to content
English
Contact Support
  • There are no suggestions because the search field is empty.

SAML NameID And EVERFI SSO ID

Learn how the SAML NameID and EVERFI SSO ID interact. 

Matching Users During Single Sign-on

This page explains how the SAML NameID and EVERFI User SSO ID and email address interrelate in the context of single sign-on.

Additionally, this page explains how a new Foundry user can be created during SAML SSO, and an existing Foundry user can be updated during SSO.

Quick Summary

The quick summary is: for a user to single sign-on into Foundry, the identity provider’s SAML Response must have a NameID value that matches with a Foundry User’s SSO ID. The match criteria is case sensitive; JaneDoe will not match with janedoe. If the user can be found, then they are logged in. Otherwise, the user will get an error saying “Sorry, we were not able to connect to your account with <Organization Name>”.

SAMLNameID-600x392.png

Illustration of an extract from a SAML Response showing the NameID property and a screen capture of a Foundry User showing the SSO ID. The value of NameID and SSO ID must match for single sign-on to succeed.
 

Setting the NameID in the EVERFI Service Provider Configuration in your Identity Provider

When you configure EVERFI as a Service Provider or Application in your identity provider, your IDP most likely allows you to specific which IDP user property gets sent in the SAML Assertion NameID property, which might also be labeled in the IDP as application username (Okta), Unique User Identifier (Azure), a Claim with a Name ID format (Microsoft AD FS), or other nomenclature. Ultimately, however this property is labeled, it will be included in the SAML Assertion sent to EVERFI in an important SAML property called NameID.

The NameID is integral to linking a user in the IDP to the same user in EVERFI’s platform.

The NameID is the unique identifier for a User in the IDP. By definition, it must be unique within the IDP. The actual value can be a username, an email address, an integer ID, a global uniqueidentifier, a student or employee ID, or any other value, as long as it’s unique within your organization’s users, always exists, and is associated to a user. EVERFI does not care what the IDP provides in the NameID, but we advise that the value be both unique and unchangeable. Ideally, avoid using email address for the NameID since email addresses commonly change when a person changes their name. The SAML NameID value and the Foundry SSO ID must have the same case sensitivity. For example, a NameID of Jeff.McDaniel@stateu.edu will NOT match to a Foundry User SSO ID of jeff.mcdaniel@stateu.edu. Although the SAML Response may provide a NameID format, Foundry does not use the format property in any way.
 

How Foundry Finds a User during SSO

Below is the detailed logic flow on how Foundry attempts to find or create a user based on the properties in the SAML Response.

1. First Match Attempt: SAML NameID to Foundry User SSO ID

  • When a user who attempts to access EVERFI is authenticated by your IDP, your IDP sends to EVERFI a SAML Assertion containing the authenticated user’s NameID. EVERFI attempts to find this user by first matching a user in your organization with a SSO ID containing the provided NameID. If found, this user is then logged in. The match comparison is case sensitive; a NameID of JDoe will not match with a Foundry User SSO ID of jdoe.

2. Second Match Attempt: Email Attribute value to EVERFI User Email

  • If a user with the NameID cannot be found, EVERFI will use the mapped email Attribute in the SAML assertion, if there is one, to search for a user in your organization who does not already have a SSO ID and whose email address matches the mapped email attribute (if any) in the SAML assertion. If a user can be found, then EVERFI will send a verification email to that email address, asking the recipient to click a link in the email to verify their identity. Once the recipient clicks the link in the verification email, Foundry will update that user to have the SSO ID of the provided NameID (which may or may not be an email address) and log the user in.

3. Creating a Non-Matched User if Just-In-Time User Provisioning is set up

  • If the searches above fail to find a matching user, then EVERFI will create a new user if the “allow registration during SSO” checkbox is checked on the IdP configuration.

  • The newly created user will have the SSO ID set to that of the NameID value, with other user properties being set by corresponding assertion attributes (email, first name, last name, etc.) and by default values entered in the identity provider configuration in Foundry.

  • If the “allow registration during SSO” checkbox is not checked on the IdP configuration, then the user will see an error message saying explaining why they could not be logged in.


Additional Details on User Matching

  • EVERFI does not attempt to match a user on first and last name, since these values can result in a false match (common names like John Smith) or mismatches (Robert or Bob).
  • While you can use an Email attribute as a “backup” way to match users as described above in #2, we do not recommend relying on this. The most reliable way for single sign-on to work is to ensure your users’ IDP NameID and Foundry user SSO ID values are in sync.
 

What Happens if a User's NameID Changes?

Suppose your SAML NameID uses email address, and a person’s email address changes in the identity provider. Then the next time that user attempts to single sign-in to Foundry, then as far as Foundry is concerned, this is a brand new user. Therefore, if a user’s NameID value changes, then you must manually or programmatically update the Foundry User’s SSO ID accordingly as described in the next section.
 

Setting the User SSO ID in Foundry

You can set the SSO ID of your users in the following ways when adding or updating users:

  • Add Users  – a customer admin user in your organization can upload a spreadsheet of users
  • User upload to update – similar to the previous method, you can download a list of users in a spreadsheet, enter their SSO ID values into the spreadsheet, and then upload the spreadsheet to update the users
  • Edit a user in the customer portal – you can set a user’s SSO ID when adding them, or update a user’s SSO ID, one at a time. Note that an admin cannot update their own user’s SSO ID, however.
  • API – Update the user’s SSO ID in the API by setting the sso_id property in a PATCH to admin/registration_sets. When you POST a new user, you can also provide the sso_id.
 

Provisioning New Users During Single Sign-On

As an option, you can configure your identity provider in Foundry to create new users during single sign-on if the user doesn’t already exist in Foundry.