oauth2.dev

assertion

IESG

Registry Context

`assertion` carries an assertion submitted to the token endpoint as an OAuth authorization grant.

Technical Summary

RFC 7521 defines `assertion` as a REQUIRED token-request parameter in the assertion authorization-grant flow. The assertion's serialization is defined by the applicable assertion profile, while RFC 7521 defines general content and processing rules.

When Used

When a client exchanges an assertion for an access token using an assertion authorization grant.

Normative Requirements

Clients

MUST
1
  1. RFC 7521 - Section 4.1

    request a scope equal to or less than the scope originally granted to the authorized accessor.

    Condition: when exchanging an assertion for an access token and requesting scope

    "the requested scope MUST be equal to or less than the scope originally granted"

REQUIRED
2
  1. RFC 7521 - Section 4.1

    include a `grant_type` parameter containing the assertion format defined by the authorization server as an absolute URI.

    Condition: when using an assertion as an authorization grant

    `grant_type` is "REQUIRED" and its value is an absolute URI.

  2. RFC 7521 - Section 4.1

    include the `assertion` parameter containing the assertion used as the authorization grant.

    Condition: when using an assertion as an authorization grant

    `assertion` is "REQUIRED. The assertion being used as an authorization grant."

OPTIONAL
1
  1. RFC 7521 - Section 4.1

    include a `scope` parameter specifying the requested scope.

    Condition: when using an assertion as an authorization grant

    `scope` is "OPTIONAL."

Authorization servers

MUST
5
  1. RFC 7521 - Section 4.1

    limit the issued access token's scope to be equal to or less than the scope originally granted to the authorized accessor.

    Condition: when exchanging an assertion for an access token

    "The authorization server MUST limit the scope of the issued access token"

  2. RFC 7521 - Section 4.1.1

    set the error response's `error` parameter to `invalid_grant`.

    Condition: if the assertion is invalid or expired

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

  3. RFC 7521 - Section 5.2

    reject an assertion that does not identify it as the intended audience.

    Condition: if its identity is absent from the assertion's intended audience

    "The authorization server MUST reject any assertion that does not contain its own identity as the intended audience."

  4. RFC 7521 - Section 5.2

    reject expired assertions, subject to allowable clock skew between systems.

    Condition: if the assertion has expired

    "The authorization server MUST reject assertions that have expired"

  5. RFC 7521 - Section 5.2

    reject assertions with an invalid signature or MAC.

    Condition: if the assertion's signature or MAC is invalid

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

SHOULD NOT
1
  1. RFC 7521 - Section 4.1

    issue an access token whose lifetime significantly exceeds the assertion's validity period.

    Condition: when issuing an access token from an assertion grant

    "authorization servers SHOULD NOT issue access tokens with a lifetime that exceeds the validity period of the assertion by a significant period"

MAY
1
  1. RFC 7521 - Section 4.1.1

    include additional information about why the assertion was considered invalid using `error_description` or `error_uri`.

    Condition: if the assertion is invalid or expired

    "The authorization server MAY include additional information" using `error_description` or `error_uri`.

assertion

MUST
6
  1. RFC 7521 - Section 5.2

    contain an Issuer.

    "The assertion MUST contain an Issuer."

  2. RFC 7521 - Section 5.2

    use the client's `client_id` as the Issuer.

    Condition: if the assertion is self-issued

    "the Issuer MUST be the value of the client's \"client_id\""

  3. RFC 7521 - Section 5.2

    contain a Subject.

    "The assertion MUST contain a Subject."

  4. RFC 7521 - Section 5.2

    use the client's `client_id` as the Subject.

    Condition: when the client is acting on behalf of itself

    "the Subject MUST be the value of the client's \"client_id\""

  5. RFC 7521 - Section 5.2

    contain an Audience identifying the authorization server as the intended audience.

    "The assertion MUST contain an Audience that identifies the authorization server as the intended audience."

  6. RFC 7521 - Section 5.2

    contain an Expires At entity limiting the time window in which it can be used.

    "The assertion MUST contain an Expires At entity"

MAY
1
  1. RFC 7521 - Section 5.2

    contain an Issued At entity specifying its UTC issuance time.

    "The assertion MAY contain an Issued At entity containing the UTC time"

Validation Guidance

error

Require both `grant_type` and `assertion` for an assertion authorization-grant request, and require `grant_type` to be the applicable absolute assertion-format URI.

error

When `scope` is supplied, verify that it does not exceed the scope originally granted; also constrain the issued token accordingly.

warning

Do not issue an access token whose lifetime significantly exceeds the assertion's validity period.

error

For an invalid or expired assertion, set `error` to `invalid_grant`; additional diagnostic fields are optional.

error

Require Issuer, Subject, Audience, and Expires At entities in the assertion.

error

For self-issued assertions or clients acting on their own behalf, verify the applicable Issuer or Subject equals the client's `client_id`.

error

Reject assertions that do not identify the authorization server as an intended audience, are expired beyond allowable clock skew, or have an invalid signature or MAC.

info

Accept an Issued At entity as an optional assertion field.

Reference

Details

Entry Id
assertion
Name
assertion
Parameter Usage Location
token request
Change Controller
IESG
Reference
RFC7521