Use Access Grants to Access Resources#

`AccessGrantSession`#

The inrupt-client-accessgrant module provides an AccessGrantSession that builds an authenticated Session object using both:

an OpenID-based session and
one or more access grants.

Then, a SolidClient/SolidSyncClient can use this session to access resources using the approved access grant(s).

Continuing the example from Create Access Requests/Grants, ExamplePrinter backend server, with the appropriate access grants, can access the resource(s) for printing.

For convenience, ExamplePrinter’s backend server’s code to instantiate AccessGrantClient for ExamplePrinter is repeated here:

public class ExamplePrinterRequestingClass {

   private final URI PS_ACCESS_GRANT_URI = URI.create("https://vc.inrupt.com");
   private Session session;  // Session for ExamplePrinter.
   // ... Logic to initialize the ExamplePrinter's session has been omitted for brevity.

   private final AccessGrantClient accessgrantClient = new AccessGrantClient(PS_ACCESS_GRANT_URI)
         .session(session);

   // ...
   // ...

}

1. Get the Access Grant(s) to Use#

Note

The user can only access those access grants where the user is the creator of the access grant (i.e., the grantor) or the recipient of the access grant (i.e., the grantee). That is, the ESS’ Access Grant service only returns those access grants where the user is the creator or the recipient.

If the Access Grant’s id is known, the application can directly retrieve the access grant using AccessGrantClient.fetch with the Access Grant’s id.

Note

The fetch operation can return expired or future access grants.

// String grantID = "https://vc.{ESS DOMAIN}/vc/xxxxxx...";
AccessGrant accessGrant = accessgrantClient.fetch(URI.create(grantID), AccessGrant.class)
      .toCompletableFuture()
      .join();

The application can use AccessGrantClient.query to query for active (i.e., current and not expired) access grants. To use AccessGrantClient.query for access grants, you can either:

Pass in an AccessCredentialQuery object AccessCredentialQuery<AccessGrant> that specifies the query field values (i.e., a combination of the resource, creator, recipient, purpose(s), and mode(s)); or
Pass in query field values directly; that is, a combination of the resource, creator, recipient, purpose, mode, and the class (AccessGrant.class when querying for access requests).

You can use AccessCredentialQuery.Builder and its methods to build an AccessCredentialQuery fir access grants:

Method	Descriptions
.resource	Optional. Include the resource in the query object. To match a query that specifies a resource, access grants must include the specified resource in their list of resource(s).
.creator	Optional. Include the access grant creator (i.e., the grantor/the resource owner who granted the request) in the query object.
.recipient	Optional. Include the grant recipient (i.e., the grantee) in the query object.
.purpose	Optional. Include a purpose in the query object. To match the query that specifies a purpose, access grants must include the specified purpose in their list of purpose(s). You can call this method multiple times to specify additional purposes. To match the query that specifies multiple purposes, access grants must include all specified purposes.
.mode	Optional. Include the access mode in the query object. To match the query that specifies a mode, access grants must include the specified access mode in their list of mode(s). You can call this method multiple times to specify multiple access modes. To match the query that specifies multiple modes, access grants must include all specified modes. For example, you can call `.mode("Read").mode("Write")` to query for access grants that contains both `Read` AND `Write` modes.
.build	Builds the AccessCredentialQuery. To build a query object for access grants (i.e., `AccessCredentialQuery<AccessGrant>`), specify the class `AccessGrant.class` to the .build method.

The following example queries for active access grants, given to Example Printer, that provide Read access for a specific resource for the purpose of photo printing. Specifically,

The example uses the AccessCredentialQuery.Builder and its methods to:
- Specify the resource .resource(...), the purpose .purpose(...), and the access mode .mode("Read"), and
- Build .build(AccessGrant.class) an AccessCredentialQuery<AccessGrant>.
Calls AccessGrantClient.query with the built AccessCredentialQuery<AccessGrant> object.

AccessCredentialQuery<AccessGrant> accessGrantQuery = new AccessCredentialQuery.Builder()
   .resource(URI.create("https://storage.example.com/some/resource"))
   .purpose(URI.create("https://purpose.example.com/PhotoPrinting"))
   .mode("Read")
   .build(AccessGrant.class);

List<AccessGrant> grants = accessgrantClient.query(accessGrantQuery).toCompletableFuture().join();

From the list, the resource owner can select the access grant to act upon.

You can use AccessGrantClient.query for access grants by passing the query field values as parameters. Pass in AccessGrant.class as the access credential class parameter and any combination of the following parameters:

Parameters	Descriptions
Resource.	Optional. A resource referred to in the grant. To match the query, access grants must include the specified resource in their list of resource(s).
Grant creator.	Optional. The resource owner to who granted the access request; i.e., the grantor.
Grant recipient.	Optional. The recipient of the access grant; i.e., the grantee.
Purpose for the grant.	Optional. A purpose stated in the grant. To match the query, access grants must include the specified purpose in their list of purpose(s). To specify multiple purposes to match, use the AccessCredentialQuery instead.
Granted access mode.	Optional. An access mode stated in the grant. To match the query, access grants must include the specified access mode in their list of mode(s). To specify multiple modes to match, use the AccessCredentialQuery instead.

The following example queries for active access grants, given to Example Printer, that provide Read access for a specific resource for the purpose of photo printing. That is, the query specifies non-null values for the:

Resource,
Access Mode (Read),
Purpose, and
Access Credential class of AccessGrant.class.

All other parameters are passed null values.

List<AccessGrant> grantsToExamplePrinter = accessgrantClient.query(
   URI.create("https://storage.example.com/some/resource"),
   null,       // Creator of grant; i.e., the grantor
   null,       // Recipient of the access grant; i.e., the grantee
   URI.create("https://purpose.example.com/PhotoPrinting"),  // Purpose
   "Read",     // Access Modes
   AccessGrant.class).toCompletableFuture().join();

From the list, the application can select the access grant to use.

2. Create an AccessGrantSession#

To instantiate an AccessGrantSession, call the constructor with the following parmeters:

OpenID-based session
Access Grants to Use

For example, the following code instantiates an AccessGrantSession using both the ExamplePrinter’s OpenID Session and the access grant:

Session agSession = AccessGrantSession.ofAccessGrant(session, accessGrant);

3. Create a Solid Client#

To access the resource with access grants, create a SolidSyncClient or SolidClient using the AccessGrantSession:

SolidSyncClient client = SolidSyncClient.getClient().session(agSession);

4. Access the Resource#

Use the SolidSyncClient.send() method to access the non-RDF resources and SolidSyncClient.read() method to read RDF resources.

For example, the following code uses the client associated with ExamplePrinter and the access grants to read the image file (a Non-RDF resource) at the resource URL:

SolidNonRDFSource resource = client.read(URI.create("https://storage.example.com/some/resource"), SolidNonRDFSource.class).toCompletableFuture().join();

Tip

If you receive an HTTP 403 Forbidden error, check that you have enabled the use of access grants for the resource.