Use Access Grants to Access Resources#

This page details how a server-side application can use Inrupt’s solid-client-access-grants library to access Pod Resource(s) with approved Access Grants.

Access Requests and Grants

The following Inrupt products are available to support Access Requests and Grants:

  • solid-client-access-grants library for managing access requests and grants

  • Inrupt’s Enterprise Solid Server (ESS) provides support for access requests and grants. ESS serializes the access requests and grants as Verifiable Credentials (VCs). To allow the use of access grants for a resource, ESS’ ACP supports access policy based on a VC type matcher.

  • Inrupt’s PodBrowser supports access request management.

Specify Bearer Token Type for Session#

Inrupt’s Enterprise Solid Server supports UMA flow to exchange the access grants for access tokens. These UMA access tokens can then be used to access the resources.

The solid-client-access-grants’s read and write APIs handle the UMA exchange and sends the returned UMA access token to access the resource. The library’s read and write APIs support the use of Bearer tokens (and not DPoP tokens), and as such, they require the authenticated Sessions to use Bearer tokens (instead of the default DPoP).

To obtain an authenticated Session that uses Bearer tokens, set the tokenType for the Session during the Session.login().

For example, the following server-side code instantiates a Session and specifies the tokenType of Bearer during login (the default tokenType is DPoP):

import { Session } from "@inrupt/solid-client-authn-node";
//...

const session = new Session();

// ...

if (!session.info.isLoggedIn) {
  await sessionTokenTypeBearer.login({
    clientId: process.env.CLIENT_ID,
    clientSecret: process.env.CLIENT_SECRET,
    oidcIssuer: process.env.IDP,
    tokenType: "Bearer", // Specify the tokenType option
  });
}

The application uses the client credentials received during client registration. For more information on static registration of client applications, see Authenticate (Node.js: Single-User App).

Retrieve Access Grants#

As part of the Access Request/Grant flow, when the Resource Owner grants or denies the Access Request, the id of the approved/denied Access Grant (serialized as VC) is sent back to the requesting app as a query parameter.

The requesting app can use getAccessGrantFromRedirectUrl to get the Access Grant (serialized as VC)

import {
   getAccessGrantFromRedirectUrl
} from "@inrupt/solid-client-access-grants";

// ...

const myAccessGrantVC = await getAccessGrantFromRedirectUrl(
   myURL,
   { fetch: session.fetch }     // fetch from the authenticated Session
);

Read and Write SolidDataset#

If the requestor has an access grant (serialized as VC) that allows the requestor to read a SolidDataset, the requestor can retrieve that SolidDataset using the @inrupt/solid-client-access-grants function getSolidDataset. The authenticated session must use Bearer token type. See Specify Bearer Token Type for Session for details.

If the requestor has an access grant VC that allows the requestor to write or append a SolidDataset, the requestor can save that SolidDataset using the @inrupt/solid-client-access-grants function saveSolidDatasetAt. The authenticated session must use Bearer token type. See Specify Bearer Token Type for Session for details.

To read or modify the data in the SolidDataset, use the @inrupt/solid-client library’s functions.

Disambiguation

Ensure that you are using getSolidDataset and saveSolidDatasetAt from the @inrupt/solid-client-access-grants and not the @inrupt/solid-client library.

For example:

import {
   getSolidDataset,
   saveSolidDatasetAt
} from "@inrupt/solid-client-access-grants";

import {
  getThing,
  getStringNoLocale,
  addUrl,
  addStringNoLocale,
  buildThing,
  createThing,
  setThing
} from "@inrupt/solid-client";

// ...


// Use `getSolidDataset` from `@inrupt/solid-client-access-grants`
const mySolidDataset = await getSolidDataset(
   resourceURL,
   myAccessGrantVC,  // Access Grant (serialized as VC) that provides the user read access to get the SolidDataset
   { fetch : session.fetch } // fetch from the authenticated Session with tokenType Bearer
)

// Use functions from `@inrupt/solid-client` to modify the SolidDataset
// const myDataThing = getThing( ... );
// ...
// let myUpdatedSolidDataset = ...;
// ...

// Use `saveSolidDatasetAt` from `@inrupt/solid-client-access-grants`
const savedSolidDataset = await saveSolidDatasetAt(
  resourceURL,
  myUpdatedSolidDataset,
  myAccessGrantVC,             // Access Grant (serialized as VC) that grants the user write access to save the SolidDataset
  { fetch: session.fetch }     // authenticated Session with tokenType Bearer
);

To access the contents of the SolidDataset, use the @inrupt/solid-client library’s functions. For examples, see:

Read and Write Non-RDF Files#

If the requestor has an Access Grant (serialized as VC) that allows the requestor to read a non-RDF file (e.g., .pdf, .jpeg, etc.), the requestor can retrieve the file using the @inrupt/solid-client-access-grants function getFile. The authenticated session must use Bearer token type. See Specify Bearer Token Type for Session for details.

If the requestor has an access grant VC that allows the requestor to write a non-RDF file (e.g., .pdf, .jpeg, etc.), the requestor can:

  • Update an existing file using the @inrupt/solid-client-access-grants function overwriteFile.

  • Write a new file using the @inrupt/solid-client-access-grants function saveFileInContainer.

The authenticated session must use Bearer token type. See Specify Bearer Token Type for Session for details.

Disambiguation

Ensure that you are using getFile, overwriteFile, and saveFileInContainer from the @inrupt/solid-client-access-grants and not the @inrupt/solid-client library.

For example:

import {
   getFile, overwriteFile
} from "@inrupt/solid-client-access-grants";

// ...

// file is a Blob (see https://developer.mozilla.org/docs/Web/API/Blob)
const file = await getFile(
  fileURL,               // File in Pod to Read
  myAccessGrantVC,       // Access Grant (serialized as VC) that grants the user read access to the File
  { fetch: session.fetch }  // authenticated Session with tokenType Bearer
);

// ...

const updated = await overwriteFile(
  fileURL,               // URL for the file
  fileWithNewContent,    // File
  myAccessGrantVC,       // Access Grant (serialized as VC) that grants the user read access to the File
  { contentType: fileWithNewContent.type,
    fetch: session.fetch }  // authenticated Session with tokenType Bearer
);