Create Access Requests/Grants

AccessGrantClient

The inrupt-client-accessgrant module provides an AccessGrantClient to interact with the ESS Access Grant Service. The ESS Access Grant Service runs at:

https://vc.{ESS DOMAIN}.com

To interact with the service, the AccessGrantClient has the following methods:

Method	Description
AccessGrantClient.issue	Issues access requests and grants that are serialized as VCs.
AccessGrantClient.revoke	Updates the status of the access requests/grants to revoked.
AccessGrantClient.query	Queries for access requests and grants VCs and derive a Verifiable Presentation from the matching VCs.

Create an Access Request

AccessGrantClient.issue calls ESS Access Grant service’s /issue endpoint to get an access request (or an access grant). A requesting app can use AccessGrantClient.issue to get an access request. When calling the the method for an access request, provide:

• VC Type as a URI:

  • http://www.w3.org/ns/solid/vc#SolidAccessRequest for requests.

  Tip

  You can find URI for SolidAccessRequest (and SolidAccessGrant) at https://schema.inrupt.com/credentials/v1.jsonld.

• WebID of the resource owner.

• Resource(s) to which the access is being requested.

• Request access modes (Read, Write, Append).

• Purpose(s) as URI.

• Expiration Date.

Note

The AccessGrant class is for both Access Request and Access Grant.

For example, a user visits an ExamplePrinter’s website which provides photo printing services. When the ExamplePrinter’s web application asks for the photos to print, the user enters the URLs of the photos that are located in the user’s Pod. To continue, the ExamplePrinter’s backend server uses AccessGrantClient.issue to create access requests to read the photos; namely:

1. Instantiate a AccessGrantClient using the authenticated session of the ExamplePrinter.

   final URI MY_ESS_ACCESS_GRANT_SERVICE = URI.create("https://vc.{MY_ESS_DOMAIN}.com");
   final AccessGrantClient client = new AccessGrantClient(MY_ESS_ACCESS_GRANT_SERVICE)
      .session(session);     // the authenticated session of the requestor ExamplePrinter
   

2. Define the information needed to create an access request:

   final URI TYPE_REQUEST = URI.create("http://www.w3.org/ns/solid/vc#SolidAccessRequest");
   final Set<String> modes = new HashSet<>(Arrays.asList("Read"));
   final Set<URI> resources = Collections.singleton(URI.create("https://storage.example.com/someExampleIdenfier/pictures/picnic.jpg"));
   final Set<String> purposes = Collections.singleton("https://purpose.example/ProvidePrintingService");
   final Instant currentInstant = Instant.now();
   final Instant expiration = currentInstant.plus(30, ChronoUnit.MINUTES);
   

3. Call AccessGrantClient.issue with the information needed to create an access request:

   AccessGrant accessRequest =  client.issue(
           TYPE_REQUEST,
           URI.create("https://id.inrupt.com/ownerOfResource"),
           resources,
           modes,
           purposes,
           expiration).toCompletableFuture().join();
   

   Note

   The AccessGrant class is for both Access Request and Access Grant.

Create an Access Grant

AccessGrantClient.issue calls the /issue endpoint to get an access grant (or access request).

A resource owner can use an access management app to view an access request and, if the resource owner decides to grant the request, create an access grant. The access management app can use AccessGrantClient.issue to get an access grant.

When calling the the method for an access grant, provide:

• VC Type as a URI:

  • http://www.w3.org/ns/solid/vc#SolidAccessGrant for access grants.

  Tip

  You can find URI for SolidAccessGrant (and SolidAccessRequest) at https://schema.inrupt.com/credentials/v1.jsonld.

• Resource(s) to which the access is being requested.

• Access modes (Read, Write, Append) to grant.

• Purpose(s) as URI.

• Expiration Date.

For example, the user who visited an ExamplePrinter’s website to print pictures can go to a trusted access management app. The access management app can display the access request and then, if the user decides to grant the requested access to ExamplePrinter, create an access grant; namely:

1. Instantiate a AccessGrantClient using the authenticated session of the resource owner.

   //  Session session = OpenIdSession.ofIdToken(idToken); //idToken of the resource owner.
   
   final URI MY_ESS_ACCESS_GRANT_SERVICE = URI.create("https://vc.{MY_ESS_DOMAIN}.com");
   AccessGrantClient clientForUser = new AccessGrantClient(MY_ESS_ACCESS_GRANT_SERVICE)
      .session(session);      // the authenticated session of resource owner
   

2. Retrieve the access request using AccessGrantClient.fetch with the Access Request’s id.

   AccessGrant request = clientForUser.fetch(URI.create("https://vc.{ESS DOMAIN}/vc/xxxxxx..."));
   

   Note

   The AccessGrant class is for both Access Request and Access Grant.

3. Call AccessGrantClient.issue with the request information needed to create an access grant. The application can use various AccessGrant methods to get the request details:

   final URI TYPE_GRANT = URI.create("http://www.w3.org/ns/solid/vc#SolidAccessGrant");
   final Instant currentInstant = Instant.now();
   final Instant expiration = currentInstant.plus(60, ChronoUnit.MINUTES);
   
   AccessGrant accessGrant =  clientForUser.issue(
           TYPE_GRANT,
           accessRequest.getGrantor(),  // getGrantor returns credentialSubject.id, which for a request is the requestor
           accessRequest.getResources(),
           accessRequest.getModes(),
           accessRequest.getPurpose(),
           expiration).toCompletableFuture().join();