OpenID Connect Migration Profile for SAML 2.0 Service Providers

1.1. Non-Goals

The profile is scoped to federation interoperability and identity continuity. It does NOT define:¶

• API authorization architectures, scope design, or resource-server authorization policy;¶

• entitlement systems or portable role/group authorization;¶

• provisioning, SCIM integration, or account-lifecycle workflows;¶

• runtime authorization policy expression or evaluation;¶

• governance models (approval, attestation, audit, segregation of duties);¶

• continuous access evaluation protocols (CAEP and similar);¶

• migration methodology (rollout patterns, cutover sequencing); or¶

• generalized SAML feature parity: SAML SLO, AuthzDecisionStatement, AttributeQuery, SP-specific extensions, and Holder-of-Key SubjectConfirmation are out of scope.¶

2.1. Requirements Notation

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

2.2. Terminology

This document uses the terms "authorization server", "client", "client identifier", "issuer", and "scope" from OAuth 2.0, OAuth 2.0 Authorization Server Metadata, Token Exchange, and OpenID Connect. It uses the terms "Identity Provider", "Service Provider", "entityID", "Assertion", "Attribute", "AttributeStatement", "AuthnStatement", and "AuthnContext" from SAML 2.0.¶

For the purposes of this document:¶

SAML IdP Entity ID:

The SAML entityID of the asserting party that issues SAML assertions for the deployment.¶

SAML SP Entity ID:

The SAML entityID of the relying party deployment that receives SAML assertions. In common SAML deployments, this is also the audience value used for that relying party.¶

Migration Client:

An OAuth 2.0 or OpenID Connect client that has a saml_sp_entity_id registered and represents an existing SAML SP relationship. This document uses "client" as a shorthand for Migration Client when the context is clear.¶

Subject Continuity:

The property that the same end-user is represented to the migrated relying party by a stable identifier that does not require account relinking.¶

Local Account:

The authorization server's internal account record for the end-user to which the SAML assertion is linked for token issuance and claim release.¶

Stable Local Subject Key:

A non-reassignable, unique local identifier for the resolved Local Account, used as input when this profile requires a derived subject value. It MUST be stable for the lifetime of the account, MUST be unique within the authorization server's namespace, and MUST NOT be a user-facing mutable attribute such as an email address, username, or display name. Suitable examples include an opaque internal account UUID or an LDAP entryUUID.¶

Authorization Basis:

An explicit policy statement, established prior to processing of a SAML assertion, that authorizes a specific Migration Client to receive a specific output (token type, scope, target service, or claim set) for a resolved Local Account under a bound saml_sp_entity_id. An Authorization Basis MAY come from static configuration, administrative consent, a previously recorded authorization grant at the same authorization server, or another policy mechanism that is established before the SAML input is processed.¶

6.1. saml_sp_entity_id

This document defines the saml_sp_entity_id client metadata parameter.¶

The saml_sp_entity_id value is a string that identifies the SAML 2.0 SP Entity ID to which the OAuth client is bound.¶

When saml_sp_entity_id is present:¶

• its value MUST exactly match the SAML SP Entity ID used in the existing SAML deployment;¶

• the authorization server MUST bind the client registration to that SAML SP relationship for purposes of subject continuity and claim release policy;¶

• the authorization server MAY allow multiple OAuth clients to share the same saml_sp_entity_id when local policy determines that those clients represent the same historical relying-party relationship;¶

• the authorization server MUST reject registration if the value is unknown, disallowed, or local policy does not authorize the client to use that binding; and¶

• the authorization server MUST ensure that the client authenticated at runtime is one of the clients authorized to use that saml_sp_entity_id.¶

An authorization server MAY support saml_sp_entity_id for dynamic client registration, static client registration, or both. For statically registered clients, the saml_sp_entity_id binding MAY be established through administrative configuration rather than a client registration request.¶

Because this profile is defined only for confidential clients, an authorization server MUST NOT enable this profile for a public client registration.¶

6.2. saml_idp_entity_id

This document also defines saml_idp_entity_id as an OPTIONAL client metadata parameter. It carries the same syntax and semantics as the authorization server metadata parameter of the same name (Section 7.1), applied to a single client registration. It exists for SAML deployments in which the IdP issues per-SP entityIDs rather than a single global entityID (multi-tenant SaaS IdPs, federation hubs, per-SP audit or compliance isolation).¶

When present, the client-level value overrides the authorization server metadata default for assertions submitted by the authenticated client. The authorization server MUST validate the SAML Assertion Issuer (and the SAML Response Issuer, when a Response wrapper is submitted) against the effective saml_idp_entity_id for the authenticated client.¶

This binding is security-critical for the same reasons as saml_sp_entity_id: the authorization rules in Section 6.1.1 apply equally to per-client saml_idp_entity_id. Anonymous or open dynamic registration MUST NOT be permitted to set or change this value.¶

Migration Clients learn their effective saml_idp_entity_id through their registration mechanism: administrative configuration (static), the RFC 7591 registration response (dynamic), or RFC 7592 retrieval. At runtime, the client observes the IdP's effective entityID directly from the SAML Response or Assertion Issuer element; mismatch with the registered value produces an invalid_request rejection (see Section 9.3). This profile does not expose per-client values through authorization server metadata.¶

6.3. saml_metadata_uri

This document also defines saml_metadata_uri as an OPTIONAL client metadata parameter, with the same syntax and semantics as the authorization server metadata parameter of the same name (Section 7.2), applied to a single client registration. It is intended for deployments that use per-client saml_idp_entity_id and exchange SAML metadata on a per-relationship basis.¶

When registered, the URI MUST resolve to a SAML metadata document whose EntityDescriptor entityID exactly matches the client's effective saml_idp_entity_id. The validation rules in Section 7.2 (HTTPS, EntityDescriptor verification, signature handling) apply unchanged. When present, the client-level value overrides the authorization server metadata default for SAML key material and other IdP metadata used to validate assertions submitted by this client.¶

7.1. saml_idp_entity_id

This document defines the saml_idp_entity_id authorization server metadata parameter.¶

The saml_idp_entity_id value is a string that identifies the SAML 2.0 IdP Entity ID bound to the OAuth issuer.¶

When saml_idp_entity_id is present:¶

• it MUST equal a SAML IdP Entity ID used by the corresponding SAML IdP;¶

• it MUST identify a SAML IdP that is operated by or under the administrative control of the same entity that operates the OAuth authorization server identified by this OAuth issuer;¶

• it is the default value against which incoming SAML assertion issuers are validated when no per-client saml_idp_entity_id (Section 6.2) is registered for the authenticated client.¶

In deployments where every Migration Client registers a per-client saml_idp_entity_id override, the authorization server metadata value MAY be omitted. The authorization server MUST nevertheless ensure, for every authenticated client, that an effective saml_idp_entity_id is configured before consuming SAML input from that client; absence of both the AS-level and client-level values for an authenticated client MUST cause the SAML input to be rejected.¶

The OpenID Connect iss claim and OAuth authorization server issuer metadata value remain OAuth issuer identifiers. They are not required to equal any SAML IdP Entity ID, and they commonly will not, because OAuth issuer values are HTTPS URLs with OAuth-specific discovery semantics.¶

7.2. saml_metadata_uri

This document defines the saml_metadata_uri authorization server metadata parameter.¶

The saml_metadata_uri value is an HTTPS URI that resolves to the SAML metadata document describing the default SAML IdP entity bound to the OAuth issuer. When per-client saml_idp_entity_id overrides are in use, this authorization server metadata value is the default; clients MAY register a per-client saml_metadata_uri override (Section 6.3) for SAML metadata describing their specific SP-IdP relationship.¶

When saml_metadata_uri is present:¶

• the referenced SAML metadata MUST describe the effective saml_idp_entity_id for the same context (the authorization server metadata saml_idp_entity_id for the AS-level URI, or the client-level saml_idp_entity_id for a per-client URI);¶

• any implementation that fetches saml_metadata_uri MUST verify that the retrieved document is a well-formed SAML metadata document containing an EntityDescriptor whose entityID attribute exactly matches the effective saml_idp_entity_id for the same context; if this validation fails, the retrieved document MUST NOT be used;¶

• if the retrieved SAML metadata document includes an XML signature, implementations SHOULD validate that signature against a pre-configured trust anchor before using the document;¶

• the authorization server SHOULD make the metadata available in a form suitable for standard SAML metadata processing;¶

• clients and migration tooling MAY use the metadata to correlate the OAuth issuer with the pre-existing SAML trust configuration.¶

