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 lives in the Subject of the SAML Response and is the identifier the SP uses to bind a user.
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 | Long-lived ID for stable user linkage. |
| 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.
- 🧭 Need reliable account matching: persistent or emailAddress.
- 🧭 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
NameIDMappingRequest/Response can reissue NameIDs, but many IdPs do not support it; define an operational process for changes.
- For persistent reissue, decide how to map to existing accounts.
- If mapping is unsupported, prepare a manual change and notification flow with the IdP admin.
- 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
- 🔍 Subject > NameID contains the expected Format.
- 🔍 NameIDPolicy / Format in metadata matches expectations.
- 🔍 SP is not restricting allowed NameID Formats inadvertently.