-
Notifications
You must be signed in to change notification settings - Fork 27
/
draft-uma-scoped-access.xml
377 lines (300 loc) · 15.6 KB
/
draft-uma-scoped-access.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN"
"http://xml.resource.org/authoring/rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY UMA PUBLIC "" "http://kantarainitiative.org/confluence/display/uma/Home">
<!ENTITY UMAreqs PUBLIC "" "http://kantarainitiative.org/confluence/display/uma/UMA+Requirements">
]>
<rfc category="std" docName="draft-uma-scoped-access" ipr="trust200902">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc='yes' ?>
<?rfc tocdepth='3' ?>
<?rfc symrefs='yes' ?>
<?rfc sortrefs='yes' ?>
<?rfc compact='yes' ?>
<?rfc subcompact='no' ?>
<?rfc strict='yes' ?>
<front>
<title abbrev="UMA Resource Registration">UMA Scoped Access
Proposal</title>
<author fullname="Eve Maler" initials="E" surname="Maler">
<organization>PayPal</organization>
<address>
<email>eve@xmlgrrl.com</email>
</address>
</author>
<author fullname="Paul Bryan" initials="P" surname="Bryan">
<organization>P. Bryan Consulting</organization>
<address>
<email>email@pbryan.net</email>
</address>
</author>
<date day="21" month="December" year="2010" />
<abstract>
<t>This specification proposes a method for achieving scoped access with
User-Managed Access (UMA). This method assumes that, as currently
specified in the UMA core protocol, a host must outsource the validation
of requester access tokens to the authorization manager (AM) when access
is attempted on a protected resource.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>This specification proposes a method for achieving scoped access with
User-Managed Access (UMA). This method assumes that, as currently
specified in the UMA core protocol, a host must outsource the validation
of requester access tokens to the authorization manager (AM) when access
is attempted on a protected resource.</t>
<t>After a host registers resource set identifiers and the identifiers
of permissible actions on those resource sets, the authorization manager
(AM) is responsible for following the authorizing user's instructions in
mapping authorization constraints to particular combinations of these
identifiers. The triple of a set of constraints, a resource set, and a
list of actions can be considered a "policy", and its latter two-thirds,
the resource set/actions portion, can be considered a "permission",
granted by the AM on the user's behalf when the requesting party meets
the constraints.</t>
<t>In order to enable communication about scopes and permissions in the
process of granting and controlling access, this specification defines a
JSON-formatted data structure that describes a set of one or more
permissions, called a scope description, and defines how to use a unique
scope identifier that refers to this description.</t>
<t>Following is the flow of scope communications:<list style="numbers">
<t>Step 1:<list style="letters">
<t>Host registers resource set descriptions and action
descriptions with AM (described in
[[draft-uma-resource-reg]]).</t>
<t>AM maps authorization constraints to permissions according to
the user's instructions (out of band).</t>
</list></t>
<t>Step 2:<list style="letters">
<t>Requester attempts to access protected resource at host,
allowing host to infer the requester's desired resource set and
action.</t>
<t>Host tells requester the identifier of a resource set that
would suffice for access to the resource, and redirects
requester to AM (defined in this specification for now). It is
assumed that the requester has out-of-band knowledge of possible
actions on the resource to which it had attempted access,
through host API documentation.</t>
<t>Requester asks AM for an access token, specifying the
identifiers of the desired resource set and action(s) (defined
in this specification for now).</t>
<t>AM looks up the authorization constraints associated with
these identifiers and asks for claims as required to satisfy the
constraints.</t>
<t>Assuming the constraints are satisfied, AM issues an access
token and optional refresh token to requester.</t>
<t>AM registers, in the user-specific portion of the host
registration area, a scope description that lists the
permissions corresponding to the issued access token (defined in
this specification for now).</t>
</list></t>
<t>Step 3:<list style="letters">
<t>Requester attempts to access the resource again, this time
presenting its requester access token.</t>
<t>Host conveys token to AM for validation.</t>
<t>AM responds saying if the token is still valid (not expired)
and providing the token's scope identifier (defined in this
specification for now).</t>
<t>Host looks up scope description and confirms that the
attempted access matches the permissions granted for this token
(defined in this specification for now).</t>
</list></t>
</list></t>
<section title="Notational Conventions">
<t>The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
document are to be interpreted as described in <xref
target="RFC2119"></xref>.</t>
<t>Unless otherwise noted, all the protocol parameter names and values
are case sensitive.</t>
</section>
<section title="Terminology">
<t>See the core UMA protocol spec [[draft-uma-core]] and the UMA
resource registration spec [[draft-uma-resource-reg]] for additional
term definitions.</t>
<t><list hangIndent="6" style="hanging">
<t hangText="scope description"><vspace />A JSON-formatted data
structure that represents a set of one or more permissions that
have been granted to a requesting party.</t>
<t hangText="scope identifier">A unique identifier representing a
scope description. (The word "scope" may be used to represent
either this identifier or the corresponding description, depending
on context.)</t>
<t hangText="permission"><vspace />A resource set identifier and a
list of action identifiers, which together represent a range of
access abilities that an authorizing user is willing to grant.</t>
</list></t>
</section>
</section>
<section title="Host tells requester resource set identifier">
<t>TBS (see item 2b in flow list above)</t>
</section>
<section title="Requester supplies desired resource set and action(s) to AM">
<t>TBS (see item 2c in flow list above)</t>
</section>
<section title="AM registers scope description">
<t>(See item 2f in flow list above)</t>
<t>The AM registers scope descriptions as a way to record the
permissions associated with a requester access token in a persistent
fashion. A scope description is in JSON [[cite]] form. It is an object
with the following parameters:</t>
<t>An action description is an object with the name "scope" and the
following parameters:<list style="hanging">
<t hangText="_id">REQUIRED. An identifier that MUST be identical to
the {scopeid} path component of the scope description URI (see
below). Some RESTful database technologies provide special features
for populating this parameter automatically.</t>
<t hangText="permissions">REQUIRED. Contains an array of at least
one object that has "resource_set" and "actions" parameters:<list
style="hanging">
<t hangText="resource_set">REQUIRED. The identifier of a
resource set. The identifier MUST correspond to a resource set
registered by this host for this user at this AM.</t>
<t hangText="actions">REQUIRED. An array referencing one or more
identifiers of actions that are authorized on this resource set.
Each action identifier MUST correspond to an action registered
by this host for this user at this AM.</t>
</list></t>
</list></t>
<figure>
<preamble>For example, this description characterizes a scope whose
single permission involves reading and updating a resource set
representing "all" resources being protected for this user at this
host:</preamble>
<artwork><![CDATA[{
"scope": {
"_id": 1234afbd,
"permissions": [
{
"resource_set": "all",
"actions": [ "read", "update" ]
}, ...
]
}
}]]></artwork>
</figure>
<t>Scope descriptions MAY contain extension parameters that are not
defined in this specification. The names of extension parameters MUST
begin with "x-".</t>
</section>
<section title="AM provides the token's scope identifier">
<t>TBS (see item 3c in flow list above)</t>
</section>
<section title="Host looks up token's scope description">
<t>(See item 3d in flow list above)</t>
<t>The host uses a RESTful API at the AM's host_registration_uri to read
scope descriptions at the time of token validation. The host MUST use
its valid host access token obtained previously in UMA protocol step 1
to gain access to the API.</t>
<t>Individual scope descriptions are managed at URIs with this
structure: "{reguri}/host/{hostid}/user/{userid}/scope/{scopeid}"</t>
<t>The components of these URIs are defined as follows:<list
style="hanging">
<t hangText="{reguri}">The AM's host_registration_uri as advertised
in its metadata. This endpoint, its security requirements, and its
requirements around advertisement in metadata are defined in UMA
protocol step 1 [[uma-draft-core]].</t>
<t hangText="{hostid}">A registration area at the AM that is
specific to this host. The host MUST use the OAuth client identifier
it was assigned by this AM as its host identifier. If the host
identifier does not match the host access token used at the host
registration endpoint, the AM MUST report an error and fail to act
on the request (see Section [[Error Responses]] below).</t>
<t hangText="{userid}">The portion of the host's registration area
at this AM that is specific to this user, assigned during
registration of resource information for this user.</t>
<t hangText="{scopeid}">An identifier for a scope description,
assigned during initial registration of this description.</t>
</list></t>
<t>The only allowed scope lookup API operation is:<list style="symbols">
<t>Read scope description: GET
/host/{hostid}/user/{userid}/scope/{scopeid}</t>
</list></t>
<t>With this operation, a host reads a previously registered scope
description at the AM using the GET method. If any other HTTP method is
attempted, the AM MUST respond with a 403 Forbidden message and fail to
take any other action.</t>
<figure>
<preamble>HTTP request:</preamble>
<artwork><![CDATA[GET /host/{hostid}/user/{userid}/scope/{scopeid} HTTP/1.1
...]]></artwork>
</figure>
<figure>
<preamble>HTTP response (success):</preamble>
<artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json
ETag: (entity tag of the scope artifact)
...
(Body contains JSON representation of scope description.)]]></artwork>
</figure>
<figure>
<preamble>HTTP response (not found):</preamble>
<artwork><![CDATA[HTTP/1.1 404 Not Found
...
(Body provides user-readable explanation of the error.)]]></artwork>
</figure>
<figure>
<preamble>HTTP response to any method other than GET or to a {hostid}
path component that does not match the presented host access token
(forbidden):</preamble>
<artwork><![CDATA[HTTP/1.1 403 Forbidden
...
(Body provides user-readable explanation of the error.)]]></artwork>
</figure>
</section>
<section title="Security Considerations">
<t>TBS</t>
</section>
<section title="Privacy Considerations">
<t>TBS</t>
</section>
<section title="TODOs">
<t><list style="symbols">
<t>ISSUE: How is the {userid} established at the point when an AM
needs to register a scope description? (See item 2f in the flow list
in the introduction, above.)</t>
<t>Should the AM respond to a token validation request by returning
the applicable scope structure rather than by pointing to it through
a scope identifier? Alternatively, is the scope description
mechanism needed at all? If the host were to supply candidate
resource sets and actions when asking for validation, the AM could
perform the lookup and matching operation itself, and return a
simple "YES" or "NO". However, if we chose this option, the host
could not cache the token/scope mapping, and the scope description
mechanism would not be available for other uses (such as eventual
token scope upgrading).</t>
</list></t>
</section>
<section title="Acknowledgments">
<t><list style="symbols">
<t>[TBS]</t>
</list></t>
</section>
<section title="Document History">
<t>[[ to be removed by RFC editor before publication as an RFC ]]</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2617.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hammer-hostmeta-13.xml'?>
<!--
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5785.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2104.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2818.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3023.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3447.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-html401-19991224.xml' ?>
-->
</references>
</back>
</rfc>