The SAML metadata document referenced by saml_metadata_uri SHOULD include an AdditionalMetadataLocation element pointing at the authorization server metadata document for the bound OAuth issuer, with the namespace attribute set to a URI identifying the relevant metadata format (for example, https://datatracker.ietf.org/doc/html/rfc8414 for OAuth authorization server metadata, or https://openid.net/specs/openid-connect-discovery-1_0.html for OpenID Provider configuration). This forms a bidirectional binding between the SAML IdP entity and the OAuth issuer, both of which can be verified through their respective protocol metadata.¶

7.3. token_exchange_requested_token_types_supported

This document defines the token_exchange_requested_token_types_supported authorization server metadata parameter.¶

The token_exchange_requested_token_types_supported value is a JSON array of strings containing the token type URIs that the authorization server accepts as requested_token_type values for SAML token exchange under this profile.¶

If the authorization server publishes metadata and supports Token Exchange under this profile, it SHOULD include this metadata value.¶

When token_exchange_requested_token_types_supported is present:¶

• each value MUST be one of urn:ietf:params:oauth:token-type:refresh_token, urn:ietf:params:oauth:token-type:id_token, or urn:ietf:params:oauth:token-type:access_token;¶

• if urn:ietf:params:oauth:token-type:id_token is included, the authorization server MUST be an OpenID Provider; and¶

• if urn:ietf:params:oauth:token-type:access_token is included, the authorization server MUST support the target-selection processing defined by the Token Exchange access token rules for access token requests.¶

This profile intentionally limits requested_token_type to these three values. Other token type URIs defined by [RFC8693], such as urn:ietf:params:oauth:token-type:jwt, are outside the scope of this profile.¶

7.4. introspection_token_types_supported

This document defines the introspection_token_types_supported authorization server metadata parameter.¶

The introspection_token_types_supported value is a JSON array of strings. Each string is a token type URI identifying a token format that the authorization server accepts for direct introspection at its introspection endpoint according to Section 10.¶

When introspection_token_types_supported includes urn:ietf:params:oauth:token-type:saml2:¶

• the authorization server's introspection_endpoint metadata MUST be present;¶

• the introspection endpoint MUST accept the request pattern defined in Section 10;¶

• the authorization server SHOULD accept token_type_hint=urn:ietf:params:oauth:token-type:saml2.¶

7.5. Capability and Metadata Matrix

The following table summarizes the authorization server metadata used to signal capabilities defined by this profile.¶

Omission of token_exchange_requested_token_types_supported or introspection_token_types_supported does not imply support for the corresponding capability. A client or migration tool MUST NOT assume support for Token Exchange requested token types or direct SAML assertion introspection unless the relevant metadata or an equivalent administrative configuration indicates that support.¶

7.6. SAML Key Material

This document does not define an authorization server metadata parameter for SAML signing keys or encryption keys. That omission is intentional.¶

SAML keys are published and processed through SAML metadata and KeyDescriptor elements, while OAuth and OpenID Connect signing keys are published and processed through jwks_uri or jwks. Even when the same underlying key material is reused, it MUST be published and validated using the metadata and encoding rules of each protocol separately.¶

7.7. Federation Metadata Coexistence

A deployment migrating from SAML 2.0 to this profile typically operates both protocols in parallel for some period. The two protocols publish metadata through independent mechanisms that this profile does not unify: SAML 2.0 metadata as EntityDescriptor documents ([SAML2-METADATA]), OAuth/OIDC metadata at the .well-known/oauth-authorization-server and .well-known/openid-configuration endpoints ([RFC8414], [OIDC-DISCOVERY]). Both can be published from the same authority simultaneously.¶

Deployments SHOULD observe the following during parallel operation:¶

• The SAML IdP entityID and the OAuth issuer identify the same administrative authority but remain distinct values used in their own protocol contexts; see Section 8.4 for the validation rule, including incidental string equality.¶

• SAML signing keys (published via KeyDescriptor) and OAuth/OIDC signing keys (published via jwks_uri) rotate on independent schedules. A SAML-side key rollover does not affect ID Token signature validation, and a JWS-side rollover does not affect SAML assertion signature validation. Deployments SHOULD coordinate rollover windows to avoid cross-protocol confusion in operational tooling.¶

• The bidirectional metadata pointer described in Section 7.2 (SAML metadata AdditionalMetadataLocation referencing the OAuth/OIDC metadata document, and AS metadata saml_metadata_uri referencing the SAML metadata document) is OPTIONAL but RECOMMENDED for discovery tooling during the migration period. It allows administrators and federation registries to traverse from either side to the other.¶

This profile does not alter the discovery flow for either protocol, and does not define a mechanism for retiring the SAML side of a deployment or archiving SAML metadata after migration completes. Those operational decisions are outside the profile.¶

8.1. Accepted SAML Inputs

This profile uses an assertion-centric processing model: the effective security token is always one SAML Assertion. The submitted SAML input MUST be either:¶

• a signed SAML Assertion; or¶

• a signed SAML Response containing exactly one bearer Assertion. When a Response wrapper is submitted, the authorization server extracts the enclosed assertion and treats it as the effective assertion.¶

The SAML input MUST contain exactly one unencrypted SAML 2.0 bearer assertion. Encrypted assertions, SAML protocol messages other than Response, and assertions using subject confirmation methods other than bearer are out of scope.¶

The token type identifier urn:ietf:params:oauth:token-type:saml2 identifies both input forms. The Response wrapper is a transport convenience that the Migration Client may forward directly from the SAML SP exchange; it carries no independent authorization semantics under this profile.¶

8.2. Response Wrapper Processing

If a signed SAML Response is submitted, the authorization server:¶

• MAY use the response signature to establish integrity and SAML Response Issuer authenticity for the enclosed Assertion when that Assertion is not independently signed;¶

• MUST NOT treat successful validation of a SAML Response signature as proof that response-level fields such as Destination, Consent, or Response/@InResponseTo have been validated;¶

• MUST NOT allow response-level fields by themselves to determine subject continuity, claim release, or target binding under this profile;¶

• MUST verify that the top-level StatusCode value is urn:oasis:names:tc:SAML:2.0:status:Success;¶

• MUST reject the response if a subordinate StatusCode element is present; and¶

• MAY ignore StatusMessage and StatusDetail except for logging or diagnostics.¶

This profile does not define full response-level protocol processing. Deployments that require additional response-level checks MUST perform them outside this profile before or during extraction of the effective Assertion. Such additional checks SHOULD include, at minimum, verification that Response/@Destination matches the intended endpoint, validation that Response/@InResponseTo, if present, corresponds to a previously issued <AuthnRequest> ID, and confirmation that the Response/@ID value has not been replayed.¶

8.3. Encrypted Content

This profile does not define processing of encrypted SAML content. The authorization server MUST reject any submitted SAML input that is itself an EncryptedAssertion, and MUST reject any effective assertion containing EncryptedID or EncryptedAttribute elements.¶

In SAML deployments that require encryption between the IdP and SP, the Migration Client, acting as the SAML SP, is responsible for decrypting the SAML input using the SP's decryption key before submitting it under this profile. The plaintext SAML input the Migration Client submits MUST satisfy the signature requirements in Section 8. In practice, this means the IdP MUST sign the inner Assertion independently, since a signature on the enclosing Response element does not survive decryption of an EncryptedAssertion it contains.¶

The introspection pattern does not eliminate the SAML SP-side decryption key in encryption-required deployments, because that key is held by the SAML SP and not by the authorization server.¶

8.4. SAML and OAuth Issuer Boundary

This profile uses distinct issuer identifiers from different protocol contexts:¶

• SAML Response Issuer: the value of the SAML Response/Issuer element, when a SAML Response wrapper is submitted;¶

• SAML Assertion Issuer: the value of the effective SAML Assertion/Issuer element;¶

• Trusted SAML IdP Entity ID: the effective saml_idp_entity_id for the authenticated client, which is the client-level saml_idp_entity_id (Section 6.2) when registered, otherwise the authorization server metadata value (Section 7.1); and¶

• OAuth issuer identifier: the authorization server issuer value used in OAuth authorization server metadata and as the OpenID Connect ID Token iss claim.¶

The SAML Assertion Issuer MUST match the Trusted SAML IdP Entity ID. When a SAML Response wrapper is submitted, the SAML Response Issuer MUST also match the Trusted SAML IdP Entity ID.¶

The OAuth issuer identifier and the Trusted SAML IdP Entity ID identify related but distinct protocol issuers. The iss claim in an ID Token issued under this profile MUST be the OAuth issuer identifier, not the SAML Assertion Issuer or SAML Response Issuer.¶

The authorization server MUST NOT copy a SAML issuer value into the ID Token iss claim or use a SAML issuer value as a substitute for OAuth issuer metadata.¶

The OAuth issuer identifier and the Trusted SAML IdP Entity ID MAY have identical string values when a deployment co-locates the SAML IdP and the OAuth authorization server. Such equality is incidental: each value is still used in its own protocol context, and validation still uses each value through its own metadata and signature path.¶

8.5. Signature, SAML Issuer, and Audience Binding

The authorization server MUST:¶

1. determine the effective Assertion to be processed:¶

   • if the submitted SAML input is an Assertion, that Assertion is the effective assertion and it MUST be signed;¶

   • if the submitted SAML input is a Response, that Response MUST be signed, it MUST contain exactly one enclosed Assertion, and that enclosed Assertion becomes the effective assertion for the remaining rules in this section;¶

2. validate the signed SAML element or elements using SAML metadata and SAML key material, not JOSE metadata;¶

3. if the submitted SAML input is a Response, verify that:¶

   • the SAML Response/Issuer value matches the Trusted SAML IdP Entity ID defined in Section 8.4;¶

   • the top-level Response/Status/StatusCode/@Value is urn:oasis:names:tc:SAML:2.0:status:Success; and¶

   • no nested Response/Status/StatusCode/StatusCode element is present;¶

4. validate the effective Assertion according to the assertion processing rules in [SAML2-CORE] Section 2, including Assertion/Issuer ([SAML2-CORE] Section 2.3.3), subject and subject confirmation ([SAML2-CORE] Sections 2.4-2.4.1.3), and conditions ([SAML2-CORE] Section 2.5), enforcing both Conditions/@NotBefore and Conditions/@NotOnOrAfter;¶

5. verify that the effective SAML Assertion/Issuer value matches the Trusted SAML IdP Entity ID defined in Section 8.4;¶

6. verify that the effective Assertion contains at least one AudienceRestriction element;¶

7. verify that the bound saml_sp_entity_id appears as an Audience value in every AudienceRestriction element in the effective assertion, since multiple AudienceRestriction elements are conjunctive under [SAML2-CORE] Section 2.5.1.4 (each restriction must be satisfied independently). Additional Audience values within each AudienceRestriction are permitted and MUST NOT by themselves invalidate the assertion; and¶

8. reject the SAML input if the authenticated client, the saml_sp_entity_id registered to that client, and the validated Audience matching that saml_sp_entity_id do not all align, as required by the three-way binding in Section 4.¶

An authorization server consuming SAML input under this profile MUST reject any encrypted assertion, any submitted SAML input that is neither an Assertion nor a Response as defined by this profile, or any assertion using a subject confirmation method outside this profile. Endpoint-specific error behavior is defined by Section 9.3 and Section 10.3.¶

8.6. Bearer Subject Confirmation Data Validation

The authorization server MUST identify at least one usable SubjectConfirmation element with the bearer method URI (urn:oasis:names:tc:SAML:2.0:cm:bearer). If multiple bearer SubjectConfirmation elements are present, any one valid bearer confirmation is sufficient. For a usable bearer SubjectConfirmationData:¶

• NotOnOrAfter, if present, MUST be in the future at the time of processing;¶

• Recipient, if present, MUST have been validated by the Migration Client as part of its SAML SP processing before the assertion is submitted. The authorization server SHOULD additionally verify that Recipient is consistent with the ACS URLs registered for the bound saml_sp_entity_id as a defense-in-depth measure, and MUST reject the assertion if Recipient identifies the authorization server's own token endpoint or introspection endpoint;¶

• InResponseTo, if present, MUST be validated either by the component that handled the front-channel SAML exchange or by equivalent state known to the authorization server;¶

• if InResponseTo is absent, the assertion MAY still be accepted, except that deployments requiring SP-initiated request correlation for the bound SAML relationship MUST reject such assertions;¶

• Address, if present, MUST be validated either by the component that handled the front-channel SAML exchange or by deployment-specific means available to the authorization server; and¶

• if any present value cannot be validated under the preceding rules, the authorization server MUST reject the assertion as unusable under this profile.¶

The primary forwarding-prevention guarantee in this profile is the three-way binding defined in Section 4, not Recipient validation.¶

8.7. Replay and Freshness

The authorization server MUST enforce any applicable SAML one-time-use, replay-prevention, assertion freshness, and proxying restrictions associated with the trusted SAML deployment.¶

At minimum, the authorization server MUST detect reuse of the same Assertion/@ID value from the same SAML Assertion Issuer until the assertion's validity window or local freshness window has expired. Whether reuse within that window is accepted, rejected, or further constrained by the authenticated client and bound saml_sp_entity_id is a deployment policy decision; a stricter rule, where stated below, takes precedence.¶

The replay-detection state MUST be shared across all endpoints that consume SAML input under this profile; an Assertion/@ID consumed at the Token Exchange endpoint MUST be visible to replay detection at the introspection endpoint, and vice versa.¶

If the SAML assertion's Conditions element includes a OneTimeUse condition, the authorization server MUST treat the assertion as exhausted immediately after its first successful use and MUST reject any subsequent submission of the same assertion, even within its validity window.¶

An active introspection response or successful Token Exchange response does not, by itself, require the assertion to be treated as exhausted unless local replay policy or SAML OneTimeUse semantics require that result.¶

A client retry of a transient-failure response (network error, timeout, authorization server overload) using the same SAML assertion is not a replay attack. Authorization servers SHOULD distinguish idempotent retries from replay attempts -- for example, by recognizing that the same authenticated client is submitting the same Assertion/@ID within a short window after a non-success response, and returning the same outcome rather than rejecting as replay. Deployments enforcing SAML OneTimeUse cannot offer this accommodation, since OneTimeUse consumes the assertion on first successful use regardless of client intent.¶

Authorization servers SHOULD permit a limited clock skew tolerance when evaluating time-based conditions such as Conditions/@NotBefore, Conditions/@NotOnOrAfter, and SubjectConfirmationData/@NotOnOrAfter. Any clock skew allowance MUST be consistent with local security policy and SHOULD NOT exceed five minutes, in accordance with [SAML2-CORE] Section 2.5.1.2.¶

When an AuthnStatement is present, the authorization server SHOULD verify that the time elapsed since AuthnStatement/@AuthnInstant does not exceed a deployment-configured freshness window. In the absence of a stricter local policy, a maximum freshness window of 8 hours is RECOMMENDED, consistent with typical enterprise SSO session durations. This assertion-age check is independent of Conditions/@NotOnOrAfter and SessionNotOnOrAfter.¶

Client authentication does not replace SAML assertion validation. A valid client cannot cause an invalid or misbound SAML assertion to become acceptable.¶

9.1. Request

The client makes a Token Exchange request to the token endpoint using the parameters described below.¶

The following non-normative example requests an ID Token from a SAML assertion:¶

POST /token HTTP/1.1
Host: as.example.edu
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Asaml2
&subject_token=PHNhbWxwOlJlc3BvbnNlLi4u
&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token
&scope=openid%20profile%20email
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIs...

The request parameters are summarized below:¶

grant_type:¶

REQUIRED. The value urn:ietf:params:oauth:grant-type:token-exchange.¶

subject_token:¶

REQUIRED. The base64url-encoded octet sequence, as defined in Section 5 of [RFC4648], of the XML serialization of either:¶

• a signed SAML 2.0 <Assertion> element obtained for the existing SAML SP relationship; or¶

• a signed SAML 2.0 <Response> containing exactly one bearer <Assertion> for that relationship.¶

The encoded value MUST NOT be line wrapped and SHOULD NOT include padding characters (=) (following [RFC7522]). Clients using libraries that emit padding by default SHOULD strip trailing = before sending; authorization servers SHOULD accept padded values for interoperability. When a SAML <Response> is supplied, it is a signed wrapper from which the effective assertion is extracted per Section 8.¶

subject_token_type:¶

REQUIRED. The value urn:ietf:params:oauth:token-type:saml2. When a SAML <Response> wrapper is supplied, this token type identifies the effective enclosed SAML 2.0 assertion rather than the wrapper element itself.¶

requested_token_type:¶

REQUIRED. This profile permits only the values shown in the following table.¶

[RFC8693] marks requested_token_type as OPTIONAL at the Token Exchange protocol level. This profile narrows that rule: an omitted requested_token_type MUST be rejected with invalid_request. The three output types defined here have incompatible processing paths -- refresh tokens establish persistent sessions, ID Tokens are short-lived identity assertions, and access tokens require target service resolution -- so no default value is safe. Explicit client intent is required to avoid this ambiguity.¶

Target-selection processing for access token requests is defined in Section 9.2.1.¶

scope:¶

Conditional. The scope requirement depends on requested_token_type, as defined above. This profile permits ordinary OAuth scope values in addition to OpenID Connect scopes.¶

This profile does not define a token-endpoint parameter for fine-grained claim selection. Claims included in a directly issued ID Token, and claims later made available through UserInfo, are determined by the granted scope, the rules in Section 13, and the claim release policy for the relying-party relationship represented by the bound saml_sp_entity_id.¶

resource:¶

OPTIONAL. For access token requests, one or more resource indicators as defined by [RFC8707]. Clients requesting an access token under this profile SHOULD send a single resource value when a resource URI is known.¶

audience:¶

OPTIONAL. For access token requests, one or more logical target service identifiers as defined by [RFC8693].¶

The target-selection rules for resource and audience depend on requested_token_type, as defined above.¶

This profile does not define the use of actor_token, actor_token_type, or authorization_details. The authorization server MUST reject any Token Exchange request that includes any of these parameters with invalid_request. Actor-based delegation is outside the migration use case and would establish a delegation chain that the SAML assertion does not authorize. authorization_details processing is not defined by this profile.¶

Client authentication at the token endpoint uses the client's registered OAuth 2.0 client authentication method (see Section 6). The authenticated client MUST be authorized for the saml_sp_entity_id that matches the SAML assertion audience.¶

9.2. Authorization Server Processing

9.3. Error Response

If the request is malformed, the authorization server MUST return an error response as defined by [RFC6749] and [RFC8693].¶

The authorization server MUST use invalid_request for malformed or internally inconsistent Token Exchange parameters, including SAML input that is invalid, expired, audience-mismatched, encrypted, supplied in an unsupported wrapper form, wrapped in a SAML Response whose Status is not acceptable under this profile, or otherwise unusable under this profile.¶

The authorization server SHOULD use:¶

• unauthorized_client when the authenticated client is not permitted to use the bound saml_sp_entity_id relationship or the requested token type;¶

• invalid_target when the resource and audience parameters are missing, malformed, inconsistent, unknown, or unacceptable for the requested access token; and¶

• invalid_scope when the requested scope cannot be granted.¶

The authorization server SHOULD also use invalid_request when: the assertion cannot be resolved to exactly one active Local Account; the assertion is rejected as replay or otherwise exhausted under Section 8; or a currently asserted stable subject identifier conflicts with an existing persisted mapping and no explicitly authorized administrative remapping exists.¶

10.1. Request

The client makes an introspection request to the introspection endpoint using the parameters described below.¶

The following non-normative example asks the authorization server to validate a SAML assertion and return normalized JSON claims and SAML protocol metadata:¶

POST /introspect HTTP/1.1
Host: as.example.edu
Content-Type: application/x-www-form-urlencoded

token=PHNhbWxwOlJlc3BvbnNlLi4u
&token_type_hint=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Asaml2
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIs...

The request parameters are summarized below:¶

token:¶

REQUIRED. The base64url-encoded octet sequence, as defined in Section 5 of [RFC4648], of the XML serialization of either:¶

• a signed SAML 2.0 <Assertion> element obtained for the existing SAML SP relationship; or¶

• a signed SAML 2.0 <Response> containing exactly one bearer <Assertion> for that relationship.¶

The encoded value MUST NOT be line wrapped and SHOULD NOT include padding characters (=) (following [RFC7522]). Clients using libraries that emit padding by default SHOULD strip trailing = before sending; authorization servers SHOULD accept padded values for interoperability. When a SAML <Response> is supplied, it is a signed wrapper from which the effective assertion is extracted per Section 8.¶

token_type_hint:¶

OPTIONAL. If sent, the value MUST be urn:ietf:params:oauth:token-type:saml2. When a SAML <Response> wrapper is supplied, this token type hint still identifies the effective enclosed SAML 2.0 assertion rather than the wrapper element itself. If a token_type_hint value other than urn:ietf:params:oauth:token-type:saml2 is sent, the authorization server SHOULD return an HTTP 400 response.¶

This profile does not define a request parameter for selecting a subset of normalized claims in the introspection response.¶

Client authentication for the introspection endpoint follows [RFC7662] and authorization server policy. The authenticated client MUST be authorized for the saml_sp_entity_id that matches the SAML assertion audience.¶

10.2. Authorization Server Processing

10.3. Error Response

If the introspection request is malformed, for example because the token parameter is absent or its value cannot be decoded as valid base64url, the authorization server MUST return an HTTP 400 (Bad Request) error response as defined by [RFC7662], not an introspection response.¶

If client authentication fails, or if the client is not authorized to use the introspection endpoint at all, the authorization server MUST return an HTTP 401 (Unauthorized) or HTTP 403 (Forbidden) response, consistent with [RFC7662] Section 2.2 and authorization server policy.¶

A syntactically valid request in which the client is authenticated and authorized, but the presented SAML assertion is invalid, expired, audience- mismatched, replayed, or otherwise not usable for the client, MUST result in an introspection response with "active": false. The authorization server SHOULD NOT include additional members in such a response.¶

12.1. NameID Format Recognition

The following NameID formats are recognized for subject mapping purposes under this profile:¶

• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: A persistent, SP-specific or globally non-reassignable identifier. MAY be used as input to the subject mapping rules in this section.¶

• urn:oasis:names:tc:SAML:2.0:nameid-format:transient: A session-scoped, non-persistent identifier. MUST NOT be used as input to subject mapping under this profile and MUST NOT be used as the OpenID Connect sub.¶

• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: A mutable account attribute. Treated as defined in Section 11. MUST NOT be used as sub.¶

• urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: Deployment-defined semantics. MUST NOT be used as a subject mapping input unless local policy has explicitly established the identifier as stable and non-reassignable for the trusted SAML issuer.¶

• urn:oasis:names:tc:SAML:2.0:nameid-format:entity: Identifies a system entity, not an end-user. MUST NOT be used as a subject mapping input.¶

Any other NameID format MUST NOT be used as a subject mapping input under this profile unless local policy explicitly establishes its semantics as persistent and non-reassignable.¶

12.2. Subject Type Determination

The authorization server MUST determine whether the migrated client is using a public subject or a pairwise subject. The registered subject_type, if present, MUST be used for this determination. If no subject_type is registered, the authorization server MUST apply public as the effective subject type, in accordance with Section 6.1.¶

If multiple clients sharing the same saml_sp_entity_id have registered conflicting subject_type values and no single effective subject type can be determined per Section 6.1, the authorization server MUST fail the profile operation.¶

When the authorization server uses, or would otherwise use, the urn:oasis:names:tc:SAML:attribute:subject-id or urn:oasis:names:tc:SAML:attribute:pairwise-id attribute as a subject mapping input, it MUST validate that attribute according to the SAML V2.0 Subject Identifier Attributes Profile. In particular, the attribute MUST use NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:uri and contain exactly one non-empty AttributeValue that conforms to that profile's syntax and semantics. If no persisted mapping exists and the attribute corresponding to the client's effective subject type is present but fails these requirements, the authorization server MUST reject the profile operation rather than derive a different sub from fallback rules.¶

If a persisted mapping already exists and the current assertion also contains a valid subject identifier input matching the client's effective subject type, or a persistent NameID that would otherwise be eligible as a subject mapping input, the authorization server MUST compare the current asserted identifier context to the persisted source identifier context. If they differ, the authorization server MUST NOT silently replace the persisted mapping based only on the current assertion. The authorization server MAY continue only when an explicitly authorized administrative remapping has bound the new identifier context to the same Local Account; otherwise it MUST fail the profile operation.¶

When multiple clients share the same saml_sp_entity_id, the authorization server MUST apply the same effective subject mapping rules to all such clients. In particular, it MUST produce the same sub value for the same resolved Local Account when those clients are operating under the same subject type semantics.¶

12.3. Pairwise Subject Identifier Mapping

For clients using pairwise subject identifiers, the authorization server MUST determine sub using the first applicable rule:¶

1. If the authorization server already has a persisted pairwise mapping for the same resolved Local Account and the same saml_sp_entity_id, it MUST reuse that mapping, subject to the mismatch handling rules above.¶

2. If no persisted mapping exists and the SAML assertion contains a valid urn:oasis:names:tc:SAML:attribute:pairwise-id attribute (as validated by the rules in Section 12.2), the authorization server MUST use that attribute value as sub and MUST persist the resulting mapping.¶

3. If no persisted mapping exists and the assertion contains a persistent NameID (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) whose semantics are SP-specific, stable, and non-reassignable for that same SAML SP relationship, the authorization server MAY use that value as sub, and it MUST persist the resulting mapping.¶

4. Otherwise, the authorization server MUST derive a deterministic, non-reassignable pairwise identifier by combining the Stable Local Subject Key and the bound saml_sp_entity_id using a collision-resistant method. The pairwise subject computation defined in Section 8 of [OIDC-CORE] is a suitable derivation method, using saml_sp_entity_id as the sector identifier input to that computation. The authorization server MUST persist the resulting mapping.¶

The pairwise-id attribute value has the format localpart@scope as defined by [SAML2-SUBJ-ID]. When a pairwise-id value is used as sub, the resulting value carries this scoped format. Clients MUST NOT treat a sub value derived from pairwise-id as an email address or interpret the scope portion as an email domain.¶

12.4. Public Subject Identifier Mapping

For clients using public subject identifiers, the authorization server MUST determine sub using the first applicable rule:¶

1. If the authorization server already has a persisted public subject mapping for the same resolved Local Account under the same OAuth issuer, it MUST reuse that mapping, subject to the mismatch handling rules above.¶

2. If no persisted mapping exists and the SAML assertion contains a valid urn:oasis:names:tc:SAML:attribute:subject-id attribute (as validated by the rules in Section 12.2), the authorization server MUST use that attribute value as sub and MUST persist the resulting mapping.¶

3. If no persisted mapping exists and the assertion contains a persistent NameID (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) whose semantics are stable, non-reassignable, and not SP-specific, the authorization server MAY use that value as sub, and it MUST persist the resulting mapping.¶

4. Otherwise, the authorization server MUST derive a deterministic, non-reassignable public identifier from the Stable Local Subject Key alone, without client-specific input, using a collision-resistant method. The authorization server MUST persist the resulting mapping.¶

12.5. Common Rules

For all subject types:¶

• before issuing any chosen or derived value as sub, the authorization server MUST ensure that it satisfies the [OIDC-CORE] sub requirements, including that it be a case-sensitive string no longer than 255 ASCII characters;¶

• if the chosen source identifier would exceed that limit or contain non-ASCII characters, the authorization server MUST derive a deterministic, collision-resistant ASCII sub value from the chosen source identifier and required context, and it MUST persist the resulting mapping;¶

• if both subject-id and pairwise-id are available, the authorization server MUST select the one whose semantics match the client's effective subject type;¶

• the authorization server MUST NOT expose a pairwise-id value to a client other than a client bound to the corresponding saml_sp_entity_id;¶

• the authorization server MUST NOT use a transient identifier as the OpenID Connect sub;¶

• the authorization server MUST NOT directly use mutable identifiers such as an email address, a NameID in the SAML emailAddress format, or a non-persistent NameID format as the OpenID Connect sub.¶

When the only usable SAML subject input is a NameID whose semantics are those of an email address, and Section 11 succeeds under the rules above, the authorization server MUST derive sub from the resolved Stable Local Subject Key using the applicable fallback rule in this section rather than using the asserted email value itself.¶

When a persistent NameID is used as an input to subject mapping, the authorization server MUST evaluate the identifier together with its qualifier context. In particular:¶

• SPNameQualifier, if present for pairwise processing, MUST correspond to the bound saml_sp_entity_id or to an equivalent configured identifier for that same relying-party relationship;¶

• NameQualifier, if present, MUST correspond to the trusted SAML IdP identity or to an equivalent configured identifier for that same issuer;¶

• SPProvidedID, if present, MUST be treated as part of the source identifier context rather than ignored; and¶

• two NameID values that differ in value or qualifier context MUST be treated as distinct unless local policy can prove them equivalent.¶

12.6. SAML Subject Identifier Claim

This document defines the sub_id claim, which carries the original SAML NameID context alongside sub. It exists for migrated clients that need that context -- for example, to correlate sessions against legacy SAML-keyed audit logs or account databases.¶

sub_id is a JSON object following the subject identifier pattern of [RFC9493]. The format member discriminates among possible identifier shapes; future profiles may register additional formats in the IANA "Security Event Identifier Formats" registry. This document defines one format, saml-nameid, for SAML NameID values. When sub_id is present in an ID Token, UserInfo response, or introspection response under this profile, it MUST include a format member.¶

When format is saml-nameid, the sub_id object MAY contain the following members:¶

format:

String. REQUIRED. The value saml-nameid.¶

issuer:

String. The SAML Assertion Issuer value from the assertion that established this identifier. When present, this value MUST match the effective saml_idp_entity_id for the authenticated client.¶

nameid:

String. REQUIRED. The textual content of the SAML NameID element.¶

nameid_format:

String. The SAML NameID/@Format attribute value when present.¶

name_qualifier:

String. The SAML NameID/@NameQualifier attribute value when present.¶

sp_name_qualifier:

String. The SAML NameID/@SPNameQualifier attribute value when present.¶

sp_provided_id:

String. The SAML NameID/@SPProvidedID attribute value when present.¶

The authorization server MUST omit any member for which it has no validated value. Encrypted NameID forms (EncryptedID) are rejected under Section 8.3 and MUST NOT appear in sub_id.¶

13.1. Authentication Event Claims

When a SAML assertion contains an AuthnStatement, the authorization server SHOULD map its contents as follows:¶

• AuthnStatement/@AuthnInstant, when mapped, MUST be emitted as the OpenID Connect auth_time claim as a NumericDate value. Implementations MUST convert the XML dateTime value to the number of seconds elapsed since 1970-01-01T00:00:00Z when producing this NumericDate value.¶

• AuthnContext/AuthnContextClassRef maps to the OpenID Connect acr claim. Mapping rules are in Section 13.1.1.¶

• AuthnStatement/@SessionIndex MAY be used as authoritative input to the OpenID Connect sid claim, as defined by [OIDC-FC-LOGOUT] and [OIDC-BC-LOGOUT], when the deployment supports session continuity or logout semantics.¶

  When sid is emitted, it MUST identify the OpenID Provider session corresponding to the SAML-authenticated session and MUST be unique within the OAuth issuer. The authorization server MUST NOT assume that the raw SAML SessionIndex is already a valid sid; it MUST either reuse the raw value only when local policy guarantees it is issuer-scoped and collision-resistant for this purpose, or derive and persist an OpenID Provider-scoped sid bound to that SAML-authenticated session. If SessionIndex is absent from the selected AuthnStatement, sid MUST NOT be emitted unless the authorization server has another authoritative session identifier for that SAML-authenticated session.¶

• AuthnStatement/@SessionNotOnOrAfter MAY be emitted as the OpenID Connect Enterprise Extensions session_expiry claim ([OIDC-ENTERPRISE-EXTENSIONS]) when an ID Token is issued for the same SAML-authenticated session. When emitted, session_expiry MUST be a JSON integer containing the number of seconds elapsed since 1970-01-01T00:00:00Z, and its value MUST NOT be later than the selected AuthnStatement/@SessionNotOnOrAfter. The authorization server MUST NOT derive session_expiry from the SAML assertion's Conditions/@NotOnOrAfter, because that value limits assertion validity, not the underlying authenticated session.¶

The OpenID Connect amr claim identifies authentication methods, not an authentication context class. Therefore:¶

• the authorization server MUST NOT copy the SAML AuthnContextClassRef directly into amr;¶

• the authorization server MAY populate amr only when it can derive concrete authentication methods from local policy or explicit SAML authentication evidence; and¶

• when amr is populated, the authorization server SHOULD use values from the Authentication Method Reference Values registry [RFC8176], and it MUST represent amr as a JSON array of strings.¶

If multiple AuthnStatement elements are present, the authorization server MUST select the statement local policy designates as authoritative. Absent such a policy, the authorization server MUST omit auth_time, acr, amr, and sid rather than emit values from an arbitrarily selected statement. Selecting by AuthnInstant alone is not safe, because the most recent statement may reflect SAML identity proxying re-issuance rather than original end-user authentication; deployments using proxied assertions MUST configure which AuthnStatement is authoritative.¶

If the selected AuthnStatement contains SessionNotOnOrAfter, the authorization server MUST treat that instant as an upper bound on operations that preserve the SAML-authenticated session under this profile. In particular:¶

• the authorization server MUST NOT issue a refresh token whose validity extends beyond SessionNotOnOrAfter;¶

• if it issues an access token or ID Token directly from the assertion and that token is intended to represent the same authenticated session, the token expiration time MUST NOT extend beyond SessionNotOnOrAfter; and¶

• once SessionNotOnOrAfter has passed, the authorization server MUST reject further session-preserving use of the assertion or derived refresh token.¶

Earlier session-end signals and revocation cascade are defined in Section 14.¶

The following SAML data has no direct standard OpenID Connect claim mapping:¶

• AuthnContextDecl¶

• AuthnContextDeclRef¶

• AuthnContext/AuthenticatingAuthority¶

• SubjectLocality¶

If the AuthnContext contains an AuthnContextDeclRef element but no AuthnContextClassRef, the authorization server MUST NOT emit an acr claim unless local policy defines a deterministic mapping from that declaration reference to a specific ACR value. If no such mapping exists, acr MUST be omitted.¶

Such values MAY be conveyed in private claims by prior agreement between the authorization server and client. Deployments using such claims SHOULD use collision-resistant claim names.¶

13.2. Attribute Claims

A NameID in emailAddress format is not by itself an attribute mapping input. However, if the assertion contains a NameID whose format is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, or whose semantics are those of an email address under local policy, the authorization server MAY use that value as the OpenID Connect email claim when:¶

• claim release policy for the relying-party relationship permits release of email;¶

• the value is bound by local policy to the resolved Local Account; and¶

• no higher-precedence SAML attribute mapping produces a conflicting email claim value.¶

If the emailAddress NameID conflicts with an email value derived from a SAML attribute and no deterministic local precedence rule exists, the authorization server SHOULD omit the email claim rather than guess. An emailAddress NameID MUST NOT by itself cause the authorization server to emit email_verified=true.¶

When a SAML attribute directly corresponds to a registered OpenID Connect claim, the authorization server SHOULD emit that claim. When the SAML deployment uses attribute Name values based on object identifiers or URIs, the authorization server MAY apply a deployment-specific mapping table that resolves those names to the equivalent OpenID Connect claim names.¶

Non-normative example mappings for common SAML attributes and for InCommon and eduPerson deployments are provided in Appendix B.¶

All AttributeStatement elements in the assertion MUST be processed as a single logical attribute set. Attributes having the same Name and the same NameFormat are part of the same logical attribute and their values MUST be combined in document order. Attributes that differ by Name or NameFormat MUST be treated as distinct inputs even if their FriendlyName values are the same.¶

An omitted NameFormat MUST be treated as urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified for purposes of attribute grouping and mapping under this profile.¶

Mapping decisions MUST be based primarily on the SAML attribute Name and NameFormat. FriendlyName MAY be used only as a secondary hint when no deterministic Name-based mapping exists. If Name, NameFormat, and FriendlyName would imply conflicting claim mappings, the authorization server MUST use the Name and NameFormat interpretation.¶

Standard registered OpenID Connect identity claims (email, given_name, family_name, name, preferred_username, phone_number, etc.) are single-valued strings. auth_time is a single numeric value. amr is an array of strings.¶

Attribute processing MUST follow these rules:¶

• a single SAML AttributeValue maps to a single JSON value;¶

• multiple SAML AttributeValue elements MAY map to a JSON array only for claims whose syntax permits arrays or for private claims defined by prior agreement;¶

• boolean-valued SAML attributes SHOULD map to JSON booleans when the XML type is unambiguous;¶

• if multiple source values are available for a registered single-valued claim, the authorization server MUST either apply a deterministic, claim-specific precedence rule or omit that claim;¶

• if multiple distinct SAML attributes could map to the same registered claim, the authorization server MUST apply a deterministic precedence rule based on SAML attribute identifiers or omit that claim;¶

• when multiple SAML attributes from the same logical attribute set could map to the same registered OpenID Connect claim and they differ only by NameFormat, the authorization server SHOULD prefer the attribute whose NameFormat is urn:oasis:names:tc:SAML:2.0:attrname-format:uri (the canonical federation form) over :basic or :unspecified forms;¶

• the authorization server MUST NOT emit a JSON array for a registered single-valued claim; and¶

• generic attribute mapping MUST NOT overwrite sub, auth_time, acr, amr, or sid values that were derived by the rules in this document.¶

The authorization server MUST NOT infer email_verified from the mere presence of an email attribute. The authorization server MUST NOT infer phone_number_verified from the mere presence of a phone_number attribute. These verified status claims MUST be populated only when an explicit verification assertion is available from the SAML deployment or from a local policy determination.¶

Attributes that do not correspond to standard OpenID Connect claims MAY be returned as private claims when both parties have a prior agreement on syntax and semantics.¶

13.3. UserInfo Responses

If an access token issued under this profile is presented to the OpenID Provider's UserInfo endpoint, the OpenID Provider MUST process that request in accordance with [OIDC-CORE] and the additional rules in this section.¶

The UserInfo response:¶

• MUST include the sub claim;¶

• MUST use a sub value consistent with Section 12;¶

• MUST apply the claim mapping rules in Section 13.1 and Section 13.2 to any returned claims;¶

• MAY include the sub_id claim defined in Section 12.6 when the granted scope includes saml_subject and policy permits release; and¶

• MUST NOT include claims that would not be releasable to the same relying party under this profile.¶

The OpenID Provider MUST determine which claims to return based on the granted scope, any other OpenID Connect claim-selection mechanism it supports, and the claim release policy applicable to the relying-party relationship represented by the bound saml_sp_entity_id.¶

If an ID Token and a UserInfo response are both issued under the same migrated authorization context, the sub value in the UserInfo response MUST exactly match the sub value in the corresponding ID Token.¶

If the UserInfo response includes auth_time, acr, amr, or sid, those values MUST be derived according to Section 13.1. The same consistency rule applies to sub_id when it was emitted in the corresponding ID Token under Section 12.6. When an ID Token has been issued for the same migrated authorization context, the authorization server MUST:¶

• cache the values of auth_time, acr, amr, sid, and sub_id at the time of ID Token issuance;¶

• return those cached values in any UserInfo response for the duration of the access token's validity, even if the originating SAML assertion has since expired; and¶

• ensure the UserInfo values for these claims match the corresponding claims in the most recently issued ID Token for that migrated authorization context.¶

This profile does not require the UserInfo response to repeat every claim available in an ID Token, nor does it require claims omitted from the ID Token to be present in UserInfo. Any claim returned from UserInfo under this profile MUST reflect the same Local Account resolution, subject continuity, and claim release policy used for the access token.¶

Any claim returned from UserInfo MUST be permitted by the claim release policy in effect at the time of access token issuance and by the claim release policy in effect at the time of the UserInfo request. The authorization server MAY retain the issuance-time policy snapshot for continuity, but MUST NOT use that snapshot to return claims disallowed by current policy or by the current Local Account or session state.¶

14.1. Session Termination

The authorization server MUST treat the earlier of the following as the operative end of the migrated session for a given originating SAML assertion:¶

• the assertion's SessionNotOnOrAfter value, when present in the authoritative AuthnStatement (Section 13.1);¶

• any authoritative signal that the underlying SAML-authenticated session ended earlier (for example, a SAML SLO event observed at the IdP that the authorization server learns through deployment-specific means);¶

• an authorization server policy decision to terminate the migrated session (administrative action, risk-based revocation, etc.).¶

When the migrated session has ended, the authorization server:¶

• MUST reject further use of any refresh token derived from the originating assertion for session-preserving operations;¶

• SHOULD revoke or expire access tokens derived from those refresh tokens according to local capabilities; and¶

• MAY propagate the termination to OpenID Connect clients through [OIDC-BC-LOGOUT] when the deployment supports back-channel logout signaling, using the sid claim (Section 13.1) to identify the affected session.¶

This document does not define how the authorization server discovers SAML SLO events. Deployments that require coordinated SAML and OIDC logout MUST establish that discovery through deployment-specific means outside this profile.¶

14.2. Token Revocation

OAuth 2.0 Token Revocation [RFC7009] applies to tokens issued under this profile without modification. Beyond the generic RFC 7009 rules, this profile imposes the following cascade semantics:¶

• revocation of a refresh token issued under this profile MUST end the migrated session bound to that refresh token. The authorization server SHOULD revoke or expire all access tokens derived from the revoked refresh token according to local capabilities;¶

• revocation of an access token issued under this profile MUST end that token's usability but does not by itself terminate the migrated session or invalidate the underlying refresh token (if any).¶

The "migrated session bound to that refresh token" refers to the session represented by the specific refresh token being revoked, not all sessions for the same Local Account. Revoking one refresh token does not affect other refresh tokens issued for the same Local Account (for example, tokens issued for other devices) unless deployment policy explicitly cascades. To end all sessions for a Local Account, the authorization server MUST take the account-level action described in Section 14.1.¶

If the authorization server learns that the resolved Local Account has been disabled, deprovisioned, or suspended, it MUST end the migrated session as described in Section 14.1.¶

A subsequent submission of a new SAML assertion through this profile (Section 9) establishes a new migrated session that is not affected by the prior revocation.¶

15.1. Threat Model

This profile assumes the following:¶

• The SAML IdP and the authorization server are operated by, or under the administrative control of, the same authority (see Section 3). They share a trust boundary, but are network-separated components that communicate through their respective protocols.¶

• Migration Clients are confidential clients (public clients are excluded; see Section 6.1). Their client authentication credentials are not directly disclosed to end-users.¶

• The Migration Client's saml_sp_entity_id (and per-client saml_idp_entity_id if used) binding is established under the authorization rules in Section 6.1.1; self-asserted dynamic registration of these values is disallowed.¶

The following attacker capabilities are in scope:¶

• An attacker who obtains a SAML assertion in transit (through XSS in the SP, intermediary compromise, log leakage, or similar). The three-way binding (Section 4) and replay detection (Section 8.7) limit what such an assertion enables.¶

• An attacker who attempts to dynamically register a client with a saml_sp_entity_id or saml_idp_entity_id they are not authorized to bind. The registration authorization rules (Section 6.1.1) require out-of-band authorization for these values.¶

• An attacker who attempts XML Signature Wrapping, replay, or algorithm-downgrade attacks against a submitted SAML assertion. The signature, replay, and algorithm rules in Section 8 and the considerations below address these.¶

• An attacker who attempts to induce SSRF through a maliciously registered saml_metadata_uri. HTTPS-only fetches, redirect restrictions, and host allowlisting limit this.¶

The following are out of scope for this profile and remain the deployment's responsibility:¶

• Compromise of the SAML IdP or the authorization server themselves (including their signing keys).¶

• Side channels, traffic analysis, and other infrastructure-level threats not specific to this profile.¶

• SAML SLO discovery: the mechanism by which the authorization server learns of a SAML session ending. Propagation from the authorization server to OpenID Connect clients via [OIDC-BC-LOGOUT] is OPTIONAL and addressed in Section 14.¶

• End-user account compromise upstream of the SAML IdP.¶

15.2. SAML Assertion and Signature Risks

15.3. Metadata Fetching and SSRF

When an authorization server or migration tooling fetches a saml_metadata_uri at either the authorization server metadata level or the client registration level, the fetch target is derived from a configuration value that may be attacker-influenced in some deployment models. Per-client saml_metadata_uri values registered through dynamic client registration are particularly exposed, since they originate from a registering party. Implementations MUST restrict fetches to URIs that use the HTTPS scheme and MUST NOT follow redirects to non-HTTPS URIs. Deployments SHOULD additionally constrain permitted fetch targets to a pre-approved allowlist of hosts, in order to prevent Server-Side Request Forgery (SSRF) attacks against internal services. The registration authorization rules in Section 6.1.1 apply to per-client saml_metadata_uri values, so an attacker using dynamic client registration cannot freely set this value.¶

15.4. Replay and Bearer Assertion Risks

SAML assertions used with Token Exchange or introspection are bearer artifacts. Authorization servers MUST detect and prevent replay of the same assertion according to the security properties of the underlying SAML deployment, any SAML OneTimeUse condition, and the replay rules in Section 8. Client authentication alone is not sufficient protection against replay of a stolen assertion.¶

Authorization servers deployed across multiple nodes MUST share assertion identifier state used for replay detection across all nodes, or use equivalent distributed coordination. Per-node replay stores are insufficient.¶

When this profile accepts a signed SAML Response as a wrapper for the effective assertion, response-level signature validation does not by itself validate response-level protocol fields such as Destination or Response/@InResponseTo. This profile requires the wrapped Response to carry a top-level SAML StatusCode of Success with no subordinate status code, but other response-level protocol checks remain outside this profile. Deployments that depend on those additional checks MUST ensure they are performed outside this profile before the enclosed assertion is used to issue tokens or return claims.¶

15.5. Binding Security

The bindings defined by saml_sp_entity_id and saml_idp_entity_id are security-critical, both at the authorization server metadata level and at the per-client registration level. If a client can register an arbitrary saml_sp_entity_id or saml_idp_entity_id, it may be able to exchange any SAML assertion captured for that SP-IdP pair into OAuth tokens or claims under the bound relying-party relationship, collapsing the three-way binding defined in Section 4. Authorization servers MUST therefore protect registration and administrative mapping of both values according to Section 6.1.1. In particular, anonymous or open dynamic client registration MUST NOT be permitted to set either value.¶

When multiple OAuth clients share the same saml_sp_entity_id, the authorization server is intentionally treating them as the same relying-party context. Such sharing MUST therefore be an explicit IdP or authorization server policy decision. Accidental sharing can expose the same pairwise sub values and claims to clients that should have been isolated from one another.¶

15.6. Token and Claim Security

Mutable, transient, or reassignable NameID formats used as sub can cause account takeover or misbinding after identifier reuse; the stability rules in Section 12.5 exclude them for that reason.¶

Incorrect amr translation can overstate the assurance of an authentication; see Section 13.1 for the rule that amr is populated only from concrete authentication evidence.¶

The introspection pattern can expose normalized claims without minting OAuth tokens; see Section 10 for the requirement that introspection clients be authenticated and authorized for the bound relying-party context.¶

An ID Token issued directly from Token Exchange MUST meet the same signing, audience, issuer, and claim integrity requirements as one issued through an ordinary OpenID Connect flow (see Section 9.2.4).¶

Access tokens issued under this profile are bearer tokens by default. They are therefore subject to the usual risks associated with bearer credentials, including replay by any party that obtains the token value through interception, log leakage, or compromise of an intermediary. Deployments protecting sensitive resources SHOULD consider sender-constrained access tokens, such as DPoP-bound tokens or mTLS client-certificate-bound tokens, in accordance with the underlying OAuth sender-constraint specifications. This profile does not preclude their use: a Migration Client MAY present a DPoP proof or use mTLS client authentication at the token endpoint, and the authorization server MAY issue sender-constrained access tokens in the Token Exchange response when its policy and the client's registration support that mechanism.¶

15.7. Protocol Confusion and Transport Security

Mixing SAML trust inputs and OAuth trust inputs creates a risk of protocol confusion. Implementations MUST validate SAML assertions using SAML metadata and MUST validate ID Tokens and other JOSE objects using OAuth or OpenID Connect key discovery. Implementations MUST NOT assume that a key published in one metadata format is automatically valid in the other.¶

Authorization servers MUST apply transport security to the token endpoint, introspection endpoint, metadata retrieval, and any other endpoint used by this profile in the same manner as the underlying OAuth, OpenID Connect, and SAML specifications that they extend.¶

17.1. OAuth Dynamic Client Registration Metadata

This document requests registration of the following values in the OAuth Dynamic Client Registration Metadata registry established by [RFC7591]:¶

• Client Metadata Name: saml_sp_entity_id¶

• Client Metadata Description: Identifier of the SAML 2.0 Service Provider entity bound to the client for migration and subject continuity¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 6.1¶

• Client Metadata Name: saml_idp_entity_id¶

• Client Metadata Description: Per-client override for the identifier of the SAML 2.0 Identity Provider entity expected to issue assertions for this client, when the SAML IdP emits per-SP entityIDs¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 6.2¶

• Client Metadata Name: saml_metadata_uri¶

• Client Metadata Description: Per-client override for the HTTPS URI of the SAML metadata document describing the SAML 2.0 Identity Provider entity expected to issue assertions for this client¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 6.3¶

17.2. OAuth Authorization Server Metadata

This document requests registration of the following values in the OAuth Authorization Server Metadata registry established by [RFC8414]:¶

• Metadata Name: saml_idp_entity_id¶

• Metadata Description: Default identifier of the SAML 2.0 Identity Provider entity bound to the authorization server issuer; may be overridden per client registration¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 7.1¶

• Metadata Name: saml_metadata_uri¶

• Metadata Description: Default HTTPS URI for the SAML metadata describing the SAML Identity Provider entity bound to the authorization server issuer; may be overridden per client registration¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 7.2¶

• Metadata Name: token_exchange_requested_token_types_supported¶

• Metadata Description: JSON array of token type URIs accepted as requested_token_type values for SAML token exchange under this profile¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 7.3¶

• Metadata Name: introspection_token_types_supported¶

• Metadata Description: JSON array of token type URIs identifying token types accepted for direct introspection at the authorization server's introspection endpoint according to this profile¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 7.4¶

17.3. OAuth Token Type Hints

This document requests registration of the following value in the OAuth Token Type Hints registry established by [RFC7009]. The token type URI below is defined by [RFC8693] as a token type identifier; this registration makes it available as a token_type_hint value at introspection and revocation endpoints, which use a separate registry.¶

• Hint Value: urn:ietf:params:oauth:token-type:saml2¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 10.1¶

17.4. OAuth Token Introspection Response Registry

This document requests registration of the following values in the OAuth Token Introspection Response registry established by [RFC7662]:¶

• Response Name: saml¶

• Response Description: JSON object containing normalized SAML protocol metadata extracted from the validated SAML input¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 10.2.3¶

• Response Name: sub_id¶

• Response Description: Structured subject identifier carrying provenance about the identifier, returned at the top level of the introspection response in parallel with its placement in ID Tokens and UserInfo responses¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 10.2.3, Section 12.6¶

• Response Name: auth_time¶

• Response Description: Time of end-user authentication, expressed as a NumericDate value, with the same semantics as the OpenID Connect auth_time claim; returned at the top level of the introspection response under this profile¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 10.2.3, Section 13.1¶

• Response Name: acr¶

• Response Description: Authentication Context Class Reference value with the same semantics as the OpenID Connect acr claim; returned at the top level of the introspection response under this profile¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 10.2.3, Section 13.1¶

• Response Name: amr¶

• Response Description: JSON array of Authentication Method Reference values with the same semantics as the OpenID Connect amr claim; returned at the top level of the introspection response under this profile¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 10.2.3, Section 13.1¶

• Response Name: sid¶

• Response Description: Session identifier with the same semantics as the OpenID Connect sid claim ([OIDC-FC-LOGOUT], [OIDC-BC-LOGOUT]); returned at the top level of the introspection response under this profile¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 10.2.3, Section 13.1¶

• Response Name: session_expiry¶

• Response Description: Session expiration time, expressed as a JSON integer Unix timestamp, with the same semantics as the OpenID Connect Enterprise Extensions session_expiry claim; returned at the top level of the introspection response under this profile¶

• Change Controller: IETF¶

• Specification Document(s): This document, Section 10.2.3, Section 13.1¶

Other OpenID Connect standard claims listed in the IANA "JSON Web Token Claims" registry (such as email, email_verified, given_name, family_name, name, preferred_username, phone_number, and phone_number_verified) MAY also appear as top-level members of the introspection response under this profile when the claim mapping rules in Section 13 produce them. Their semantics in the introspection response are the same as in the corresponding ID Token or UserInfo response; this document does not redefine those claims and does not introduce additional introspection-registry entries for them. A deployment that includes such a claim in its introspection response is relying on the existing JWT Claims registry definition.¶

17.5. JSON Web Token Claims

This document requests registration of the following claim in the IANA "JSON Web Token Claims" registry established by RFC 7519:¶

• Claim Name: sub_id¶

• Claim Description: Structured subject identifier carrying provenance about the identifier (such as the original SAML NameID context) alongside the primary sub claim¶

• Change Controller: IETF¶

• Reference: This document, Section 12.6¶

17.6. OAuth Scope Values

This document defines the following OAuth scope value:¶

• Scope Value: saml_subject¶

• Description: Requests release of the sub_id claim defined in Section 12.6, carrying the original SAML NameID context for the migrated relying-party relationship¶

• Reference: This document, Section 12.6¶

17.7. Security Event Identifier Formats

This document requests registration of the following value in the IANA "Security Event Identifier Formats" registry established by [RFC9493]:¶

• Format Name: saml-nameid¶

• Description: Subject identifier format representing a SAML 2.0 NameID with its qualifiers and SAML Issuer¶

• Change Controller: IETF¶

• Reference: This document, Section 12.6¶

18.1. Normative References

[OIDC-BC-LOGOUT]

Jones, M. B. and J. Bradley, "OpenID Connect Back-Channel Logout 1.0", <https://openid.net/specs/openid-connect-backchannel-1_0.html>.

[OIDC-CORE]

Sakimura, N., Bradley, J., Jones, M. B., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 2", <https://openid.net/specs/openid-connect-core-1_0-18.html>.

[OIDC-DISCOVERY]

Sakimura, N., Bradley, J., Jones, M. B., and E. Jay, "OpenID Connect Discovery 1.0 incorporating errata set 2", <https://openid.net/specs/openid-connect-discovery-1_0.html>.

[OIDC-ENTERPRISE-EXTENSIONS]

Hardt, D. and K. McGuinness, "OpenID Connect Enterprise Extensions 1.0", September 2025, <https://openid.net/specs/openid-connect-enterprise-extensions-1_0.html>.

[OIDC-FC-LOGOUT]

Jones, M. B., "OpenID Connect Front-Channel Logout 1.0", <https://openid.net/specs/openid-connect-frontchannel-1_0.html>.

[OIDC-REGISTRATION]

Sakimura, N., Bradley, J., and M. B. Jones, "OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 2", <https://openid.net/specs/openid-connect-registration-1_0.html>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC4648]

Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, <https://www.rfc-editor.org/rfc/rfc4648>.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/rfc/rfc6749>.

[RFC7591]

Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/rfc/rfc7591>.

[RFC7662]

Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/rfc/rfc7662>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8176]

