oauth2.dev

urn:ietf:params:oauth:grant-type:saml2-bearer

IESG

Registry Context

This OAuth URI is used as the grant_type value when a client exchanges a SAML 2.0 bearer assertion for an access token.

Technical Summary

RFC 7522 defines this URN as the grant_type value for the SAML 2.0 bearer assertion authorization grant and registers it in the OAuth URI registry.

When Used

In an OAuth access token request where a SAML 2.0 assertion is presented as the authorization grant.

Normative Requirements

Clients

MUST NOT
3
  1. RFC 7522 - Section 2.1

    The assertion parameter MUST NOT contain more than one SAML 2.0 Assertion..

    Condition: When presenting a SAML bearer assertion as an authorization grant.

    It MUST NOT contain more than one SAML 2.0 Assertion.

  2. RFC 7522 - Section 2.1

    The base64url-encoded assertion data MUST NOT be line wrapped..

    Condition: When encoding the assertion parameter.

    the base64url-encoded data MUST NOT be line wrapped

  3. RFC 7522 - Section 2.1

    Base64url pad characters ('=') MUST NOT be included in the assertion parameter..

    Condition: When encoding the assertion parameter.

    pad characters ("=") MUST NOT be included

MUST
1
  1. RFC 7522 - Section 2.1

    The SAML Assertion XML data MUST be base64url encoded according to RFC 4648 Section 5, with padding bits set to zero..

    Condition: When encoding the assertion parameter.

    The SAML Assertion XML data MUST be encoded using base64url.

Authorization servers

MUST
9
  1. RFC 7522 - Section 3

    The authorization server MUST validate the assertion according to the criteria in RFC 7522 Section 3 before issuing an access token..

    Condition: Before issuing an access token based on the assertion.

    the authorization server MUST validate the Assertion according to the criteria below

  2. RFC 7522 - Section 3

    The authorization server MUST reject an assertion that does not identify it as an intended audience..

    MUST reject any Assertion that does not contain its own identity as the intended audience

  3. RFC 7522 - Section 3

    The authorization server MUST verify that Recipient matches the token endpoint URL or acceptable alias receiving the assertion..

    Condition: When SubjectConfirmationData contains Recipient.

    MUST verify that the value of the Recipient attribute matches the token endpoint URL

  4. RFC 7522 - Section 3

    The authorization server MUST reject the entire assertion when the Conditions NotOnOrAfter instant has passed, subject to allowable clock skew..

    Condition: When the Conditions NotOnOrAfter instant has passed.

    MUST reject the entire Assertion if the NotOnOrAfter instant on the <Conditions> element has passed

  5. RFC 7522 - Section 3

    The authorization server MUST reject a SubjectConfirmation when its SubjectConfirmationData NotOnOrAfter instant has passed, subject to allowable clock skew..

    Condition: When the SubjectConfirmationData NotOnOrAfter instant has passed.

    MUST reject the <SubjectConfirmation> if the NotOnOrAfter instant ... has passed

  6. RFC 7522 - Section 3

    The authorization server MUST reject assertions with an invalid signature or MAC..

    MUST reject Assertions with an invalid signature or MAC

  7. RFC 7522 - Section 3

    The authorization server MUST reject an assertion that is otherwise invalid under the SAML 2.0 core specification..

    MUST reject an Assertion that is not valid in all other respects

  8. RFC 7522 - Section 3.1

    The authorization server MUST validate client credentials when they are present in the request..

    Condition: If client credentials are present.

    if client credentials are present ... the authorization server MUST validate them

  9. RFC 7522 - Section 3.1

    The error parameter MUST be invalid_grant when the assertion is invalid or its subject-confirmation requirements cannot be met..

    Condition: When rejecting an invalid assertion.

    The value of the "error" parameter MUST be the "invalid_grant" error code.

MAY
1
  1. RFC 7522 - Section 3

    The authorization server MAY prevent bearer assertion replay by retaining used assertion ID values for the assertion's validity period..

    The authorization server MAY ensure that Bearer Assertions are not replayed

