oauth2.dev

token

IETF

Registry Context

The token response type requests an access token directly from the authorization endpoint using the OAuth 2.0 implicit grant. Current OAuth security guidance says clients should generally avoid this flow because authorization responses can leak or expose access tokens to replay.

Technical Summary

For an RFC 6749 implicit authorization request, response_type is required and must equal token. A successful response carries access_token and token_type in the redirection URI fragment, conditionally carries scope and state, and must not contain a refresh token. RFC 9700 recommends using the authorization code flow instead unless token-injection and leakage threats are mitigated.

When Used

Historically used by clients requiring an access token directly from an authorization response. New deployments should generally use the authorization code flow instead.

Normative Requirements

Clients

MUST
2

  1. RFC 6749 - Section 4.2.1

    Set response_type to token..

    Condition: When constructing an implicit grant authorization request.

    Value MUST be set to "token".

  2. RFC 6749 - Section 4.2.2

    Ignore unrecognized response parameters..

    Condition: When processing an implicit grant access token response.

    The client MUST ignore unrecognized response parameters.

REQUIRED
2

  1. RFC 6749 - Section 3.1.1

    Include the response_type parameter in the authorization request..

    Condition: When making a request to the authorization endpoint.

    response_type REQUIRED.

  2. RFC 6749 - Section 4.2.1

    Include client_id in the implicit grant authorization request..

    Condition: When constructing an implicit grant authorization request.

    client_id REQUIRED.

SHOULD NOT
1

  1. RFC 9700 - Section 2.1.2

    Use the implicit grant or another response type that issues access tokens in the authorization response..

    Condition: Unless access-token injection is prevented and the identified token-leakage vectors are mitigated.

    Clients SHOULD NOT use the implicit grant (response type token) or other response types issuing access tokens in the authorization response.

SHOULD
3

  1. RFC 6749 - Section 10.3

    Request access tokens with the minimal necessary scope..

    Condition: When requesting an access token.

    The client SHOULD request access tokens with the minimal scope necessary.

  2. RFC 6749 - Section 4.2.1

    Use state to prevent cross-site request forgery..

    Condition: When constructing an implicit grant authorization request.

    The parameter SHOULD be used for preventing cross-site request forgery.

  3. RFC 9700 - Section 2.1.2

    Use the code response type or another response type that causes access tokens to be issued in the token response..

    Condition: Instead of using the implicit grant.

    Clients SHOULD instead use the response type code ... or any other response type that causes the authorization server to issue access tokens in the token response.

RECOMMENDED
1

  1. RFC 6749 - Section 4.2.1

    Include an opaque state value to maintain state between the request and callback..

    Condition: When constructing an implicit grant authorization request.

    state RECOMMENDED.

OPTIONAL
2

  1. RFC 6749 - Section 4.2.1

    Include redirect_uri in the implicit grant authorization request..

    Condition: When constructing an implicit grant authorization request.

    redirect_uri OPTIONAL.

  2. RFC 6749 - Section 4.2.1

    Include scope in the implicit grant authorization request..

    Condition: When constructing an implicit grant authorization request.

    scope OPTIONAL.

Authorization servers

MUST NOT
5

  1. RFC 6749 - Section 4.2.2

    Issue a refresh token..

    Condition: When producing an implicit grant access token response.

    The authorization server MUST NOT issue a refresh token.

  2. RFC 6749 - Section 4.2.2.1

    Automatically redirect the user-agent to the invalid redirection URI..

    Condition: If the redirect URI is missing, invalid, or mismatched, or the client identifier is missing or invalid.

    The authorization server MUST NOT automatically redirect the user-agent to the invalid redirection URI.

  3. RFC 6749 - Section 4.2.2.1

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

    Condition: When returning an implicit grant error response.

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

  4. RFC 6749 - Section 4.2.2.1

    Include characters outside %x20-21 / %x23-5B / %x5D-7E in error_description..

    Condition: When error_description is included.

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

  5. RFC 6749 - Section 4.2.2.1

    Include characters outside %x21 / %x23-5B / %x5D-7E in error_uri..

    Condition: When error_uri is included.

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

MUST
4

  1. RFC 6749 - Section 10.3

    Ensure unauthorized parties cannot generate, modify, or guess values that produce valid access tokens..

    Condition: When issuing and validating access tokens.

    The authorization server MUST ensure that access tokens cannot be generated, modified, or guessed to produce valid access tokens by unauthorized parties.

  2. RFC 6749 - Section 3.1.1

    Return an error response..

    Condition: If response_type is missing or not understood.

    The authorization server MUST return an error response.

  3. RFC 6749 - Section 4.2.1

    Verify that the URI to which it will redirect the access token matches a redirection URI registered by the client..

    Condition: When validating an implicit grant authorization request.

    The authorization server MUST verify that the redirection URI to which it will redirect the access token matches a redirection URI registered by the client.

  4. RFC 6749 - Section 4.2.2.1

    Make error_uri conform to URI-reference syntax..

    Condition: When error_uri is included.

    Values for the "error_uri" parameter MUST conform to the URI-reference syntax.