Jones, M., Hunt, P., and A. Nadalin, "Authentication Method Reference Values", RFC 8176, DOI 10.17487/RFC8176, June 2017, <https://www.rfc-editor.org/rfc/rfc8176>.

[RFC8414]

Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/rfc/rfc8414>.

[RFC8693]

Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, DOI 10.17487/RFC8693, January 2020, <https://www.rfc-editor.org/rfc/rfc8693>.

[RFC8707]

Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, February 2020, <https://www.rfc-editor.org/rfc/rfc8707>.

[RFC9493]

Backman, A., Ed., Scurtescu, M., and P. Jain, "Subject Identifiers for Security Event Tokens", RFC 9493, DOI 10.17487/RFC9493, December 2023, <https://www.rfc-editor.org/rfc/rfc9493>.

[SAML2-CORE]

OASIS, "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", 2005, <https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf>.

[SAML2-METADATA]

OASIS, "Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0", 2005, <https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf>.

[SAML2-SUBJ-ID]

OASIS, "SAML V2.0 Subject Identifier Attributes Profile Version 1.0", 2019, <https://docs.oasis-open.org/security/saml-subject-id-attr/v1.0/saml-subject-id-attr-v1.0.html>.

18.2. Informative References

[EDUPERSON]

REFEDS, "eduPerson Object Class Specification", <https://refeds.org/specifications/eduperson>.

