Skip to content

Commit 568c3c4

Browse files
elf-pavlikelf-pavlik
committed
[spec] update authorization flows
1 parent dad2c26 commit 568c3c4

8 files changed

Lines changed: 240 additions & 117 deletions

File tree

‎proposals/primer/authorization-flows.bs‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
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 provides her [=WebID=] to Projectron</td>
20+
</tr>
21+
<tr>
22+
<td><b>3</b></td>
23+
<td>Projectron dereferences her [=WebID=] and retrieves her IdP and [=Authorization Agent=] from her [=Identity Profile Document=]</td>
24+
</tr>
25+
<tr>
26+
<td><b>4</b></td>
27+
<td>Projectron [[#agent-registration-discovery|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>Projectron receives a <code>401 Not Authorized</code> because Alice / Projectron needs to authenticate first</td>
32+
</tr>
33+
<tr>
34+
<td><b>6</b></td>
35+
<td>Projectron initiates a [[SOLID-OIDC]] flow with Alice's Identity Provider and receives a DPOP-bound Access Token and Proof</td>
36+
</tr>
37+
<tr>
38+
<td><b>7</b></td>
39+
<td>Now authenticated, Projectron [[#agent-registration-discovery|asks]] Alice's [=Authorization Agent=] again for a Projectron [=Application Registration=]</td>
40+
</tr>
41+
<tr>
42+
<td><b>8</b></td>
43+
<td>Alice's [=Authorization Agent=] checks the [=Agent Registry=] in Alice's Pod for a Projectron [=Application Registration=]</td>
44+
</tr>
45+
<tr>
46+
<td><b>9</b></td>
47+
<td>No [=Application Registration=] for Projectron is found.
48+
Projectron now knows that Alice hasn't given it permission to access her data, so it must ask.</td>
49+
</tr>
50+
<tr>
51+
<td><b>10</b></td>
52+
<td>Projectron redirects Alice to her [=Authorization Agent=], supplying its [=identity=] for context</td>
53+
</tr>
54+
<tr>
55+
<td><b>11</b></td>
56+
<td>Alice's [=Authorization Agent=] dereferences the supplied Projectron [=identity=], retrieving Projection's
57+
[=Application=] profile graph and corresponding [=Access Need Groups=] from the [=Identity Profile Document=],
58+
as well as <code>hasAuthorizationCallbackEndpoint</code></td>
59+
</tr>
60+
<tr>
61+
<td><b>12</b></td>
62+
<td>Alice's [=Authorization Agent=] presents the [=Access Need Groups=] from Projectron's [=Application=]
63+
profile graph, so that Alice understands what kind of data is being requested, and why.</td>
64+
</tr>
65+
<tr>
66+
<td><b>13</b></td>
67+
<td>Alice's chooses the [[#access-scopes|scope of access]] that Projectron will receive to the data it has
68+
asked for access to via the presented [=Access Needs=].</td>
69+
</tr>
70+
<tr>
71+
<td><b>14-16</b></td>
72+
<td>Alice's [=Authorization Agent=] records her decision as an [=Access Authorization=] in Alice's
73+
[=Authorization Registry=]. An [=Application Registration=] is created for Projectron in
74+
Alice's [=Agent Registry=]. An [=Access Grant=] and corresponding [=Data Grants=] are generated
75+
from the [=Access Authorization=] and stored in the Projectron [=Application Registration=].
76+
</tr>
77+
<tr>
78+
<td><b>17</b></td>
79+
<td>Alice's [=Authorization Agent=] redirects her back to Projectron now that the appropriate access has been granted</td>
80+
</tr>
81+
<tr>
82+
<td><b>18</b></td>
83+
<td>Projectron [[#agent-registration-discovery|asks]] Alice's [=Authorization Agent=] again for a Projectron [=Application Registration=]</td>
84+
</tr>
85+
<tr>
86+
<td><b>19</b></td>
87+
<td>Alice's [=Authorization Agent=] finds the newly created Projectron [=Application Registration=] in the [=Agent Registry=] in Alice's Pod</td>
88+
</tr>
89+
<tr>
90+
<td><b>20</b></td>
91+
<td>Alice's [=Authorization Agent=] [[#agent-registration-discovery|provides]] the URI of the [=Application Registration=] to Projectron</td>
92+
</tr>
93+
<tr>
94+
<td><b>21</b></td>
95+
<td>Projectron learns what access it received through the [=Access Grant=] in Alice's Projectron [=Application Registration=]</td>
96+
</tr>
97+
<tr>
98+
<td><b>22</b></td>
99+
<td>Projectron may now function as intended, within the scope of authorization it was given by Alice.</td>
100+
</tr>
101+
</tbody>
102+
</table>
103+
</figure>
104+
105+
<img class="sequence-diagram" src="diagrams/application-requests-access-flow.seq.mmd.svg" />
106+
107+
Issue(138):

‎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

‎proposals/specification/data-authorization.bs‎

Lines changed: 87 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -64,114 +64,6 @@ Slight variations concerning where [=Access Needs=] are sourced from, and
6464
how notification of access is provided, are the only differences from
6565
one flow to another.
6666

67-
<figure>
68-
<table class="data tree" align="left">
69-
<col>
70-
<col>
71-
<thead>
72-
<tr>
73-
<th>Step</th>
74-
<th>Description</th>
75-
</tr>
76-
</thead>
77-
<tbody>
78-
<tr>
79-
<td><b>1</b></td>
80-
<td>Alice's finds an [=Application=] called Projectron that she'd like
81-
to use to manage her Projects and Tasks.</td>
82-
</tr>
83-
<tr>
84-
<td><b>2</b></td>
85-
<td>Alice provides her [=WebID=] to Projectron</td>
86-
</tr>
87-
<tr>
88-
<td><b>3</b></td>
89-
<td>Projectron dereferences her [=WebID=] and retrieves her IdP and [=Authorization Agent=] from her [=Identity Profile Document=]</td>
90-
</tr>
91-
<tr>
92-
<td><b>4</b></td>
93-
<td>Projectron [[#agent-registration-discovery|asks]] Alice's [=Authorization Agent=] if Alice already has an [=Application Registration=] for Projectron</td>
94-
</tr>
95-
<tr>
96-
<td><b>5</b></td>
97-
<td>Projectron receives a `401 Not Authorized`, because Alice / Projectron needs to authenticate first</td>
98-
</tr>
99-
<tr>
100-
<td><b>6</b></td>
101-
<td>Projectron initiates a [[SOLID-OIDC]] flow with Alice's Identity Provider and receives a DPOP-bound Access Token and Proof</td>
102-
</tr>
103-
<tr>
104-
<td><b>7</b></td>
105-
<td>Now authenticated, Projectron [[#agent-registration-discovery|asks]] Alice's [=Authorization Agent=] again for a Projectron [=Application Registration=]</td>
106-
</tr>
107-
<tr>
108-
<td><b>8</b></td>
109-
<td>Alice's [=Authorization Agent=] checks the [=Agent Registry=] in Alice's Pod for a Projectron [=Application Registration=]</td>
110-
</tr>
111-
<tr>
112-
<td><b>9</b></td>
113-
<td>No [=Application Registration=] for Projectron is found.
114-
Projectron now knows that Alice hasn't given it permission to access her data, so it must ask.</td>
115-
</tr>
116-
<tr>
117-
<td><b>10</b></td>
118-
<td>Projectron redirects Alice to her [=Authorization Agent=], supplying its [=identity=] for context</td>
119-
</tr>
120-
<tr>
121-
<td><b>11</b></td>
122-
<td>Alice's [=Authorization Agent=] dereferences the supplied Projectron [=identity=], retrieving Projection's
123-
[=Application=] profile graph and corresponding [=Access Need Groups=] from the [=Identity Profile Document=],
124-
as well as <code>redirect_uri</code></td>
125-
</tr>
126-
<tr>
127-
<td><b>12</b></td>
128-
<td>Alice's [=Authorization Agent=] presents the [=Access Need Groups=] from Projectron's [=Application=]
129-
profile graph, so that Alice understands what kind of data is being requested, and why.</td>
130-
</tr>
131-
<tr>
132-
<td><b>13</b></td>
133-
<td>Alice's chooses the [[#access-scopes|scope of access]] that Projectron will receive to the data it has
134-
asked for access to via the presented [=Access Needs=].</td>
135-
</tr>
136-
<tr>
137-
<td><b>14-16</b></td>
138-
<td>Alice's [=Authorization Agent=] records her decision as an [=Access Authorization=] in Alice's
139-
[=Authorization Registry=]. An [=Application Registration=] is created for Projectron in
140-
Alice's [=Agent Registry=]. An [=Access Grant=] and corresponding [=Data Grants=] are generated
141-
from the [=Access Authorization=] and stored in the Projectron [=Application Registration=].
142-
</tr>
143-
<tr>
144-
<td><b>17</b></td>
145-
<td>Alice's [=Authorization Agent=] redirects her back to Projectron now that the appropriate access has been granted</td>
146-
</tr>
147-
<tr>
148-
<td><b>18</b></td>
149-
<td>Projectron [[#agent-registration-discovery|asks]] Alice's [=Authorization Agent=] again for a Projectron [=Application Registration=]</td>
150-
</tr>
151-
<tr>
152-
<td><b>19</b></td>
153-
<td>Alice's [=Authorization Agent=] finds the newly created Projectron [=Application Registration=] in the [=Agent Registry=] in Alice's Pod</td>
154-
</tr>
155-
<tr>
156-
<td><b>20</b></td>
157-
<td>Alice's [=Authorization Agent=] [[#agent-registration-discovery|provides]] the URI of the [=Application Registration=] to Projectron</td>
158-
</tr>
159-
<tr>
160-
<td><b>21</b></td>
161-
<td>Projectron learns what access it received through the [=Access Grant=] in Alice's Projectron [=Application Registration=]</td>
162-
</tr>
163-
<tr>
164-
<td><b>22</b></td>
165-
<td>Projectron may now function as intended, within the scope of authorization it was given by Alice.</td>
166-
</tr>
167-
</tbody>
168-
</table>
169-
</figure>
170-
171-
<img class="sequence-diagram" src="diagrams/application-requests-access-flow.seq.mmd.svg" />
172-
173-
Issue(138):
174-
17567
## Authorization Agent ## {#authorization-agent}
17668

17769
An <dfn>Authorization Agent</dfn> is an [=Application=] designated by
@@ -183,11 +75,92 @@ are processed by the [=Authorization Agent=].
18375
Similarly, any decisions by the [=Social Agent=] to share data with another [=Agent=]
18476
are processed by the [=Authorization Agent=].
18577

78+
<table class="classinfo data" align="left" id="classAuthorizationAgent">
79+
<colgroup></colgroup>
80+
<colgroup></colgroup>
81+
<colgroup></colgroup>
82+
<thead>
83+
<tr>
84+
<th>Property</th>
85+
<th>Range</th>
86+
<th>Description</th>
87+
</tr>
88+
</thead>
89+
<tbody>
90+
<tr>
91+
<td>hasAuthorizationRedirectEndpoint</td>
92+
<td>IRI</td>
93+
<td>URI used to redirect to the Authorization Agent
94+
from an [=Application=] for authorization</td>
95+
</tr>
96+
</tbody>
97+
</table>
98+
99+
<figure>
100+
<figcaption>[=Authorization Agent=] at https://auth.alice.example/ -
101+
<a href="snippets/alice.jarvis.example/alice.jarvis.example.ttl">View</a>
102+
</figcaption>
103+
<pre class=include-code>
104+
path: snippets/alice.jarvis.example/alice.jarvis.example.ttl
105+
highlight: turtle
106+
show: 6-20
107+
</pre>
108+
</figure>
109+
110+
### Authorization Redirect Endpoint ### {#authorization-redirect-endpoint}
111+
112+
An [=Application=] capable of redirecting, should redirect the user to
113+
Authorization Redirect Endpoint advertised by the user's [=Authorization Agent=].
114+
115+
The following query parameters are defined:
116+
117+
118+
<table class="classinfo data" align="left">
119+
<colgroup></colgroup>
120+
<colgroup></colgroup>
121+
<colgroup></colgroup>
122+
<thead>
123+
<tr>
124+
<th>Parameter</th>
125+
<th>Required</th>
126+
<th>Description</th>
127+
</tr>
128+
</thead>
129+
<tbody>
130+
<tr>
131+
<td>client_id</td>
132+
<td>Yes</td>
133+
<td>URI used to identify the [=Application=]
134+
requesting the authorization</td>
135+
</tr>
136+
<tr>
137+
<td>resource</td>
138+
<td>No</td>
139+
<td>URI used to indicate the [=Data Instance=].
140+
Used for [[#resource-indication]]</td>
141+
</tr>
142+
</tbody>
143+
</table>
144+
145+
<figure>
146+
<figcaption>Example redirect</figcaption>
147+
<pre highlight=http>
148+
GET /redirect?client_id=https%3A%2F%2Fprojectron.example%2F%23id HTTP/1.1
149+
Host: alice.jarvis.example
150+
</pre>
151+
</figure>
152+
153+
154+
### Resource Indication ### {#resource-indication}
155+
156+
When the <code>resource</code> query parameter is used, the Authorization Agent will use it
157+
as an indication that access to a specific data instance is intended to be shared.
158+
186159
### Authorization Agent Discovery ### {#authorization-agent-discovery}
187160

188161
The [=Authorization Agent=] for a given [=Social Agent=] can be discovered
189162
by de-referencing the [=identity=] of that [=Social Agent=], and extracting
190-
the object value of the `interop:hasAuthorizationAgent` statement from the
163+
the object value of the <code>interop:hasAuthorizationAgent</code> statement from the
191164
[=Social Agent=] graph in the returned [=identity profile document=].
192165

193166
The extracted [=Authorization Agent=] IRI <em class="rfc2119">MUST</em> be
@@ -202,8 +175,8 @@ a unique sub-domain (see example below) or path.
202175
<pre class=include-code>
203176
path: snippets/alice.example/alice.example.ttl
204177
highlight: turtle
205-
show: 9-20
206-
line-highlight: 14
178+
show: 8-20
179+
line-highlight: 13
207180
</pre>
208181
</figure>
209182

@@ -218,12 +191,12 @@ a corresponding [=Agent Registration=] for them can query the
218191
[=Authorization Agent=] for that target [=Social Agent=].
219192

220193
To discover a corresponding [=Agent Regsitration=] the requesting [=Agent=]
221-
may perform an `HTTP HEAD` or `HTTP GET` request on the IRI of the
194+
may perform an HTTP <code>HEAD</code> or HTTP <code>GET</code> request on the IRI of the
222195
[=Authorization Agent=] for the target [=Social Agent=].
223196

224-
The response will include an `HTTP Link` header relating the [=Agent Registration=]
197+
The response will include an <code>HTTP Link</code> header relating the [=Agent Registration=]
225198
to the [=Agent=] making the request via the
226-
`http://www.w3.org/ns/solid/interop#registeredAgent` link relation.
199+
<code>http://www.w3.org/ns/solid/interop#registeredAgent</code> link relation.
227200

228201
<figure>
229202
<figcaption>HEAD request to and response from Authorization Agent</figcaption>

‎proposals/specification/index.bs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Editor: Justin Bingham
1212
Editor: Eric Prud'hommeaux
1313
Editor: elf Pavlik
1414
Markup Shorthands: markdown yes
15-
Boilerplate: style-darkmode off, conformance no
15+
Boilerplate: conformance no
16+
Dark Mode: off
1617
Abstract:
1718
This specification details how Social Agents and Applications
1819
can safely share and interoperate over data in Solid Pods.

‎proposals/specification/interop.shex‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,8 @@ PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
6565
interop:applicationDescription xsd:string ;
6666
interop:applicationAuthor IRI // shex:reference <#AgentShape> ;
6767
interop:applicationThumbnail IRI? ;
68-
interop:hasAccessNeedGroup IRI* // shex:reference <#AccessNeedGroupShape>
68+
interop:hasAccessNeedGroup IRI* // shex:reference <#AccessNeedGroupShape> ;
69+
interop:hasAuthorizationCallbackEndpoint IRI? ;
6970
}
7071

7172
<#AccessNeedGroupShape> {

0 commit comments

Comments
 (0)