commerce-canon/research/authentication-federation/saml-nameid-federation.md

# SAML NameID Federation

## Source Type

Standard. OASIS SAML 2.0 Core and Profiles for Web Browser SSO; NameID formats
and federation metadata conventions.

## Domain

Enterprise federation, single sign-on, assertion semantics, and cross-domain
identity correlation.

## Why This Source Matters

SAML 2.0 remains central to enterprise federation. NameID formats, assertion
subject statements, attribute statements, and IdP/SP metadata define how
enterprise identities cross organizational boundaries.

## Key Concepts

- **Identity Provider (IdP)**: asserts authentication and attributes about a
  subject to service providers.
- **Service Provider (SP)**: consumes assertions and establishes local session.
- **Assertion**: XML security token containing subject, conditions, authn
  statements, and attribute statements.
- **Subject / NameID**: identifier for the principal at the IdP; carries
  Format attribute defining syntax and semantics.
- **NameID formats**: transient, persistent, emailAddress, X509SubjectName,
  kerberos, entity, unspecified, and others.
- **Persistent NameID**: stable, opaque identifier for a principal at an IdP.
- **Transient NameID**: one-time identifier for a single federation session.
- **AttributeStatement**: SAML attributes (mail, eduPersonPrincipalName, group
  memberships) about the subject.
- **AuthnStatement**: authentication instant, session index, and context class.
- **AudienceRestriction**: scopes assertion to intended SP entity IDs.
- **Metadata**: XML describing IdP/SP endpoints, certificates, NameID formats,
  and supported attributes.
- **Affiliation / discovery**: federations aggregate metadata for trust circles.

## Relevant Terminology

| Term | Source meaning |
| --- | --- |
| Principal | Authenticated entity; identified by NameID in assertion. |
| NameID | Subject identifier chosen by IdP; format determines semantics. |
| Persistent NameID | Long-lived opaque ID stable for principal at IdP. |
| Transient NameID | Ephemeral ID for one session; privacy-preserving. |
| Subject | SAML assertion subject element holding NameID. |
| Attribute | Named property asserted about subject. |
| EntityID | Unique identifier for IdP or SP in metadata. |
| Assertion | Signed statement about authentication and attributes. |
| SessionIndex | Handle for single logout correlation. |
| Audience | Intended SP for assertion consumption. |

## Modeling Assumptions

- **NameID is the primary correlation key** between IdP and SP for account
  linking.
- **Format determines persistence and privacy**; persistent enables cross-
  session linking, transient prevents it.
- **Principal means authenticated subject**, not a pre-provisioned local user.
- **Attributes are asserted**, not authoritative directory records in the SP.
- **Trust is pairwise** between IdP and SP via metadata exchange.
- **Groups may appear as attributes**, not as first-class relationship tuples.
- **Federation operates across organizational boundaries**; each side
  maintains its own namespace.

## Identity-Canon Implications

- SAML **NameID** maps to **Identifier** or **Scoped Identifier** depending
  on format (persistent vs. transient).
- **Persistent NameID** supports **Synonymity Assertion** linking SP local
  Account to IdP identifier.
- **Transient NameID** maps to session-scoped **Scoped Identifier** with no
  cross-session synonymity.
- **Principal** in assertion maps to **Authenticated Subject** projection.
- **AttributeStatement** attributes map to **Claim** objects.
- **EntityID** maps to **Scope** identifier for IdP/SP.
- **AudienceRestriction** maps to Scope boundary for assertion validity.
- **Attribute-based group membership** maps to **Claim** (group attribute) or
  Membership hint, not canonical Group unless provisioned.
- Supports S02 (multi-scope accounts), S13 (strong link via persistent NameID).

## Terminology Conflicts

- **Principal vs. Subject**: SAML uses both; principal is authenticated entity,
  subject is XML element.
- **Principal vs. Authorization Principal**: SAML principal is auth subject,
  not Cedar principal.
- **Persistent vs. Pairwise**: SAML persistent NameID is IdP-wide stable;
  OIDC pairwise is RP-specific.
- **NameID vs. emailAddress format**: email as identifier conflates Identifier
  with contact attribute.
- **Attribute vs. Claim**: SAML attribute is XML element; canon Claim is
  issuer statement — compatible but different syntax.

## Candidate Canonical Mappings

| SAML concept | Candidate canonical concept |
| --- | --- |
| NameID (persistent) | Identifier |
| NameID (transient) | Scoped Identifier (session-bound) |
| NameID (emailAddress) | Identifier (with attribute conflation risk) |
| Principal | Authenticated Subject |
| Subject element | Protocol binding for Authenticated Subject |
| AttributeStatement attribute | Claim |
| EntityID (IdP/SP) | Scope identifier |
| Assertion | Credential / signed assertion |
| Audience | Scope boundary |
| SessionIndex | Session correlation reference (projection) |
| SP local account mapping | Synonymity Assertion |

## Open Questions

- Should persistent NameID map to strong Synonymity by default, or only after
  SP verification (S13)?
- How should eduPerson / SCHAC attribute vocabularies map to Profile vs. Claim?
- Does transient NameID session scope warrant a distinct Lifecycle State on the
  Scoped Identifier?
- Should federation metadata trust map to **Trust Relationship** with
  certificate Evidence Source?

## References

- SAML 2.0 Core — http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf
- SAML 2.0 Profiles — http://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf
- SAML NameID Format URIs — http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf (§8.3)
- REFEDS entity categories — https://refeds.org/category