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 |
---|---|
Issues access requests and grants that are serialized as VCs. |
|
Updates the status of the access requests/grants to revoked. |
|
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:
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
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);
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:
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
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.
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();