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