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.
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>”.
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
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
firstname.lastname@example.org. 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_idproperty in a PATCH to
admin/registration_sets. See example in Foundry API documentation. When you POST a new user, you can also provide the
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.