[I-D.ietf-oauth-identity-assertion-authz-grant]

Parecki, A., McGuinness, K., and B. Campbell, "Identity Assertion JWT Authorization Grant", Work in Progress, Internet-Draft, draft-ietf-oauth-identity-assertion-authz-grant-03, 22 April 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-identity-assertion-authz-grant-03>.

[INCOMMON-ATTRS]

InCommon, "InCommon Federation Attributes", <https://incommon.org/federation/attributes/>.

[INCOMMON-OID]

InCommon, "InCommon Object Identifiers", <https://incommon.org/community/mace-registries/incommon-object-identifiers/>.

[REFEDS-RS]

REFEDS, "REFEDS Research and Scholarship Entity Category", <https://refeds.org/category/research-and-scholarship>.

[RFC7009]

Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, August 2013, <https://www.rfc-editor.org/rfc/rfc7009>.

[RFC7522]

Campbell, B., Mortimore, C., and M. Jones, "Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7522, DOI 10.17487/RFC7522, May 2015, <https://www.rfc-editor.org/rfc/rfc7522>.

[SAML2-IOP]

OASIS, "SAML V2.0 Metadata Interoperability Profile Version 1.0", 2009, <https://docs.oasis-open.org/security/saml/Post2.0/sstc-metadata-iop.html>.

