-
Notifications
You must be signed in to change notification settings - Fork 27
/
draft-uma-resource-reg.html
748 lines (693 loc) · 48.3 KB
/
draft-uma-resource-reg.html
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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><title>UMA Resource Registration</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="UMA Resource Registration">
<meta name="generator" content="xml2rfc v1.35 (http://xml.resource.org/)">
<style type='text/css'><!--
body {
font-family: verdana, charcoal, helvetica, arial, sans-serif;
font-size: small; color: #000; background-color: #FFF;
margin: 2em;
}
h1, h2, h3, h4, h5, h6 {
font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
font-weight: bold; font-style: normal;
}
h1 { color: #900; background-color: transparent; text-align: right; }
h3 { color: #333; background-color: transparent; }
td.RFCbug {
font-size: x-small; text-decoration: none;
width: 30px; height: 30px; padding-top: 2px;
text-align: justify; vertical-align: middle;
background-color: #000;
}
td.RFCbug span.RFC {
font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
font-weight: bold; color: #666;
}
td.RFCbug span.hotText {
font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
font-weight: normal; text-align: center; color: #FFF;
}
table.TOCbug { width: 30px; height: 15px; }
td.TOCbug {
text-align: center; width: 30px; height: 15px;
color: #FFF; background-color: #900;
}
td.TOCbug a {
font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
font-weight: bold; font-size: x-small; text-decoration: none;
color: #FFF; background-color: transparent;
}
td.header {
font-family: arial, helvetica, sans-serif; font-size: x-small;
vertical-align: top; width: 33%;
color: #FFF; background-color: #666;
}
td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
td.author-text { font-size: x-small; }
/* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
a.info {
/* This is the key. */
position: relative;
z-index: 24;
text-decoration: none;
}
a.info:hover {
z-index: 25;
color: #FFF; background-color: #900;
}
a.info span { display: none; }
a.info:hover span.info {
/* The span will display just on :hover state. */
display: block;
position: absolute;
font-size: smaller;
top: 2em; left: -5em; width: 15em;
padding: 2px; border: 1px solid #333;
color: #900; background-color: #EEE;
text-align: left;
}
a { font-weight: bold; }
a:link { color: #900; background-color: transparent; }
a:visited { color: #633; background-color: transparent; }
a:active { color: #633; background-color: transparent; }
p { margin-left: 2em; margin-right: 2em; }
p.copyright { font-size: x-small; }
p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
ol.text { margin-left: 2em; margin-right: 2em; }
ul.text { margin-left: 2em; margin-right: 2em; }
li { margin-left: 3em; }
/* RFC-2629 <spanx>s and <artwork>s. */
em { font-style: italic; }
strong { font-weight: bold; }
dfn { font-weight: bold; font-style: normal; }
cite { font-weight: normal; font-style: normal; }
tt { color: #036; }
tt, pre, pre dfn, pre em, pre cite, pre span {
font-family: "Courier New", Courier, monospace; font-size: small;
}
pre {
text-align: left; padding: 4px;
color: #000; background-color: #CCC;
}
pre dfn { color: #900; }
pre em { color: #66F; background-color: #FFC; font-weight: normal; }
pre .key { color: #33C; font-weight: bold; }
pre .id { color: #900; }
pre .str { color: #000; background-color: #CFF; }
pre .val { color: #066; }
pre .rep { color: #909; }
pre .oth { color: #000; background-color: #FCF; }
pre .err { background-color: #FCC; }
/* RFC-2629 <texttable>s. */
table.all, table.full, table.headers, table.none {
font-size: small; text-align: center; border-width: 2px;
vertical-align: top; border-collapse: collapse;
}
table.all, table.full { border-style: solid; border-color: black; }
table.headers, table.none { border-style: none; }
th {
font-weight: bold; border-color: black;
border-width: 2px 2px 3px 2px;
}
table.all th, table.full th { border-style: solid; }
table.headers th { border-style: none none solid none; }
table.none th { border-style: none; }
table.all td {
border-style: solid; border-color: #333;
border-width: 1px 2px;
}
table.full td, table.headers td, table.none td { border-style: none; }
hr { height: 1px; }
hr.insert {
width: 80%; border-style: none; border-width: 0;
color: #CCC; background-color: #CCC;
}
--></style>
</head>
<body>
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
<tr><td class="header">Network Working Group</td><td class="header">C. Scholz, Ed.</td></tr>
<tr><td class="header">Internet-Draft</td><td class="header">COM.lounge GmbH</td></tr>
<tr><td class="header">Intended status: Standards Track</td><td class="header">M. Machulak</td></tr>
<tr><td class="header">Expires: August 24, 2011</td><td class="header">Newcastle University</td></tr>
<tr><td class="header"> </td><td class="header">E. Maler</td></tr>
<tr><td class="header"> </td><td class="header"> </td></tr>
<tr><td class="header"> </td><td class="header">P. Bryan</td></tr>
<tr><td class="header"> </td><td class="header">ForgeRock</td></tr>
<tr><td class="header"> </td><td class="header">February 20, 2011</td></tr>
</table></td></tr></table>
<h1><br />UMA Resource Registration<br />draft-uma-resource-reg</h1>
<h3>Abstract</h3>
<p>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.
</p>
<h3>Status of this Memo</h3>
<p>
This Internet-Draft is submitted in full
conformance with the provisions of BCP 78 and BCP 79.</p>
<p>
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current
Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p>
<p>
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any time.
It is inappropriate to use Internet-Drafts as reference material or to cite
them other than as “work in progress.”</p>
<p>
This Internet-Draft will expire on August 24, 2011.</p>
<h3>Copyright Notice</h3>
<p>
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.</p>
<p>
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.</p>
<a name="toc"></a><br /><hr />
<h3>Table of Contents</h3>
<p class="toc">
<a href="#anchor1">1.</a>
Introduction<br />
<a href="#anchor2">1.1.</a>
Notational Conventions<br />
<a href="#anchor3">1.2.</a>
Terminology<br />
<a href="#anchor4">1.3.</a>
Requirements Analysis<br />
<a href="#anchor5">2.</a>
Example<br />
<a href="#anchor6">3.</a>
Prerequisites<br />
<a href="#action-desc">4.</a>
Action Description<br />
<a href="#resource-set-desc">5.</a>
Resource Set Description<br />
<a href="#reg-api">6.</a>
Resource Registration API<br />
<a href="#create-resource-set">6.1.</a>
Create Resource Set Description<br />
<a href="#read-resource-set">6.2.</a>
Read Resource Set Description<br />
<a href="#update-resource-set">6.3.</a>
Update Resource Set Description<br />
<a href="#delete-resource-set">6.4.</a>
Delete Resource Set Description<br />
<a href="#list-resource-sets">6.5.</a>
List Resource Set Descriptions<br />
<a href="#anchor7">7.</a>
Security Considerations<br />
<a href="#anchor8">8.</a>
Privacy Considerations<br />
<a href="#anchor9">9.</a>
TODOs<br />
<a href="#anchor10">10.</a>
Acknowledgments<br />
<a href="#anchor11">11.</a>
Document History<br />
<a href="#rfc.references1">12.</a>
Normative References<br />
<a href="#rfc.authors">§</a>
Authors' Addresses<br />
</p>
<br clear="all" />
<a name="anchor1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1"></a><h3>1.
Introduction</h3>
<p>This specification defines the resource registration protocol for User-Managed Access (<a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core]). 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.
</p>
<p>(Intellectual property notice: The User-Managed Access Work Group operates under <a href='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)</a> and the publication of this document is governed by the policies outlined in this option.)
</p>
<p>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.
</p>
<p>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".
</p>
<p>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.
</p>
<p>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.
</p>
<p>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.
</p>
<a name="anchor2"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.1"></a><h3>1.1.
Notational Conventions</h3>
<p>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 <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</span><span>)</span></a>.
</p>
<p>Unless otherwise noted, all the protocol parameter names and values are case sensitive.
</p>
<a name="anchor3"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.2"></a><h3>1.2.
Terminology</h3>
<p>See <a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core] for additional term definitions.
</p>
<p></p>
<blockquote class="text"><dl>
<dt>registration endpoint</dt>
<dd>A protected endpoint at the AM capable of receiving resource information from a host.
</dd>
<dt>resource set description</dt>
<dd>A JSON-formatted data structure that represents a set of one or more resources to be AM-protected and maps possible actions to them.
</dd>
<dt>action description</dt>
<dd>A JSON-formatted data structure that represents a possible action on a resource set.
</dd>
</dl></blockquote>
<a name="anchor4"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.3"></a><h3>1.3.
Requirements Analysis</h3>
<p>This specification, in combination with the UMA core protocol specification and the scoped-access specification, has been informed by the following resource registration requirements:</p>
<ul class="text">
<li>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.)
</li>
<li>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.)
</li>
<li>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.)
</li>
<li>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.)
</li>
<li>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.)
</li>
<li>"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.)
</li>
<li>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.)
</li>
<li>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.)
</li>
</ul>
<a name="anchor5"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2"></a><h3>2.
Example</h3>
<p>The following example illustrates the intent and usage of the resource registration protocol.
</p>
<p>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".
</p>
<p>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.
</p>
<p>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.
</p>
<p>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 husband@email.example.net" or "Share only with people in my 'family' group".
</p>
<p>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.)
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
{
"_id": "view"
"name": "View Photo and Related Info",
"icon_uri": "http://www.example.com/icons/reading-glasses"
}
}</pre></div><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
{
"_id": "all"
"name": "All Actions",
"icon_uri": "http://www.example.com/icons/galaxy"
}
}</pre></div>
<p>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).
</p>
<p>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.
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"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"]
}
}</pre></div>
<p>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.
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>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"]
}
}</pre></div>
<p>Once this description has been successfully registered, Photoz is responsible for responding to requesters' attempts to access this photo in the manner described in <a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core], achieving protection of the resource by "outsourcing" this task to CopMonkey.
</p>
<p>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).
</p>
<p>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.
</p>
<a name="anchor6"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3"></a><h3>3.
Prerequisites</h3>
<p>In order for a host to be able to register resource information with an AM it needs to fulfill the following prerequisites:</p>
<ul class="text">
<li>The host has obtained a host access token from the AM as explained in UMA core protocol step 1.
</li>
<li>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.
</li>
</ul>
<a name="action-desc"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.4"></a><h3>4.
Action Description</h3>
<p>The host defines an action that is available for use with resources it manages in an action description encoded in <a class='info' href='#RFC4627'>JSON<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627] 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.
</p>
<p>An action description is an object with the name "action" and with the following parameters:</p>
<blockquote class="text"><dl>
<dt>_id</dt>
<dd>REQUIRED. A string that uniquely identifies the action across all actions available at this host.
</dd>
<dt>name</dt>
<dd>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.
</dd>
<dt>icon_uri</dt>
<dd>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.
</dd>
</dl></blockquote>
<p>For example, this description characterizes an action that involves reading or viewing resources (vs. creating them or editing them in some fashion):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
{
"_id": "view"
"name": "Read-only",
"icon_uri": "http://www.example.com/icons/reading-glasses"
}
}</pre></div>
<p>Action descriptions MAY contain extension parameters that are not defined in this specification. The names of extension parameters MUST begin with "x-" or "X-".
</p>
<a name="resource-set-desc"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5"></a><h3>5.
Resource Set Description</h3>
<p>The host defines a resource set that needs UMA protection in a resource set description encoded in <a class='info' href='#RFC4627'>JSON<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627] form. The host registers the description and manages its lifecycle at the AM through the resource registration API.
</p>
<p>A resource set description is an object with the name "resource_set" and with the following parameters:</p>
<blockquote class="text"><dl>
<dt>_id</dt>
<dd>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 <a class='info' href='#reg-api'>Section 6<span> (</span><span class='info'>Resource Registration API</span><span>)</span></a> for more information. (Typically this matching is achieved through automatically populating the parameter value on initial registration of the description.)
</dd>
<dt>name</dt>
<dd>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.
</dd>
<dt>icon_uri</dt>
<dd>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.
</dd>
<dt>actions</dt>
<dd>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.
</dd>
</dl></blockquote>
<p>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 <a class='info' href='#action-desc'>Section 4<span> (</span><span class='info'>Action Description</span><span>)</span></a>:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"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"]
}
}</pre></div>
<p>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-".
</p>
<p>When a host creates or updates a resource set description (see <a class='info' href='#reg-api'>Section 6<span> (</span><span class='info'>Resource Registration API</span><span>)</span></a>), 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.
</p>
<a name="reg-api"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6"></a><h3>6.
Resource Registration API</h3>
<p>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.
</p>
<p>Individual resource set descriptions are managed at URIs with this structure: "{reguri}/host/{hostid}/resource_set/{resourcesetid}"
</p>
<p>The components of these URIs are defined as follows:</p>
<blockquote class="text"><dl>
<dt>{reguri}</dt>
<dd>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 <a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core]).
</dd>
<dt>{hostid}</dt>
<dd>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.
</dd>
<dt>{resourcesetid}</dt>
<dd>An identifier for a resource set description. The identifier MUST match the "_id" parameter value in the description itself.
</dd>
</dl></blockquote>
<p>Without a specific resource identifier path component, the URI applies to the set of resource set descriptions already registered.
</p>
<p>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.</p>
<ul class="text">
<li>Create resource set description: PUT /host/{hostid}/resource_set/{resourcesetid}
</li>
<li>Read resource set description: GET /host/{hostid}/resource_set/{resourcesetid}
</li>
<li>Update resource set description: PUT /host/{hostid}/resource_set/{resourcesetid}
</li>
<li>Delete resource set description: DELETE /host/{hostid}/resource_set/{resourcesetid}
</li>
<li>List resource set descriptions: GET /host/{hostid}/resource_set/
</li>
</ul>
<p>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.
</p>
<p>HTTP response (unsupported method or host ID not matching the presented host access token):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 403 Forbidden
...
(Body provides user-readable explanation of the error.)</pre></div>
<a name="create-resource-set"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1"></a><h3>6.1.
Create Resource Set Description</h3>
<p>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 <a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core].
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/{hostid}/user/{userid}/resource/{resourceid}
Content-Type: application/json
...
(Body contains JSON representation of resource set description to be created.)</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 201 Created
Content-Type: application/json
Location: (URL of the created resource, same as that which was PUT.)
...</pre></div>
<a name="read-resource-set"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.2"></a><h3>6.2.
Read Resource Set Description</h3>
<p>Reads a previously registered resource set description using the GET method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/{hostid}/user/{userid}/resource/{resourceid} HTTP/1.1
...</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>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.)</pre></div>
<p>HTTP response (not found):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 404 Not Found
...
(Body provides user-readable explanation of the error.)</pre></div>
<a name="update-resource-set"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.3"></a><h3>6.3.
Update Resource Set Description</h3>
<p>Updates a previously registered resource set description using the PUT method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>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.)</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 204 No Content
...</pre></div>
<p>HTTP response (entity tag does not match):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 412 Precondition failed
...</pre></div>
<a name="delete-resource-set"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.4"></a><h3>6.4.
Delete Resource Set Description</h3>
<p>Deletes a previously registered resource set description using the DELETE method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>DELETE /host/{hostid}/user/{userid}/resource/{resourceid}
If-Match: (entity tag of the resource if operation to be idempotent)
...</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 204 No content
...</pre></div>
<p>HTTP response (not found):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 404 Not Found
...
(Body provides user-readable explanation of the error.)</pre></div>
<p>HTTP response (entity tag does not match):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 412 Precondition failed
...</pre></div>
<a name="list-resource-sets"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.5"></a><h3>6.5.
List Resource Set Descriptions</h3>
<p>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.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/{hostid}/resource_set/
...</pre></div>
<p>HTTP response:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 200 OK
Content-Type: application/json
...
(Body contains JSON array of {resourcesetid} values.)</pre></div>
<a name="anchor7"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.7"></a><h3>7.
Security Considerations</h3>
<p>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.
</p>
<p>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.
</p>
<a name="anchor8"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.8"></a><h3>8.
Privacy Considerations</h3>
<p>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.
</p>
<a name="anchor9"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.9"></a><h3>9.
TODOs</h3>
<p></p>
<ul class="text">
<li>In <a class='info' href='#action-desc'>Section 4<span> (</span><span class='info'>Action Description</span><span>)</span></a>, 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?
</li>
<li>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.
</li>
<li>Give example of what a list of resource set IDs looks like in <a class='info' href='#list-resource-sets'>Section 6.5<span> (</span><span class='info'>List Resource Set Descriptions</span><span>)</span></a>.
</li>
<li>Consider the question of i18n of resource set and action "name" strings in addition to the extension-parameter mechanism.
</li>
</ul>
<a name="anchor10"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.10"></a><h3>10.
Acknowledgments</h3>
<p></p>
<ul class="text">
<li>[TBS]
</li>
</ul>
<a name="anchor11"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.11"></a><h3>11.
Document History</h3>
<p>Changes in 20 Feb 2011 version:</p>
<ul class="text">
<li>Cleaned up nits and minor wording revisions noted in comments sent to the mailing list on 13 Feb 2011 (<a href='http://groups.google.com/group/kantara-initiative-uma-wg/browse_frm/thread/f498afdb5bfe7f60'>http://groups.google.com/group/kantara-initiative-uma-wg/browse_frm/thread/f498afdb5bfe7f60</a>).
</li>
<li>Revised the discussion of resource set identifier uniqueness and redistributed some information about this identifier between Sections 5 and 6.
</li>
<li>Switched the positions of the Example and Prerequisites sections.
</li>
<li>Revised TODOs accordingly.
</li>
</ul>
<p>Changes in 6 Jan 2011 version:</p>
<ul class="text">
<li>Removed action-related API methods.
</li>
<li>Revised Example section to take into account the new "passive" way of declaring actions.
</li>
<li>Added "_id" parameters.
</li>
<li>Changed "resource" to "resource set", "{resourcesetid}, or "resource_set" as appropriate throughout.
</li>
<li>Removed user-specific path component of the registration URI.
</li>
<li>Allowed "X-" in addition to "x-" for extension parameters.
</li>
<li>Broke out the two descriptions into their own sections.
</li>
<li>A bit of editorial cleanup all over.
</li>
</ul>
<p>Changes in 30 Dec 2010 version:</p>
<ul class="text">
<li>Unsupported HTTP methods in registration API return 403
</li>
<li>Folded error section in to API section and changed from UMA-level error to 403
</li>
<li>Changed name of "resource" parameter to "resource_set"
</li>
<li>Added TODO issue about referencing standard sets of actions and reconsidering in-band IDs, and cleaned up the TODO list generally
</li>
<li>Fleshed out citations and requirements analysis
</li>
<li>Added huge worked-example section at the beginning (which contains issues not yet captured in the TODO section)
</li>
</ul>
<a name="rfc.references1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<h3>12. Normative References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
<td class="author-text">Bradner, “<a href="http://www.ietf.org/rfc/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a>,” March 1997.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC4627">[RFC4627]</a></td>
<td class="author-text">Crockford, D., “<a href="http://tools.ietf.org/html/rfc4627">The application/json Media Type for JavaScript Object Notation (JSON)</a>,” July 2006.</td></tr>
<tr><td class="author-text" valign="top"><a name="draft-uma-core">[draft-uma-core]</a></td>
<td class="author-text">Scholz, C., “<a href="http://mrtopf.clprojects.net/uma/draft-uma-core.html">UMA 1.0 Core Protocol</a>,” December 2010.</td></tr>
</table>
<a name="rfc.authors"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<h3>Authors' Addresses</h3>
<table width="99%" border="0" cellpadding="0" cellspacing="0">
<tr><td class="author-text"> </td>
<td class="author-text">Christian Scholz (editor)</td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">COM.lounge GmbH</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:cs@comlounge.net">cs@comlounge.net</a></td></tr>
<tr><td class="author" align="right">URI: </td>
<td class="author-text"><a href="http://comlounge.net">http://comlounge.net</a></td></tr>
<tr cellpadding="3"><td> </td><td> </td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Maciej Machulak</td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Newcastle University</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:m.p.machulak@ncl.ac.uk">m.p.machulak@ncl.ac.uk</a></td></tr>
<tr><td class="author" align="right">URI: </td>
<td class="author-text"><a href="http://ncl.ac.uk/">http://ncl.ac.uk/</a></td></tr>
<tr cellpadding="3"><td> </td><td> </td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Eve Maler</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:eve@xmlgrrl.com">eve@xmlgrrl.com</a></td></tr>
<tr cellpadding="3"><td> </td><td> </td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Paul Bryan</td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">ForgeRock</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:email@pbryan.net">email@pbryan.net</a></td></tr>
</table>
</body></html>