data-caching.md

Data caching options

The SDK can be configured to cache ID tokens and access tokens either in memory or in local storage. The default is in memory. This setting can be controlled using the cacheLocation option when creating the Auth0 client.

To use the in-memory mode, no additional options need are required as this is the default setting. To configure the SDK to cache data using local storage, set cacheLocation as follows:

await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  clientId: '<AUTH0_CLIENT_ID>',
  cacheLocation: 'localstorage', // valid values are: 'memory' or 'localstorage'
  authorizationParams: {
    redirect_uri: '<MY_CALLBACK_URL>'
  }
});

Important: This feature will allow the caching of data such as ID and access tokens to be stored in local storage. Exercising this option changes the security characteristics of your application and should not be used lightly. Extra care should be taken to mitigate against XSS attacks and minimize the risk of tokens being stolen from local storage.

Creating a custom cache

The SDK can be configured to use a custom cache store that is implemented by your application. This is useful if you are using this SDK in an environment where more secure token storage is available, such as potentially a hybrid mobile app.

To do this, provide an object to the cache property of the SDK configuration.

The object should implement the following functions. Note that all of these functions can optionally return a Promise or a static value.

Signature	Return type	Description
get(key)	Promise or object	Returns the item from the cache with the specified key, or undefined if it was not found
set(key: string, object: any)	Promise or void	Sets an item into the cache
remove(key)	Promise or void	Removes a single item from the cache at the specified key, or no-op if the item was not found
allKeys()	Promise<string[]> or string []	(optional) Implement this if your cache has the ability to return a list of all keys. Otherwise, the SDK internally records its own key manifest using your cache. Note: if you only want to ensure you only return keys used by this SDK, the keys we use are prefixed with @@auth0spajs@@

Here's an example of a custom cache implementation that uses sessionStorage to store tokens and apply it to the Auth0 SPA SDK:

const sessionStorageCache = {
  get: function (key) {
    const value = sessionStorage.getItem(key);

    return value ? JSON.parse(value) : undefined;
  },

  set: function (key, value) {
    sessionStorage.setItem(key, JSON.stringify(value));
  },

  remove: function (key) {
    sessionStorage.removeItem(key);
  },

  // Optional
  allKeys: function () {
    return Object.keys(sessionStorage);
  }
};

await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  clientId: '<AUTH0_CLIENT_ID>',
  cache: sessionStorageCache,
  authorizationParams: {
    redirect_uri: '<MY_CALLBACK_URL>'
  }
});

Note: The cache property takes precedence over the cacheLocation property if both are set. A warning is displayed in the console if this scenario occurs.

We also export the internal InMemoryCache and LocalStorageCache implementations, so you can wrap your custom cache around these implementations if you wish.