A.1. Convert SAML to an ID Token

The calendar application has completed SAML Web SSO and received a signed assertion from the IdP for Alice, a user who already has a Local Account at the authorization server. The application wants a signed OpenID Connect ID Token it can verify locally and use to establish Alice's session, without implementing a separate OIDC authorization code flow. It presents the SAML assertion to the token endpoint via Token Exchange, requesting an ID Token with scope=openid profile email saml_subject so that the ID Token also carries the original SAML NameID context in sub_id. The authorization server validates the assertion, resolves Alice's Local Account, derives her pairwise sub, maps her authentication claims, and returns an ID Token directly in the Token Exchange response.¶

POST /token HTTP/1.1
Host: login.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&requested_token_type=urn:ietf:params:oauth:token-type:id_token
&scope=openid+profile+email+saml_subject
&subject_token=PHNhbWwyOkFzc2VydGlvbiB4bWxuczpzYW1sMj0iLi4uIj4uLi48L3NhbWwyOkFzc2VydGlvbj4
&subject_token_type=urn:ietf:params:oauth:token-type:saml2
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNsaWVudC0xIn0...

{
  "issued_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0...",
  "token_type": "N_A",
  "scope": "openid profile email saml_subject",
  "expires_in": 3600
}

The ID Token carried in the access_token response member might contain claims like:¶

