Skip to content

Clarify SAML NameID stability, scope, and non-NameID resolution #105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mcguinness wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Clarify SAML NameID stability, scope, and non-NameID resolution #105

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aa39c06
clarify SAML NameID stability, scope, and non-NameID resolution
mcguinness Jun 17, 2026
873b8ab
polish: split run-on sentences in SAML NameID processing bullets
mcguinness Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion draft-ietf-oauth-identity-assertion-authz-grant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,7 +283,7 @@ It is RECOMMENDED that the ID-JAG contain an `email` {{OpenID.Core}} and/or `aud

This specification defines the SAML NameID Subject Identifier Format for use in the `sub_id` claim {{RFC9493}}. The SAML NameID Subject Identifier Format is identified by the name `saml-nameid` and identifies a subject using a SAML 2.0 Assertion Subject `<NameID>` value within the context of a SAML issuer {{OASIS.saml-core-2.0-os}}.

This format is intended for deployments where the Resource Authorization Server resolves users using SAML SSO subject identifiers rather than the ID-JAG issuer's `iss` and `sub` values.
This format is intended for deployments where the Resource Authorization Server resolves users using a SAML `<NameID>` from its SSO trust relationship with the IdP Authorization Server, rather than the ID-JAG issuer's `iss` and `sub` values.

A Subject Identifier in this format MUST contain:

Expand Down Expand Up @@ -326,6 +326,14 @@ When the Resource Authorization Server resolves users by SAML Assertion Subject

When constructing a SAML NameID Subject Identifier, the IdP Authorization Server MUST derive its members from the SAML Assertion Subject `<NameID>` value it would use for SSO to the target Resource Authorization Server, or from an equivalent configured mapping that records the SAML `<NameID>` value and attributes the IdP Authorization Server would issue for that subject and Resource Authorization Server. Each optional field MUST be included exactly when the corresponding attribute is present on that `<NameID>` or in the configured mapping. The SAML NameID `sub_id` MUST identify the same subject as the ID-JAG `sub` claim.

The SAML NameID Subject Identifier is intended to function as a stable, cross-trust-domain identifier for the End-User. The following requirements apply to the SAML `<NameID>` value conveyed in this format:

* **Stability.** The `nameid` value MUST be a SAML `<NameID>` that the Resource Authorization Server treats as stable for SSO subject resolution. Transient NameID Formats (such as `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`, defined in Section 8.3.8 of {{OASIS.saml-core-2.0-os}}) MUST NOT be used, because their values change across sessions and cannot serve as a cross-trust-domain identifier. Other Formats (including `emailAddress` and `persistent`) MAY be used. The SAML NameID Subject Identifier inherits the lifecycle and subject-resolution properties of the underlying Format. For example, when `emailAddress` is used, the same considerations that apply to SAML SSO with mutable email identifiers (changes propagating to the relying party, reassignment risks) apply to the SAML NameID Subject Identifier.

* **Identifier scope.** A SAML `<NameID>` is unique within the context of the SAML issuer (`issuer`) and the Service Provider (as scoped by `sp_name_qualifier` when present), not globally unique within the issuer. NameIDs may be public (a single value for an End-User across all Service Providers) or pairwise (different values per Service Provider). When the IdP Authorization Server issues pairwise NameIDs, the `nameid` value placed in the SAML NameID Subject Identifier MUST be the value the IdP would issue to the SAML Service Provider corresponding to the target Resource Authorization Server. The IdP Authorization Server MUST maintain the mapping between the OAuth `client_id` of the Resource Authorization Server and the SAML Service Provider entity ID used for SSO with the corresponding application, so pairwise NameIDs resolve under the correct Service Provider scope. The IdP Authorization Server MUST NOT assume the `nameid` value identifies the same End-User across different Service Providers without the qualifying scope members.

* **Non-NameID subject resolution.** Some SAML deployments resolve users by a SAML attribute outside the `<Subject>` element (for example, an attribute in the `<AttributeStatement>` such as the `http://schemas.microsoft.com/identity/claims/objectidentifier` attribute used by Microsoft Entra ID). In those deployments, the SAML NameID Subject Identifier is not the correct vehicle. The IdP Authorization Server SHOULD convey the relevant attribute value as an additional claim in the ID-JAG so the Resource Authorization Server can perform subject resolution. The choice of attribute and identifier type is deployment-specific: a SAML Service Provider and Resource Authorization Server may use either pairwise (different values per Service Provider) or public (a single value across Service Providers) identifiers, depending on local needs. Immutable identifiers are preferred. Mutable identifiers (such as `emailAddress`) MAY be used for subject resolution, subject to the considerations described in the Stability requirement above. When the attribute is pairwise per Service Provider, the IdP Authorization Server MUST use the value scoped to the SAML Service Provider corresponding to the target Resource Authorization Server.

@aaronpk aaronpk Jun 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't love the suggestion of including arbitrary new claims in the ID-JAG that mirror the custom SAML attributes. If anything, there should be a single ID-JAG claim that all the custom claims live under to mirror the namespace of SAML attributes, otherwise there may be conflicts with other ID-JAG claims.

@mcguinness mcguinness Jun 19, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is overlap here with #100

The IdP AS may already need to map SAML Attributes to OIDC standard JWT and ID Token claims when a client exchanges a SAML Assertion for an ID Token and/or Refresh Token (which can be refreshed for an ID Token).

Additionally an IdP AS IdP could issue any number of SAML Attribute Statements that may be used for subject resolution (e.g customerId, accountId, partnerId, externalId, etc). SAML Attribute Statements have namespaces and can also be complex types that don't have 1:1 mappings to JSON values.

In my SAML to OIDC migration profile I had to define how to map SAML Attribute Statements to standard ID Token/UserInfo claims as well as private claims

https://mcguinness.github.io/connect-saml-profiles/draft-connect-saml-migration-profile.html#section-12.2

I think we may need to pull in some of this language here.

I don't think it makes sense to have the ID-JAG reflect full SAML Attribute Statements like I did for introspection

https://mcguinness.github.io/connect-saml-profiles/draft-connect-saml-migration-profile.html#name-delegate-saml-validation-wi

Its the IdP's job to transform/map the claims to an ID-JAG when needed and the claims will already be specific to the IdP. Outside of a few federations like InCommon there isn't standardized attributes for SAML.


The Resource Authorization Server MAY use `sub_id` for subject resolution when it supports the indicated Subject Identifier Format. The Resource Authorization Server MUST compare every member of the SAML NameID Subject Identifier that is part of the set of identifier fields it uses for subject resolution for that SAML issuer. The Resource Authorization Server MUST NOT resolve the subject using only the `nameid` value unless local policy explicitly defines `nameid` alone as the subject identifier for that SAML issuer. In particular, when the SAML Assertion Subject `<NameID>` is scoped to a Service Provider, the `sp_name_qualifier` value is part of the subject namespace.

If the Resource Authorization Server requires a SAML NameID Subject Identifier for subject resolution, it MUST reject the token request with an `invalid_grant` error as defined in {{Section 5.2 of RFC6749}} if any of the following is true:
Expand Down
Loading