oauth2.dev

refresh_token

IETF

Registry Context

The refresh_token parameter carries a refresh token in a token endpoint refresh request and can carry a newly issued refresh token in a successful token response.

Technical Summary

RFC 6749 requires refresh_token in a refresh-token grant request and makes it optional in a successful token response. Refresh tokens are client-bound confidential credentials. RFC 9700 additionally requires risk-based issuance, binding to the consented scope and resource servers, and replay detection for public clients.

When Used

Used when a client exchanges a refresh token at the token endpoint for a new access token, and when the authorization server initially issues or subsequently rotates a refresh token.

Normative Requirements

Clients

MUST NOT
1
  1. RFC 6749 - Section 6

    request any scope not originally granted by the resource owner..

    Condition: when including scope in a refresh request

    The requested scope MUST NOT include any scope not originally granted by the resource owner.

MUST
3
  1. RFC 6749 - Section 6

    set grant_type to "refresh_token"..

    Condition: when making a refresh-token grant request

    Value MUST be set to "refresh_token".

  2. RFC 6749 - Section 6

    authenticate with the authorization server..

    Condition: if the client is confidential, was issued client credentials, or has other authentication requirements

    the client MUST authenticate with the authorization server as described in Section 3.2.1.

  3. RFC 6749 - Section 6

    discard the old refresh token and replace it with the new refresh token..

    Condition: if a new refresh token is issued

    the client MUST discard the old refresh token and replace it with the new refresh token.

REQUIRED
2
  1. RFC 6749 - Section 6

    include the refresh_token parameter in the refresh request..

    Condition: when making a refresh-token grant request

    refresh_token REQUIRED. The refresh token issued to the client.

  2. RFC 6749 - Section 6

    include the grant_type parameter in the refresh request..

    Condition: when making a refresh-token grant request

    grant_type REQUIRED.

OPTIONAL
1
  1. RFC 6749 - Section 6

    include the scope parameter in the refresh request..

    Condition: when making a refresh-token grant request

    scope OPTIONAL.

Authorization servers

MUST
12
  1. RFC 6749 - Section 10.4

    maintain the binding between a refresh token and the client to which it was issued..

    Condition: when issuing and processing refresh tokens

    The authorization server MUST maintain the binding between a refresh token and the client to whom it was issued.

  2. RFC 6749 - Section 10.4

    verify the binding between the refresh token and client identity..

    Condition: whenever the client identity can be authenticated

    The authorization server MUST verify the binding between the refresh token and client identity whenever the client identity can be authenticated.

  3. RFC 6749 - Section 10.4

    ensure unauthorized parties cannot generate, modify, or guess values that produce valid refresh tokens..

    Condition: when designing and issuing refresh tokens

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

  4. RFC 6749 - Section 5.1

    include Cache-Control with value "no-store" and Pragma with value "no-cache"..

    Condition: in any response containing a refresh token or other sensitive information

    The authorization server MUST include the HTTP "Cache-Control" response header field with a value of "no-store" ... as well as the "Pragma" response header field with a value of "no-cache".

  5. RFC 6749 - Section 6

    require client authentication..

    Condition: for confidential clients and clients issued credentials or assigned other authentication requirements

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

  6. RFC 6749 - Section 6

    authenticate the client and ensure the refresh token was issued to that client..

    Condition: if client authentication is included

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

  7. RFC 6749 - Section 6

    validate the refresh token..

    Condition: when processing a refresh request

    The authorization server MUST: validate the refresh token.

  8. RFC 6749 - Section 6

    keep the new refresh token's scope identical to the scope of the refresh token presented by the client..

    Condition: if a new refresh token is issued

    the refresh token scope MUST be identical to that of the refresh token included by the client in the request.

  9. RFC 9700 - Section 4.14.2

    determine whether to issue refresh tokens to a particular client based on a risk assessment..

    Condition: before issuing refresh tokens

    Authorization servers MUST determine, based on a risk assessment, whether to issue refresh tokens to a certain client.

  10. RFC 9700 - Section 4.14.2

    bind issued refresh tokens to the scope and resource servers consented to by the resource owner..

    Condition: if refresh tokens are issued

    those refresh tokens MUST be bound to the scope and resource servers as consented by the resource owner.

  11. RFC 9700 - Section 4.14.2

    use sender-constrained refresh tokens or refresh token rotation to detect replay for public clients..

    Condition: when issuing refresh tokens to public clients

    Authorization servers MUST utilize one of these methods to detect refresh token replay by malicious actors for public clients.

  12. RFC 9700 - Section 4.14.2

    ensure the integrity of a refresh token value that encodes its associated grant..

    Condition: if grant information is encoded into the refresh token itself

    Authorization servers MUST ensure the integrity of the refresh token value in this case.