{
  "iss": "https://login.example.com",
  "sub": "p7b4cf5d-9c2f-4f22-a6b9-6e3d8df5a1b0",
  "sub_id": {
    "format": "saml-nameid",
    "issuer": "https://login.example.com/idp",
    "nameid": "alice-pairwise-7c3f",
    "nameid_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "name_qualifier": "https://login.example.com/idp",
    "sp_name_qualifier": "https://calendar.example.com/saml/sp"
  },
  "aud": "s6BhdRkqt3",
  "exp": 1776805200,
  "iat": 1776804900,
  "auth_time": 1776794400,
  "acr": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
  "sid": "op-sid-61b7d66f-4a6f-4f04-b0e5-9b8176d92ad0",
  "session_expiry": 1776805200,
  "email": "alice@example.com",
  "given_name": "Alice",
  "family_name": "Ng"
}

A.2. Delegate SAML Validation with Introspection

The calendar application wants to avoid implementing SAML XML signature validation and assertion processing entirely. It uses an SP-initiated flow: before redirecting Alice to the IdP, it generates an AuthnRequest and saves local state including the request ID and ACS URL. When the IdP returns a signed SAML Response to the ACS, the application submits it directly to the AS's introspection endpoint rather than parsing it. The AS validates the XML signatures, checks the assertion against all profile rules, and returns normalized identity claims at the top level of the response alongside SAML protocol metadata in a saml object. The application then correlates the returned saml values against its stored request state to confirm the response was intended for this flow, and uses the top-level identity claims (sub, email, etc.) to establish Alice's session.¶

