Home Wiki

Refresh Token Grant

The refresh token grant can be used with a longer-lived refresh token requesting the token endpoint for a new token.

How to enable it

It’s enabled by default, with any rodauth-oauth feature.

plugin :rodauth do
  enable :oauth_authorization_code_grant # for example
end

POST /token

The endpoint for refreshing the token is, as per RFC, the same one for generating access tokens.

Request Parameters

The request will have to contain:

grant_type: must be "refresh_token";
refresh_token: the refresh token;

Response Parameters

A successful refresh of a token will send back the following parameters in the response JSON body:

access_token: a new access token;
token_type: the type of token;
expires_in: number of seconds after which the new access token expires;
refresh_token: a new refresh token (or the same, see the “protection policy” below);

A failed request will get the following parameters in the response JSON body:

error_code: the code error, as per RFC;
error_description: the description of the error;

Examples

require "httpx"
response = HTTPX.post("https://oauth-server.com/token",json: {
                  client_id: ENV["CLIENT_ID"],
                  client_secret: ENV["CLIENT_SECRET"],
                  grant_type: "refresh_token",
                  token: "2r90j212j901jdf9jdj9dj0n"
                })
response.raise_for_status
payload = JSON.parse(response.to_s)
puts payload #=> {"access_token" => "awr23f3h8f9d2h89...", ....

# using cURL
> curl --data '{"client_id":"$OAUTH_CLIENT_ID","client_secret":"$OAUTH_CLIENT_SECRET","grant_type":"token","code":"2r90j212j901jdf9jdj9dj0n"}' https://oauth-server.com/token

How to use it

Refreshed tokens can be used the same way as other access tokens.

Refresh Token Expiration

For all expired access tokens with a refresh token, its refresh token can only be used for the period defined by oauth_refresh_token_expires_in (default: 1 year) since the access token expired.

Protection Policy

Inspired by the OAuth 2.1 Framework RFC.

By default, the option oauth_refresh_token_protection_policy is set to "rotation". This consists of the following rules:

all refresh tokens requests will also generate a new refresh token, i.e. all refresh tokens can be used only once;
All usage of refresh token which have already been used will be interpreted as a security breach, i.e. someone gained access to the tokens, and access tokens generated using the compromised refresh tokens will be immediately revoked.

"sender_constrained" and "none" are also supported.

Home

honeyryder