Refresh Token

Overview#

Refresh Tokens are a Credential in the form of a Sender Constrained Token issued to the OAuth Client by the Authorization Server that is used to obtain a new Access Tokens.

You may need a new Access Tokens because:

Issuing a Refresh Token is OPTIONAL at the discretion of the Authorization Server.

If the Authorization Server issues a Refresh Token, it is included when issuing an Access Token

A Refresh Token is a string representing the authorization granted to the OAuth Client by the Resource Owner.

The Refresh Token is usually opaque to the OAuth Client.

The Refresh Token denotes an identifier used to retrieve the Authorization information.

Refresh Token usually require a check against the Authorization Server.

Unlike Access Tokens, Refresh Tokens are intended for use only with Authorization Servers and are never sent to Resource Servers.

Obtaining Refresh Token#

Although the OAuth 2.0 specifications do not appear to define how to obtain a Refresh Token, the industry seems to have adopted that an OAuth Scope of offline_access within the Authorization Request or Authentication Request using an Authorization Code Grant may optionally get a Refresh Token.

OAuth 2.0 specifications specifically state:

Security considerations#

Refresh Token are long-lived. This means when a OAuth Client gets a Refresh Token from an Authorization Server, the Refresh Token must be stored securely to keep it from being used by potential attackers. If a Refresh Token is leaked, it could be used to obtain new Access Tokens (and access protected resources) until it is either blacklisted or it expires (which may take a long time).

Refresh Token must be issued to a single authenticated OAuth Client to prevent use of leaked tokens by other parties.

Using Refresh Token[1]#

This is a simple example of how Refresh Token can be obtained and used. Using a simple CURL command as the client.

The Token_endpoint could be (/oauth/token), which handles issuing of all types of grants (access and refresh tokens).

Assuming there is a Resource Owner ‘test‘ with password ‘test‘ and a OAuth Client ‘testclient‘ with a client secret ‘secret‘, a sample Access Token Request of a new Access Token/Refresh Token pair could be the following: 

$ curl -X POST -H 'Authorization: Basic dGVzdGNsaWVudDpzZWNyZXQ=' -d 'grant_type=password&username=test&password=test' localhost:3000/oauth/token
{
    "token_type":"bearer",
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiVlx1MDAxNcKbwoNUwoonbFPCu8KhwrYiLCJpYXQiOjE0NDQyNjI1NDMsImV4cCI6MTQ0NDI2MjU2M30.MldruS1PvZaRZIJR4legQaauQ3_DYKxxP2rFnD37Ip4",
    "expires_in":20,
    "refresh_token":"fdb8fdbecf1d03ce5e6125c067733c0d51de209c"
}
The authorization header contains the client id and secret encoded as BASE64 (testclient:secret).

When a new Access Token is required, you can use the Refresh Token to get a new Access Token by using the token_endpoint as shown below: 

$ curl -X POST -H 'Authorization: Basic dGVzdGNsaWVudDpzZWNyZXQ=' -d 'refresh_token=fdb8fdbecf1d03ce5e6125c067733c0d51de209c&grant_type=refresh_token' localhost:3000/oauth/token
{
    "token_type":"bearer",
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiVlx1MDAxNcKbwoNUwoonbFPCu8KhwrYiLCJpYXQiOjE0NDQyNjI4NjYsImV4cCI6MTQ0NDI2Mjg4Nn0.Dww7TC-d0teDAgsmKHw7bhF2THNichsE6rVJq9xu_2s",
    "expires_in":20,
    "refresh_token":"7fd15938c823cf58e78019bea2af142f9449696a"
}
Notice in the above command, that the grant_type is the "refresh_token" and not the grant_type used in the original Access Token Request. As the result of this command a new Access Token is returned.

Offline Access#

More Information#

There might be more information for this subject on one of the following:
Please see our Copyright And Intellectual Property Page and Standard Disclaimer Pages!