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 level 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 access requests and grants as Verifiable Credentials (VCs).

  • Inrupt’s PodBrowser supports access request management.

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.

redirectToAccessManagementUi

Redirects the resource owners to their access management application (e.g., PodBrowser).

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#

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:

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

  2. 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,
             "resourceOwner": resourceOwner,
             "expirationDate": accessExpiration,
             "purpose": [ "https://example.com/purposes#print" ]
          },
          { fetch : session.fetch } // From the requestor's (i.e., ExamplePrinter's) authenticated session
      );
    }
    
  3. 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 PodBrowser as the default access management application.

    // Call `redirectToAccessManagementUi` to redirect to
    // the user's access management app, defaulting to PodBrowser 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://podbrowser.inrupt.com/privacy/access/requests/"
       }
    );
    

    Tip

    If the call is made on the server-side, also include the redirectCallback option.

  4. 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.

  5. Upon redirect, the URL will include add a query parameter with the id of the approved or denied 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.