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 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 issuing Access Requests and exercising Access Grants; for example:

issueAccessRequest

Creates an Access Request, serialized as a signed Verifiable Credential.

Server-side code can use the function to create Access 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:

  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,   // 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
  );
}

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

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

Adding custom fields to an Access Request#

Access Requests are based on a use-case-agnostic data model, and capture information about access to resources. However, it is also useful to be able to tie Access Requests and Access Grants into business-specific processes, which requires the core data model to have extension points.

Starting in version 3.2.0, @inrupt/solid-client-access-grants supports adding custom fields to an Access Request. issueAccessRequest has a new customFields option, accepting a set of CustomField. A CustomField is a key/value entry where the key MUST be a URL, and the value a literal (string, boolean or number). The provided values are embedded within the issued Access Request.

If an incorrect CustomField value is provided, AccessGrantError is thrown. Invalid CustomField definitions include not using a URL as a key, or not using a literal as a value. The TypeScript typing is provided as a guideline.

async function requestAccessToPhotos(photosToPrint, resourceOwner){

   // requestVC will have the provided custom fields in addition
   // to the regular fields for Access Requests.
   const requestVC = await issueAccessRequest(
      {
         "access":  { read: true },
         "resources": photosToPrint,
         "resourceOwner": resourceOwner,
         "purpose": [ "https://example.com/purposes#print" ]
      },
      {
         fetch : session.fetch,
         // ExamplePrinter can add custom fields that are relevant
         // to its own application into the Access Request.
         customFields: new Set([{
            key: new URL("https://example.com/printer/orderId"),
            value: "my-order-id"
         }]),
      }
   );
}

Querying for Access Requests#

Starting in @inrupt/solid-client-access-grants@v3.2.0, the application can use the query function to query for active (i.e., current and not expired) Access Requests made to a user. To use query for Access Requests, you can pass in a AccessRequestFilter object that specifies the query filter values (i.e., a combination of the resource, creator, recipient, purpose, and type).

The AccessRequestFilter object has the following fields:

Key

Descriptions

type

The Access Credential type (in this case, SolidAccessRequest).

status

Optional. Include a credential status in the query object. The following values are supported for Access Requests:

  • Pending returns all Access Requests that have neither been granted, denied or canceled.

  • Granted returns all Access Requests that have been granted by the resource owner.

  • Denied returns all Access Requests that have been denied by the resource owner.

  • Canceled returns all Access Requests that have been canceled by the requesting agent.

fromAgent

Optional. Include the creator of the Access Request in the query filter. This is the requestor. In the example, the creator value is the ExamplePrinter’s WebID https://id.example.com/examplePrinter.

toAgent

Optional. Include the recipient of the Access Request in the query filter. This is the resource owner.

resource

Optional. Include the resource in the query object. Use this filter to return Access Requests bound to a specific resource.

purpose

Optional. Include a purpose in the query object. Use this filter to return Access Requests bound to a specific purpose.

issuedWithin

Optional. Include a time constraint on the issuance date in the query object. All matched credentials will have been issued within the provided duration value. Certain time constraints are available for use with this method, including:

  • P1D One day (DURATION.ONE_DAY)

  • P7D Seven days (DURATION.ONE_WEEK)

  • P1M One month (DURATION.ONE_MONTH)

  • P3M Three months (DURATION.THREE_MONTH)

revokedWithin

Optional. Include a time constraint on the revocation date in the query object. All matched credentials will have been revoked or canceled within the provided duration value. Certain time constraints are available for use with this method, including:

  • P1D One day (DURATION.ONE_DAY)

  • P7D Seven days (DURATION.ONE_WEEK)

  • P1M One month (DURATION.ONE_MONTH)

  • P3M Three months (DURATION.THREE_MONTH)

The result is paginated, so the agent may need to make multiple calls to the query function to get all of the Access Requests matching the provided filter.

The following example queries for active Access Requests made by ExamplePrinter for a given resource.

const page1 = await query({
   type: "SolidAccessRequest",
   status: "Pending",
   fromAgent: new URL("https://id.example.com/ExamplePrinter"),
}, {
   fetch: session.fetch,
   queryEndpoint: new URL("https://vc.example.org/query"),
});
if (page1.next !== undefined) {
   const page2 = await query(page1.next, {
      fetch: session.fetch,
      queryEndpoint: new URL("https://vc.example.org/query"),
   });
}

paginatedQuery is a utility provided for iterating through the result pages:

const pages = paginatedQuery({
    type: "SolidAccessRequest",
    status: "Pending",
    fromAgent: new URL("https://id.example.com/ExamplePrinter"),
 }, {
    fetch: session.fetch,
    queryEndpoint: new URL("https://vc.example.org/query"),
 });
let i = 0;
for await (const page of pages) {
    console.log(`Page ${i} has ${page.items.length} items.`)
    i += 1;
}