SAML 2.0 to OpenID Connect and OAuth 2.0 Migration Profile

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 local identifier for the resolved Local Account, used as input when this profile requires a derived subject value.¶

3.1. Authorization and Consent Model

The authorization server MUST NOT treat a valid SAML assertion as end-user consent to issue OAuth tokens, release OpenID Connect claims, or return an active introspection response. The assertion proves the authentication event and supplies identity inputs; authorization remains an authorization server policy decision.¶

Before issuing a token or returning an active introspection response, the authorization server MUST have an explicit authorization basis. That basis:¶

• MUST be bound to the authenticated client, the saml_sp_entity_id, and the resolved Local Account;¶

• for Token Exchange, MUST be bound to the requested token type, requested scope, and, for access tokens, the resolved target service set; and¶

• for introspection, MUST authorize the authenticated client to validate the presented SAML input and receive any returned claims for the bound relying-party relationship.¶

The 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.¶

The authorization server MUST NOT create, expand, or infer an authorization grant solely from the presence, validity, or contents of the SAML assertion. SAML attributes MAY be used as inputs to an already-established authorization policy rule, but the policy rule itself MUST exist independently of the assertion presented in the current request.¶

For requests involving refresh tokens, ID Tokens, OpenID Connect scopes, target services, or claim release, the authorization server MUST apply the following additional rules:¶

• if the requested scope includes offline_access, policy MUST authorize refresh token issuance to the authenticated client for the resolved Local Account and bound saml_sp_entity_id;¶

• a prior SAML SSO event by itself MUST NOT authorize refresh token issuance;¶

• if the requested token type is urn:ietf:params:oauth:token-type:id_token, or if an access token request includes openid, policy MUST authorize release of the resulting OpenID Connect subject and claims to the authenticated client under the bound saml_sp_entity_id;¶

• the authorization server MUST NOT release claims solely because corresponding SAML attributes are present in the assertion; and¶

• if the requested OAuth scope, OpenID Connect scope, target service, or claim set exceeds what the prior SAML relying-party relationship and current authorization server policy permit, the authorization server MUST either narrow the granted scope and returned claims to the permitted set or reject the request with invalid_scope, invalid_target, or unauthorized_client, as appropriate.¶

If end-user consent is required by local policy and no valid consent or equivalent policy exists, the authorization server MUST reject the request with invalid_scope or unauthorized_client according to local policy.¶

4.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.¶

When multiple OAuth clients share the same saml_sp_entity_id, the authorization server MUST treat them as the same relying-party context for claim release and subject continuity under this profile.¶

If multiple OAuth clients sharing the same saml_sp_entity_id present conflicting subject_type values, the authorization server MUST reject the registration or runtime request that would create inconsistent subject semantics.¶

Clients SHOULD register subject_type explicitly when using this profile. When subject_type is not registered but saml_sp_entity_id is present, the authorization server MUST apply public as the effective subject type. This default aligns with OpenID Connect Core behavior when subject_type is not registered; deployments that previously relied on SAML SP-specific (pairwise) identifiers SHOULD register subject_type=pairwise explicitly to preserve that behavior. When subject_type is pairwise and saml_sp_entity_id is present, the authorization server MUST use the saml_sp_entity_id as the relying-party input for pairwise subject continuity.¶

When saml_sp_entity_id is present, a registered sector_identifier_uri [OIDC-REGISTRATION] MUST NOT alter pairwise subject calculation under this profile. If a client registration includes both saml_sp_entity_id and sector_identifier_uri, the authorization server MUST either ensure that the sector_identifier_uri represents the same historical relying-party context as the bound saml_sp_entity_id or reject the registration or request as inconsistent.¶

5.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 the SAML IdP Entity ID used by the corresponding SAML IdP;¶

• it MUST identify the 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 MUST be the value against which incoming SAML assertion issuers are validated when this profile processes SAML assertions directly.¶

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

5.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 SAML IdP Entity ID bound to the OAuth issuer.¶

When saml_metadata_uri is present:¶

• the referenced SAML metadata MUST describe the same saml_idp_entity_id;¶

• 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 saml_idp_entity_id; 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.¶

5.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.¶

5.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 8.¶

If this metadata value is omitted, no support is implied for direct introspection of additional token types under this profile.¶

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 8;¶

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

5.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.¶

5.6. SAML Key Material and ACR Metadata

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.¶

An OpenID Provider supporting this profile and publishing acr_values_supported metadata in Discovery [OIDC-DISCOVERY] SHOULD include any acr values that it can emit under this profile, including SAML AuthnContextClassRef URIs that it passes through without transformation when that set is enumerable. If the OpenID Provider cannot publish a reliable list, it SHOULD omit acr_values_supported rather than publish incomplete or misleading metadata.¶

6.1. Accepted SAML Inputs

For this profile, urn:ietf:params:oauth:token-type:saml2 can identify either a base64url-encoded SAML 2.0 assertion, as in [RFC8693], or a signed SAML Response wrapper 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.¶

