Skip to content

Commit 22289b3

Browse files
elf-pavlikelf-pavlik
authored
Merge pull request #320 from elf-pavlik/resource-indication
Resource indication
2 parents dad2c26 + 34624d7 commit 22289b3

14 files changed

Lines changed: 363 additions & 161 deletions

‎proposals/primer/app-authorization-flow.bs‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
<figure>
2+
<table class="data tree" align="left">
3+
<col>
4+
<col>
5+
<thead>
6+
<tr>
7+
<th>Step</th>
8+
<th>Description</th>
9+
</tr>
10+
</thead>
11+
<tbody>
12+
<tr>
13+
<td><b>1</b></td>
14+
<td>Alice finds an Application called Projectron that she'd like
15+
to use to manage her Projects and Tasks.</td>
16+
</tr>
17+
<tr>
18+
<td><b>2</b></td>
19+
<td>Alice authenticates to Projectron with her WebID.</td>
20+
</tr>
21+
<tr>
22+
<td><b>3</b></td>
23+
<td>Projectron dereferences her WebID and retrieves Authorization Agent from her WebID Profile Document.</td>
24+
</tr>
25+
<tr>
26+
<td><b>4</b></td>
27+
<td>Projectron asks Alice's Authorization Agent whether Alice already has an Application Registration for Projectron.</td>
28+
</tr>
29+
<tr>
30+
<td><b>5</b></td>
31+
<td>Alice's Authorization Agent checks the Agent Registry in Alice's Pod for a Projectron Application Registration.</td>
32+
</tr>
33+
<tr>
34+
<td><b>6</b></td>
35+
<td>No Application Registration for Projectron is found.
36+
Projectron now knows that Alice hasn't given it permission to access her data, so it must ask.</td>
37+
</tr>
38+
<tr>
39+
<td><b>7</b></td>
40+
<td>Projectron redirects Alice to her Authorization Agent, supplying its identifier for context.</td>
41+
</tr>
42+
<tr>
43+
<td><b>8</b></td>
44+
<td>Alice's Authorization Agent dereferences the supplied Projectron identifier, retrieving Projectron's
45+
Application profile graph and corresponding Access Need Groups from the WebID Profile Document,
46+
as well as <code>hasAuthorizationCallbackEndpoint</code>.</td>
47+
</tr>
48+
<tr>
49+
<td><b>9</b></td>
50+
<td>Alice's Authorization Agent presents the Access Need Groups from Projectron's Application
51+
profile graph, so that Alice understands what kind of data is being requested, and why.</td>
52+
</tr>
53+
<tr>
54+
<td><b>10</b></td>
55+
<td>Alice's chooses the scope of access that Projectron will receive, to the data to
56+
which it has asked for access via the presented Access Needs.</td>
57+
</tr>
58+
<tr>
59+
<td><b>11-13</b></td>
60+
<td>Alice's Authorization Agent records her decision as an Access Authorization in Alice's
61+
Authorization Registry. An Application Registration is created for Projectron in
62+
Alice's Agent Registry. An Access Grant and corresponding Data Grants are generated
63+
from the Access Authorization and stored in the Projectron Application Registration.
64+
</tr>
65+
<tr>
66+
<td><b>14</b></td>
67+
<td>Alice's Authorization Agent redirects her back to Projectron, now that the appropriate access has been granted.</td>
68+
</tr>
69+
<tr>
70+
<td><b>15</b></td>
71+
<td>Projectron again asks Alice's Authorization Agent for a Projectron Application Registration.</td>
72+
</tr>
73+
<tr>
74+
<td><b>16</b></td>
75+
<td>Alice's Authorization Agent finds the newly created Projectron Application Registration in the Agent Registry in Alice's Pod.</td>
76+
</tr>
77+
<tr>
78+
<td><b>17</b></td>
79+
<td>Alice's Authorization Agent provides the URI of the Application Registration to Projectron.</td>
80+
</tr>
81+
<tr>
82+
<td><b>18</b></td>
83+
<td>Projectron learns what access it received through the Access Grant in Alice's Projectron Application Registration.</td>
84+
</tr>
85+
<tr>
86+
<td><b>19</b></td>
87+
<td>Projectron may now function as intended, within the scope of authorization it was given by Alice.</td>
88+
</tr>
89+
</tbody>
90+
</table>
91+
</figure>
92+
93+
<img class="sequence-diagram" src="diagrams/application-requests-access-flow.seq.mmd.svg">