Before redirecting Alice to the IdP, the SP stores local request state such as:¶

{
  "request_id": "_sp-authnrequest-8f3a",
  "acs_url": "https://calendar.example.com/saml/acs",
  "sp_entity_id": "https://calendar.example.com/saml/sp",
  "idp_entity_id": "https://login.example.com/idp"
}

After the IdP returns a SAML Response to the ACS, the application submits it to the introspection endpoint:¶

POST /introspect HTTP/1.1
Host: login.example.com
Content-Type: application/x-www-form-urlencoded

token=PHNhbWwycDpSZXNwb25zZSB4bWxuczpzYW1sMj0iLi4uIiB4bWxuczpzYW1sMnA9Ii4uLiI-Li4uPC9zYW1sMnA6UmVzcG9uc2U-
&token_type_hint=urn:ietf:params:oauth:token-type:saml2
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNsaWVudC0xIn0...

{
  "active": true,
  "sub": "p7b4cf5d-9c2f-4f22-a6b9-6e3d8df5a1b0",
  "sub_id": {
    "format": "saml-nameid",
    "issuer": "https://login.example.com/idp",
    "nameid": "alice-pairwise-7c3f",
    "nameid_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "name_qualifier": "https://login.example.com/idp",
    "sp_name_qualifier": "https://calendar.example.com/saml/sp"
  },
  "auth_time": 1776794400,
  "acr": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
  "sid": "op-sid-61b7d66f-4a6f-4f04-b0e5-9b8176d92ad0",
  "email": "alice@example.com",
  "given_name": "Alice",
  "family_name": "Ng",
  "saml": {
    "response": {
      "id": "_d71b9f4f8b5b4a4b8f2f",
      "issue_instant": "2026-04-21T18:00:00Z",
      "destination": "https://calendar.example.com/saml/acs",
      "in_response_to": "_sp-authnrequest-8f3a"
    },
    "assertion": {
      "id": "_a75adf55d9a24d6f8c2b",
      "issue_instant": "2026-04-21T18:00:00Z",
      "audiences": [
        "https://calendar.example.com/saml/sp"
      ],
      "not_before": "2026-04-21T17:55:00Z",
      "not_on_or_after": "2026-04-21T18:05:00Z",
      "subject_confirmation": {
        "recipient": "https://calendar.example.com/saml/acs",
        "in_response_to": "_sp-authnrequest-8f3a",
        "not_on_or_after": "2026-04-21T18:05:00Z",
        "address": "192.0.2.44"
      }
    },
    "attributes": [
      {
        "name": "urn:oid:0.9.2342.19200300.100.1.3",
        "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "friendly_name": "mail",
        "values": ["alice@example.com"]
      },
      {
        "name": "urn:oid:2.5.4.42",
        "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "friendly_name": "givenName",
        "values": ["Alice"]
      },
      {
        "name": "urn:oid:2.5.4.4",
        "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "friendly_name": "sn",
        "values": ["Ng"]
      }
    ]
  }
}

