Authenticate (Browser)

Inrupt provides the solid-client-authn-browser library to authenticate in a browser.

npm install @inrupt/solid-client-authn-browser

Authentication in Solid is based on OpenID Connect (OIDC), which means the authentication has the following flow:

  1. The application starts the login process by sending the user to the user’s Solid Identity Provider.

  2. The user logs in to the Solid Identity Provider.

  3. The Solid Identity Provider sends the user back to your application, where the application handles the returned authentication information to complete the login process.

Login Flow: 1) Start Login by redirecting user to Solid Identity Provider. 2) User logs in.  3) Solid Identity Provider redirects the user back to the application to handle the returned authentication information.

Important

The login is only complete after the user is redirected back to the application; i.e., your application must be reloaded between the start of the login and its completion.

Login Process

  1. Call the library’s login() function to start the process. Pass in the following login options:

    oidcIssuer

    Set to the user’s Solid Identity Provider (where the login function will send the user).

    redirectUrl

    Set to the location that the Solid Identity Provider will send the user back once logged in.

    clientName

    (Optional) Set to the display name for the client during the login process. When logging in, the user has to approve the client’s access to the requested data. The clientName is the name displayed during the approval step. If clientName is not provided, a random identifier is generated and used for the name.

    For other options available to the function, see ILoginInputOptions.

    This process redirects the user from your application to the Solid Identity Provider.

  2. Once redirected to the Solid Identity Provider, the user logs in.

    Upon successful login, the Solid Identity Provider sends the user back to your application to complete the login process.

  3. Call library’s handleIncomingRedirect() to complete the login process. The function collects the information provided by the Solid Identity Provider.

    The session is logged in only after it handles the incoming redirect from the Solid Identity Provider.

    Note

    By default, refreshing the current page logs out the user. To mitigate this and offer a better user experience, see Session Restore upon Browser Refresh.

Once logged in, the library’s fetch() function can retrieve data using the available login information. You can pass this fetch() function as an option to the solid-client functions (e.g., getSolidDataset, saveSolidDatasetAt) to include the user’s credentials with a request.

Example

The following example uses the solid-client-authn-browser library to login to a Solid server. It passes the fetch() function as an option to the solid-client functions getSolidDataset and saveSolidDatasetAt to read and write data to a Pod where the logged-in user has the appropriate access.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser'
import { getSolidDataset, saveSolidDatasetAt } from "@inrupt/solid-client";

async function loginAndFetch() {
  // 1. Call the handleIncomingRedirect() function to complete the authentication process.
  //   If the page is being loaded after the redirect from the Solid Identity Provider
  //      (i.e., part of the authentication flow), the user's credentials are stored in-memory, and
  //      the login process is complete. That is, a session is logged in 
  //      only after it handles the incoming redirect from the Solid Identity Provider.
  //   If the page is not being loaded after a redirect from the Solid Identity Provider, 
  //      nothing happens.
  await handleIncomingRedirect();

  // 2. Start the Login Process if not already logged in.
  if (!getDefaultSession().info.isLoggedIn) {
    // The `login()` redirects the user to their identity provider;
    // i.e., moves the user away from the current page.
    await login({
      // Specify the URL of the user's Solid Identity Provider; e.g., "https://broker.pod.inrupt.com" or "https://inrupt.net"
      oidcIssuer: "https://broker.pod.inrupt.com",
      // Specify the URL the Solid Identity Provider should redirect to after the user logs in,
      // e.g., the current page for a single-page app.
      redirectUrl: window.location.href,
      // Pick an application name that will be shown when asked 
      // to approve the application's access to the requested data.
      clientName: "My application"
    });
  }

  // 3. Make authenticated requests by passing `fetch` to the solid-client functions.
  // The user must have logged in as someone with the appropriate access to the specified URL.
  
  // For example, the user must be someone with Read access to the specified URL.
  const myDataset = await getSolidDataset(
    "https://pod.inrupt.com/docsteam/profile/card", {
    fetch: fetch
  });

  // ...
  
  // For example, the user must be someone with Write access to the specified URL.
  const savedSolidDataset = await saveSolidDatasetAt(
    "https://pod.inrupt.com/docsteam/profile/card",
    myChangedDataset, {
    fetch: fetch
  });
}

loginAndFetch();

For working examples, you can look at the sample apps distributed with the code: