Manage Access Requests#

This page details how an agent can use Inrupt’s solid-client-access-grants library to request access to Pod Resource(s). This access request includes the specific access mode requested (e.g., read, write, append), the resource(s) to access, etc.

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 requests and grants as Verifiable Credentials (VCs).
Inrupt’s Access Management Component (AMC) supports access request management. New as part of ESS 2.2 Specifically, using the @inrupt/solid-client-access-grants library, AMC provides functionality to grant or deny requests as well as revoke existing grants.

`solid-client-access-grants` API#

Inrupt’s solid-client-access-grants library provides various functions for issuing access requests and exercising access grants; for example:

issueAccessRequest	Creates an Access Request, serialized as a signed Verifiable Credential. A server-side code can use the function to create requests. Important Starting in version 2.1 of ESS, an access request for a Container applies both to the Container and its descendants unless explicitly specified otherwise in the request with an `inherit: false`. To specify the `inherit` field in the request, version 2.1.+ of `@inrupt/solid-client-access-grants-js` adds an `inherit` option to issueAccessRequest. Set `inherit: false` to create a request for the Container only.
redirectToAccessManagementUi	Redirects the resource owners to their access management application (e.g., Inrupt’s Authorization Management Component). The requestor code can use the function to redirect the resource owner to the access management application where the owner can grant or deny access. If called server-side, a `redirectCallback` must be passed in the options for the library to handle redirection depending on the Web framework. The access management application returns the resource owners to the URL specified in function call.
getSolidDataset	Uses the access grants to retrieve a SolidDataset.
saveSolidDatasetAt	Uses the access grants to save a SolidDataset.
getFile	Uses the access grant to retrieve a file.

Requesting Access#

Important

Starting in version 2.1 of ESS, an access request for a Container applies both to the Container and its descendants unless explicitly specified otherwise in the request with an inherit: false.

To specify the inherit field in the request, version 2.1.+ of @inrupt/solid-client-access-grants-js adds an inherit option to issueAccessRequest. Set inherit: false to create a request for the Container only.

The following example implements the code for the access requestor (i.e., ExamplePrinter) in the example introduced in Access Requests and Grants.

To start the access request flow:

ExamplePrinter’s client-side code calls on its server-side application to create an access request.

The server-side application can use issueAccessRequest to create an access request for the photos belonging to the resourceOwner (in this example, "https://id.example.com/snoringsue");

async function requestAccessToPhotos(photosToPrint, resourceOwner){

  // ExamplePrinter sets the requested access (if granted) to expire in 5 minutes.
  let accessExpiration = new Date( Date.now() +  5 * 60000 );

  // Call `issueAccessRequest` to create an access request
  //
  const requestVC = await issueAccessRequest(
      {
         "access":  { read: true },
         "resources": photosToPrint,   // Array of URLs
         "resourceOwner": resourceOwner,
         "expirationDate": accessExpiration,
         "purpose": [ "https://example.com/purposes#print" ]
      },
      { fetch : session.fetch } // From the requestor's (i.e., ExamplePrinter's) authenticated session
  );
}

After having received the Access Request, the requestor calls redirectToAccessManagementUi to redirect the user to the user’s access management application. Pass to the function:
- the id of the request (in this example, the id of the Access Request Verifiable Credential) and
- the URL to which the access management application should return the user after the access request has been granted or denied.
The following example is for a client-side call, and it includes an optional fallbackAccessManagementUI option that specifies Inrupt’s Authorization Management Component (AMC) as the default access management application.
```
// Call `redirectToAccessManagementUi` to redirect to
// the user's access management app, defaulting to AMC if not set.
// The user logs into the access management application and decides to grant or deny the request.

redirectToAccessManagementUi(
   requestVC.id,
   "https://www.example.net/exampleprinter/returnwithgrantVC/",
   {
     fallbackAccessManagementUi: "https://amc.inrupt.com/accessRequest",
     fetch : session.fetch // From the requestor's (i.e., ExamplePrinter's) authenticated session
   }
);
```
Tip

If the call is made on the server-side, also include the redirectCallback option.
At this point, the user is redirected away from the requesting app (e.g., ExamplePrinter app) to the user’s Access Management app, where they will either approve or deny the Access Request. The Access Management app will then redirect the user back to the URL provided in the call to redirectToAccessManagementUi.
Upon redirect, the URL will include add a query parameter with the id of the approved Access Grant. The requesting app can use getAccessGrantFromRedirectUrl to get the Access Grant.

With an approved Access Grant, the requestor can access the resource. See Use Access Grants to Access Resources.

Manage Access Requests#

solid-client-access-grants API#

Requesting Access#

`solid-client-access-grants` API#