assertion issuer

MUST
9
  1. RFC 7522 - Section 3

    The assertion's Issuer element MUST contain a unique identifier for the entity that issued it..

    The Assertion's <Issuer> element MUST contain a unique identifier

  2. RFC 7522 - Section 3

    The assertion MUST contain Conditions, AudienceRestriction, and Audience elements identifying the authorization server as an intended audience..

    The Assertion MUST contain a <Conditions> element with an <AudienceRestriction> element

  3. RFC 7522 - Section 3

    The assertion MUST contain a Subject element identifying its subject principal..

    The Assertion MUST contain a <Subject> element identifying the principal

  4. RFC 7522 - Section 3

    The assertion MUST have an expiry limiting the period during which it can be used..

    The Assertion MUST have an expiry that limits the time window

  5. RFC 7522 - Section 3

    The Subject element MUST contain at least one bearer-method SubjectConfirmation element..

    The <Subject> element MUST contain at least one <SubjectConfirmation> element

  6. RFC 7522 - Section 3

    The SubjectConfirmation element MUST contain SubjectConfirmationData when Conditions lacks a suitable NotOnOrAfter attribute..

    Condition: If the Conditions element lacks a suitable NotOnOrAfter attribute.

    the <SubjectConfirmation> element MUST contain a <SubjectConfirmationData> element

  7. RFC 7522 - Section 3

    SubjectConfirmationData MUST contain a Recipient identifying the authorization server's token endpoint URL or an acceptable alias..

    Condition: When SubjectConfirmationData is present.

    MUST have a Recipient attribute with a value indicating the token endpoint URL

  8. RFC 7522 - Section 3

    SubjectConfirmationData MUST contain a NotOnOrAfter attribute limiting the assertion confirmation period..

    Condition: When SubjectConfirmationData is present.

    MUST have a NotOnOrAfter attribute that limits the window

  9. RFC 7522 - Section 3

    The assertion MUST be digitally signed or have a MAC applied by its issuer..

    The Assertion MUST be digitally signed or have a Message Authentication Code

compliant application

MUST
2
  1. RFC 7522 - Section 3

    Issuer values MUST be compared using RFC 3986 simple string comparison unless an application profile specifies otherwise..

    Condition: In the absence of an application profile specifying otherwise.

    compliant applications MUST compare Issuer values using the Simple String Comparison method

  2. RFC 7522 - Section 3

    Audience values MUST be compared using RFC 3986 simple string comparison unless an application profile specifies otherwise..

    Condition: In the absence of an application profile specifying otherwise.

    compliant applications MUST compare the Audience values using the Simple String Comparison method

Validation Guidance

error

Verify that grant_type is exactly urn:ietf:params:oauth:grant-type:saml2-bearer for this grant profile.

error

Reject an assertion parameter containing more than one SAML 2.0 Assertion.

error

Reject assertion data that is not valid unpadded, non-line-wrapped base64url with zero padding bits.

error

Validate the assertion's issuer, audience, subject, expiry, bearer subject confirmation, recipient, signature or MAC, and general SAML validity.

error

Validate client credentials when the token request includes them.

error

Return invalid_grant when assertion validation or subject confirmation fails.

warning

Consider retaining used assertion IDs until expiration to detect replay.

Security Notes

RFC 7522 - Section 6

RFC 7522 does not mandate replay protection; implementations may optionally retain used assertion IDs for the assertion validity period.

RFC 7522 - Section 7

SAML assertions may contain privacy-sensitive information and should be transmitted over encrypted channels such as TLS; deployments should minimize disclosed information.

Reference

Details

Entry Id
urn:ietf:params:oauth:grant-type:saml2-bearer
Urn
urn:ietf:params:oauth:grant-type:saml2-bearer
Common Name
SAML 2.0 Bearer Assertion Grant Type Profile for OAuth 2.0
Change Controller
IESG
Reference
RFC7522, RFC-ietf-oauth-rfc7523bis-11