This profile is limited to signed SAML input containing exactly one unencrypted SAML 2.0 bearer assertion. The SAML input is signed either as a signed Assertion or as a signed SAML Response containing exactly one bearer Assertion. Encrypted assertions are out of scope. SAML protocol messages other than Response, and assertions that rely on subject confirmation methods other than bearer, are also out of scope.¶

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

• a signed SAML Assertion; or¶

• a signed SAML Response from which the authorization server extracts exactly one enclosed Assertion.¶

6.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.¶

6.3. Encrypted Content

This profile does not define processing of encrypted subject or attribute content inside an otherwise accepted assertion, including EncryptedID and EncryptedAttribute. An authorization server consuming SAML input under this profile MUST reject any effective assertion containing such elements.¶

6.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 saml_idp_entity_id value bound to the OAuth issuer identifier; 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.¶

6.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 6.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 SAML 2.0 processing rules, including Assertion/Issuer, time validity (enforcing both Conditions/@NotBefore and Conditions/@NotOnOrAfter), conditions, and subject confirmation;¶

5. verify that the effective SAML Assertion/Issuer value matches the Trusted SAML IdP Entity ID defined in Section 6.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 at least one AudienceRestriction element; additional Audience values beyond the bound saml_sp_entity_id are permitted, need not correspond to the bound saml_sp_entity_id, and MUST NOT by themselves invalidate the assertion; and¶

8. reject the SAML input if client authentication, assertion audience, and the bound saml_sp_entity_id do not all identify the same relying-party migration context.¶

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 7.3 and Section 8.3.¶

6.6. Bearer Subject Confirmation

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 match a recipient URI or ACS endpoint associated by local configuration or SAML metadata with the bound saml_sp_entity_id. The valid Recipient values for a given saml_sp_entity_id are the ACS URLs registered in the bound SP's SAML metadata or equivalent administrative configuration; the AS's own token endpoint and introspection endpoint are not valid Recipient values under this profile. This check applies to assertions submitted under both the Token Exchange pattern and the introspection pattern;¶

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

• if InResponseTo is absent, the assertion MAY still be accepted under this profile. Deployments that require SP-initiated request correlation for the bound SAML relationship MUST reject such assertions;¶

• Address, if present, MUST either have been validated by the component that handled the front-channel SAML exchange or be validated 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.¶

6.7. Replay and Freshness

The authorization server MUST enforce any applicable SAML one-time-use, replay-prevention, and assertion freshness requirements associated with the trusted SAML deployment. At minimum, it 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 authorization server MUST also enforce any applicable SAML proxying restrictions.¶

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 under this profile 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 under this profile unless local replay policy or SAML OneTimeUse semantics require that result.¶

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. Such an assertion-age check is independent of the Conditions/@NotOnOrAfter validity constraint and of SessionNotOnOrAfter.¶

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

6.8. Migration Binding Rationale

This profile uses the SAML SP Entity ID as the primary migration key because SAML pairwise subject identifiers, attribute release policy, and audience restrictions are already typically bound to that value.¶

7.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
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
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

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 MUST NOT include padding characters (=). This encoding convention follows the operational form used by [RFC7522]. When a SAML <Response> is supplied, it is used only as a signed wrapper from which this profile extracts the effective assertion, according to Section 6.¶

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.¶

Target-selection processing for access token requests is defined in Section 7.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 11, 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 in this Token Exchange request. Deployments MAY support them by separate agreement, but they are outside this profile.¶

Only confidential clients can use this profile. Client authentication at the token endpoint uses the client's registered OAuth 2.0 client authentication method. The authenticated client MUST be a confidential client authorized for the saml_sp_entity_id that matches the SAML assertion audience.¶

7.2. Authorization Server Processing

7.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 6; or a currently asserted stable subject identifier conflicts with an existing persisted mapping and no explicitly authorized administrative remapping exists.¶

8.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
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

token=PHNhbWxwOlJlc3BvbnNlLi4u
&token_type_hint=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Asaml2

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 MUST NOT include padding characters (=). This encoding convention follows the operational form used by [RFC7522]. When a SAML <Response> is supplied, it is used only as a signed wrapper from which this profile extracts the effective assertion, according to Section 6.¶

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.¶

Only confidential clients can use this profile. Client authentication for the introspection endpoint is performed according to [RFC7662] and authorization server policy. The authenticated client MUST be authorized for the saml_sp_entity_id that matches the SAML assertion audience.¶

8.2. Authorization Server Processing

8.3. Error Response

If the introspection request is malformed — for example, 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.¶

10.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 9. 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.¶

10.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 4.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 4.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.¶

10.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 10.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.¶

10.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 10.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.¶

10.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 9 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.¶

11.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. The value SHOULD be copied without transformation. Clients operating under this migration profile MUST be prepared to receive SAML authentication context class URIs as acr values (for example, urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport). These are not registered OpenID Connect ACR values. If local policy maps SAML context class references to a registered Level of Assurance scheme, that mapping takes precedence over direct passthrough.¶

