Category: Federation & SSO
Name Identifier
Also known as: NameID, SAML NameID, SAML subject identifier
Simply put
A Name Identifier (NameID) is the piece of a SAML login message that identifies which user the message is about. When one system logs a user in and vouches for them to another system, the NameID is the value that tells the receiving system who that user is. It can take different forms, such as an email address or a scrambled identifier that reveals no personal details.
Formal definition
In SAML 2.0, the NameID is the element (typically carried within the <Subject> of an assertion) that identifies the authenticated subject to the relying party. Its NameID Format determines the structure and semantics of the value, common formats include email address, persistent, and transient identifiers, and the format and value are generally determined by the Identity Provider's configuration. Best practice in many deployments is for the NameID to be non-volatile and opaque so it uniquely and stably identifies the subject without exposing personal information; the appropriate format depends on the SP's requirements and the IdP's release policy. Note that the NameID is an identifier asserted as part of the authentication result and is distinct from authorization decisions and from any additional SAML attributes released alongside it.
Why it matters
The NameID is the anchor that ties a federated login to a specific user account at the relying party. In a SAML 2.0 SSO flow, the receiving service provider (SP) uses the NameID from the assertion to determine which local account the authenticated session belongs to. If the NameID value or its format changes unexpectedly, for example, when an Identity Provider is reconfigured to release a different format, the SP may fail to match the returning user to their existing account, resulting in failed logins or, worse, the creation of duplicate or mismatched accounts. Because of this, the stability and format of the NameID are operationally significant decisions, not incidental configuration details.
Who it's relevant to
IAM and Federation Engineers
Engineers configuring SAML 2.0 SSO must decide which NameID Format to release from the Identity Provider and confirm that the service provider expects that same format. Choosing a stable, opaque persistent identifier where account continuity matters, versus a transient identifier where correlation should be avoided, directly affects whether returning users are matched to the correct account.
Security Architects
Architects weighing privacy and correlation risks benefit from understanding that an opaque, non-volatile NameID can uniquely identify a subject without exposing personal details such as email addresses. The choice of format shapes how much identifying information crosses the federation boundary and how consistently subjects can be tracked across sessions.
System Administrators Managing SP Integrations
Administrators onboarding service providers to an existing IdP need to reconcile the NameID format the SP requires with what the IdP's release policy provides. Mismatches in format or unexpected changes to the asserted value are a common source of failed logins and duplicate accounts at the relying party.
Inside NameID
NameID element
The XML element within a SAML 2.0 assertion's <saml:Subject> that carries the identifier for the authenticated principal, allowing the service provider to recognize the subject the assertion pertains to.
Format attribute
An attribute on the NameID that declares how the identifier value should be interpreted. Common formats include persistent, transient, emailAddress, unspecified, and entity, each conveying different semantics about stability and reusability of the value.
NameQualifier and SPNameQualifier
Optional attributes that scope the identifier, typically indicating the identity provider (NameQualifier) and the intended service provider (SPNameQualifier) domains within which the NameID is meaningful.
Identifier value
The actual string content of the element that identifies the subject. Depending on the format, this may be a stable opaque identifier, a one-time transient value, or an email address.
Persistent format identifier
A stable, typically pseudonymous identifier that remains consistent for the same subject across sessions, supporting account linking at the service provider over time.
Transient format identifier
A temporary identifier that is generally valid only for a single session and is not intended for correlation across logins, often used to preserve privacy.
Common questions
Answers to the questions practitioners most commonly ask about NameID.
Is the NameID the same thing as a username or login credential?
No. A NameID is an identifier used within a SAML 2.0 assertion to represent the subject (the authenticated principal) to a service provider. It is not a credential and plays no part in authentication itself; authentication happens at the identity provider before the assertion is issued. The NameID conveys who the authenticated subject is to the relying party, but it does not verify identity and is not presented as a secret. In many deployments the NameID may not even resemble a human-readable username, depending on the configured format.
Does the NameID determine what a user is allowed to access?
No. The NameID is an identification construct, not an authorization mechanism. It tells the service provider which subject the assertion concerns, but the access decision is made separately, typically by evaluating attributes, roles, or policies at the service provider or a downstream policy decision point. Conflating the NameID with entitlements is a common error; a subject identifier and the permissions granted to that subject are distinct concerns that should be handled separately.
Which NameID Format should be chosen when integrating a new service provider?
SAML 2.0 defines several formats, including persistent, transient, emailAddress, unspecified, and others. The appropriate choice depends on the service provider's requirements and privacy goals. A persistent format is typically used when the service provider needs a stable, opaque identifier that correlates the same subject across sessions, while a transient format is often used when no long-term correlation is desired. Because behavior varies by vendor and profile, confirm the exact format the service provider expects during onboarding rather than assuming a default.
What is the practical difference between a persistent and a transient NameID at runtime?
A persistent NameID is intended to remain stable for the same subject-provider pairing across multiple sessions, which supports account linking and consistent identification over time. A transient NameID is typically generated per session and is not intended to be reused or correlated across logins, which favors privacy. In most deployments this choice affects whether the service provider can maintain a durable local account mapping. The specific persistence guarantees depend on identity provider configuration.
How should a service provider handle a subject whose NameID value changes over time?
If the NameID value changes unexpectedly, the service provider may fail to match the incoming subject to an existing local account, which can result in duplicate accounts or lost access mappings. In most deployments a persistent format is selected specifically to avoid this. When change is unavoidable, some architectures rely on additional stable attributes for account matching rather than the NameID alone. The correct approach depends on the service provider's account-linking design and is generally decided during integration.
Can additional attributes be relied upon instead of, or alongside, the NameID for identifying a subject?
In many deployments service providers use the NameID as the primary subject identifier while also consuming attributes carried in the assertion for account matching, personalization, or authorization inputs. Whether an attribute can substitute for the NameID depends on the service provider's configuration and the stability and uniqueness of that attribute. Using an attribute for identification is a deployment decision and should not be assumed; the assertion's subject is formally represented by the NameID unless the integration explicitly specifies otherwise.
Common misconceptions
The NameID is what authenticates the user to the service provider.
The NameID is an identifier carried within an assertion; it supports identification of the subject. Authentication is performed by the identity provider, and the SAML 2.0 assertion as a whole conveys the authentication result. The NameID by itself does not verify who the principal is.
A NameID is always a stable, reusable value such as an email address or username.
The meaning and stability of a NameID depend on its Format attribute. Transient formats are intended to change per session and should not be used for persistent account linking, while persistent formats provide stability. Treating all NameID values as durable can break federation depending on configuration.
The NameID contains all the attributes a service provider needs about the user.
The NameID identifies the subject, but additional user attributes are typically conveyed through separate attribute statements in the assertion rather than embedded in the NameID. It is a subject identifier, not a general-purpose attribute container.
Best practices
Choose the NameID Format deliberately based on the use case: use persistent formats for durable account linking and transient formats where per-session, privacy-preserving identifiers are appropriate.
Agree on the NameID Format and value semantics between the identity provider and service provider during federation setup, since mismatches commonly cause account linking or login failures.
Avoid relying on transient NameID values for long-term user correlation, as they are generally not stable across sessions.
Where privacy is a concern, prefer opaque pseudonymous identifiers over directly identifying values such as email addresses in the NameID.
Populate NameQualifier and SPNameQualifier appropriately when identifier scoping matters, so the identifier is unambiguously interpreted within the intended IdP and SP domains.
Validate the containing SAML 2.0 assertion's signature and conditions before trusting the NameID, and treat the NameID as a subject identifier rather than as proof of authentication in isolation.
