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.

Read/Write APIs#

The @inrupt/solid-client-access-grants library provides various read and write APIs that allows agents with appropriate access grants to read/write Pod resources; such as:

Disambiguation

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

These APIs support the use of Bearer tokens (and not DPoP tokens). See Specify Bearer Token Type for Session for details.

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 the Access Request, the id of the Access Gran(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 that allows the requestor to perform read/write operations on a SolidDataset, the requestor can use the appropriate @inrupt/solid-client-access-grants read and write APIs; for example:

solid-client-access-grants Functions

Description

getSolidDataset

To read/fetch a SolidDataset from a Pod.

saveSolidDatasetAt

To write a SolidDataset to a Pod.

deleteSolidDataset

To delete a SolidDataset from a Pod.

To use these functions, the authenticated session must use Bearer token type. See Specify Bearer Token Type for Session for details.

To read or modify the data in a local SolidDataset (e.g., getThing, addUrl, setThing of a fetched SolidDataset or a new SolidDataset), use the @inrupt/solid-client library’s functions.

Disambiguation

Ensure that you are using getSolidDataset, saveSolidDatasetAt, and deleteSolidDataset 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 that allows the requestor to perform read/write operations on a non-RDF file (e.g., .pdf, .jpeg, etc.), the requestor can use the appropriate @inrupt/solid-client-access-grants read and write APIs; for example:

solid-client-access-grants Functions

Description

getFile

To read/fetch a file from a Pod.

overwriteFile

To update an existing file in a Pod.

Unlike the corresponding function in @inrupt/solid-client, you cannot use solid-client-access-grants overwriteFile to save a new file.

saveFileInContainer

To write a new file to a Pod.

deleteFile

To delete a file from a Pod.

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, saveFileInContainer, deleteFile 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";

// ...

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
);