REQUIRED
6

  1. RFC 6749 - Section 4.2.2

    Include access_token in a successful implicit grant response..

    Condition: If the resource owner grants the access request.

    access_token REQUIRED.

  2. RFC 6749 - Section 4.2.2

    Include token_type in a successful implicit grant response..

    Condition: If the resource owner grants the access request.

    token_type REQUIRED.

  3. RFC 6749 - Section 4.2.2

    Include scope in a successful implicit grant response..

    Condition: If the issued scope is not identical to the scope requested by the client.

    otherwise, REQUIRED.

  4. RFC 6749 - Section 4.2.2

    Include state with the exact value received from the client..

    Condition: If state was present in the authorization request.

    state REQUIRED if the "state" parameter was present in the client authorization request.

  5. RFC 6749 - Section 4.2.2.1

    Include the error parameter in an implicit grant error response..

    Condition: When returning an error through a valid redirection URI.

    error REQUIRED.

  6. RFC 6749 - Section 4.2.2.1

    Include state with the exact value received from the client in the error response..

    Condition: If state was present in the authorization request and an error is returned through the redirection URI.

    state REQUIRED if a "state" parameter was present in the client authorization request.

SHOULD
4

  1. RFC 6749 - Section 10.3

    Take the client identity into account when deciding how to honor requested scope..

    Condition: When issuing an access token.

    The authorization server SHOULD take the client identity into account when choosing how to honor the requested scope.

  2. RFC 6749 - Section 4.2.2

    Provide the expiration time by other means or document the default value..

    Condition: If expires_in is omitted.

    The authorization server SHOULD provide the expiration time via other means or document the default value.

  3. RFC 6749 - Section 4.2.2

    Document the size of values it issues..

    Condition: When issuing response values.

    The authorization server SHOULD document the size of any value it issues.

  4. RFC 6749 - Section 4.2.2.1

    Inform the resource owner of the error..

    Condition: If the redirect URI is missing, invalid, or mismatched, or the client identifier is missing or invalid.

    The authorization server SHOULD inform the resource owner of the error.

RECOMMENDED
1

  1. RFC 6749 - Section 4.2.2

    Include expires_in in a successful implicit grant response..

    Condition: If the resource owner grants the access request.

    expires_in RECOMMENDED.

MAY
1

  1. RFC 6749 - Section 10.3

    Issue an access token with fewer rights than requested..

    Condition: When issuing an access token.

    The authorization server ... MAY issue an access token with less rights than requested.

OPTIONAL
1

  1. RFC 6749 - Section 4.2.2

    Omit scope from a successful implicit grant response..

    Condition: If the issued scope is identical to the scope requested by the client.

    scope OPTIONAL, if identical to the scope requested by the client.

client and authorization server

MUST
2

  1. RFC 6749 - Section 10.3

    Keep access-token credentials confidential in transit and storage..

    Condition: When handling access tokens.

    Access token credentials ... MUST be kept confidential in transit and storage.

  2. RFC 6749 - Section 10.3

    Transmit access-token credentials only using TLS with server authentication..

    Condition: When transmitting access tokens.

    Access token credentials MUST only be transmitted using TLS.

Validation Guidance

error

Require response_type and require its value to be exactly token for an implicit grant authorization request.

error

Require client_id in an implicit grant authorization request.

error

When redirecting an access token, verify the redirect URI against the client's registered redirection URIs.

error

Return an authorization error when response_type is missing or unsupported.

error

For successful response_type=token responses, require access_token and token_type in the URI fragment.

error

Require scope when the issued scope differs from the requested scope.

error

Require state to be returned unchanged when the authorization request included state.

error

Reject any refresh_token in an implicit grant response.

error

Clients must tolerate unrecognized response parameters.

error

Do not redirect to an invalid or unverified redirect URI when reporting an authorization error.

error

For errors returned through a valid redirect URI, require error in the fragment and enforce the parameter character restrictions.

warning

Treat use of response_type=token as a security warning unless access-token injection and leakage threats are demonstrably mitigated.

Security Notes

RFC 6749 - Section 10.3

Implicit-grant access tokens are transmitted in the URI fragment, which can expose them to unauthorized parties.

RFC 6749 - Section 10.3

Access-token credentials must remain confidential in transit and storage and must only be transmitted using TLS with server authentication.

RFC 9700 - Section 2.1.2

Authorization responses carrying access tokens are vulnerable to token leakage and replay, and no standardized sender-constraining method binds such tokens to a specific client.

RFC 9700 - Section 2.1.2

Current security best practice advises clients not to use the implicit grant unless access-token injection is prevented and relevant leakage vectors are mitigated.

Reference

RFC6749

Details

Entry Id
token
Name
token
Change Controller
IETF
Reference
RFC6749