SHOULD
1
  1. RFC 6749 - Section 10.4

    deploy other means to detect refresh token abuse..

    Condition: when client authentication is not possible

    the authorization server SHOULD deploy other means to detect refresh token abuse.

MAY
4
  1. RFC 6749 - Section 10.4

    issue refresh tokens to web application clients and native application clients..

    Authorization servers MAY issue refresh tokens to web application clients and native application clients.

  2. RFC 6749 - Section 6

    issue a new refresh token..

    Condition: when issuing an access token in response to a valid refresh request

    The authorization server MAY issue a new refresh token.

  3. RFC 6749 - Section 6

    revoke the old refresh token..

    Condition: after issuing a new refresh token to the client

    The authorization server MAY revoke the old refresh token after issuing a new refresh token.

  4. RFC 9700 - Section 4.14.2

    automatically revoke refresh tokens following a security event..

    Condition: in case of a security event such as a password change or logout

    Authorization servers MAY revoke refresh tokens automatically in case of a security event.

OPTIONAL
1
  1. RFC 6749 - Section 5.1

    include the refresh_token parameter in a successful token response..

    Condition: when constructing a successful token response

    refresh_token OPTIONAL.

authorization server and client

MUST
2
  1. RFC 6749 - Section 10.4

    keep refresh tokens confidential in transit and storage and share them only between the authorization server and the client to which they were issued..

    Condition: when handling refresh tokens

    Refresh tokens MUST be kept confidential in transit and storage, and shared only among the authorization server and the client.

  2. RFC 6749 - Section 10.4

    transmit refresh tokens only using TLS with server authentication..

    Condition: when transmitting refresh tokens

    Refresh tokens MUST only be transmitted using TLS as described in Section 1.6 with server authentication.

refresh token

SHOULD
1
  1. RFC 9700 - Section 4.14.2

    expire after a period of client inactivity..

    Condition: if it has not been used to obtain fresh access tokens for some time

    Refresh tokens SHOULD expire if the client has been inactive for some time.

Validation Guidance

error

Require exactly one refresh_token parameter and grant_type=refresh_token for a refresh-token grant request.

error

Reject a requested scope containing any scope not originally granted; treat omitted scope as the originally granted scope.

info

Permit successful token responses to omit refresh_token; when present, process it as a newly issued refresh token.

error

For a rotated refresh token, require the client to replace the old token and preserve the original refresh-token scope.

error

Enforce client authentication and token-to-client binding whenever the client can be authenticated.

error

Protect refresh tokens in storage and transit, use authenticated TLS, and prevent guessing, unauthorized generation, and modification.

error

Set Cache-Control: no-store and Pragma: no-cache on responses containing refresh tokens.

error

Base refresh-token issuance on a risk assessment and bind issued tokens to the consented scope and resource servers.

error

For public clients, use sender-constrained refresh tokens or refresh token rotation to detect replay.

warning

Apply an inactivity lifetime to refresh tokens and consider automatic revocation after security events.

Security Notes

RFC 6749 - Section 10.4

Refresh tokens are confidential credentials shared only between the authorization server and the client to which they were issued.

RFC 6749 - Section 10.4

Refresh tokens must be protected against guessing, modification, unauthorized generation, and insecure transmission.

RFC 9700 - Section 4.14.2

Public-client refresh tokens require sender constraint or rotation to detect replay.

RFC 9700 - Section 4.14.2

Refresh tokens must remain limited to the scope and resource servers consented to by the resource owner.

Reference

Details

Entry Id
refresh_token
Name
refresh_token
Parameter Usage Location
token request, token response
Change Controller
IETF
Reference
RFC6749