oauth2.dev

invalid_grant

IETF

Registry Context

OAuth 2.0 token endpoint error code indicating that the supplied authorization grant or refresh token is invalid.

Technical Summary

RFC 6749 defines `invalid_grant` for a provided authorization grant or refresh token that is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

When Used

In a token endpoint error response when the supplied authorization grant or refresh token has one of the conditions defined for `invalid_grant` in RFC 6749 Section 5.2.

Normative Requirements

Authorization servers

MUST NOT
1

  1. RFC 6749 - Section 5.2

    Include characters outside `%x20-21 / %x23-5B / %x5D-7E` in the `error` parameter value..

    Condition: when returning the `error` parameter

    Values for the "error" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.

MUST
8

  1. RFC 6749 - Section 4.1.3

    Require client authentication for confidential clients and clients issued client credentials or assigned other authentication requirements..

    Condition: when processing an authorization-code access-token request

    The authorization server MUST: require client authentication for confidential clients or for any client that was issued client credentials

  2. RFC 6749 - Section 4.1.3

    Authenticate the client when client authentication is included..

    Condition: when processing an authorization-code access-token request that includes client authentication

    The authorization server MUST: authenticate the client if client authentication is included

  3. RFC 6749 - Section 4.1.3

    Ensure that the authorization code was issued to the authenticated confidential client or, for a public client, to the `client_id` in the request..

    Condition: when processing an authorization-code access-token request

    The authorization server MUST: ensure that the authorization code was issued to the authenticated confidential client, or if the client is public, ensure that the code was issued to "client_id" in the request

  4. RFC 6749 - Section 4.1.3

    Verify that the authorization code is valid..

    Condition: when processing an authorization-code access-token request

    The authorization server MUST: verify that the authorization code is valid

  5. RFC 6749 - Section 4.1.3

    Ensure that `redirect_uri` is present if it was included in the initial authorization request and, if included, ensure that the values are identical..

    Condition: when processing an authorization-code access-token request

    The authorization server MUST: ensure that the "redirect_uri" parameter is present if the "redirect_uri" parameter was included in the initial authorization request, and if included ensure that their values are identical

  6. RFC 6749 - Section 6

    Require client authentication for confidential clients and clients issued client credentials or assigned other authentication requirements..

    Condition: when processing a refresh-token request

    The authorization server MUST: require client authentication for confidential clients or for any client that was issued client credentials

  7. RFC 6749 - Section 6

    Authenticate the client when client authentication is included and ensure that the refresh token was issued to the authenticated client..

    Condition: when processing a refresh-token request that includes client authentication

    The authorization server MUST: authenticate the client if client authentication is included and ensure that the refresh token was issued to the authenticated client

  8. RFC 6749 - Section 6

    Validate the refresh token..

    Condition: when processing a refresh-token request

    The authorization server MUST: validate the refresh token.

REQUIRED
1

  1. RFC 6749 - Section 5.2

    Include the `error` parameter containing a single ASCII error code from the codes listed in Section 5.2..

    Condition: when returning a token endpoint error response under Section 5.2

    error REQUIRED. A single ASCII [USASCII] error code from the following

Validation Guidance

error

Require an `error` value in Section 5.2 token endpoint error responses and accept `invalid_grant` as one of the defined values.

error

Reject an `error` value containing characters outside `%x20-21 / %x23-5B / %x5D-7E`.

error

Use `invalid_grant` only when the supplied authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

error

For refresh-token requests, require applicable client authentication, validate included client authentication and token-to-client binding, and validate the refresh token.

error

For authorization-code token requests, require applicable client authentication and verify included authentication, code validity, client binding, and applicable redirect URI binding.

error

Return an error response as described in Section 5.2 when a refresh request fails verification or is invalid.

Reference

RFC6749

Details

Entry Id
invalid_grant
Name
invalid_grant
Usage Location
token endpoint
Protocol Extension
OAuth 2.0 Authorization Framework
Change Controller
IETF
Reference
RFC6749