Subscribe to more awesome content!

Understanding Refresh Tokens

Learn about refresh tokens and how they fit in the authentication process.

Try Auth0 For Free

What is a Refresh Token?

A Refresh Token is a special kind of token that can be used to obtain a renewed access token —that allows accessing a protected resource— at any time. You can request new access tokens until the refresh token is blacklisted. Refresh tokens must be stored securely by an application because they essentially allow a user to remain authenticated forever.

How Refresh Tokens work

Whenever an Access Token is required to access a protected resource, a client may use a Refresh Token to get a new Access Token issued by the Authentication Server. Although Access Tokens can be renewed at any time using Refresh Tokens, they should be renewed when old ones have expired, or when getting access to a new resource for the first time. Refresh Tokens never expire. They are usually subject to strict storage requirements to ensure they are not leaked. Nevertheless, they can be blacklisted by the authorization server.
REFRESH TOKEN

Using Refresh Tokens

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

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

Assuming there is a user ‘test‘ with password ‘test‘ and a client ‘testclient‘ with a client secret ‘secret‘, a sample 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 the Access Token expires, 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 user/password pair. As the result of this command a new Access Token is returned.

Security Considerations

Refresh Tokens are long-lived. This means when a client gets one from a server, this token must be stored securely to keep it from being used by potential attackers, for this reason, it is not safe to store them in the browser. If a Refresh Token is leaked, it may be used to obtain new Access Tokens (and access protected resources) until it is blacklisted. Refresh Tokens must be issued to a single authenticated client to prevent the use of leaked tokens by other parties. Access Tokens must also be kept secret, but due to its shorter life, security considerations are less critical.

How Refresh tokens are used in Auth0

Auth0 does the hard part of managing the authentication process for you.Refresh tokens are not an exception. Once you have setup your app with us, follow the docs here to learn how to get a Refresh Token.
REFRESH TOKEN WITH AUTH0

Contact Us

*
*
*
*
*