After the authorization server validates XML signatures and SAML assertion processing rules and returns the active response, the SP performs local correlation and location checks over the returned JSON values, for example:¶

saml.response is present
saml.response.destination == stored.acs_url
saml.response.in_response_to == stored.request_id
saml.assertion.subject_confirmation.recipient == stored.acs_url
saml.assertion.subject_confirmation.in_response_to == stored.request_id
stored.sp_entity_id is in saml.assertion.audiences
current_time < saml.assertion.subject_confirmation.not_on_or_after
current_time < saml.assertion.not_on_or_after

A.3. Convert SAML to an Access Token or Refresh Token

The calendar application holds a SAML assertion for Alice and needs OAuth tokens for two different purposes: calling a protected payments API in the same organization, and establishing a long-lived session that can outlive the SAML assertion itself. Both are handled via Token Exchange; the requested_token_type parameter selects which artifact the AS issues.¶

In the first case, the application needs a Bearer access token scoped to the payments API. It uses resource indicators to identify the target resource and requests only the scopes required for that service:¶

POST /token HTTP/1.1
Host: login.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&requested_token_type=urn:ietf:params:oauth:token-type:access_token
&scope=payments.read+payments.write
&resource=https%3A%2F%2Fapi.example.com%2Fpayments
&audience=payments-api
&subject_token=PHNhbWwyOkFzc2VydGlvbiB4bWxuczpzYW1sMj0iLi4uIj4uLi48L3NhbWwyOkFzc2VydGlvbj4
&subject_token_type=urn:ietf:params:oauth:token-type:saml2
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNsaWVudC0xIn0...

{
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "access_token": "mF_9.B5f-4.1JqM",
  "token_type": "Bearer",
  "scope": "payments.read payments.write",
  "expires_in": 3600
}

In the second case, the application wants a refresh token to bootstrap a long-lived migrated session. It includes offline_access in scope alongside the OpenID Connect scopes it needs. The AS issues a refresh token bound to Alice's Local Account; subsequent refresh token grants can produce access tokens and ID Tokens without requiring a new SAML assertion:¶

POST /token HTTP/1.1
Host: login.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&requested_token_type=urn:ietf:params:oauth:token-type:refresh_token
&scope=openid+offline_access+profile+email
&subject_token=PHNhbWwycDpSZXNwb25zZSB4bWxuczpzYW1sMj0iLi4uIiB4bWxuczpzYW1sMnA9Ii4uLiI-Li4uPC9zYW1sMnA6UmVzcG9uc2U-
&subject_token_type=urn:ietf:params:oauth:token-type:saml2
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNsaWVudC0xIn0...

{
  "issued_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
  "access_token": "vF9dft4qmTcXkZ26zL8b6u",
  "token_type": "N_A",
  "scope": "openid offline_access profile email",
  "expires_in": 1209600
}

B.1. Common SAML Attribute Mappings

Many SAML deployments use a small set of attribute names that map directly to registered OpenID Connect claims. Common examples:¶

The rules in Section 13.2 (in particular, the NameFormat preference rule preferring urn:oasis:names:tc:SAML:2.0:attrname-format:uri over :basic/:unspecified) govern how these are resolved when the assertion uses urn:oid: Name values alongside friendly names.¶

B.2. InCommon and eduPerson Deployments

Many InCommon deployments use eduPerson attributes, including the REFEDS Research and Scholarship attribute bundle. InCommon deployments commonly use urn:oid: Name values in addition to friendly names; the mapping rules in Section 13.2 govern how such OID-based names are resolved to OpenID Connect claims. The core rules in Section 13 still govern claim typing, precedence, and subject handling. Within that framework, deployments commonly use the following mappings and constraints:¶

• mail to email¶

• displayName to name¶

• givenName to given_name¶

• sn or surname to family_name¶

• eduPersonNickname to nickname, when locally useful¶

• telephoneNumber to phone_number, when locally useful¶

• eduPersonPrincipalName to preferred_username only when local policy permits release as a user-facing identifier; it should not determine sub¶

• eduPersonScopedAffiliation in a collision-resistant private claim that preserves its multi-valued syntax¶

• eduPersonAffiliation and eduPersonPrimaryAffiliation in collision- resistant private claims rather than overloaded standard claims¶

• eduPersonEntitlement in a collision-resistant private claim; it should not be translated directly into OAuth scope¶

• eduPersonAssurance in a collision-resistant private claim or as input to local assurance policy; it should not be copied directly into amr and should not overwrite acr unless local policy explicitly defines that translation¶

• eduPersonUniqueId as a stable account-linking or subject-continuity input, and only secondarily as a private claim when needed¶

• eduPersonTargetedID as a legacy pairwise subject continuity input, not as a general-purpose user-facing claim¶

• eduPersonOrcid in a collision-resistant private claim¶

• eduPersonPrincipalNamePrior only by explicit policy for relying parties that require historical identifier information¶

For InCommon-style bundles used only to preserve legacy application behavior, the authorization server SHOULD prefer standard OpenID Connect claims when there is a good semantic match and SHOULD retain the original attribute semantics in private claims rather than mapping them to unrelated standard claims such as groups, roles, or scope.¶

C.1. Common SAML AuthnContextClassRef URIs

C.2. Notes on these mappings

• amr is a JSON array; multi-factor SAML classes naturally produce multiple values (typically including mfa).¶

• acr values shown for NIST 800-63 are strings of the form "aal1", "aal2", "aal3". Deployments MAY use URI forms such as those defined by REFEDS for federated higher-education contexts.¶

• The Smartcard / SmartcardPKI / X509 rows depend heavily on key storage (software vs. hardware-bound) and whether a second factor (PIN, password) is also asserted. Deployments SHOULD configure the mapping based on the IdP's actual authentication setup, not the SAML class URI alone.¶

• The Kerberos row reflects that most enterprise Kerberos deployments are password-derived; deployments using stronger Kerberos factors (smart card initial credentials, etc.) SHOULD map accordingly.¶

• PreviousSession and unspecified provide no derivable assurance signal; acr SHOULD be omitted, and amr SHOULD NOT be populated from them.¶

• When the SAML deployment uses non-standard AuthnContextClassRef URIs (vendor-specific, IdP-specific, or federation-defined), the authorization server MAY pass the URI through to acr per Section 13.1, with amr populated only when the local mapping explicitly authorizes specific values.¶

C.3. Pass-through and absence

When local policy does not provide a mapping for an asserted AuthnContextClassRef, the authorization server SHOULD copy the SAML URI to acr without transformation per Section 13.1. The authorization server MUST NOT populate amr in this case, since deriving amr from an unmapped class URI would overstate the assurance.¶