Session Restore upon Browser Refresh

For security reasons, solid-client-authn-browser does not store access tokens in the localStorage or any other place that persists across page refresh.

This means that upon page refresh/reload, the access token is lost, and your web application will be logged out. This page provides various procedures to log your application back in without user interaction.

Enable Session Restore

As part of the authentication flow in a browser environment, your application calls solid-client-authn-browser’s handleIncomingRedirect() function. The handleIncomingRedirect() function can accept the following properties in its options parameter:

Option	Description
url	The URL the user is being redirected from the Solid Identity Provider. Defaults to window.location.href if unspecified.
restorePreviousSession	A boolean that indicates whether the application should log the user back in after a page reload without user intervention. If the user is not already logged in at the time of the page reload, restorePreviousSession has no impact, and the user manually logs in to the Solid Identity Provider as part of the application’s login flow. Default: false

To automatically log the user back in after a page refresh, in your application, call handleIncomingRedirect() with restorePreviousSession set true. The initial authentication and later page refresh has the following flow:

1. For the initial authentication, the application calls login() to start the process. The function redirects the user away to the user’s Solid Identity Provider where the user can login.

2. The user logs in. Upon successful login, the Solid Identity Provider sends the user back to your application.

3. The application call handleIncomingRedirect({ restorePreviousSession : true }) to complete the login process.

   The application can now perform authenticated operations on the user’s Pod.

4. At some point, the user refreshes the page, causing the application to reload and log out the user. That is, the application can no longer make authenticated requests.

5. However, if on reload, the application starts by calling handleIncomingRedirect({ restorePreviousSession : true }), the user goes through a process called silent authentication. In a silent authentication process, the browser redirects to the Solid Identity Provider as before but with a configuration that immediately returns the user back to the application without any user interaction.

   That is, whether the user is still logged in to the Solid Identity Provider or not, the user is redirected back to the application, specifically to the redirectUrl parameter set during the login() call.

6. When the user returns back to the application, the application calls handleIncomingRedirect({ restorePreviousSession : true }). If the user is still logged in when redirected back, this completes the login process, and the user is logged back in.

   The user can refresh the page again and repeat the same process as long as the user is still logged in to the Solid Identity Provider.

Important

When session restore is enabled, calling handleIncomingRedirect() may cause a redirection away from the current page. To take the user back to the URL from which handleIncomingRedirect({ restorePreviousSession : true }) was called, see Use Session Restore Event Handler.

Use Session Restore Event Handler

For the initial authentication, your application calls the login() function with various parameters, including the redirectUrl parameter. This parameter is set to the location where the Solid Identity Provider should return your user once logged in.

If session restore is enabled and the user reloads any page of your application (such as by refreshing the page or following a link), this redirectURL is also where the Solid Identity Provider returns the user during the silent authentication. In some cases, this redirectURL may differ from the actual page the user reloaded, such as if your application uses a framework with client-side routing like NextJS. In addition to the redirection, this also results in loss of application state.

You can use the session’s events function to route the user back to the refreshed page instead of to the redirectURL. That is, with session restore enabled, when the user returns back to the application after the silent authentication, a sessionRestore event is fired. You can use the session’s events.on function with the following parameters to register your own callback to invoke:

• "sessionRestore" (the event to associate with the callback)

• a callback to be invoked with the URL of the refreshed page .

Your callback can implement any application-specific logic needed to restore the user back to the refreshed page.

Important

While this process routes the user back to the refreshed page, it does not address the loss of application state.

The following NextJS example uses onSessionRestore() to redirect back to the current page after a refresh:

import { handleIncomingRedirect, EVENTS } from "@inrupt/solid-client-authn-browser";
import { useEffect } from "react";
import { useRouter } from "next/router";

export default function MyApp() {
  const router = useRouter();

  // 1. Register the callback to restore the user's page after refresh and
  //    redirection from the Solid Identity Provider.
  session.events.on(EVENTS.SESSION_RESTORED, (url) => {
    router.push(url);
  });

  useEffect(() => {
    // 2. When loading the component, call `handleIncomingRedirect` to authenticate
    //    the user if appropriate, or to restore a previous session.
    handleIncomingRedirect({
      restorePreviousSession: true,
    }).then((info) => {
      console.log(`Logged in with WebID [${info.webId}]`);
    });
  }, []);

  // ... rest of the component, where `login()` should be called to initiate the
  // login process.
}

For information on initiating the login process, see Login Process.