SAML NameID and NameID Format
NameID defines how a user is identified in SAML. Choosing the right NameID Format keeps your integration stable.
🪪 What is NameID?
NameID normally appears in Assertion/Subject inside the Response. The SP reads it from a validated assertion and includes the issuer when mapping an account.
Key points
- ✅ Issued by IdP and used by SP to map users.
- ✅ Choose between stable IDs or session-only IDs via the Format.
- ✅ You can reuse another attribute (e.g., email) as NameID in some setups.
📑 Common NameID Formats
Agree on the format up front; IdP and SP must match expectations.
Available NameID Formats
| Format | Description / Use case |
|---|---|
| persistent | An opaque long-lived identifier, usually scoped to an IdP/SP pair rather than shared across services. |
| transient | Changes per session; better for privacy-focused scenarios. |
| emailAddress | Uses email as NameID; common in SaaS integrations. |
| unspecified | No fixed format; relies on IdP/SP agreement. |
| X509SubjectName | Uses certificate Subject name; certificate-based environments. |
| WindowsDomainQualifiedName | DOMAIN\user format; Windows/AD integrations. |
| kerberos | Uses Kerberos principal; Kerberos-integrated environments. |
| entity | Uses entity ID as NameID; limited cases. |
How to choose
Decide between stability and privacy; then check implementation support.
- 🧭 For stable account matching, consider persistent or another non-changing identifier. Email addresses can change or be reassigned; do not automatically merge accounts solely by email.
- 🧭 Want less traceability: transient.
- 🧭 Verify IdP/SP support for the chosen Format.
⚙️ Configuration Tips
Format mismatches are a common cause of authentication failures. Align settings on both sides.
NameIDPolicy and requests
AuthnRequest can state the desired NameID Format via NameIDPolicy. If the IdP does not support it, authentication fails.
- Specify a Format in NameIDPolicy and expect failure if the IdP cannot provide it.
- When requesting persistent, confirm the IdP can issue and retain it.
- Even with unspecified, agree on what value will actually be sent.
Reissuing/changing NameID
ManageNameIDRequest/Response communicates identifier changes or termination. NameIDMappingRequest/Response requests an alternate format or namespace for the same subject. Check support and plan account migration separately.
- For persistent reissue, decide how to map to existing accounts.
- If ManageNameID is unsupported, agree on an account migration and notification process.
- Test NameID changes in staging to see the impact before production.
Common pitfalls
- ⚠️ Mismatch in expected NameID Format causes authentication failures.
- ⚠️ emailAddress risks changing if domains/users change.
- ⚠️ persistent IDs need a plan for reissue and existing account mapping.
🧯 Troubleshooting
Check for format mismatches or metadata drift first; it often narrows the cause quickly.
Checklist
- 🔍 Response > Assertion > Subject > NameID has the expected Format (after decryption when encrypted).
- 🔍 Distinguish NameIDPolicy in AuthnRequest from NameIDFormat in metadata.
- 🔍 SP is not restricting allowed NameID Formats inadvertently.