Skip to content

Commit 963947d

Browse files
elf-pavlikelf-pavlik
committed
[primer] update both primers with authorization flows
1 parent 568c3c4 commit 963947d

8 files changed

Lines changed: 229 additions & 150 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's 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 with her WebID to Projectron</td>
20+
</tr>
21+
<tr>
22+
<td><b>3</b></td>
23+
<td>Projectron dereferences her WebID and retrieves Authorization Agent from her Identity Profile Document</td>
24+
</tr>
25+
<tr>
26+
<td><b>4</b></td>
27+
<td>Projectron asks Alice's Authorization Agent if 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 identity for context</td>
41+
</tr>
42+
<tr>
43+
<td><b>8</b></td>
44+
<td>Alice's Authorization Agent dereferences the supplied Projectron identity, retrieving Projection's
45+
Application profile graph and corresponding Access Need Groups from the Identity 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 it has
56+
asked for access to 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 asks Alice's Authorization Agent again 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 case where application hasn't been registered yet it needs to initiate flow with Authorization Agent.
110110

111-
Issue: Add details as soon as defined for Authorization Agent
111+
After successful flow 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+
In cases where the application has already been registered, and the user wants to
118+
initiate 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: 13 additions & 9 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,7 +253,7 @@ 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

260258
An Access Grant is immutable, it never gets updated, instead it can be only replaced with a newer Access Grant.
261259

@@ -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+
In cases where the application has already been registered, and the user wants to
300+
initiate 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/authorization-flows.bs‎

Lines changed: 0 additions & 107 deletions
This file was deleted.

‎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 Identity 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 Identity 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

0 commit comments

Comments
 (0)