Platform Selector


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

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


What Happens if a 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:

  • User upload – 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. See example in Foundry API documentation. 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. See User Registration in Single Sign-On for details.