Solid affords us the opportunity to create a valuable and
+powerful ecosystem where people and organizations retain control
+of their data, but are also able to put it to work and use it
+to its full potential. The fundamentals of Solid make this possible,
+but further definition of standard methods and mechanisms
+must be established
+to make it practical, intuitive, and secure.
This specification details how Social Agents in the Solid ecosystem
+can read, write, and manage data stored in a Solid pod using
+disparate Applications.
§ 6 Data Registrations details how Social Agents register, organize, and
+lookup their data. Data is stored uniformly, avoiding complex
+physical hierarchies. Shape trees and shapes provide strong data validation and
+intuitive data boundaries.
Agents are the primary actors in an interoperable Solid ecosystem.
+
An Agent is denoted by an identity. Dereferencing that identity leads to identity profile document, where a graph of useful information
+about the Agent can be found. This graph is used by the Agent as a starting point to look up their own data, as well as data that has
+been shared with them.
+
The Agent graph in an identity profile document is designed to be
+publicly accessible, but many of the things the Agent links to are
+designed to be private, or accessible only by others they have authorized.
+
An Agent can dereference the identity of another Agent to obtain
+the public information they need to interact with them.
A Social Agent is a strongly identifiable individual, group, or
+organization that can own or be responsible for data, and provide authorization to the
+access of that data by other Agents.
A Registry is a place where a Social Agent can store and find
+different types of data, often for particular purposes. Each type
+of Registry serves a specific purpose or function.
The Registry SetMAY use any resource or
+subject names. It SHOULD NOT be readable
+by the public. It SHOULD be accessible
+and manageable by the Social Agent that owns it, or other Social Agents that have received appropriate authorization, via
+authorized Applications.
An Application is a software-based Agent that a Social Agent uses to access, manipulate, and manage the data in
+their control, as well as the data they’ve been granted access to.
An Application Registration provides the Social Agent with a place to maintain metadata, state, preferences, and
+other application-specific data associated with a given Application they
+have elected to use.
Note: Commonly the Authorization Agent, making the request on behalf of the Social Agent accepting the invitation,
+ will create corresponding Social Agent Registration after receiving the [WEBID] in the response,
+ which means that it is not available before receiving the response.
+
5.4. Agent Registry
+
An Agent Registry is a collection of Agent Registrations.
Data Registrations let Social Agents store and manage the
+data they control. Data of various types is organized and stored in a
+uniform way to aid validation, authorization,
+discovery, and more.
+
Complex hierarchies that hinder interoperability are avoided
+by storing data in a relatively flat hierarchy. This creates natural
+data boundaries that make data storage and authorization more intuitive.
A Data Registry is a collection of Data Registrations, each
+of which represents a unique type of data, identified by a shape tree.
+
A Data Registry can be used for basic discovery, but it is not
+designed nor intended to be an efficient means to query or index data.
+However, it is intended to be used as reliable source data for different
+query engines or indexing schemes.
Slight variations concerning where Access Needs are sourced from, and
+how notification of access is provided, are the only differences from
+one flow to another.
+
7.1. Authorization Agent
+
An Authorization Agent is an Application designated by
+a Social Agent to be responsible for managing the access to data
+under their control, linked via their Registry Set.
When the resource query parameter is used, the Authorization Agent will use it
+as an indication that access to a specific data instance is intended to be shared.
The response will include an HTTP Link header relating the Agent Registration to the Agent making the request via the http://www.w3.org/ns/solid/interop#registeredAgent link relation.
+
+ HEAD request to and response from Authorization Agent
+
Social Agents and Applications in the ecosystem often
+require access to data controlled by some other Social Agent.
+Consequently, a common way to explain
+and communicate data needs between these parties is required.
An Access Need represents the requirement of one specific type
+of data represented by a shape tree, as part of an Access Need Group.
+
It is often the case that a shape tree associated with an Access Need references other shape trees, providing a
+path to request access to related types. Consequently, Access Needs can be specified that inherit from other Access Needs through a shape tree reference.
Requested mode of access for the creator of a Data Instance.
+ Adds to the set of modes linked via interop:accessMode. Only valid when accessMode includes acl:Create, acl:Write, or acl:Append
+
An Access Need Group Description provides a short label or
+title and a more in-depth description that explains why a given Access Need Group is being requested of a Social Agent.
<#en-need-group-pm>
+ ainterop:AccessNeedGroupDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedGroupprojectron:need-group-pm;
+ skos:prefLabel"Read and Contribute to Projects"@en ;
+ skos:definition"Allow Projectron to read the Projects you select, and create new ones. Projectron won't modify existing data, but can add more."@en .
+
+
+
8.3.2. Access Need Description
+
An Access Need Description provides a specific
+explanation of why that data type is being requested by
+a given Access Need.
<#en-need-project>
+ ainterop:AccessNeedDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedprojectron:need-project;
+ skos:prefLabel"Access to Projects is essential for Projectron to perform its core function of Project Management"@en .
+
<>
+ ainterop:AccessDescriptionSet;
+ interop:usesLanguage"en"^^xsd:language.
+
+<#en-need-group-pm>
+ ainterop:AccessNeedGroupDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedGroupprojectron:need-group-pm;
+ skos:prefLabel"Read and Contribute to Projects"@en ;
+ skos:definition"Allow Projectron to read the Projects you select, and create new ones. Projectron won't modify existing data, but can add more."@en .
+
+<#en-need-project>
+ ainterop:AccessNeedDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedprojectron:need-project;
+ skos:prefLabel"Access to Projects is essential for Projectron to perform its core function of Project Management"@en .
+
+<#en-need-task>
+ ainterop:AccessNeedDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedprojectron:need-task;
+ skos:prefLabel"Access to Tasks allows Projectron to identify and manage the work to be done in a given Project."@en .
+
Access Grants are generated from Access Authorizations. They are shared
+with a given Agent to communicate the scope of access that has been
+granted to them.
+
9.1. Access Authorization
+
An Access Authorization records the decision of a Social Agent to grant access to some portion of data in their control to
+another Agent.
A Data Authorization records the decision of a Social Agent to grant access to a specific type of data in their control, identified
+by a Shape Tree. They are always associated with a single Access Authorization.
Additional access mode assigned to the creator of a
+ data instance. Adds to the set of modes linked via interop:accessMode. Only valid when accessMode includes acl:Create, acl:Write, or acl:Append
+
A Data Grant provides an Agent with a detailed description
+of access that has been granted to them for a specific type of data,
+identified by a Shape Tree. Each Data Grant is associated with
+a single Access Grant.
Additional access mode assigned to the creator of a
+ data instance. Adds to the set of modes linked via interop:accessMode. Only valid when accessMode includes acl:Create, acl:Write, or acl:Append
+
A Delegated Data Grant is a sub-class of Data Grant used when a grantee re-shares or "delegates" access they’ve
+received to another Agent. The most common use case
+is when Alice shares access with Bob, and Bob delegates
+that access to his project management application.
+
+ Alice’s Delegated Data Grant for Projectron to access Projects
+ that Bob shared with her at https://alice.example/agents/2f2f3628/fe818190 - View
+
+
+
+ Alice’s Delegated Data Grant for Projectron to access Tasks
+ that Bob shared with her at https://alice.example/agents/2f2f3628/017d6a07 - View
+
Each Data Authorization applies to a specific type of data,
+identified by a shape tree. The amount of access authorized for data
+of that type is specified by the Access Scope, via interop:scopeOfAuthorization.
This specification uses some access modes in the acl: namespace that
+have not been adopted to demonstrate the most secure and accurate
+expression of a Social Agent’s authorization. Discussions are underway to add these modes.
+
[WAC] does not have any mechanism to extend or modify
+inherited permissions.
Only Data Instances of the data owner’s that are associated with Data Instances allowed by another authorization or grant
+
+
9.6.1. All
+
The interop:Allaccess scope includes all data of a specified type
+belonging to a given data owner, and all data of that same type shared with the data
+owner, across all of the data owner’s registries.
The follow example illustrates Alice’s authorization to give Projectron access to
+data of type pm-shapetrees:ProjectTree with a scope of interop:All. Since
+Alice has two Data Registries and Bob has shared projects with her, several Data Grants will be generated from this Data Authorization and shared
+with Projectron.
+
Note:interop:All is only valid for a Data Authorization.
+Generated Data Grants use the more specific interop:AllFromRegistry for each unique Data Registry, including Bob’s.
+
+ Alice’s Data Authorization for Projectron to access Projects
+ at https://alice.example/authorization/54a1b6a0 - View
+
+
+
+ Alice’s Data Grant for Projectron to access her Projects in
+ her Personal Data Registry at
+ https://alice.example/agents/2f2f3628/a0623c8f - View
+
+
+
+ Alice’s Delegated Data Grant for Projectron to access Projects
+ that Bob shared with her at https://alice.example/agents/2f2f3628/fe818190 - View
+
The interop:AllFromAgentaccess scope includes all data of a given type
+owned and shared by a specified Social Agent, across all of their Data Registries. Essentially, Alice can use this scope to delegate
+any access that she has been given to another Social Agent’s data (e.g. Bob), to another Agent of her choosing.
+
The Social Agent whose access is being shared is identified via interop:dataOwner.
The following example illustrates Alice’s authorization to give Performchart access to
+data of type pm-shapetrees:ProjectTree with a scope of interop:AllFromAgent and an interop:dataOwner of Bob.
+
Note: While Bob has granted Alice the ability to manipulate his project data,
+Alice grants Performchart a narrower scope of read-only access.
+
+ Alice’s Data Authorization for Performchart to access Projects
+ that Bob shared with her at https://alice.example/authorization/0e36ba8f - View
+
Alice generates one Delegated Data Grant for Performchart to access
+the Project data that Bob shared with her, which she stores in
+the Agent Registration for Performchart in her Agent Registry.
+It is marked as a delegation of Bob’s Data Grant via interop:delegationOfGrant.
+
+ Alice’s Delegated Data Grant for Performchart to access Projects
+ that Bob shared with her at https://alice.example/agents/c2328cdd/efc426c9 - View
+
The following example illustrates Bob’s authorization to give Alice access to
+all data of type pm-shapetrees:ProjectTree in the Data Registry he uses
+for his professional work.
+
+ Bob’s Data Authorization at https://bob.example/authorization/e4b1b154
+ for Alice to access his Project data - View
+
When a Data Grant is assigned the interop:AllFromRegistry scope, the interop:grantee is authorized to access all Data Instances in the Data Registration linked via interop:hasDataRegistration,
+limited by the access modes linked via interop:accessMode.
+
In the above example, Bob would be giving Alice the following access to pm-shapetrees:ProjectTreeData Instances (Projects) in the bob-work-data:08a99a10Data Registration:
+
+
+
Read the Data Registration
+
+
List all Projects
+
+
Read all Projects
+
+
Create a new Project
+
+
Read a Project she creates
+
+
Delete a Project she creates
+
+
Create resources in a Project she creates
+
+
Modify existing resources in a Project she creates
Create new Data Instances. Access modes assigned to
+ the creator on the created Data Instance should be a union of interop:accessMode and interop:createAccessMode modes. acl:Create is not currently supported.
+ Substitute with acl:Write or acl:Append, but may exceed intended scope
+ of access.
+
Modify Data Instances. Modification of Data Registration graph
+ not permitted. acl:Update is not currently supported. Substitute with acl:Write or acl:Append, but may exceed intended scope of access.
+
+
acl:Delete
+
Delete Data Instances. Deletion of Data Registration not permitted. acl:Delete is not currently supported. Substitute with acl:Write, but
+ may exceed intended scope of access.
+
The following example illustrates Jose’s authorization for Alice to access
+two specific Data Instances of pm-shapetrees:ProjectTree in the Data Registry he uses for his professional work.
+
+ Jose’s Data Authorization at https://jose.example/authorization/69095550
+ for Alice to access his Project data - View
+
When a Data Grant is assigned the interop:SelectedFromRegistry scope, the interop:grantee is authorized to access only the specific Data Instances linked via interop:hasDataInstance in the Data Registration linked via interop:hasDataRegistration,
+limited by the access modes linked via interop:accessMode.
Create new resources within the Data Instances where applicable. Access modes assigned to
+ the creator on a created resource should be a union of interop:accessMode and interop:createAccessMode modes. acl:Create is not currently supported.
+ Substitute with acl:Write or acl:Append, but may exceed intended scope
+ of access.
+
+
acl:Read
+
Read Data Instance and any contained resources where applicable.
+
+
acl:Update
+
Modify Data Instance and any contained resources where applicable. acl:Update is not currently supported. Substitute with acl:Write or acl:Append, but may exceed intended scope of access.
+
+
acl:Append
+
Add new data to resources in the Data Instance, without changing any
+ existing data.
+
+
acl:Delete
+
Delete Data Instance or any contained resources where applicable. acl:Delete is not currently supported. Substitute with acl:Write, but
+ may exceed intended scope of access.
+
The interop:Inheritedaccess scope is unique in that it depends
+on the existence of another Data Authorization with a scope of interop:All, interop:AllFromAgent, interop:AllFromRegistry, or interop:SelectedFromRegistry.
+
When a Data Authorization exists with
+one of those scopes, and its interop:registeredShapeTree specifies
+one or more virtual hierarchies via st:references, a corresponding Data Authorization with a scope of interop:Inherited can be created
+for each distinct reference.
The shape treepm-shapetrees:ProjectTree specifies one virtual hierarchy
+via st:references, indicating that a Project Data Instance virtually
+includes Task instances of pm-shapetrees:TaskTree through the
+predicate pm:hasTask.
+
+ ProjectTree definition at https://data.example/shapetrees/pm-shapetrees.tree - View Definition
+
+
+
+ Alice’s Data Grant for Projectron to access Tasks associated
+ with authorized Work Projects at
+ https://alice.example/agents/2f2f3628/0945218b - View
+
When a Data Grant is assigned the interop:Inherited scope, the interop:grantee is authorized to access only the specific Data Instances linked via st:references in the shape tree of the Data Grant linked via interop:inheritsFromGrant
+
In the example above, Alice grants Projectron the following access to only thepm-shapetrees:TaskTreeData Instances (Tasks) in the alice-work-data:df4ab227Data Registration that are linked
+to pm-shapetrees:ProjectTreeData Instances (Projects) in the alice-work-data:8501f084Data Registration.
+
For example, the three Tasks linked from the Project Data Instance below via pm:hasTask would be included in the interop:Inherited scope.
Create new Data Instances linked by shape tree reference. Access modes assigned to
+ the creator on the created Data Instance should be a union of interop:accessMode and interop:createAccessMode modes. acl:Create is not currently supported.
+ Substitute with acl:Write or acl:Append, but may exceed intended scope
+ of access.
+
Modify Data Instances linked by shape tree reference. acl:Update is not currently supported. Substitute with acl:Write or acl:Append, but may exceed intended scope of access.
+
+
acl:Append
+
Add new data to Data Instances linked by shape tree reference,
+ without changing any existing data.
+
+
acl:Delete
+
Delete Data Instances linked by shape tree reference. Deletion of Data Registration not permitted. acl:Delete is not currently supported. Substitute with acl:Write, but
+ may exceed intended scope of access.
+
The resource names for Access GrantsSHOULD be unpredictable.
+
10. Security
+
10.1. Application Authorization
+
For authorization purposes, client Applications in use today fall into
+two buckets:
+
Strongly identifiable applications can be identified by
+third parties independently from the Social Agent controlling them.
+Only server-side applications are
+strongly identifiable. As confidential clients, they can keep secrets
+and can present attestations and third-party credentials
+via DNS / domain certificates.
Weakly identifiable applications include in-browser Javascript Applications and native desktop or mobile Applications. They are
+considered weakly identifiable because they
+are not able to keep secrets on an instance level. They are often referred to
+as public clients. Native apps should be strongly-identifiable in theory
+(since they are able to keep secrets on an instance level), but not in
+practice because the OS manufacturers do not make their trust
+infrastructure available. Weakly identifiable clients are only strongly
+identifiable to the Social Agent controlling them.
+
In the case of Weakly identifiable applications, the ability for a Solid
+pod to limit access to data by the Application in use is only as strong as
+the trustworthiness of the Social Agent piloting that Application, along with
+their ability to avoid using malicious Applications. The identity of the Application can be manipulated
+by the Social Agent in control. This means that Alice can strongly control
+the Applications that she uses to access her own data, but has
+limited ability to control the Applications that Bob uses to access the data
+she shares with him.
+
11. Definitions
+
All definitions as stated below should be considered in the context of
+an interoperable ecosystem for Solid, whether explicitly stated
+or not.
+
Solid is a protocol made up of a number of open web standards
+aimed at decentralizing data on the web.
+
A Solid pod is a place for storing and accessing data via
+the Solid protocol, with mechanisms for controlling who or what can
+access that data.
+
An interoperable ecosystem is
+a collection of Solid compatible applications developed by one or more
+entities, used by a community of users, that can safely access and manipulate
+the same kinds of data in pods.
+
A server-side application runs on a dedicated server. They may
+also act as autonomous authenticated agents.
+
A user-piloted application runs on a user’s device, with the user
+as the authenticated agent. They include in-browser javascript
+applications, native desktop applications, and mobile applications.
An identity is a unique URI that can be dereferenced
+to return an identity profile document. Compatible
+identity systems include WebID and DID.
+
An identity profile document is a linked data document obtained by
+dereferencing the URI for a given identity. It provides information that
+can be used to prove that a given Agent controls the document.
+
A WebID is a web resource at an HTTP URI which refers to an agent. An identity profile document can be accessed by
+dereferencing the WebID. [WEBID]
+
A DID is a URI that associates a DID subject (e.g. an agent,
+thing, data model, abstract entity, etc.) with a DID document,
+equivalent to an identity profile document, to allow trustable
+interactions with that subject. [DID]
+
An application identity is a web resource at an HTTP URI
+that uniquely identifies a given Application, and dereferences to an application profile document.
+
An application profile document is a linked data document
+obtained by dereferencing the URI for a given application identity.
+
An acl resource as defined by [WAC] may be directly
+associated with a resource or indirectly associated with a resource
+through inheritance. It determines which authorization subjects can
+access a resource, and the modes of access they have for it.
+
An access mode denotes operations (e.g. read, write)
+that a given authorization subject can perform on a resource.
A shape provides a schema that RDF data graphs must meet in order
+to be considered conformant. A shape associated with a given resource in a pod ensures that any data stored in that resource must conform to the
+associated shape. Shape languages include [SHEX] and [SHACL].
+
A Shape Tree defines a prospective tree of related resources
+which can be read and written by applications. The shape tree associates
+each of these resources with a shape. This allows one to treat a set of
+related resources as a single grouping, and apply that to a range of
+operations including access control, data organization, data validation,
+and data migration. [SHAPETREES]
+
A Shape Tree Decorator provides additional human-readable
+description and context for a given shape tree.
+
A Shape Tree Reference provides the necessary context to
+associate instances of related shape trees via a ShapePath
This specification uses some access modes in the acl: namespace that
+have not been adopted to demonstrate the most secure and accurate
+expression of a Social Agent’s authorization. Discussions are underway to add these modes. ↵
+
[WAC] does not have any mechanism to extend or modify
+inherited permissions. ↵
This primer is intended to accompany [SAI].
+It is focused on providing a friendly introduction for developers of libraries intended
+for solid applications.
+
This document was developed alongside the open-source TypeScript implementation [SAI-JS]
+
We will follow example of an application called Projectron,
+which manages projects and tasks.
+End user, named Alice, collaborates on projects
+with other Individuals and Organizations.
+
2. Shape Tree
+
Shape Trees [SHAPETREES] allow for the definition and validation of data hierarchies
+including which shapes [SHEX] should be used to validate data.
+In our examples, we are going to use the following Shapes and Shape Trees.
In this primer we will consider the use-case of a project management application
+identified by https://projectron.example/#app Every application has public WebID Document providing information about it.
+
+
projectron:\#idainterop:Application;interop:applicationName"Projectron";interop:applicationDescription"Manage projects with ease";interop:applicationAuthoracme:\#corp;interop:applicationThumbnailprojectron:thumb.svg;interop:hasAccessNeedGroupprojectron:\#need-group-pm.projectron:\#need-group-pminterop:accessNecessityinterop:accessRequired;interop:accessScenariointerop:PersonalAccess;interop:authenticatesAsinterop:Pilot;interop:hasAccessDecoratorIndexprojectron:index;interop:hasAccessNeedprojectron:\#need-project.projectron:\#need-projectainterop:AccessNeed;interop:registeredShapeTreesolidtrees:Project;interop:accessNecessityinterop:accessRequired;interop:accessModeacl:read,acl:write.projectron:\#need-issueainterop:AccessNeed;interop:registeredShapeTreesolidtrees:Issue;interop:accessNecessityinterop:accessRequired;interop:accessModeacl:read,acl:write;interop:inheritsFromNeedprojectron:\#need-project.
+ Projectron WebID document
+
+
Access Needs explain what kind of data application works with.
+They use combination of § 2 Shape Tree and access modes to
+convey how the application can work with data.
+
Details can change based on experience from implementing Authorization Agent role
+
4. Authorization Flow
+
User always needs to authenticate first.
+For the rest of this primer we’ll be assuming that user has already authenticated,
+and that applicaction know WebID of the authenticated user.
+
4.1. Authorization Agent Discovery
+
Every user has an Authorization Agent which can be discovered from
+their WebID Document via interop:hasAuthorizationAgent predicate.
Here we see that Alice designates https://auth.alice.example/ as their Authorization Agent.
+
4.2. Application Registration Discovery
+
Application can discover Application Registration created for it by the user,
+by performing HEAD or GET request on IRI denoting
+user’s Authorization Agent. Response will include HTTP Link header relating
+Application Registration to the application making the request using http://www.w3.org/ns/solid/interop#registeredAgent as link relation.
In cases where an application hasn’t been registered yet, it needs to initiate the flow with the Authorization Agent.
+
After successful flow, the application will be able to discover its registration.
+
+
+
+
+
+
+
+
Step
+
Description
+
+
+
1
+
Alice finds an Application called Projectron that she’d like
+ to use to manage her Projects and Tasks.
+
+
2
+
Alice authenticates to Projectron with her WebID.
+
+
3
+
Projectron dereferences her WebID and retrieves Authorization Agent from her WebID Profile Document.
+
+
4
+
Projectron asks Alice’s Authorization Agent whether Alice already has an Application Registration for Projectron.
+
+
5
+
Alice’s Authorization Agent checks the Agent Registry in Alice’s Pod for a Projectron Application Registration.
+
+
6
+
No Application Registration for Projectron is found.
+ Projectron now knows that Alice hasn’t given it permission to access her data, so it must ask.
+
+
7
+
Projectron redirects Alice to her Authorization Agent, supplying its identifier for context.
+
+
8
+
Alice’s Authorization Agent dereferences the supplied Projectron identifier, retrieving Projectron’s
+ Application profile graph and corresponding Access Need Groups from the WebID Profile Document,
+ as well as hasAuthorizationCallbackEndpoint.
+
+
9
+
Alice’s Authorization Agent presents the Access Need Groups from Projectron’s Application
+ profile graph, so that Alice understands what kind of data is being requested, and why.
+
+
10
+
Alice’s chooses the scope of access that Projectron will receive, to the data to
+ which it has asked for access via the presented Access Needs.
+
+
11-13
+
Alice’s Authorization Agent records her decision as an Access Authorization in Alice’s
+ Authorization Registry. An Application Registration is created for Projectron in
+ Alice’s Agent Registry. An Access Grant and corresponding Data Grants are generated
+ from the Access Authorization and stored in the Projectron Application Registration.
+
+
14
+
Alice’s Authorization Agent redirects her back to Projectron, now that the appropriate access has been granted.
+
+
15
+
Projectron again asks Alice’s Authorization Agent for a Projectron Application Registration.
+
+
16
+
Alice’s Authorization Agent finds the newly created Projectron Application Registration in the Agent Registry in Alice’s Pod.
+
+
17
+
Alice’s Authorization Agent provides the URI of the Application Registration to Projectron.
+
+
18
+
Projectron learns what access it received through the Access Grant in Alice’s Projectron Application Registration.
+
+
19
+
Projectron may now function as intended, within the scope of authorization it was given by Alice.
+
+
+
+
4.4. Resource Indication
+
When the application has already been registered, and the user wants to
+initiate a sharing-specific § 6.1 Data Instance, an authorization flow with resource
+indication is available.
+
+
+
+
+
+
+
+
Step
+
Description
+
+
+
1
+
Alice’s is authenticated with Projectron.
+
+
2
+
Alice has already authorized Projectron.
+
+
3
+
Projectron has read its Access Grant and displayed projects.
+
+
4
+
Alice initiates sharing of a specific project.
+
+
5
+
Projectron redirects Alice to her Authorization Agent, indicating the selected project.
+
+
6-8
+
Alice’s Authorization Agent fetches the indicated project and checks who already has access to it.
+ It also fetches list of all registered social agents to present it to Alice.
+
+
9
+
Alice chooses all the social agents with which she wants to share the selected project,
+ as well as modes of access for all selected agents. If the shape tree has references (e.g., tasks) she can
+ also select modes of access for each inherited shape tree.
+
+
10-11
+
Alice’s Authorization Agent records new access authorizations for all the selected agents
+ and regenerates access grants provided in their agent registrations.
+
+
12
+
Alice’s Authorization Agent dereferences the supplied Projectron WebID, retrieving Projection’s
+ Application profile graph from the WebID Profile Document,
+ to discover the hasAuthorizationCallbackEndpoint.
+
+
13
+
Alice’s Authorization Agent redirects her back to Projectron, now that the project has been shared.
+
+
14
+
Alice continues using Projectron.
+
+
+
+
5. Application Registration
+
Application Registration can be considered an entry point to all the data
+that the user authorized it to access. The next step in the discovery of that data
+is the Access Grant linked via interop:hasAccessGrant predicate.
+ Alice’s data grant for Projectron - Pro Projects
+
+
A Data Grant is immutable, it never gets updated, instead it can be only replaced
+with a newer Data Grant.
+
Data Grant can be consider as the most important data structure, it provides following information:
+
+
dataOwner
+
+
Social Agent who owns the data
+
grantedBy
+
+
Social Agent who granted the access
+
registeredShapeTree
+
+
Shape Tree used by related Data Registration
+
hasDataRegistration
+
+
Data Registration that this Data Grant applies to. As well as iriPrefix of that Data Registration (see § 6 Data Registration)
+
accessMode
+
+
List of access modes defining what application can do with the data
+
scopeOfGrant
+
+
Defines which instances can be accessed (see § 5.2.1 Scopes)
+
inheritsFromGrant
+
+
If grant has InheritInstances scope, it will be the Data Grant for Data Registraion with parent Data Instances (see § 5.2.2 Inheritance)
+
hasDataInstance
+
+
If grant has SelectedInstances scope, it will be all the Data Instances that application can access in the Data Registration
+
delegationOfGrant
+
+
If Data Grant is issued by Social Agent other than data owner, it will be the original Data Grant issued by the data owner (see § 5.2.3 Delegation)
+
+
5.2.1. Scopes
+
Data Grant can have one of three scopes:
+
+
AllFromRegistry
+
+
All the Data Instances in the Data Registration. Application will be able to access the Data Registration and see the list of all contained instances (see § 6 Data Registration)
+
SelectedFromRegistry
+
+
Only specific Data Instances in the Data Registration. Application will not be able to access the Data Registration, so it will not see the list al all contained instances. Instad list of selected Data Instances is available via hasDataInstance
+
Inherited
+
+
Only those Data Instances in the Data Registration, which are related to parent kData Instances in Data Registration of the Data Grant referenced with inheritsFromGrant (see § 5.2.2 Inheritance)
+
+
5.2.2. Inheritance
+
InheritInstances Data Grant doesn’t provide access to the Data Registration, so
+application can’t get the list of all the Data Instances. Neither it provides a list of specific
+Data Instances in the Data Registration.
+
To find Data Instances from that Data Registration, application first needs to access parent
+Data Instances from Data Registration which Data Grant referenced by inheritsFromGrant makes accessible. Based on shape tree definition, each parent Data Instance will reference all its
+child Data Instances.
+
Both parent and child Data Registrations have to be in the same Data Registry. Since only one
+Data Registration for specific shape tree can be created in any given Data Registry.
+All parent Data Instances are from one Data Registration and all child Data Instances are from
+one Data Registration.
+
5.2.3. Delegation
+
Application doesn’t need to handle delegated Data Grants in any special way.
+To know if Data Grant was issued by currently logged in user or someone else,
+application should rely on dataOwner information in the Data Grant.
As we discussed in § 5.2.2 Inheritance a Shape Tree will specify how parent data instances
+relate to child data instances. For Project shape three the predicate is pm:hasTask,
+links to child Task data instances.
When creating or updating data instance with HTTP PUT method. Application should include
+link header linking Data Instance to Data Registration using link relation http://www.w3.org/ns/solid/interop#targetDataRegistration
+
Update should include If-Match HTTP header with value of ETag from
+HTTP response when the representation was retreived.
This primer is intended to accompany [SAI].
+It is focused on providing a friendly introduction for developers of libraries intended
+for solid authorization agents.
+
This document was developed alongside the open-source TypeScript implementation [SAI-JS] and open-source Java implementation [SAI-JAVA].
+
2. Shape Tree
+
Shape Trees [SHAPETREES] allow for the definition and validation of data hierarchies
+including which shapes [SHEX] should be used to validate data.
+In our examples, we are going to use the following Shapes and Shape Trees.
In a Data Registry, there can be at most one Data Registration for any given shape tree.
+
4.1. Data Registration
+
Data Registration is a container, which contains Data Instances. Each of those Data Instances conforms to one specific
+shape tree assigned to the Data Registration.
+ Data Registration for projects in one of Alice’s Data Registries
+
+
+
registeredShapeTree
+
+
Shape Tree used by this Data Registration
+
+
4.2. Data Instance
+
Data Instance is a resource representing something specific, for example, a project or a task.
+An Authorization Agent is not responsible for modifying data instances. Sometimes it still needs to access them
+during § 7 Gathering Authorizations from the user if the user wants to select specific data instances.
+
5. Authorization Registry
+
Authorization Registry is a container, which contains Access Authorizations.
+Each of those Access Authorizations is created for a specific grantee,
+and groups together one or more Data Authorizations.
An Access Authorization is immutable, it never gets updated, instead it can be only replaced
+with a newer Access Authorization.
+
5.2. Data Authorization
+
Data Authorization, similar to § 6.7 Data Grant, represents access granted by a specific Social Agent.
+It is always associated with a specific § 2 Shape Tree. Depending on its scope it can apply to all the
+Data Instances in any number of Data Registrations. In that case, interop:hasDataRegistration will not be specified.
+ Alice’s data authorization for Projectron to ACME’s Projects
+
+
A Data Authorization is immutable, it never gets updated, instead it can be only replaced
+with a newer Data Authorization.
+
5.2.1. Scopes
+
Data Authorization can have one of five scopes:
+
+
All
+
+
All the Data Instances in all the Data Registration the End-user has access to.
+This includes ones owned by the End-user as well as ones owned by others, where End-user has been granted access.
+
AllFromAgent
+
+
All the Data Instances in all the Data Registrations, owned by a specific social agent.
+This could be the End-user themselves or any other social agent who granted access to the End-user.
There can be only one Agent Registration for any given agent in Agent Registry.
+Its main purpose is to make § 6.6 Access Grant available to the registered agent.
In the case of Social Agent Registration for ACME, created in Alice’s Agent Registry. The reciprocal registration
+will be the Social Agent Reigstration for Alice, created in ACME’s Agent Registry.
+
+
6.3. Social Agent Invitation
+
Social Agent Invitation represents an invitation for a Social Agent. It takes advantage of an existing and secure
+communication channel between two agents to pass a secret link that allows accepting the invitation.
+This flow results in both agents establishing a pair of Reciprocal Registrations.
+If the platform supports it, the Authorization Agent of the sender can use [WEB-SHARE] to pass the secret
+link to the user’s messaging app. On the other side, the Authorization Agent of the recipient can use [WEB-SHARE-TARGET] to register with the platform and receive a secret link from the user’s messaging app.
+Independent of the platform, Authorization Agents should always allow a simple copy of the link by the sender
+(e.g., navigator.clipboard.writeText) and paste it by the recipient.
+
6.4. Application Registration
+
Application Registrations are created by the End-user for applications they use.
+Since applications do not own or share data, they will never have a [#reciprocal-registration].
+
6.5. Agent Registration Discovery
+
Both Social Agent and Application can discover Agent Registration created for them,
+by performing HEAD or GET request on IRI denoting
+the Authorization Agent. Response will include HTTP Link header relating
+Agent Registration to the agent making the request using http://www.w3.org/ns/solid/interop#registeredAgent as link relation.
+
In a case where End-user using an application performs the discovery on their
+own Authorization Agent. The response will include a link to the Application registration.
+ HEAD request to and response from End-user’s Authorization Agent
+
+
In the case where the client acting on behalf of one social agent, performs the discovery on
+another’s social agent Authorization Agent. The response will include a link to Social Agent Registration.
+ Alice’s data grant for Projectron - Pro Projects
+
+
A Data Grant is immutable, it never gets updated, instead it can be only replaced
+with a newer Data Grant.
+
Data Grant can be consider as the most important data structure, it provides following information:
+
+
dataOwner
+
+
Social Agent who owns the data
+
grantedBy
+
+
Social Agent who granted the access
+
registeredShapeTree
+
+
Shape Tree used by related Data Registration
+
hasDataRegistration
+
+
Data Registration that this Data Grant applies to. As well as iriPrefix of that Data Registration (see § 4.1 Data Registration)
+
accessMode
+
+
List of access modes defining what application can do with the data
+
scopeOfGrant
+
+
Defines which instances can be accessed (see § 6.7.1 Scopes)
+
inheritsFromGrant
+
+
If grant has InheritInstances scope, it will be the Data Grant for Data Registraion with parent Data Instances (see § 6.7.2 Inheritance)
+
hasDataInstance
+
+
If grant has SelectedInstances scope, it will be all the Data Instances that application can access in the Data Registration
+
delegationOfGrant
+
+
If Data Grant is issued by Social Agent other than data owner, it will be the original Data Grant issued by the data owner (see § 6.7.3 Delegation)
+
+
6.7.1. Scopes
+
Data Grant can have one of three scopes:
+
+
AllFromRegistry
+
+
All the Data Instances in the Data Registration. Application will be able to access the Data Registration and see the list of all contained instances (see § 4.1 Data Registration)
+
SelectedFromRegistry
+
+
Only specific Data Instances in the Data Registration. Application will not be able to access the Data Registration, so it will not see the list al all contained instances. Instad list of selected Data Instances is available via hasDataInstance
+
Inherited
+
+
Only those Data Instances in the Data Registration, which are related to parent kData Instances in Data Registration of the Data Grant referenced with inheritsFromGrant (see § 6.7.2 Inheritance)
+
+
6.7.2. Inheritance
+
InheritInstances Data Grant doesn’t provide access to the Data Registration, so
+application can’t get the list of all the Data Instances. Neither it provides a list of specific
+Data Instances in the Data Registration.
+
To find Data Instances from that Data Registration, application first needs to access parent
+Data Instances from Data Registration which Data Grant referenced by inheritsFromGrant makes accessible. Based on shape tree definition, each parent Data Instance will reference all its
+child Data Instances.
+
Both parent and child Data Registrations have to be in the same Data Registry. Since only one
+Data Registration for specific shape tree can be created in any given Data Registry.
+All parent Data Instances are from one Data Registration and all child Data Instances are from
+one Data Registration.
+
6.7.3. Delegation
+
Application doesn’t need to handle delegated Data Grants in any special way.
+To know if Data Grant was issued by currently logged in user or someone else,
+application should rely on dataOwner information in the Data Grant.
Access Receipt helps to establish data sharing between two social agents. Once received the authorization agent
+should prompt the user to approve creating § 6.2 Social Agent Registration for that data owner.
+If user approves § 6.2.1 Reciprocal Registration can be associated and subscription for notifications established
+to keep track on the latest § 6.6 Access Grant. Once reciprocal registration gets associated there is no
+further need for its data owner to send access receipts to the agent registered in that reciprocal registration.
An Access Need represents the requirement of one specific type of data represented by a shape tree,
+as part of an Access Need Group.
+
Complete this section based on implementation of UI for Authorization Agent Service
+
7. Gathering Authorizations from the user
+
The most common case is authorizing an application based on its § 6.10 Access Need.
+The authorization screen should combine those Access Needs with existing § 5.1 Access Authorization if one exists.
+It should also assist the user in composing new Access Authorization, taking into account all their:
+
+
+
Data Registries with Data Registrations and Data Instances
Alice finds an Application called Projectron that she’d like
+ to use to manage her Projects and Tasks.
+
+
2
+
Alice authenticates to Projectron with her WebID.
+
+
3
+
Projectron dereferences her WebID and retrieves Authorization Agent from her WebID Profile Document.
+
+
4
+
Projectron asks Alice’s Authorization Agent whether Alice already has an Application Registration for Projectron.
+
+
5
+
Alice’s Authorization Agent checks the Agent Registry in Alice’s Pod for a Projectron Application Registration.
+
+
6
+
No Application Registration for Projectron is found.
+ Projectron now knows that Alice hasn’t given it permission to access her data, so it must ask.
+
+
7
+
Projectron redirects Alice to her Authorization Agent, supplying its identifier for context.
+
+
8
+
Alice’s Authorization Agent dereferences the supplied Projectron identifier, retrieving Projectron’s
+ Application profile graph and corresponding Access Need Groups from the WebID Profile Document,
+ as well as hasAuthorizationCallbackEndpoint.
+
+
9
+
Alice’s Authorization Agent presents the Access Need Groups from Projectron’s Application
+ profile graph, so that Alice understands what kind of data is being requested, and why.
+
+
10
+
Alice’s chooses the scope of access that Projectron will receive, to the data to
+ which it has asked for access via the presented Access Needs.
+
+
11-13
+
Alice’s Authorization Agent records her decision as an Access Authorization in Alice’s
+ Authorization Registry. An Application Registration is created for Projectron in
+ Alice’s Agent Registry. An Access Grant and corresponding Data Grants are generated
+ from the Access Authorization and stored in the Projectron Application Registration.
+
+
14
+
Alice’s Authorization Agent redirects her back to Projectron, now that the appropriate access has been granted.
+
+
15
+
Projectron again asks Alice’s Authorization Agent for a Projectron Application Registration.
+
+
16
+
Alice’s Authorization Agent finds the newly created Projectron Application Registration in the Agent Registry in Alice’s Pod.
+
+
17
+
Alice’s Authorization Agent provides the URI of the Application Registration to Projectron.
+
+
18
+
Projectron learns what access it received through the Access Grant in Alice’s Projectron Application Registration.
+
+
19
+
Projectron may now function as intended, within the scope of authorization it was given by Alice.
+
+
+
+
8. Sharing resources indicated by the application
+
When the application has already been registered, and the user wants to
+initiate a sharing-specific § 4.2 Data Instance, an authorization flow with resource
+indication is available.
+
+
+
+
+
+
+
+
Step
+
Description
+
+
+
1
+
Alice’s is authenticated with Projectron.
+
+
2
+
Alice has already authorized Projectron.
+
+
3
+
Projectron has read its Access Grant and displayed projects.
+
+
4
+
Alice initiates sharing of a specific project.
+
+
5
+
Projectron redirects Alice to her Authorization Agent, indicating the selected project.
+
+
6-8
+
Alice’s Authorization Agent fetches the indicated project and checks who already has access to it.
+ It also fetches list of all registered social agents to present it to Alice.
+
+
9
+
Alice chooses all the social agents with which she wants to share the selected project,
+ as well as modes of access for all selected agents. If the shape tree has references (e.g., tasks) she can
+ also select modes of access for each inherited shape tree.
+
+
10-11
+
Alice’s Authorization Agent records new access authorizations for all the selected agents
+ and regenerates access grants provided in their agent registrations.
+
+
12
+
Alice’s Authorization Agent dereferences the supplied Projectron WebID, retrieving Projection’s
+ Application profile graph from the WebID Profile Document,
+ to discover the hasAuthorizationCallbackEndpoint.
+
+
13
+
Alice’s Authorization Agent redirects her back to Projectron, now that the project has been shared.
+
+
14
+
Alice continues using Projectron.
+
+
+
+
9. Generating Access Grant from Access Authorization
+
Based on an § 5.1 Access Authorization, authorization agent can generate an § 6.6 Access Grant.
+For § 5.2 Data Authorization using AllFromRegistry, SelectedFromRegistry scope,
+a single § 6.7 Data Grant gets generated. Similar for data authorization using Inherited scope and
+inheriting from data authorization with one of those two scopes. Here a data authorization gets directly
+translated into a data grant, only changing type and all authorization specific properties to grant specific properties.
+
For data authorization using All or AllFromAgent, zero or more data grant gets generated.
+This number depends on a number of Data Registries owned by the social agent giving the authorization,
+as well as number of data grants given to them by other social agents. Data authorization with Inherited scope
+will also have zero or more data grants if it is inheriting from data authorization using one of those two scopes.
This primer is intended to accompany [SAI].
+It is focused on providing a friendly introduction for developers of libraries intended
+for solid applications.
+
This document was developed alongside the open-source TypeScript implementation [SAI-JS]
+
We will follow example of an application called Projectron,
+which manages projects and tasks.
+End user, named Alice, collaborates on projects
+with other Individuals and Organizations.
+
2. Shape Tree
+
Shape Trees [SHAPETREES] allow for the definition and validation of data hierarchies
+including which shapes [SHEX] should be used to validate data.
+In our examples, we are going to use the following Shapes and Shape Trees.
In this primer we will consider the use-case of a project management application
+identified by https://projectron.example/#app Every application has public WebID Document providing information about it.
+
+
projectron:\#idainterop:Application;interop:applicationName"Projectron";interop:applicationDescription"Manage projects with ease";interop:applicationAuthoracme:\#corp;interop:applicationThumbnailprojectron:thumb.svg;interop:hasAccessNeedGroupprojectron:\#need-group-pm.projectron:\#need-group-pminterop:accessNecessityinterop:accessRequired;interop:accessScenariointerop:PersonalAccess;interop:authenticatesAsinterop:Pilot;interop:hasAccessDecoratorIndexprojectron:index;interop:hasAccessNeedprojectron:\#need-project.projectron:\#need-projectainterop:AccessNeed;interop:registeredShapeTreesolidtrees:Project;interop:accessNecessityinterop:accessRequired;interop:accessModeacl:read,acl:write.projectron:\#need-issueainterop:AccessNeed;interop:registeredShapeTreesolidtrees:Issue;interop:accessNecessityinterop:accessRequired;interop:accessModeacl:read,acl:write;interop:inheritsFromNeedprojectron:\#need-project.
+ Projectron WebID document
+
+
Access Needs explain what kind of data application works with.
+They use combination of § 2 Shape Tree and access modes to
+convey how the application can work with data.
+
Details can change based on experience from implementing Authorization Agent role
+
4. Authorization Flow
+
User always needs to authenticate first.
+For the rest of this primer we’ll be assuming that user has already authenticated,
+and that applicaction know WebID of the authenticated user.
+
4.1. Authorization Agent Discovery
+
Every user has an Authorization Agent which can be discovered from
+their WebID Document via interop:hasAuthorizationAgent predicate.
Here we see that Alice designates https://auth.alice.example/ as their Authorization Agent.
+
4.2. Application Registration Discovery
+
Application can discover Application Registration created for it by the user,
+by performing HEAD or GET request on IRI denoting
+user’s Authorization Agent. Response will include HTTP Link header relating
+Application Registration to the application making the request using http://www.w3.org/ns/solid/interop#registeredAgent as link relation.
In cases where an application hasn’t been registered yet, it needs to initiate the flow with the Authorization Agent.
+
After successful flow, the application will be able to discover its registration.
+
+
+
+
+
+
+
+
Step
+
Description
+
+
+
1
+
Alice finds an Application called Projectron that she’d like
+ to use to manage her Projects and Tasks.
+
+
2
+
Alice authenticates to Projectron with her WebID.
+
+
3
+
Projectron dereferences her WebID and retrieves Authorization Agent from her WebID Profile Document.
+
+
4
+
Projectron asks Alice’s Authorization Agent whether Alice already has an Application Registration for Projectron.
+
+
5
+
Alice’s Authorization Agent checks the Agent Registry in Alice’s Pod for a Projectron Application Registration.
+
+
6
+
No Application Registration for Projectron is found.
+ Projectron now knows that Alice hasn’t given it permission to access her data, so it must ask.
+
+
7
+
Projectron redirects Alice to her Authorization Agent, supplying its identifier for context.
+
+
8
+
Alice’s Authorization Agent dereferences the supplied Projectron identifier, retrieving Projectron’s
+ Application profile graph and corresponding Access Need Groups from the WebID Profile Document,
+ as well as hasAuthorizationCallbackEndpoint.
+
+
9
+
Alice’s Authorization Agent presents the Access Need Groups from Projectron’s Application
+ profile graph, so that Alice understands what kind of data is being requested, and why.
+
+
10
+
Alice’s chooses the scope of access that Projectron will receive, to the data to
+ which it has asked for access via the presented Access Needs.
+
+
11-13
+
Alice’s Authorization Agent records her decision as an Access Authorization in Alice’s
+ Authorization Registry. An Application Registration is created for Projectron in
+ Alice’s Agent Registry. An Access Grant and corresponding Data Grants are generated
+ from the Access Authorization and stored in the Projectron Application Registration.
+
+
14
+
Alice’s Authorization Agent redirects her back to Projectron, now that the appropriate access has been granted.
+
+
15
+
Projectron again asks Alice’s Authorization Agent for a Projectron Application Registration.
+
+
16
+
Alice’s Authorization Agent finds the newly created Projectron Application Registration in the Agent Registry in Alice’s Pod.
+
+
17
+
Alice’s Authorization Agent provides the URI of the Application Registration to Projectron.
+
+
18
+
Projectron learns what access it received through the Access Grant in Alice’s Projectron Application Registration.
+
+
19
+
Projectron may now function as intended, within the scope of authorization it was given by Alice.
+
+
+
+
4.4. Resource Indication
+
When the application has already been registered, and the user wants to
+initiate a sharing-specific § 6.1 Data Instance, an authorization flow with resource
+indication is available.
+
+
+
+
+
+
+
+
Step
+
Description
+
+
+
1
+
Alice’s is authenticated with Projectron.
+
+
2
+
Alice has already authorized Projectron.
+
+
3
+
Projectron has read its Access Grant and displayed projects.
+
+
4
+
Alice initiates sharing of a specific project.
+
+
5
+
Projectron redirects Alice to her Authorization Agent, indicating the selected project.
+
+
6-8
+
Alice’s Authorization Agent fetches the indicated project and checks who already has access to it.
+ It also fetches list of all registered social agents to present it to Alice.
+
+
9
+
Alice chooses all the social agents with which she wants to share the selected project,
+ as well as modes of access for all selected agents. If the shape tree has references (e.g., tasks) she can
+ also select modes of access for each inherited shape tree.
+
+
10-11
+
Alice’s Authorization Agent records new access authorizations for all the selected agents
+ and regenerates access grants provided in their agent registrations.
+
+
12
+
Alice’s Authorization Agent dereferences the supplied Projectron WebID, retrieving Projection’s
+ Application profile graph from the WebID Profile Document,
+ to discover the hasAuthorizationCallbackEndpoint.
+
+
13
+
Alice’s Authorization Agent redirects her back to Projectron, now that the project has been shared.
+
+
14
+
Alice continues using Projectron.
+
+
+
+
5. Application Registration
+
Application Registration can be considered an entry point to all the data
+that the user authorized it to access. The next step in the discovery of that data
+is the Access Grant linked via interop:hasAccessGrant predicate.
+ Alice’s data grant for Projectron - Pro Projects
+
+
A Data Grant is immutable, it never gets updated, instead it can be only replaced
+with a newer Data Grant.
+
Data Grant can be consider as the most important data structure, it provides following information:
+
+
dataOwner
+
+
Social Agent who owns the data
+
grantedBy
+
+
Social Agent who granted the access
+
registeredShapeTree
+
+
Shape Tree used by related Data Registration
+
hasDataRegistration
+
+
Data Registration that this Data Grant applies to. As well as iriPrefix of that Data Registration (see § 6 Data Registration)
+
accessMode
+
+
List of access modes defining what application can do with the data
+
scopeOfGrant
+
+
Defines which instances can be accessed (see § 5.2.1 Scopes)
+
inheritsFromGrant
+
+
If grant has InheritInstances scope, it will be the Data Grant for Data Registraion with parent Data Instances (see § 5.2.2 Inheritance)
+
hasDataInstance
+
+
If grant has SelectedInstances scope, it will be all the Data Instances that application can access in the Data Registration
+
delegationOfGrant
+
+
If Data Grant is issued by Social Agent other than data owner, it will be the original Data Grant issued by the data owner (see § 5.2.3 Delegation)
+
+
5.2.1. Scopes
+
Data Grant can have one of three scopes:
+
+
AllFromRegistry
+
+
All the Data Instances in the Data Registration. Application will be able to access the Data Registration and see the list of all contained instances (see § 6 Data Registration)
+
SelectedFromRegistry
+
+
Only specific Data Instances in the Data Registration. Application will not be able to access the Data Registration, so it will not see the list al all contained instances. Instad list of selected Data Instances is available via hasDataInstance
+
Inherited
+
+
Only those Data Instances in the Data Registration, which are related to parent kData Instances in Data Registration of the Data Grant referenced with inheritsFromGrant (see § 5.2.2 Inheritance)
+
+
5.2.2. Inheritance
+
InheritInstances Data Grant doesn’t provide access to the Data Registration, so
+application can’t get the list of all the Data Instances. Neither it provides a list of specific
+Data Instances in the Data Registration.
+
To find Data Instances from that Data Registration, application first needs to access parent
+Data Instances from Data Registration which Data Grant referenced by inheritsFromGrant makes accessible. Based on shape tree definition, each parent Data Instance will reference all its
+child Data Instances.
+
Both parent and child Data Registrations have to be in the same Data Registry. Since only one
+Data Registration for specific shape tree can be created in any given Data Registry.
+All parent Data Instances are from one Data Registration and all child Data Instances are from
+one Data Registration.
+
5.2.3. Delegation
+
Application doesn’t need to handle delegated Data Grants in any special way.
+To know if Data Grant was issued by currently logged in user or someone else,
+application should rely on dataOwner information in the Data Grant.
As we discussed in § 5.2.2 Inheritance a Shape Tree will specify how parent data instances
+relate to child data instances. For Project shape three the predicate is pm:hasTask,
+links to child Task data instances.
When creating or updating data instance with HTTP PUT method. Application should include
+link header linking Data Instance to Data Registration using link relation http://www.w3.org/ns/solid/interop#targetDataRegistration
+
Update should include If-Match HTTP header with value of ETag from
+HTTP response when the representation was retreived.
This primer is intended to accompany [SAI].
+It is focused on providing a friendly introduction for developers of libraries intended
+for solid authorization agents.
+
This document was developed alongside the open-source TypeScript implementation [SAI-JS] and open-source Java implementation [SAI-JAVA].
+
2. Shape Tree
+
Shape Trees [SHAPETREES] allow for the definition and validation of data hierarchies
+including which shapes [SHEX] should be used to validate data.
+In our examples, we are going to use the following Shapes and Shape Trees.
In a Data Registry, there can be at most one Data Registration for any given shape tree.
+
4.1. Data Registration
+
Data Registration is a container, which contains Data Instances. Each of those Data Instances conforms to one specific
+shape tree assigned to the Data Registration.
+ Data Registration for projects in one of Alice’s Data Registries
+
+
+
registeredShapeTree
+
+
Shape Tree used by this Data Registration
+
+
4.2. Data Instance
+
Data Instance is a resource representing something specific, for example, a project or a task.
+An Authorization Agent is not responsible for modifying data instances. Sometimes it still needs to access them
+during § 7 Gathering Authorizations from the user if the user wants to select specific data instances.
+
5. Authorization Registry
+
Authorization Registry is a container, which contains Access Authorizations.
+Each of those Access Authorizations is created for a specific grantee,
+and groups together one or more Data Authorizations.
An Access Authorization is immutable, it never gets updated, instead it can be only replaced
+with a newer Access Authorization.
+
5.2. Data Authorization
+
Data Authorization, similar to § 6.7 Data Grant, represents access granted by a specific Social Agent.
+It is always associated with a specific § 2 Shape Tree. Depending on its scope it can apply to all the
+Data Instances in any number of Data Registrations. In that case, interop:hasDataRegistration will not be specified.
+ Alice’s data authorization for Projectron to ACME’s Projects
+
+
A Data Authorization is immutable, it never gets updated, instead it can be only replaced
+with a newer Data Authorization.
+
5.2.1. Scopes
+
Data Authorization can have one of five scopes:
+
+
All
+
+
All the Data Instances in all the Data Registration the End-user has access to.
+This includes ones owned by the End-user as well as ones owned by others, where End-user has been granted access.
+
AllFromAgent
+
+
All the Data Instances in all the Data Registrations, owned by a specific social agent.
+This could be the End-user themselves or any other social agent who granted access to the End-user.
There can be only one Agent Registration for any given agent in Agent Registry.
+Its main purpose is to make § 6.6 Access Grant available to the registered agent.
In the case of Social Agent Registration for ACME, created in Alice’s Agent Registry. The reciprocal registration
+will be the Social Agent Reigstration for Alice, created in ACME’s Agent Registry.
+
+
6.3. Social Agent Invitation
+
Social Agent Invitation represents an invitation for a Social Agent. It takes advantage of an existing and secure
+communication channel between two agents to pass a secret link that allows accepting the invitation.
+This flow results in both agents establishing a pair of Reciprocal Registrations.
+If the platform supports it, the Authorization Agent of the sender can use [WEB-SHARE] to pass the secret
+link to the user’s messaging app. On the other side, the Authorization Agent of the recipient can use [WEB-SHARE-TARGET] to register with the platform and receive a secret link from the user’s messaging app.
+Independent of the platform, Authorization Agents should always allow a simple copy of the link by the sender
+(e.g., navigator.clipboard.writeText) and paste it by the recipient.
+
6.4. Application Registration
+
Application Registrations are created by the End-user for applications they use.
+Since applications do not own or share data, they will never have a [#reciprocal-registration].
+
6.5. Agent Registration Discovery
+
Both Social Agent and Application can discover Agent Registration created for them,
+by performing HEAD or GET request on IRI denoting
+the Authorization Agent. Response will include HTTP Link header relating
+Agent Registration to the agent making the request using http://www.w3.org/ns/solid/interop#registeredAgent as link relation.
+
In a case where End-user using an application performs the discovery on their
+own Authorization Agent. The response will include a link to the Application registration.
+ HEAD request to and response from End-user’s Authorization Agent
+
+
In the case where the client acting on behalf of one social agent, performs the discovery on
+another’s social agent Authorization Agent. The response will include a link to Social Agent Registration.
+ Alice’s data grant for Projectron - Pro Projects
+
+
A Data Grant is immutable, it never gets updated, instead it can be only replaced
+with a newer Data Grant.
+
Data Grant can be consider as the most important data structure, it provides following information:
+
+
dataOwner
+
+
Social Agent who owns the data
+
grantedBy
+
+
Social Agent who granted the access
+
registeredShapeTree
+
+
Shape Tree used by related Data Registration
+
hasDataRegistration
+
+
Data Registration that this Data Grant applies to. As well as iriPrefix of that Data Registration (see § 4.1 Data Registration)
+
accessMode
+
+
List of access modes defining what application can do with the data
+
scopeOfGrant
+
+
Defines which instances can be accessed (see § 6.7.1 Scopes)
+
inheritsFromGrant
+
+
If grant has InheritInstances scope, it will be the Data Grant for Data Registraion with parent Data Instances (see § 6.7.2 Inheritance)
+
hasDataInstance
+
+
If grant has SelectedInstances scope, it will be all the Data Instances that application can access in the Data Registration
+
delegationOfGrant
+
+
If Data Grant is issued by Social Agent other than data owner, it will be the original Data Grant issued by the data owner (see § 6.7.3 Delegation)
+
+
6.7.1. Scopes
+
Data Grant can have one of three scopes:
+
+
AllFromRegistry
+
+
All the Data Instances in the Data Registration. Application will be able to access the Data Registration and see the list of all contained instances (see § 4.1 Data Registration)
+
SelectedFromRegistry
+
+
Only specific Data Instances in the Data Registration. Application will not be able to access the Data Registration, so it will not see the list al all contained instances. Instad list of selected Data Instances is available via hasDataInstance
+
Inherited
+
+
Only those Data Instances in the Data Registration, which are related to parent kData Instances in Data Registration of the Data Grant referenced with inheritsFromGrant (see § 6.7.2 Inheritance)
+
+
6.7.2. Inheritance
+
InheritInstances Data Grant doesn’t provide access to the Data Registration, so
+application can’t get the list of all the Data Instances. Neither it provides a list of specific
+Data Instances in the Data Registration.
+
To find Data Instances from that Data Registration, application first needs to access parent
+Data Instances from Data Registration which Data Grant referenced by inheritsFromGrant makes accessible. Based on shape tree definition, each parent Data Instance will reference all its
+child Data Instances.
+
Both parent and child Data Registrations have to be in the same Data Registry. Since only one
+Data Registration for specific shape tree can be created in any given Data Registry.
+All parent Data Instances are from one Data Registration and all child Data Instances are from
+one Data Registration.
+
6.7.3. Delegation
+
Application doesn’t need to handle delegated Data Grants in any special way.
+To know if Data Grant was issued by currently logged in user or someone else,
+application should rely on dataOwner information in the Data Grant.
Access Receipt helps to establish data sharing between two social agents. Once received the authorization agent
+should prompt the user to approve creating § 6.2 Social Agent Registration for that data owner.
+If user approves § 6.2.1 Reciprocal Registration can be associated and subscription for notifications established
+to keep track on the latest § 6.6 Access Grant. Once reciprocal registration gets associated there is no
+further need for its data owner to send access receipts to the agent registered in that reciprocal registration.
An Access Need represents the requirement of one specific type of data represented by a shape tree,
+as part of an Access Need Group.
+
Complete this section based on implementation of UI for Authorization Agent Service
+
7. Gathering Authorizations from the user
+
The most common case is authorizing an application based on its § 6.10 Access Need.
+The authorization screen should combine those Access Needs with existing § 5.1 Access Authorization if one exists.
+It should also assist the user in composing new Access Authorization, taking into account all their:
+
+
+
Data Registries with Data Registrations and Data Instances
Alice finds an Application called Projectron that she’d like
+ to use to manage her Projects and Tasks.
+
+
2
+
Alice authenticates to Projectron with her WebID.
+
+
3
+
Projectron dereferences her WebID and retrieves Authorization Agent from her WebID Profile Document.
+
+
4
+
Projectron asks Alice’s Authorization Agent whether Alice already has an Application Registration for Projectron.
+
+
5
+
Alice’s Authorization Agent checks the Agent Registry in Alice’s Pod for a Projectron Application Registration.
+
+
6
+
No Application Registration for Projectron is found.
+ Projectron now knows that Alice hasn’t given it permission to access her data, so it must ask.
+
+
7
+
Projectron redirects Alice to her Authorization Agent, supplying its identifier for context.
+
+
8
+
Alice’s Authorization Agent dereferences the supplied Projectron identifier, retrieving Projectron’s
+ Application profile graph and corresponding Access Need Groups from the WebID Profile Document,
+ as well as hasAuthorizationCallbackEndpoint.
+
+
9
+
Alice’s Authorization Agent presents the Access Need Groups from Projectron’s Application
+ profile graph, so that Alice understands what kind of data is being requested, and why.
+
+
10
+
Alice’s chooses the scope of access that Projectron will receive, to the data to
+ which it has asked for access via the presented Access Needs.
+
+
11-13
+
Alice’s Authorization Agent records her decision as an Access Authorization in Alice’s
+ Authorization Registry. An Application Registration is created for Projectron in
+ Alice’s Agent Registry. An Access Grant and corresponding Data Grants are generated
+ from the Access Authorization and stored in the Projectron Application Registration.
+
+
14
+
Alice’s Authorization Agent redirects her back to Projectron, now that the appropriate access has been granted.
+
+
15
+
Projectron again asks Alice’s Authorization Agent for a Projectron Application Registration.
+
+
16
+
Alice’s Authorization Agent finds the newly created Projectron Application Registration in the Agent Registry in Alice’s Pod.
+
+
17
+
Alice’s Authorization Agent provides the URI of the Application Registration to Projectron.
+
+
18
+
Projectron learns what access it received through the Access Grant in Alice’s Projectron Application Registration.
+
+
19
+
Projectron may now function as intended, within the scope of authorization it was given by Alice.
+
+
+
+
8. Sharing resources indicated by the application
+
When the application has already been registered, and the user wants to
+initiate a sharing-specific § 4.2 Data Instance, an authorization flow with resource
+indication is available.
+
+
+
+
+
+
+
+
Step
+
Description
+
+
+
1
+
Alice’s is authenticated with Projectron.
+
+
2
+
Alice has already authorized Projectron.
+
+
3
+
Projectron has read its Access Grant and displayed projects.
+
+
4
+
Alice initiates sharing of a specific project.
+
+
5
+
Projectron redirects Alice to her Authorization Agent, indicating the selected project.
+
+
6-8
+
Alice’s Authorization Agent fetches the indicated project and checks who already has access to it.
+ It also fetches list of all registered social agents to present it to Alice.
+
+
9
+
Alice chooses all the social agents with which she wants to share the selected project,
+ as well as modes of access for all selected agents. If the shape tree has references (e.g., tasks) she can
+ also select modes of access for each inherited shape tree.
+
+
10-11
+
Alice’s Authorization Agent records new access authorizations for all the selected agents
+ and regenerates access grants provided in their agent registrations.
+
+
12
+
Alice’s Authorization Agent dereferences the supplied Projectron WebID, retrieving Projection’s
+ Application profile graph from the WebID Profile Document,
+ to discover the hasAuthorizationCallbackEndpoint.
+
+
13
+
Alice’s Authorization Agent redirects her back to Projectron, now that the project has been shared.
+
+
14
+
Alice continues using Projectron.
+
+
+
+
9. Generating Access Grant from Access Authorization
+
Based on an § 5.1 Access Authorization, authorization agent can generate an § 6.6 Access Grant.
+For § 5.2 Data Authorization using AllFromRegistry, SelectedFromRegistry scope,
+a single § 6.7 Data Grant gets generated. Similar for data authorization using Inherited scope and
+inheriting from data authorization with one of those two scopes. Here a data authorization gets directly
+translated into a data grant, only changing type and all authorization specific properties to grant specific properties.
+
For data authorization using All or AllFromAgent, zero or more data grant gets generated.
+This number depends on a number of Data Registries owned by the social agent giving the authorization,
+as well as number of data grants given to them by other social agents. Data authorization with Inherited scope
+will also have zero or more data grants if it is inheriting from data authorization using one of those two scopes.
Solid affords us the opportunity to create a valuable and
+powerful ecosystem where people and organizations retain control
+of their data, but are also able to put it to work and use it
+to its full potential. The fundamentals of Solid make this possible,
+but further definition of standard methods and mechanisms
+must be established
+to make it practical, intuitive, and secure.
This specification details how Social Agents in the Solid ecosystem
+can read, write, and manage data stored in a Solid pod using
+disparate Applications.
§ 6 Data Registrations details how Social Agents register, organize, and
+lookup their data. Data is stored uniformly, avoiding complex
+physical hierarchies. Shape trees and shapes provide strong data validation and
+intuitive data boundaries.
Agents are the primary actors in an interoperable Solid ecosystem.
+
An Agent is denoted by an identity. Dereferencing that identity leads to identity profile document, where a graph of useful information
+about the Agent can be found. This graph is used by the Agent as a starting point to look up their own data, as well as data that has
+been shared with them.
+
The Agent graph in an identity profile document is designed to be
+publicly accessible, but many of the things the Agent links to are
+designed to be private, or accessible only by others they have authorized.
+
An Agent can dereference the identity of another Agent to obtain
+the public information they need to interact with them.
A Social Agent is a strongly identifiable individual, group, or
+organization that can own or be responsible for data, and provide authorization to the
+access of that data by other Agents.
A Registry is a place where a Social Agent can store and find
+different types of data, often for particular purposes. Each type
+of Registry serves a specific purpose or function.
The Registry SetMAY use any resource or
+subject names. It SHOULD NOT be readable
+by the public. It SHOULD be accessible
+and manageable by the Social Agent that owns it, or other Social Agents that have received appropriate authorization, via
+authorized Applications.
An Application is a software-based Agent that a Social Agent uses to access, manipulate, and manage the data in
+their control, as well as the data they’ve been granted access to.
An Application Registration provides the Social Agent with a place to maintain metadata, state, preferences, and
+other application-specific data associated with a given Application they
+have elected to use.
Note: Commonly the Authorization Agent, making the request on behalf of the Social Agent accepting the invitation,
+ will create corresponding Social Agent Registration after receiving the [WEBID] in the response,
+ which means that it is not available before receiving the response.
+
5.4. Agent Registry
+
An Agent Registry is a collection of Agent Registrations.
Data Registrations let Social Agents store and manage the
+data they control. Data of various types is organized and stored in a
+uniform way to aid validation, authorization,
+discovery, and more.
+
Complex hierarchies that hinder interoperability are avoided
+by storing data in a relatively flat hierarchy. This creates natural
+data boundaries that make data storage and authorization more intuitive.
A Data Registry is a collection of Data Registrations, each
+of which represents a unique type of data, identified by a shape tree.
+
A Data Registry can be used for basic discovery, but it is not
+designed nor intended to be an efficient means to query or index data.
+However, it is intended to be used as reliable source data for different
+query engines or indexing schemes.
Slight variations concerning where Access Needs are sourced from, and
+how notification of access is provided, are the only differences from
+one flow to another.
+
7.1. Authorization Agent
+
An Authorization Agent is an Application designated by
+a Social Agent to be responsible for managing the access to data
+under their control, linked via their Registry Set.
When the resource query parameter is used, the Authorization Agent will use it
+as an indication that access to a specific data instance is intended to be shared.
The response will include an HTTP Link header relating the Agent Registration to the Agent making the request via the http://www.w3.org/ns/solid/interop#registeredAgent link relation.
+
+ HEAD request to and response from Authorization Agent
+
Social Agents and Applications in the ecosystem often
+require access to data controlled by some other Social Agent.
+Consequently, a common way to explain
+and communicate data needs between these parties is required.
An Access Need represents the requirement of one specific type
+of data represented by a shape tree, as part of an Access Need Group.
+
It is often the case that a shape tree associated with an Access Need references other shape trees, providing a
+path to request access to related types. Consequently, Access Needs can be specified that inherit from other Access Needs through a shape tree reference.
Requested mode of access for the creator of a Data Instance.
+ Adds to the set of modes linked via interop:accessMode. Only valid when accessMode includes acl:Create, acl:Write, or acl:Append
+
An Access Need Group Description provides a short label or
+title and a more in-depth description that explains why a given Access Need Group is being requested of a Social Agent.
<#en-need-group-pm>
+ ainterop:AccessNeedGroupDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedGroupprojectron:need-group-pm;
+ skos:prefLabel"Read and Contribute to Projects"@en ;
+ skos:definition"Allow Projectron to read the Projects you select, and create new ones. Projectron won't modify existing data, but can add more."@en .
+
+
+
8.3.2. Access Need Description
+
An Access Need Description provides a specific
+explanation of why that data type is being requested by
+a given Access Need.
<#en-need-project>
+ ainterop:AccessNeedDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedprojectron:need-project;
+ skos:prefLabel"Access to Projects is essential for Projectron to perform its core function of Project Management"@en .
+
<>
+ ainterop:AccessDescriptionSet;
+ interop:usesLanguage"en"^^xsd:language.
+
+<#en-need-group-pm>
+ ainterop:AccessNeedGroupDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedGroupprojectron:need-group-pm;
+ skos:prefLabel"Read and Contribute to Projects"@en ;
+ skos:definition"Allow Projectron to read the Projects you select, and create new ones. Projectron won't modify existing data, but can add more."@en .
+
+<#en-need-project>
+ ainterop:AccessNeedDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedprojectron:need-project;
+ skos:prefLabel"Access to Projects is essential for Projectron to perform its core function of Project Management"@en .
+
+<#en-need-task>
+ ainterop:AccessNeedDescription;
+ interop:inAccessDescriptionSet<>;
+ interop:hasAccessNeedprojectron:need-task;
+ skos:prefLabel"Access to Tasks allows Projectron to identify and manage the work to be done in a given Project."@en .
+
Access Grants are generated from Access Authorizations. They are shared
+with a given Agent to communicate the scope of access that has been
+granted to them.
+
9.1. Access Authorization
+
An Access Authorization records the decision of a Social Agent to grant access to some portion of data in their control to
+another Agent.
A Data Authorization records the decision of a Social Agent to grant access to a specific type of data in their control, identified
+by a Shape Tree. They are always associated with a single Access Authorization.
Additional access mode assigned to the creator of a
+ data instance. Adds to the set of modes linked via interop:accessMode. Only valid when accessMode includes acl:Create, acl:Write, or acl:Append
+
A Data Grant provides an Agent with a detailed description
+of access that has been granted to them for a specific type of data,
+identified by a Shape Tree. Each Data Grant is associated with
+a single Access Grant.
Additional access mode assigned to the creator of a
+ data instance. Adds to the set of modes linked via interop:accessMode. Only valid when accessMode includes acl:Create, acl:Write, or acl:Append
+
A Delegated Data Grant is a sub-class of Data Grant used when a grantee re-shares or "delegates" access they’ve
+received to another Agent. The most common use case
+is when Alice shares access with Bob, and Bob delegates
+that access to his project management application.
+
+ Alice’s Delegated Data Grant for Projectron to access Projects
+ that Bob shared with her at https://alice.example/agents/2f2f3628/fe818190 - View
+
+
+
+ Alice’s Delegated Data Grant for Projectron to access Tasks
+ that Bob shared with her at https://alice.example/agents/2f2f3628/017d6a07 - View
+
Each Data Authorization applies to a specific type of data,
+identified by a shape tree. The amount of access authorized for data
+of that type is specified by the Access Scope, via interop:scopeOfAuthorization.
This specification uses some access modes in the acl: namespace that
+have not been adopted to demonstrate the most secure and accurate
+expression of a Social Agent’s authorization. Discussions are underway to add these modes.
+
[WAC] does not have any mechanism to extend or modify
+inherited permissions.
Only Data Instances of the data owner’s that are associated with Data Instances allowed by another authorization or grant
+
+
9.6.1. All
+
The interop:Allaccess scope includes all data of a specified type
+belonging to a given data owner, and all data of that same type shared with the data
+owner, across all of the data owner’s registries.
The follow example illustrates Alice’s authorization to give Projectron access to
+data of type pm-shapetrees:ProjectTree with a scope of interop:All. Since
+Alice has two Data Registries and Bob has shared projects with her, several Data Grants will be generated from this Data Authorization and shared
+with Projectron.
+
Note:interop:All is only valid for a Data Authorization.
+Generated Data Grants use the more specific interop:AllFromRegistry for each unique Data Registry, including Bob’s.
+
+ Alice’s Data Authorization for Projectron to access Projects
+ at https://alice.example/authorization/54a1b6a0 - View
+
+
+
+ Alice’s Data Grant for Projectron to access her Projects in
+ her Personal Data Registry at
+ https://alice.example/agents/2f2f3628/a0623c8f - View
+
+
+
+ Alice’s Delegated Data Grant for Projectron to access Projects
+ that Bob shared with her at https://alice.example/agents/2f2f3628/fe818190 - View
+
The interop:AllFromAgentaccess scope includes all data of a given type
+owned and shared by a specified Social Agent, across all of their Data Registries. Essentially, Alice can use this scope to delegate
+any access that she has been given to another Social Agent’s data (e.g. Bob), to another Agent of her choosing.
+
The Social Agent whose access is being shared is identified via interop:dataOwner.
The following example illustrates Alice’s authorization to give Performchart access to
+data of type pm-shapetrees:ProjectTree with a scope of interop:AllFromAgent and an interop:dataOwner of Bob.
+
Note: While Bob has granted Alice the ability to manipulate his project data,
+Alice grants Performchart a narrower scope of read-only access.
+
+ Alice’s Data Authorization for Performchart to access Projects
+ that Bob shared with her at https://alice.example/authorization/0e36ba8f - View
+
Alice generates one Delegated Data Grant for Performchart to access
+the Project data that Bob shared with her, which she stores in
+the Agent Registration for Performchart in her Agent Registry.
+It is marked as a delegation of Bob’s Data Grant via interop:delegationOfGrant.
+
+ Alice’s Delegated Data Grant for Performchart to access Projects
+ that Bob shared with her at https://alice.example/agents/c2328cdd/efc426c9 - View
+
The following example illustrates Bob’s authorization to give Alice access to
+all data of type pm-shapetrees:ProjectTree in the Data Registry he uses
+for his professional work.
+
+ Bob’s Data Authorization at https://bob.example/authorization/e4b1b154
+ for Alice to access his Project data - View
+
When a Data Grant is assigned the interop:AllFromRegistry scope, the interop:grantee is authorized to access all Data Instances in the Data Registration linked via interop:hasDataRegistration,
+limited by the access modes linked via interop:accessMode.
+
In the above example, Bob would be giving Alice the following access to pm-shapetrees:ProjectTreeData Instances (Projects) in the bob-work-data:08a99a10Data Registration:
+
+
+
Read the Data Registration
+
+
List all Projects
+
+
Read all Projects
+
+
Create a new Project
+
+
Read a Project she creates
+
+
Delete a Project she creates
+
+
Create resources in a Project she creates
+
+
Modify existing resources in a Project she creates
Create new Data Instances. Access modes assigned to
+ the creator on the created Data Instance should be a union of interop:accessMode and interop:createAccessMode modes. acl:Create is not currently supported.
+ Substitute with acl:Write or acl:Append, but may exceed intended scope
+ of access.
+
Modify Data Instances. Modification of Data Registration graph
+ not permitted. acl:Update is not currently supported. Substitute with acl:Write or acl:Append, but may exceed intended scope of access.
+
+
acl:Delete
+
Delete Data Instances. Deletion of Data Registration not permitted. acl:Delete is not currently supported. Substitute with acl:Write, but
+ may exceed intended scope of access.
+
The following example illustrates Jose’s authorization for Alice to access
+two specific Data Instances of pm-shapetrees:ProjectTree in the Data Registry he uses for his professional work.
+
+ Jose’s Data Authorization at https://jose.example/authorization/69095550
+ for Alice to access his Project data - View
+
When a Data Grant is assigned the interop:SelectedFromRegistry scope, the interop:grantee is authorized to access only the specific Data Instances linked via interop:hasDataInstance in the Data Registration linked via interop:hasDataRegistration,
+limited by the access modes linked via interop:accessMode.
Create new resources within the Data Instances where applicable. Access modes assigned to
+ the creator on a created resource should be a union of interop:accessMode and interop:createAccessMode modes. acl:Create is not currently supported.
+ Substitute with acl:Write or acl:Append, but may exceed intended scope
+ of access.
+
+
acl:Read
+
Read Data Instance and any contained resources where applicable.
+
+
acl:Update
+
Modify Data Instance and any contained resources where applicable. acl:Update is not currently supported. Substitute with acl:Write or acl:Append, but may exceed intended scope of access.
+
+
acl:Append
+
Add new data to resources in the Data Instance, without changing any
+ existing data.
+
+
acl:Delete
+
Delete Data Instance or any contained resources where applicable. acl:Delete is not currently supported. Substitute with acl:Write, but
+ may exceed intended scope of access.
+
The interop:Inheritedaccess scope is unique in that it depends
+on the existence of another Data Authorization with a scope of interop:All, interop:AllFromAgent, interop:AllFromRegistry, or interop:SelectedFromRegistry.
+
When a Data Authorization exists with
+one of those scopes, and its interop:registeredShapeTree specifies
+one or more virtual hierarchies via st:references, a corresponding Data Authorization with a scope of interop:Inherited can be created
+for each distinct reference.
The shape treepm-shapetrees:ProjectTree specifies one virtual hierarchy
+via st:references, indicating that a Project Data Instance virtually
+includes Task instances of pm-shapetrees:TaskTree through the
+predicate pm:hasTask.
+
+ ProjectTree definition at https://data.example/shapetrees/pm-shapetrees.tree - View Definition
+
+
+
+ Alice’s Data Grant for Projectron to access Tasks associated
+ with authorized Work Projects at
+ https://alice.example/agents/2f2f3628/0945218b - View
+
When a Data Grant is assigned the interop:Inherited scope, the interop:grantee is authorized to access only the specific Data Instances linked via st:references in the shape tree of the Data Grant linked via interop:inheritsFromGrant
+
In the example above, Alice grants Projectron the following access to only thepm-shapetrees:TaskTreeData Instances (Tasks) in the alice-work-data:df4ab227Data Registration that are linked
+to pm-shapetrees:ProjectTreeData Instances (Projects) in the alice-work-data:8501f084Data Registration.
+
For example, the three Tasks linked from the Project Data Instance below via pm:hasTask would be included in the interop:Inherited scope.
Create new Data Instances linked by shape tree reference. Access modes assigned to
+ the creator on the created Data Instance should be a union of interop:accessMode and interop:createAccessMode modes. acl:Create is not currently supported.
+ Substitute with acl:Write or acl:Append, but may exceed intended scope
+ of access.
+
Modify Data Instances linked by shape tree reference. acl:Update is not currently supported. Substitute with acl:Write or acl:Append, but may exceed intended scope of access.
+
+
acl:Append
+
Add new data to Data Instances linked by shape tree reference,
+ without changing any existing data.
+
+
acl:Delete
+
Delete Data Instances linked by shape tree reference. Deletion of Data Registration not permitted. acl:Delete is not currently supported. Substitute with acl:Write, but
+ may exceed intended scope of access.
+
The resource names for Access GrantsSHOULD be unpredictable.
+
10. Security
+
10.1. Application Authorization
+
For authorization purposes, client Applications in use today fall into
+two buckets:
+
Strongly identifiable applications can be identified by
+third parties independently from the Social Agent controlling them.
+Only server-side applications are
+strongly identifiable. As confidential clients, they can keep secrets
+and can present attestations and third-party credentials
+via DNS / domain certificates.
Weakly identifiable applications include in-browser Javascript Applications and native desktop or mobile Applications. They are
+considered weakly identifiable because they
+are not able to keep secrets on an instance level. They are often referred to
+as public clients. Native apps should be strongly-identifiable in theory
+(since they are able to keep secrets on an instance level), but not in
+practice because the OS manufacturers do not make their trust
+infrastructure available. Weakly identifiable clients are only strongly
+identifiable to the Social Agent controlling them.
+
In the case of Weakly identifiable applications, the ability for a Solid
+pod to limit access to data by the Application in use is only as strong as
+the trustworthiness of the Social Agent piloting that Application, along with
+their ability to avoid using malicious Applications. The identity of the Application can be manipulated
+by the Social Agent in control. This means that Alice can strongly control
+the Applications that she uses to access her own data, but has
+limited ability to control the Applications that Bob uses to access the data
+she shares with him.
+
11. Definitions
+
All definitions as stated below should be considered in the context of
+an interoperable ecosystem for Solid, whether explicitly stated
+or not.
+
Solid is a protocol made up of a number of open web standards
+aimed at decentralizing data on the web.
+
A Solid pod is a place for storing and accessing data via
+the Solid protocol, with mechanisms for controlling who or what can
+access that data.
+
An interoperable ecosystem is
+a collection of Solid compatible applications developed by one or more
+entities, used by a community of users, that can safely access and manipulate
+the same kinds of data in pods.
+
A server-side application runs on a dedicated server. They may
+also act as autonomous authenticated agents.
+
A user-piloted application runs on a user’s device, with the user
+as the authenticated agent. They include in-browser javascript
+applications, native desktop applications, and mobile applications.
An identity is a unique URI that can be dereferenced
+to return an identity profile document. Compatible
+identity systems include WebID and DID.
+
An identity profile document is a linked data document obtained by
+dereferencing the URI for a given identity. It provides information that
+can be used to prove that a given Agent controls the document.
+
A WebID is a web resource at an HTTP URI which refers to an agent. An identity profile document can be accessed by
+dereferencing the WebID. [WEBID]
+
A DID is a URI that associates a DID subject (e.g. an agent,
+thing, data model, abstract entity, etc.) with a DID document,
+equivalent to an identity profile document, to allow trustable
+interactions with that subject. [DID]
+
An application identity is a web resource at an HTTP URI
+that uniquely identifies a given Application, and dereferences to an application profile document.
+
An application profile document is a linked data document
+obtained by dereferencing the URI for a given application identity.
+
An acl resource as defined by [WAC] may be directly
+associated with a resource or indirectly associated with a resource
+through inheritance. It determines which authorization subjects can
+access a resource, and the modes of access they have for it.
+
An access mode denotes operations (e.g. read, write)
+that a given authorization subject can perform on a resource.
A shape provides a schema that RDF data graphs must meet in order
+to be considered conformant. A shape associated with a given resource in a pod ensures that any data stored in that resource must conform to the
+associated shape. Shape languages include [SHEX] and [SHACL].
+
A Shape Tree defines a prospective tree of related resources
+which can be read and written by applications. The shape tree associates
+each of these resources with a shape. This allows one to treat a set of
+related resources as a single grouping, and apply that to a range of
+operations including access control, data organization, data validation,
+and data migration. [SHAPETREES]
+
A Shape Tree Decorator provides additional human-readable
+description and context for a given shape tree.
+
A Shape Tree Reference provides the necessary context to
+associate instances of related shape trees via a ShapePath
This specification uses some access modes in the acl: namespace that
+have not been adopted to demonstrate the most secure and accurate
+expression of a Social Agent’s authorization. Discussions are underway to add these modes. ↵
+
[WAC] does not have any mechanism to extend or modify
+inherited permissions. ↵
