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

SAML NameID And ComplyEQ SSO ID

How SAML NameID values map to user accounts during single sign‑on

Overview

SAML single sign‑on relies on specific identifiers to match users between your identity provider (IdP) and Foundry. This article explains how the SAML NameID, ComplyEQ SSO ID, and email address work together during authentication.

It also describes how Foundry:

  • Locates existing users during SSO
  • Updates user records
  • Creates new users using just‑in‑time provisioning

Quick Summary

To successfully sign in to Foundry using SSO, the NameID value in the identity provider’s SAML response must exactly match the user’s Foundry SSO ID.

  • Matching is case sensitive
  • For example, JaneDoe does not match janedoe
  • If a match is found, the user is logged in
  • If no match is found, the user sees an error stating that their account could not be connected

Setting the NameID in Your Identity Provider

When configuring ComplyEQ as a service provider or application in your identity provider, you must choose which user attribute is sent as the NameID in the SAML assertion.

This field may be labeled differently depending on the IdP:

  • Okta: Application username
  • Azure AD: Unique User Identifier
  • AD FS: Claim with a NameID format

Regardless of the label, this value becomes the NameID sent to ComplyEQ.

The NameID is critical because it links a user in your IdP to the corresponding user in Foundry. The value must be:

  • Unique
  • Always present
  • Stable over time

The NameID can be an email address, username, employee ID, GUID, or another unique identifier. While ComplyEQ does not require a specific format, we strongly recommend avoiding values that may change, such as email addresses tied to name changes.

The NameID must exactly match the user’s Foundry SSO ID, including capitalization.

How Foundry Finds a User During SSO

Foundry uses the following logic to locate or create a user when a SAML response is received.

First Match Attempt: NameID to Foundry SSO ID

When a user authenticates through the IdP, Foundry first attempts to match the NameID in the SAML assertion to a user whose SSO ID matches exactly.

This comparison is case sensitive.

Second Match Attempt: Email Attribute

If no match is found using the NameID, Foundry checks for an email attribute in the SAML assertion.

Foundry looks for a user who:

  • Does not already have an SSO ID, and
  • Has an email address that matches the email attribute

If a match is found, Foundry sends a verification email. After the user confirms their identity, Foundry assigns the SSO ID using the NameID value and logs the user in.

Creating a New User During SSO

If no existing user is found, Foundry creates a new user only if the Allow registration during SSO option is enabled in the IdP configuration.

When a new user is created:

  • The SSO ID is set to the NameID value
  • Other fields, such as name and email, are populated from SAML attributes or default IdP settings

If registration during SSO is not enabled, the user receives an error explaining why sign‑in failed.

Additional Details on User Matching

Foundry does not attempt to match users by first or last name, as this can lead to incorrect matches.

While email can be used as a fallback match, this approach is less reliable. The most consistent SSO experience occurs when:

  • The IdP NameID
  • And the Foundry SSO ID
    are always kept in sync.

What Happens if a User’s NameID Changes

If the NameID value changes in the identity provider, Foundry treats the next sign‑in attempt as a new user.

For example, if the NameID is based on email and the email address changes, Foundry will no longer recognize the user. In these cases, the user’s Foundry SSO ID must be updated to match the new NameID value.

Setting the User SSO ID in Foundry

Admins can set or update a user’s SSO ID in several ways:

  • Add Users: Upload a spreadsheet that includes SSO ID values
  • User Upload to Update: Download and re‑upload a user file with updated SSO IDs
  • Edit a User: Manually update a user’s SSO ID in the admin portal
    • Admins cannot update their own SSO ID
  • API: Update the sso_id field using a PATCH request to the appropriate endpoint

Provisioning New Users During SSO

Foundry can be configured to automatically create new users during SSO if they do not already exist. This option must be enabled in the identity provider configuration.