Manage Access Grants#

Upon receipt of an access request, resource owners can use an Access Management app to approve or deny the access request:

  • For an approved request, Inrupt’s Enterprise Solid Server (ESS) creates an access grant.

  • For a denied request, Inrupt’s Enterprise Solid Server (ESS) creates an access denial.

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 Authorization Management Component supports access request management. New as part of ESS 2.2

solid-client-access-grants API#

Inrupt’s solid-client-access-grants library provides various functions for approving or denying access requests; for example:

approveAccessRequest

Approves the request and returns an approved Access Grant, serialized as a signed Verifiable Credential. The Access Grants may be used to get access to specified resources.

A server-side code can use the function to create the Grant.

Note

ESS uses ACP policy to enables the use of access grants for a resource. The approveAccessRequest function, by default, creates an ACP policy that enables the use of access grant.

Starting in ESS 2.2, new Pods are created with default policies that enable the use of access grants; for deployments upgrading to 2.2, this change does not affect existing Pods.

When using approveAccessRequest, you can specify updateAcr: false to prevent the function from creating separate ACP policy that enables the use of access grants.

Important

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

Version 2.1.+ of @inrupt/solid-client-access-grants-js adds an inherit option to approveAccessRequest. For example:

  • You can include inherit: false as an override option to create an approved access grant for the Container only, regardless of the specification in the access request.

  • You can include inherit: true as an override option to create an approved access grant for both the Container and its descendants, regardless of the specification in the access request.

denyAccessRequest

Denies the request and returns an Access Denial, serialized as a signed Verifiable Credential.

A server-side code can use the function to deny the request.

Granting Access#

The following implements the role of the Access Management app in the example introduced in Access Requests and Grants. The role of the Access Management app is to act as a trusted third-party in the Access Request flow.

The access requestor (e.g., ExamplePrinter) sends the Resource Owner (e.g., snoringsue) to the Resource Owner’s Access Management app.

Note

When sending resource owner to the Access Management app, the requestor adds the following query parameters:

  • id of the Access Request (in the example, the id of the Access Request VC), and

  • redirectUrl, the URL where the requestor expects the Access Management app to redirect the Resource Owner after the request has been granted or denied.

In order to approve or deny an Access Request:

  1. The resource owner should log in to the Access Management app, if not already.

  2. The Access Management app displays the Access Request (found in the requestVc parameter) to the Resource Owner. [1]

  3. The Resource Owner approves or denies the Access Request.

    • If the Resource Owner approves the request, the Access Management app uses approveAccessRequest to return the id of the Access Grant VC. When calling the function, the Access Management application can also include an optional modifications object (such as to specify a subset of the requested resources or permissions or set the inherit flag).

      async function getApprovedGrantVC(accessRequestToApprove, resourceOwnerSession){

  // Call `approveAccessRequest` to acquire a Verifiable Credential
  // for the approved access grant
  const accessGrant = await approveAccessRequest(
    accessRequestToApprove,
    undefined,  // Optional modifications
    {
      updateAcr: false, // For Pods created on ESS 2.2+
      fetch: resourceOwnerSession.fetch, // From the resource owner's (i.e., snoringsue's) authenticated session
    }
  );
}

    • If the Resource Owner denies the request, the Access Management app uses denyAccessRequest to return the id of the Access Denial VC.

      async function geAccessDenialVC(accessRequestToDeny, resourceOwnerSession){

  // Call `denyAccessRequest` to create an access denial

  const accessDenial = await denyAccessRequest(
    accessRequestToDeny,
    {
      fetch: resourceOwnerSession.fetch, // From the resource owner's (i.e., snoringsue's) authenticated session
    }
  );
}

  4. Once the user acts on a request, the Access Management app redirects the user to the requesting app using the redirectUrl parameter received earlier. The id of the access grant/denial is added to the redirect URL. The requesting app can use getAccessGrantFromRedirectUrl to get the access grant.

    The requesting app can pass the id of the VC to getAccessGrant to retrieve the Access Grant.

On this page