Access Requests and Grants#

Access Requests and Grants Flow#

Inrupt’s Enterprise Solid Server (ESS) supports an authorization mechanism based on Access Requests and Grants. With access requests and grants:

An agent/requestor creates an access request for resources owned by another agent. This request includes the specific access mode (e.g. Read, Write, Append), the resource(s) to access, the owner of the resource(s), etc.
The resource owner can review the access request and either grant the access request (resulting in an access grant) or deny the access request (resulting in an access denial).
If the requesting agent has an access grant, the requesting agent can exchange the access grant for an access token in order to access the resources referenced in the access grant.

Enable Use of Access Grants#

ESS uses Access Control Policy (ACP) to define policies that determine access to Pod resources. To be able to use access grants for a resource, the resource must have a policy that enables the use of access grants.

Important

The policy only enables the use of access grants on the resource for the access modes specified in the policy. To determine the access for an agent who is using an access grant, ESS uses the intersection of:

The allowed access specified by the resource’s ACP, and
The granted access specified in the access grant for that resource.

For example:

A resource has a policy that enables the use of access grants for Read access.
A requesting agent has received an access grant for that resource that allows Read and Write access.

Then:

The requesting agent can use the access grant to Read the resource only.
The requesting agent cannot use the access grant to Write the resource, even though the access grant specifies both Read and Write access.

Starting in 2.2, ESS enables the use of access grants by default. Specifically, when ESS creates a new Pod, ESS creates default policies that enable the use of access grants for that Pod. See Initial ACP Policies for details. For deployments upgrading to 2.2, this change does not affect existing Pods.

Using the following code, the resource owner can enable the use of Access Grants to read and write the resource. If you pass in a Container (i.e., its URL ends with a slash /), the code enables the use of access grants for the Container and all its children/descendents (including those created later).

import com.inrupt.client.auth.Session;
import com.inrupt.client.openid.OpenIdSession;
import com.inrupt.client.solid.SolidSyncClient;
import com.inrupt.client.solid.SolidNonRDFSource;
import com.inrupt.client.accessgrant.AccessGrantUtils;
import com.inrupt.client.vocabulary.ACL;

import java.net.URI;

public class ExampleClass {

   private SolidSyncClient client;  // Client for the resource owner.
   // ... Logic to initialize the client has been omitted for brevity.

   public void addReadWriteAccessGrantEnablingPolicy(String resourceURL) {

       try (final SolidNonRDFSource myResource = client.read(URI.create(resourceURL), SolidNonRDFSource.class)) {
           myResource.getMetadata().getAcl().ifPresent(acl -> {
               try (final SolidRDFSource acr = client.read(acl, SolidRDFSource.class)) {
                   AccessGrantUtils.accessControlPolicyTriples(acl, ACL.Read, ACL.Write)
                           .forEach(acr.getGraph()::add);
                   client.update(acr);
               }
           });
       }
   }
}

`inrupt-client-accessgrant`#

To handle access requests and grants, Inrupt’s Java Client Library provides the inrupt-client-accessgrant module. See Setup.

The inrupt-client-accessgrant provides:

AccessGrantClient	AccessGrantClient can interact with the ESS Access Grant Service; specifically, AccessGrantClient can be used to create/verify/query/fetch access requests and grants.
AccessGrantSession	AccessGrantSession allows for the use of access grant(s) to interact with resource(s); specifically, using an AccessGrantSession, SolidClient/SolidSyncClient can access resources using the access grant(s).

Next Steps#

Create Access Requests/Grants	Create access requests and access grants.
Use Access Grants	Use Access Grants to access Pod resources.

Access Requests and Grants#