forked from KantaraInitiative/wg-uma
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-uma-resource-reg.xml
862 lines (695 loc) · 36.1 KB
/
draft-uma-resource-reg.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
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
<?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-resource-reg" 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 Resource
Registration</title>
<author fullname="Christian Scholz" initials="C" role="editor"
surname="Scholz">
<organization>COM.lounge GmbH</organization>
<address>
<email>[email protected]</email>
<uri>http://comlounge.net</uri>
</address>
</author>
<author fullname="Maciej Machulak" initials="M" surname="Machulak">
<organization>Newcastle University</organization>
<address>
<email>[email protected]</email>
<uri>http://ncl.ac.uk/</uri>
</address>
</author>
<author fullname="Eve Maler" initials="E" surname="Maler">
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Paul Bryan" initials="P" surname="Bryan">
<organization>ForgeRock</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date day="20" month="February" year="2011" />
<abstract>
<t>This specification defines the resource registration protocol for
User-Managed Access (UMA). This protocol provides a method for a host to
register, update, check, and delete resource-related information at an
authorization manager (AM) so that the user's resources can be put under
scoped protection.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>This specification defines the resource registration protocol for
User-Managed Access (<xref target="draft-uma-core">UMA</xref>). This
protocol provides a method for a host to register, update, check, and
delete resource-related information at an authorization manager (AM) so
that the user's resources can be put under scoped protection.</t>
<t>(Intellectual property notice: The User-Managed Access Work Group
operates under <eref
target="http://kantarainitiative.org/confluence/display/GI/Option+Patent+and+Copyright+%28RAND%29">Kantara
IPR Policy - Option Patent & Copyright: Reciprocal Royalty Free with
Opt-Out to Reasonable And Non discriminatory (RAND)</eref> and the
publication of this document is governed by the policies outlined in
this option.)</t>
<t>The host needs to register information about resources to be
protected so that the AM can apply authorization constraints to them
according to the user's wishes.</t>
<t>The host determines (unilaterally or as instructed by the user) the
universe of resources belonging to this user that are to be protected by
the AM, and assigns a resource identifier to sets of these resources.
Such a set might include a status update API endpoint (applying to the
user's entire update stream), or an individual status update, or a photo
album, or all photos with a particular user-assigned tag, or even the
set of "all resources managed by this user at this host".</t>
<t>The host also determines the universe of actions that is possible for
requesting parties to perform on each resource set. Such actions might
involve "viewing", "adding", "printing", or whatever other actions the
application supports for that resource set. Typically each action covers
a broad list of methods in the host's published API.</t>
<t>Once the host has registered resource sets and their descriptive
information with the AM, the AM (under the authorizing user's
instructions) is able to map particular authorization constraints to a
particular set of resources and a particular set of actions and to take
part in the process of limiting (scoping) access to resource sets.</t>
<t>Note that the host is free to offer the option to protect any subset
of the user's resources using different AMs or other means entirely, or
to protect some resources and not others; any such partitioning is
outside the scope of this specification.</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 <xref target="draft-uma-core">UMA</xref> for additional term
definitions.</t>
<t><list hangIndent="6" style="hanging">
<t hangText="registration endpoint"><vspace />A protected endpoint
at the AM capable of receiving resource information from a
host.</t>
<t hangText="resource set description"><vspace />A JSON-formatted
data structure that represents a set of one or more resources to
be AM-protected and maps possible actions to them.</t>
<t hangText="action description">A JSON-formatted data structure
that represents a possible action on a resource set.</t>
</list></t>
</section>
<section title="Requirements Analysis">
<t>This specification, in combination with the UMA core protocol
specification and the scoped-access specification, has been informed
by the following resource registration requirements:<list
style="symbols">
<t>The authorizing user needs to be presented with a user
interface at the AM that clearly indicates what resources and
actions are available when they're setting and mapping
authorization constraints. (User interface considerations are out
of scope of UMA protocol specifications, but this requirement has
protocol dependencies.)</t>
<t>The AM therefore needs to acquire from the host some
description of resources and actions to be protected, which
includes enough information to display to the authorizing user.
(Solved by this specification.)</t>
<t>The requester and requesting party, prior to receiving an
access token, should not be exposed to resource information that
compromises the authorizing user's privacy. For example, a
protected set of resources might usefully but embarrassingly be
described as "racy photos from beach vacation". It is assumed that
the host already has access to such a description and that the
nature of the host-AM trust relationship forged by the authorizing
user may qualify the AM to see this description as well. (Solved
by this specification.)</t>
<t>The AM needs to be told the relevant resource set, in
host-described terms, that corresponds to the resource the
requester is seeking access to so that it can assess the
requesting party's request for an access token against the correct
authorization constraints. (Solved by the scoped-access
specification.)</t>
<t>Therefore, when the requester attempts access at the host and
fails, the host needs to convey enough information to the AM
(whether through the requester directly or by other means) for the
latter to do this job. For privacy reasons, if the host asks the
requester to convey information directly, privacy considerations
come into play. (Solved by the scoped-access specification.)</t>
<t>"The host needs to be able to validate that a requester's
access attempt in step 3, accompanied by an access token, matches
a resource set and action associated with that access token.
(Solved by the scoped-access specification.)</t>
<t>The AM therefore needs to make an association between requester
access tokens and resource sets/actions. (Solved by the core
protocol specification. Currently it defines a run-time method for
the host to ask the AM to confirm this match. An alternative
solution that meets the requirement would be for the access token
to securely contain this information.)</t>
<t>The requester needs to know what actions are possible on the
resource it is trying to access. (This requirement is considered
out of scope for UMA; it is anticipated that host API
documentation will pick up the slack.)</t>
</list></t>
</section>
</section>
<section title="Example">
<t>The following example illustrates the intent and usage of the
resource registration protocol.</t>
<t>This example contains some steps that are exclusively in the realm of
user experience rather than web protocol, to achieve realistic
illustration; these steps are labeled "User experience only". Some other
steps are exclusively internal to the operation of the entity being
discussed; these are labeled "Internal only".</t>
<t>An authorizing user, Alice Adams, has just uploaded a photo of her
new puppy to a host, Photoz.example.com, and wants to ensure that this
specific photo is not publicly accessible.</t>
<t>Alice has already introduced this host to her AM,
CopMonkey.example.com, and thus Photoz has already obtained an OAuth
client ID and an UMA host access token from CopMonkey. However, Alice
has not previously instructed Photoz to use CopMonkey to protect any
other photos of hers.</t>
<t>Alice has previously visited CopMonkey to map a default "do not share
with anyone" authorization constraint to any resource sets registered by
Photoz, until such time as she maps some other less-draconian
constraints to those resources. (User experience only. This may have
been done at the time Alice introduced the host to the AM, and/or it
could have been a global or host-specific preference setting. A
different constraint or no constraint at all might be associated with
newly protected resources.) Other kinds of constraints she may
eventually map to particular photos or albums might be "Share only with
[email protected]" or "Share only with people in my 'family'
group".</t>
<t>Photoz itself has a publicly documented API that offers two dozen
different methods that apply to single photos, such as "addTags" and
"getSizes", but rolls them up into two photo-related actions: "viewing"
(consisting of varous read-only operations) and "all" (consisting of
various reading, editing, and printing operations). It defines two
Web-accessible JSON-encoded documents called action descriptions that
represent these actions, which it is able to reuse for all of its users
(not just Alice). The "name" parameter values are intended to be seen by
Alice when she maps authorization constraints to specific resource sets
and actions while visiting CopMonkey, such that Alice would see the
strings "View Photo and Related Info" and "All Actions", likely
accompanied by the referenced icons, in the CopMonkey interface. (Other
users of Photoz might similarly see the same labels at CopMonkey or
whatever other AM they use.)</t>
<figure>
<artwork><![CDATA[{
"action":
{
"_id": "view"
"name": "View Photo and Related Info",
"icon_uri": "http://www.example.com/icons/reading-glasses"
}
}]]></artwork>
</figure>
<figure>
<artwork><![CDATA[{
"action":
{
"_id": "all"
"name": "All Actions",
"icon_uri": "http://www.example.com/icons/galaxy"
}
}]]></artwork>
</figure>
<t>While visiting Photoz, Alice selects a link or button that instructs
the site to "Protect" or "Share" this single photo (user experience
only; Photoz could have made this a default or preference setting).</t>
<t>As a result, Photoz defines for itself a resource set that represents
this photo (internal only; Photoz is the only application that knows how
to map a particular photo to a particular resource set). Photoz also
prepares the following resource set description, which is specific to
Alice and her photo. The "name" parameter value is intended to be seen
by Alice in mapping authorization constraints to specific resource sets
and actions when she visits CopMonkey, such that Alice would see the
string "Steve the puppy!", likely accompanied by the referenced icon, in
the CopMonkey interface. The possible actions on this resource set are
indicated with URI references to the action descriptions, as defined
just above.</t>
<figure>
<artwork><![CDATA[{
"resource_set":
{
"_id": "112210f47de98100"
"name": "Steve the puppy!",
"icon_uri": "http://www.example.com/icons/flower",
"actions":
["http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"]
}
}]]></artwork>
</figure>
<t>Photoz uses the "create resource set description" method of
CopMonkey's standard UMA-based resource registration API, presenting its
Alice-specific host access token there, to register and assign an
identifier to the resource set description. The resource set identifier
path component of the URL matches the "_id" parameter value in the
description.</t>
<figure>
<artwork><![CDATA[PUT /host/photoz.example.com/resource/112210f47de98100
Content-Type: application/json
...
{
"resource_set":
{
"_id": "112210f47de98100"
"name": "Steve the puppy!",
"icon_uri": "http://www.example.com/icons/flower",
"actions":
["http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"]
}
}]]></artwork>
</figure>
<t>Once this description has been successfully registered, Photoz is
responsible for responding to requesters' attempts to access this photo
in the manner described in <xref target="draft-uma-core">UMA</xref>,
achieving protection of the resource by "outsourcing" this task to
CopMonkey.</t>
<t>At the time Alice indicates she would like this photo protected,
Photoz can choose to redirect Alice to CopMonkey for further
authorization constraint mapping, access auditing, and other AM-related
tasks (user experience only).</t>
<t>Over time, as Alice uploads other photos and creates and organizes
photo albums, and as Photoz makes new action functionality available,
Photoz can use additional methods of the resource registration API to
ensure that CopMonkey's understanding of Alice's protected resources
matches its own.</t>
</section>
<section title="Prerequisites">
<t>In order for a host to be able to register resource information with
an AM it needs to fulfill the following prerequisites:<list
style="symbols">
<t>The host has obtained a host access token from the AM as
explained in UMA core protocol step 1.</t>
<t>The host has obtained the URI of the registration API endpoint as
part of the AM's metadata as described in UMA protocol step 1.</t>
</list></t>
</section>
<section anchor="action-desc" title="Action Description">
<t>The host defines an action that is available for use with resources
it manages in an action description encoded in <xref format="default"
target="RFC4627">JSON</xref> form and made publicly accessible through a
URI reference (it MAY include a fragment identifier). The actions
available for use at any one host MUST have unique URI references so
that the host's action descriptions are distinguishable by URI
reference. Action descriptions MAY reside anywhere; the host is not
required to self-host action descriptions and may wish to point to
standardized action descriptions residing elsewhere.</t>
<t>An action description is an object with the name "action" and with
the following parameters:<list style="hanging">
<t hangText="_id">REQUIRED. A string that uniquely identifies the
action across all actions available at this host.</t>
<t hangText="name">REQUIRED. A human-readable string describing the
action. The AM SHOULD use the name in its user interface to assist
the user in mapping authorization constraints to resource sets with
this permissible action.</t>
<t hangText="icon_uri">OPTIONAL. A URI for a graphic icon
representing the action. If this is provided, the AM SHOULD use the
referenced icon in its user interface to assist the user in mapping
authorization constraints to resource sets with this permissible
action.</t>
</list></t>
<figure>
<preamble>For example, this description characterizes an action that
involves reading or viewing resources (vs. creating them or editing
them in some fashion):</preamble>
<artwork><![CDATA[{
"action":
{
"_id": "view"
"name": "Read-only",
"icon_uri": "http://www.example.com/icons/reading-glasses"
}
}]]></artwork>
</figure>
<t>Action descriptions MAY contain extension parameters that are not
defined in this specification. The names of extension parameters MUST
begin with "x-" or "X-".</t>
</section>
<section anchor="resource-set-desc" title="Resource Set Description">
<t>The host defines a resource set that needs UMA protection in a
resource set description encoded in <xref format="default"
target="RFC4627">JSON</xref> form. The host registers the description
and manages its lifecycle at the AM through the resource registration
API.</t>
<t>A resource set description is an object with the name "resource_set"
and with the following parameters:<list style="hanging">
<t hangText="_id">REQUIRED. A string that uniquely identifies the
resource set. The resource set identifier has meaning only to the
host, except insofar as the AM is able to map this resource set
description to a particular user by virtue of the particular host
access token used to access the resource registration API. The host
MAY use any identifier scheme to represent resource sets, for
example, making its identifiers unique across all users of this host
or allowing for the sharing of resource set identifiers among users.
However, for privacy reasons, it is RECOMMENDED that the host assign
an identifier that is obscured with respect to any human-readable
resource set label used at this host. Further, this identifier MUST
match the resource set identifier path component of the URI used to
manage this description in the resource registration API; see <xref
target="reg-api"></xref> for more information. (Typically this
matching is achieved through automatically populating the parameter
value on initial registration of the description.)</t>
<t hangText="name">REQUIRED. A human-readable string describing a
set of one or more resources. The AM SHOULD use the name in its user
interface to assist the user in mapping authorization constraints to
this resource set.</t>
<t hangText="icon_uri">OPTIONAL. A URI for a graphic icon
representing the resource set. If provided, the AM SHOULD use the
referenced icon in its user interface to assist the user in mapping
authorization constraints to this resource set.</t>
<t hangText="actions">REQUIRED. An array referencing one or more
identifiers of actions that are permissible 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>
<figure>
<preamble>For example, this description characterizes a resource set
(a photo album) that can potentially be only viewed, or alternatively
to which full access can be granted; the URIs point to action
descriptions, as dictated in <xref
target="action-desc"></xref>:</preamble>
<artwork><![CDATA[{
"resource_set":
{
"name": "Photo album",
"icon_uri": "http://www.example.com/icons/flower",
"actions":
["http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"]
}
}]]></artwork>
</figure>
<t>Resource set descriptions descriptions MAY contain extension
parameters that are not defined in this specification. The names of
extension parameters MUST begin with "x-" or "X-".</t>
<t>When a host creates or updates a resource set description (see <xref
target="reg-api"></xref>), the AM MUST attempt to retrieve the
referenced action descriptions. It MAY cache such descriptions as long
as indicated in the HTTP header for the action description resource
unless the resource set description is subsequently updated within the
validity period. At the beginning of an authorizing user's login session
at the AM, the AM MUST attempt to re-retrieve action descriptions
applying to that user whose cached versions have expired.</t>
</section>
<section anchor="reg-api" title="Resource Registration API">
<t>The host uses a RESTful API at the AM's host_registration_uri to
create, read, update, and delete resource set descriptions, along with
listing groups of such descriptions. 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 resource set descriptions are managed at URIs with this
structure: "{reguri}/host/{hostid}/resource_set/{resourcesetid}"</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 (see <xref target="draft-uma-core">UMA</xref>).</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 HTTP 403 Forbidden
error (see example below) and fail to act on the request.</t>
<t hangText="{resourcesetid}">An identifier for a resource set
description. The identifier MUST match the "_id" parameter value in
the description itself.</t>
</list></t>
<t>Without a specific resource identifier path component, the URI
applies to the set of resource set descriptions already registered.</t>
<t>Following is a summary of the five registration API operations the AM
is REQUIRED to support. Each is defined in its own section below. All
other methods are unsupported.<list style="symbols">
<t>Create resource set description: PUT
/host/{hostid}/resource_set/{resourcesetid}</t>
<t>Read resource set description: GET
/host/{hostid}/resource_set/{resourcesetid}</t>
<t>Update resource set description: PUT
/host/{hostid}/resource_set/{resourcesetid}</t>
<t>Delete resource set description: DELETE
/host/{hostid}/resource_set/{resourcesetid}</t>
<t>List resource set descriptions: GET
/host/{hostid}/resource_set/</t>
</list></t>
<t>The AM MUST respond to host requests using unsupported HTTP methods
with an HTTP 403 Forbidden error and MUST fail to act on the
request.</t>
<figure>
<preamble>HTTP response (unsupported method or host ID not matching
the presented host access token):</preamble>
<artwork><![CDATA[HTTP/1.1 403 Forbidden
...
(Body provides user-readable explanation of the error.)]]></artwork>
</figure>
<section anchor="create-resource-set"
title="Create Resource Set Description">
<t>Adds a new resource set description using the PUT method. The host
assigns a unique identifier to the action. The host is free to use its
own methods of identifying and describing resource sets; the AM MUST
treat them as opaque for the purpose of authorizing access, other than
associating them with the authorizing user represented by the host
access token used to access the API. On successfully registering a
resource set, the host MUST use UMA mechanisms to limit access to any
resources corresponding to this resource set, as defined in <xref
target="draft-uma-core">UMA</xref>.</t>
<figure>
<preamble>HTTP request:</preamble>
<artwork><![CDATA[PUT /host/{hostid}/user/{userid}/resource/{resourceid}
Content-Type: application/json
...
(Body contains JSON representation of resource set description to be created.)]]></artwork>
</figure>
<figure>
<preamble>HTTP response (success):</preamble>
<artwork><![CDATA[HTTP/1.1 201 Created
Content-Type: application/json
Location: (URL of the created resource, same as that which was PUT.)
...]]></artwork>
</figure>
</section>
<section anchor="read-resource-set"
title="Read Resource Set Description">
<t>Reads a previously registered resource set description using the
GET method.</t>
<figure>
<preamble>HTTP request:</preamble>
<artwork><![CDATA[GET /host/{hostid}/user/{userid}/resource/{resourceid} 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 resource artifact)
...
(Body contains JSON representation of the resource set 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>
</section>
<section anchor="update-resource-set"
title="Update Resource Set Description">
<t>Updates a previously registered resource set description using the
PUT method.</t>
<figure>
<preamble>HTTP request:</preamble>
<artwork><![CDATA[PUT /host/{hostid}/user/{userid}/resource/{resourceid}
Content-Type: application/json
If-Match: (entity tag of the resource if operation is to be idempotent)
...
(Body contains JSON representation of resource set description to be updated.)]]></artwork>
</figure>
<figure>
<preamble>HTTP response (success):</preamble>
<artwork><![CDATA[HTTP/1.1 204 No Content
...]]></artwork>
</figure>
<figure>
<preamble>HTTP response (entity tag does not match):</preamble>
<artwork><![CDATA[HTTP/1.1 412 Precondition failed
...]]></artwork>
</figure>
</section>
<section anchor="delete-resource-set"
title="Delete Resource Set Description">
<t>Deletes a previously registered resource set description using the
DELETE method.</t>
<figure>
<preamble>HTTP request:</preamble>
<artwork><![CDATA[DELETE /host/{hostid}/user/{userid}/resource/{resourceid}
If-Match: (entity tag of the resource if operation to be idempotent)
...]]></artwork>
</figure>
<figure>
<preamble>HTTP response (success):</preamble>
<artwork><![CDATA[HTTP/1.1 204 No content
...]]></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 (entity tag does not match):</preamble>
<artwork><![CDATA[HTTP/1.1 412 Precondition failed
...]]></artwork>
</figure>
</section>
<section anchor="list-resource-sets"
title="List Resource Set Descriptions">
<t>Lists all previously registered resource set identifiers for this
user using the GET method. The list is in the form of a JSON array of
{resourcesetid} values.</t>
<figure>
<preamble>HTTP request:</preamble>
<artwork><![CDATA[GET /host/{hostid}/resource_set/
...]]></artwork>
</figure>
<figure>
<preamble>HTTP response:</preamble>
<artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json
...
(Body contains JSON array of {resourcesetid} values.)]]></artwork>
</figure>
</section>
</section>
<section title="Security Considerations">
<t>This specification relies mainly on OAuth security mechanisms for
protecting the host registration endpoint at the AM so that only a
properly authorized host can access it on behalf of the intended user.
For example, the host needs to use a valid host access token issued
through a user authorization process at the endpoint, and the
interaction should take place over TLS. It is expected that the host
will protect its client secret (if it was issued one) and will protect
its host access token, particularly if used in "bearer token"
fashion.</t>
<t>In addition, this specification dictates a binding between the host
access token and the host-specific registration area on the AM to
prevent a host from interacting with a registration area not its
own.</t>
</section>
<section title="Privacy Considerations">
<t>The AM comes to be in possession of information (such as names and
icons) that may reveal information about the user, which the AM's trust
relationship with the host is assumed to accommodate. However, the
requester is a less-trusted party (in fact, entirely untrustworthy until
it acquires a requester access token in UMA protocol step 2). This
specification recommends obscuring resource set identifiers in order to
avoid leaking personally identifiable information to requesters through
the "scope" mechanism.</t>
</section>
<section title="TODOs">
<t><list style="symbols">
<t>In <xref target="action-desc"></xref>, should the action
description have an "_id" parameter or a normal "id" parameter so
that the URI path component that must match the ID can be
human-readable ("view") vs. machine-assigned gobbledygook?</t>
<t>Should the {hostid} component instead be a pseudonym assigned by
the AM (during or after OAuth client ID provisioning) to allow for
hosts' client IDs to be a string like "anonymous"? Check this
throughout the scoped-access spec progress.</t>
<t>Give example of what a list of resource set IDs looks like in
<xref target="list-resource-sets"></xref>.</t>
<t>Consider the question of i18n of resource set and action "name"
strings in addition to the extension-parameter mechanism.</t>
</list></t>
</section>
<section title="Acknowledgments">
<t><list style="symbols">
<t>[TBS]</t>
</list></t>
</section>
<section title="Document History">
<t>Changes in 20 Feb 2011 version:<list style="symbols">
<t>Cleaned up nits and minor wording revisions noted in comments
sent to the mailing list on 13 Feb 2011 (<eref
target="http://groups.google.com/group/kantara-initiative-uma-wg/browse_frm/thread/f498afdb5bfe7f60"></eref>).</t>
<t>Revised the discussion of resource set identifier uniqueness and
redistributed some information about this identifier between
Sections 5 and 6.</t>
<t>Switched the positions of the Example and Prerequisites
sections.</t>
<t>Revised TODOs accordingly.</t>
</list></t>
<t>Changes in 6 Jan 2011 version:<list style="symbols">
<t>Removed action-related API methods.</t>
<t>Revised Example section to take into account the new "passive"
way of declaring actions.</t>
<t>Added "_id" parameters.</t>
<t>Changed "resource" to "resource set", "{resourcesetid}, or
"resource_set" as appropriate throughout.</t>
<t>Removed user-specific path component of the registration URI.</t>
<t>Allowed "X-" in addition to "x-" for extension parameters.</t>
<t>Broke out the two descriptions into their own sections.</t>
<t>A bit of editorial cleanup all over.</t>
</list></t>
<t>Changes in 30 Dec 2010 version:<list style="symbols">
<t>Unsupported HTTP methods in registration API return 403</t>
<t>Folded error section in to API section and changed from UMA-level
error to 403</t>
<t>Changed name of "resource" parameter to "resource_set"</t>
<t>Added TODO issue about referencing standard sets of actions and
reconsidering in-band IDs, and cleaned up the TODO list
generally</t>
<t>Fleshed out citations and requirements analysis</t>
<t>Added huge worked-example section at the beginning (which
contains issues not yet captured in the TODO section)</t>
</list></t>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="RFC4627">
<front>
<title>The application/json Media Type for JavaScript Object
Notation (JSON)</title>
<author fullname="Douglas Crockford" initials="D"
surname="Crockford"></author>
<date month="July" year="2006" />
</front>
<format target="http://tools.ietf.org/html/rfc4627" type="TXT" />
</reference>
<reference anchor="RFC2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement
Levels</title>
<author fullname="S. Bradner" surname="Bradner"></author>
<date month="March" year="1997" />
</front>
<format target="http://www.ietf.org/rfc/rfc2119.txt" type="TXT" />
</reference>
<reference anchor="draft-uma-core">
<front>
<title>UMA 1.0 Core Protocol</title>
<author fullname="Christian Scholz" initials="C" surname="Scholz"></author>
<date month="December" year="2010" />
</front>
<format target="http://mrtopf.clprojects.net/uma/draft-uma-core.html"
type="HTML" />
</reference>
</references>
</back>
</rfc>