Auth0 issues an Access Token or an ID Token in response to an authentication request. You can use Access Tokens to make authenticated calls to a secured API, while the ID Token contains user profile attributes represented in the form of claims. Both are JWTs and therefore have expiration dates indicated using the
exp claim, as well as security measures, like signatures. Typically, a user needs a new Access Token when gaining access to a resource for the first time, or after the previous Access Token granted to them expires.
A Refresh Token is a special kind of token used to obtain a renewed Access Token. You can request new Access Tokens until the Refresh Token is blacklisted. Applications must store Refresh Tokens securely because they essentially allow a user to remain authenticated forever.
For native applications, refresh tokens improve the authentication experience significantly. The user has to authenticate only once, through the web authentication process. Subsequent re-authentication can take place without user interaction, using the Refresh Token.
You can increase security by using Refresh Token rotation which issues a new Refresh Token and invalidates the predecessor token with each request made to Auth0 for a new Access Token. Rotating the Refresh Token reduces the risk of a compromised Refresh Token.
The Refresh Token behavior is applicable to OIDC-conformant applications. You can configure an application to be OIDC-conformant in one of the following two ways:
- Enabling the OIDC Conformant flag for an app.
- Passing an
/authorizeendpoint of the Authentication API.
For more information on our authentication pipeline, see Introducing OIDC-Conformant Authentication.
Auth0 SDKs support Refresh Tokens including:
For a complete listing, see Quickstarts.
Providing secure authentication in SPAs has a number of challenges based on your application’s use case. New browser privacy controls like Intelligent Tracking Prevention (ITP) adversely impact the user experience in SPAs by preventing access to third-party cookies.
Auth0 recommends using Refresh Token Rotation which provides a secure method for using Refresh Tokens in SPAs while providing end-users with seamless access to resources without the disruption in UX caused by browser privacy technology like ITP.
Auth0’s former guidance was to use the Authorization Code Flow with Proof Key for Code Exchange (PKCE) in conjuntion with Silent Authentication in SPAs. This is more secure solution than the Implicit Flow but not as secure as the Authorization Code Flow with Proof Key for Code Exchange (PKCE) with Refresh Token Rotation. If you want a more detailed explanation about the challenges of using the Implicit Flow in SPAs, please read this blog article OAuth2 Implicit Grant and SPA.
For information on using Refresh Tokens with our mobile SDKs, see:
- Mobile / Native Quickstarts
- Lock Android: Refreshing JWT Tokens
- Lock iOS: Saving and Refreshing JWT Tokens
Restrictions and limitations
You can only get a Refresh Token if you are implementing the following flows:
If you limit offline access to your API, a safeguard configured via the Allow Offline Access switch on the API Settings, Auth0 will not return a Refresh Token for the API (even if you include the
offline_accessscope in your request).
Rules will run for the Refresh Token Exchange. To execute special logic, you can look at the
context.protocolproperty in your rule. If the value is
oauth2-refresh-token, then the rule is running during the exchange.
If you have added custom claims to your tokens using a rule, the custom claims will appear in new tokens issued when using a Refresh Token for as long as your rule is in place. Although new tokens do not automatically inherit custom claims, rules run during the Refresh Token flow, so the same code will be executed. This allows you to add or change custom claims in newly-issued tokens without forcing previously-authorized applications to obtain a new Refresh Token.