• 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.¶

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 corresponding to the authentication event that is authoritative for the OAuth or OpenID Connect transaction. When no other basis for selection exists, the authorization server SHOULD prefer the statement with the most recent AuthnInstant value. If the authorization server cannot determine the authoritative statement unambiguously, it SHOULD omit ambiguous derived claims rather than misstate them.¶

In assertions produced by SAML identity proxying, the most recent AuthnInstant may reflect the proxying IdP's re-issuance event rather than the original end-user authentication. Deployments using proxied assertions SHOULD establish an explicit policy for which AuthnStatement is authoritative and configure the authorization server accordingly.¶

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.¶

If the authorization server receives an authoritative signal that the underlying SAML-authenticated session ended earlier than SessionNotOnOrAfter, it MUST treat that earlier event as the operative end of the migrated session for purposes of this profile.¶

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.¶

11.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. Common mappings include:¶

• givenName or given_name to given_name¶

• sn, surname, or family_name to family_name¶

• displayName or name to name¶

• mail or email to email¶

• uid or preferred_username to preferred_username¶

• telephoneNumber or phone_number to phone_number¶

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.¶

Appendix B provides non-normative deployment guidance for common InCommon and eduPerson attribute mappings.¶

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.¶

The registered OpenID Connect claims listed above are single-valued string claims if present. The auth_time claim is a single numeric value. The amr claim 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;¶

• 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.¶

11.3. UserInfo Responses and OIDC Output Consistency

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 10;¶

• MUST apply the claim mapping rules in Section 11.1 and Section 11.2 to any returned claims; 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 11.1. 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, and sid at the time of ID Token issuance and MUST 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. When an ID Token has been issued, the UserInfo values for these claims MUST 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. However, 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.¶

The claim release policy applicable at the time of access token issuance and the claim release policy applicable at the time of the UserInfo request MUST both permit any claim returned from UserInfo. The authorization server MAY retain the issuance-time policy snapshot for continuity, but it MUST NOT use that snapshot to return claims that are disallowed by current policy or by the current Local Account or session state.¶

14.1. OAuth Dynamic Client Registration Metadata

This document requests registration of the following value 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: IESG¶

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

14.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: Identifier of the SAML 2.0 Identity Provider entity bound to the authorization server issuer¶

• Change Controller: IESG¶

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

• Metadata Name: saml_metadata_uri¶

• Metadata Description: HTTPS URI for the SAML metadata describing the SAML Identity Provider entity bound to the authorization server issuer¶

• Change Controller: IESG¶

• Specification Document(s): This document, Section 5.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: IESG¶

• Specification Document(s): This document, Section 5.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: IESG¶

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

14.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: IESG¶

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

14.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: claims¶

• Response Description: JSON object containing normalized subject and claim values derived from the introspected SAML assertion for the authorized client¶

• Change Controller: IESG¶

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

• Response Name: saml¶

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

• Change Controller: IESG¶

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

15.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-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>.

[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>.

15.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. 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
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

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
&subject_token=PHNhbWwyOkFzc2VydGlvbiB4bWxuczpzYW1sMj0iLi4uIj4uLi48L3NhbWwyOkFzc2VydGlvbj4
&subject_token_type=urn:ietf:params:oauth:token-type:saml2

{
  "issued_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0...",
  "token_type": "N_A",
  "scope": "openid profile email",
  "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",
  "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",
  "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 claims alongside SAML protocol metadata as JSON. 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 claims object 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
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=PHNhbWwycDpSZXNwb25zZSB4bWxuczpzYW1sMj0iLi4uIiB4bWxuczpzYW1sMnA9Ii4uLiI-Li4uPC9zYW1sMnA6UmVzcG9uc2U-
&token_type_hint=urn:ietf:params:oauth:token-type:saml2

{
  "active": true,
  "saml": {
    "input_type": "response",
    "response": {
      "id": "_d71b9f4f8b5b4a4b8f2f",
      "issuer": "https://login.example.com/idp",
      "issue_instant": "2026-04-21T18:00:00Z",
      "destination": "https://calendar.example.com/saml/acs",
      "in_response_to": "_sp-authnrequest-8f3a",
      "status_code": "urn:oasis:names:tc:SAML:2.0:status:Success",
      "has_nested_status_code": false
    },
    "assertion": {
      "id": "_a75adf55d9a24d6f8c2b",
      "issuer": "https://login.example.com/idp",
      "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_method": "urn:oasis:names:tc:SAML:2.0:cm:bearer",
      "subject_confirmation_recipient": "https://calendar.example.com/saml/acs",
      "subject_confirmation_in_response_to": "_sp-authnrequest-8f3a",
      "subject_confirmation_not_on_or_after": "2026-04-21T18:05:00Z"
    }
  },
  "claims": {
    "sub": "p7b4cf5d-9c2f-4f22-a6b9-6e3d8df5a1b0",
    "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"
  }
}

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.input_type == "response"
saml.response.issuer == stored.idp_entity_id
saml.assertion.issuer == stored.idp_entity_id
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
saml.response.status_code == "urn:oasis:names:tc:SAML:2.0:status:Success"
saml.response.has_nested_status_code == false
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
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

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

{
  "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
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

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

{
  "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
}