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 Resources 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 provides support for Access Requests and Grants. ESS serializes the Access Requests and Grants as Verifiable Credentials.

• Inrupt’s Authorization Management Component 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:

getSolidDataset saveSolidDatasetAt saveSolidDatasetInContainer deleteSolidDataset	getFile overwriteFile saveFileInContainer deleteFile

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 (not DPoP tokens).

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 Authentication Single-User Application.

Retrieve Access Grants

As part of the Access Request/Grant flow, when the Resource Owner grants the Access Request, the id of the 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 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:

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.

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.

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

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

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

• Read Data

• Write a New SolidDataset

• Modify an Existing SolidDataset

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:

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.

Ensure that you are using the APIs 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
);