‎proposals/primer/application.bs‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -106,16 +106,24 @@ Details in <a href="https://solid.github.io/data-interoperability-panel/specific
106106

107107
## User Consent ## {#user-consent}
108108

109-
In case where application haven't been registered yet it needs to initiate flow with Authorization Agent.
109+
In cases where an application hasn't been registered yet, it needs to initiate the flow with the Authorization Agent.
110110

111-
Issue: Add details as soon as defined for Authorization Agent
111+
After successful flow, the application will be able to discover its registration.
112112

113-
After successful flow aplication will be able to discover its registration.
113+
<pre class=include>path: app-authorization-flow.bs</pre>
114+
115+
## Resource Indication ## {#resource-indication}
116+
117+
When the application has already been registered, and the user wants to
118+
initiate a sharing-specific [[#data-instance]], an authorization flow with resource
119+
indication is available.
120+
121+
<pre class=include>path: resource-indication-flow.bs</pre>
114122

115123
# Application Registration # {#application-registration}
116124

117125
Application Registration can be considered an entry point to all the data
118-
that user authorized it to access. Next step in discovery of that data
126+
that the user authorized it to access. The next step in the discovery of that data
119127
is the Access Grant linked via <code>interop:hasAccessGrant</code> predicate.
120128

121129
<figure>
@@ -149,7 +157,7 @@ via <code>interop:hasDataGrant</code> predicate.
149157

150158
# Data Registration # {#data-registration}
151159

152-
<img class="flowchart-diagram" src="diagrams/pro.alice.example.flow.mmd.png" />
160+
<img class="flowchart-diagram" src="diagrams/pro.alice.example.flow.mmd.png">
153161

154162
<figure>
155163
<pre class=include-code>

‎proposals/primer/authorization-agent.bs‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ The Registry Set can be discovered from a social agent's WebID Profile using `in
5252
While WebID Profile is readable to the public, Registry Set should only be readable by its owner
5353
and their Authorization Agent.
5454

55-
<img class="flowchart-diagram" src="diagrams/registry-set.flow.mmd.png" />
55+
<img class="flowchart-diagram" src="diagrams/registry-set.flow.mmd.png">
5656

5757
<figure>
5858
<pre class=include-code>
@@ -86,7 +86,7 @@ In a Data Registry, there can be at most one Data Registration for any given sha
8686
Data Registration is a container, which contains Data Instances. Each of those Data Instances conforms to one specific
8787
shape tree assigned to the Data Registration.
8888

89-
<img class="flowchart-diagram" src="diagrams/pro.alice.example.flow.mmd.png" />
89+
<img class="flowchart-diagram" src="diagrams/pro.alice.example.flow.mmd.png">
9090

9191
<figure>
9292
<pre class=include-code>
@@ -110,8 +110,6 @@ An Authorization Agent is not responsible for modifying data instances. Sometime
110110
during [[#gathering-authorizations]] if the user wants to select specific data instances.
111111

112112

113-
Issue(186):
114-
115113
# Authorization Registry # {#authorization-registry}
116114

117115
Authorization Registry is a container, which contains Access Authorizations.
@@ -200,7 +198,7 @@ from another Social Agent and performing [[#agent-registration-discovery]]
200198
In the case of Social Agent Registration for ACME, created in Alice's Agent Registry. The reciprocal registration
201199
will be the Social Agent Reigstration for Alice, created in ACME's Agent Registry.
202200

203-
<img class="flowchart-diagram" src="diagrams/reciprocal-registration.flow.mmd.png" />
201+
<img class="flowchart-diagram" src="diagrams/reciprocal-registration.flow.mmd.png">
204202

205203
## Application Registration
206204

@@ -255,9 +253,9 @@ another's social agent Authorization Agent. The response will include a link to
255253

256254
## Access Grant ## {#access-grant}
257255

258-
An Access Grant grups together all the Data Grants provided for specific agent.
256+
An Access Grant groups together all the Data Grants provided for a specific agent.
259257

260-
An Access Grant is immutable, it never gets updated, instead it can be only replaced with a newer Access Grant.
258+
An Access Grant is immutable — it never gets updated; it can only be replaced, by a newer Access Grant.
261259

262260
<pre class=include>path: data-grant.bs</pre>
263261

@@ -292,11 +290,17 @@ It should also assist the user in composing new Access Authorization, taking int
292290
* Data Registries with Data Registrations and Data Instances
293291
* [[#access-grant]] with [[#data-grant]] others issued to them (available via all the [[#reciprocal-registration]])
294292

295-
<img src="images/authorization-screen.svg" width="100%" />
293+
<img src="images/authorization-screen.svg" width="100%">
294+
295+
<pre class=include>path: app-authorization-flow.bs</pre>
296+
297+
# Sharing resources indicated by the application # {#resource-indication}
296298

297-
Issue(186):
299+
When the application has already been registered, and the user wants to
300+
initiate a sharing-specific [[#data-instance]], an authorization flow with resource
301+
indication is available.
298302

299-
Issue(138):
303+
<pre class=include>path: resource-indication-flow.bs</pre>
300304

301305
# Generating Access Grant from Access Authorization # {#generating-grants-from-authorizations}
302306

‎proposals/primer/diagrams/application-requests-access-flow.seq.mmd‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
sequenceDiagram
2+
participant Projectron's ID Document
3+
participant Projectron
4+
participant Authorization Agent
5+
participant Alice's Pod
6+
participant Alice's WebID Document
7+
Note over Projectron: 1. 👩 Alice decides to use Projectron
8+
Note over Projectron: 2. 👩 Alice authenticates with her WebID
9+
Note over Alice's WebID Document,Projectron: 3. Projectron discovers Alice's Authorization Agent in her WebID Document
10+
Projectron->>Authorization Agent: 4. Check for Application Registration
11+
Note over Authorization Agent, Alice's Pod: 5. Searches for Application Registration
12+
Authorization Agent->>Projectron: 6. No Application Registration Found
13+
Projectron-->>Authorization Agent: 7. Redirects Alice to her Authorization Agent's Redirect Endpoint
14+
Note over Projectron's ID Document, Authorization Agent: 8. Discovers Access Needs and Authorization Callback Endpoint
15+
Note over Authorization Agent: 9. 👩 Alice revievs Projectron Access Needs
16+
Note over Authorization Agent: 10. 👩 Alice chooses scope of access for Projectron
17+
Note over Authorization Agent, Alice's Pod: 11. Record Access Authorization
18+
Note over Authorization Agent, Alice's Pod: 12. Create Application Registration
19+
Note over Authorization Agent, Alice's Pod: 13. Provide Access Grant
20+
Authorization Agent-->>Projectron: 14. Redirect Alice back to Projectron
21+
Projectron->>Authorization Agent: 15. Check for Application Registration
22+
Note over Authorization Agent, Alice's Pod: 16. Serches for Application Registration
23+
Authorization Agent->>Projectron: 17. Provide Application Registration
24+
Note over Projectron, Alice's Pod: 18. Fetch Access Grant and Data Grants
25+
Note over Projectron: 19. 🟢 Now can access all the data Alice authized it to access

‎proposals/primer/diagrams/resource-indication.seq.mmd‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
sequenceDiagram
2+
participant Projectron's ID Document
3+
participant Projectron
4+
participant Authorization Agent
5+
participant Alice's Pod
6+
Note over Projectron: 1. 👩 Alice is authenticated Projectron
7+
Note over Projectron: 2. 👩 Alice has authorized Projectron
8+
Note over Projectron, Alice's Pod: 3. Projectron has read its Access Grant and displayed projects
9+
Note over Projectron: 4. 👩 Alice initiates sharing of a specific project
10+
Projectron-->>Authorization Agent: 5. Redirect to Authorization Agent (indicating resource)
11+
Note over Authorization Agent, Alice's Pod: 6. Fetch indicated project
12+
Note over Authorization Agent, Alice's Pod: 7. Check who already has access to that project
13+
Note over Authorization Agent, Alice's Pod: 8. Fetch list of all social agents
14+
Note over Authorization Agent: 9. 👩 Alice chooses social agents and modes of access for each
15+
Note over Authorization Agent, Alice's Pod: 10. Record new authorizations for selected agents
16+
Note over Authorization Agent, Alice's Pod: 11. Regenerate access grants for selected agents
17+
Note over Projectron's ID Document, Authorization Agent: 11. Discovers Projectron's Authorization Callback Endpoint
18+
Authorization Agent-->>Projectron: 13. Redirect Alice back to Projectron
19+
Note over Projectron: 14. 👩 Alice continues using Projectron

‎proposals/primer/resource-indication-flow.bs‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<figure>
2+
<table class="data tree" align="left">
3+
<col>
4+
<col>
5+
<thead>
6+
<tr>
7+
<th>Step</th>
8+
<th>Description</th>
9+
</tr>
10+
</thead>
11+
<tbody>
12+
<tr>
13+
<td><b>1</b></td>
14+
<td>Alice's is authenticated with Projectron.</td>
15+
</tr>
16+
<tr>
17+
<td><b>2</b></td>
18+
<td>Alice has already authorized Projectron.</td>
19+
</tr>
20+
<tr>
21+
<td><b>3</b></td>
22+
<td>Projectron has read its Access Grant and displayed projects.</td>
23+
</tr>
24+
<tr>
25+
<td><b>4</b></td>
26+
<td>Alice initiates sharing of a specific project.</td>
27+
</tr>
28+
<tr>
29+
<td><b>5</b></td>
30+
<td>Projectron redirects Alice to her Authorization Agent, indicating the selected project.</td>
31+
</tr>
32+
<tr>
33+
<td><b>6-8</b></td>
34+
<td>Alice's Authorization Agent fetches the indicated project and checks who already has access to it.
35+
It also fetches list of all registered social agents to present it to Alice.</td>
36+
</tr>
37+
<tr>
38+
<td><b>9</b></td>
39+
<td>Alice chooses all the social agents with which she wants to share the selected project,
40+
as well as modes of access for all selected agents. If the shape tree has references (e.g., tasks) she can
41+
also select modes of access for each inherited shape tree.</td>
42+
</tr>
43+
<tr>
44+
<td><b>10-11</b></td>
45+
<td>Alice's Authorization Agent records new access authorizations for all the selected agents
46+
and regenerates access grants provided in their agent registrations.</td>
47+
</tr>
48+
<tr>
49+
<td><b>12</b></td>
50+
<td>Alice's Authorization Agent dereferences the supplied Projectron WebID, retrieving Projection's
51+
Application profile graph from the WebID Profile Document,
52+
to discover the <code>hasAuthorizationCallbackEndpoint</code>.</td>
53+
</tr>
54+
<tr>
55+
<td><b>13</b></td>
56+
<td>Alice's Authorization Agent redirects her back to Projectron, now that the project has been shared.</td>
57+
</tr>
58+
<tr>
59+
<td><b>14</b></td>
60+
<td>Alice continues using Projectron.</td>
61+
</tr>
62+
</tbody>
63+
</table>
64+
</figure>
65+
66+
<img class="sequence-diagram" src="diagrams/resource-indication.seq.mmd.svg">

‎proposals/specification/application.bs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,12 @@ use any resource or subject names.
6262
<td>[=Access Need Group=] representing types of data the
6363
[=Application=] needs to operate</td>
6464
</tr>
65+
<tr>
66+
<td>hasAuthorizationCallbackEndpoint</td>
67+
<td>IRI</td>
68+
<td>URI used to redirect back from [=Authorization Agent=]
69+
to the application, after completing authorization</td>
70+
</tr>
6571
</tbody>
6672
</table>
6773

0 commit comments

Comments
 (0)