idnits 2.17.1 draft-hardjono-oauth-resource-reg-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (April 4, 2015) is 3311 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7159 (ref. 'JSON') (Obsoleted by RFC 8259) -- No information found for draft-uma-core - is the name correct? Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Hardjono, Ed. 3 Internet-Draft MIT 4 Intended status: Standards Track E. Maler 5 Expires: October 6, 2015 ForgeRock 6 M. Machulak 7 Cloud Identity 8 D. Catalano 9 Oracle 10 April 4, 2015 12 OAuth 2.0 Resource Set Registration 13 draft-hardjono-oauth-resource-reg-06 15 Abstract 17 This specification defines a resource set registration mechanism 18 between an OAuth 2.0 authorization server and resource server. The 19 resource server registers information about the semantics and 20 discovery properties of its resources with the authorization server. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on October 6, 2015. 39 Copyright Notice 41 Copyright (c) 2015 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.3. Authorization Server Configuration Data . . . . . . . . . 4 60 2. Resource Set Registration . . . . . . . . . . . . . . . . . . 4 61 2.1. Scope Descriptions . . . . . . . . . . . . . . . . . . . 5 62 2.2. Resource Set Descriptions . . . . . . . . . . . . . . . . 5 63 2.3. Resource Set Registration API . . . . . . . . . . . . . . 6 64 2.3.1. Create Resource Set Description . . . . . . . . . . . 8 65 2.3.2. Read Resource Set Description . . . . . . . . . . . . 9 66 2.3.3. Update Resource Set Description . . . . . . . . . . . 9 67 2.3.4. Delete Resource Set Description . . . . . . . . . . . 10 68 2.3.5. List Resource Set Descriptions . . . . . . . . . . . 10 69 3. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 11 70 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 71 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12 72 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 73 7. Example of Registering Resource Sets . . . . . . . . . . . . 12 74 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 75 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 76 9.1. Normative References . . . . . . . . . . . . . . . . . . 17 77 9.2. Informative References . . . . . . . . . . . . . . . . . 17 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 80 1. Introduction 82 There are various circumstances under which an OAuth 2.0 [OAuth2] 83 resource server may need to communicate information about its 84 protected resources to its authorization server: 86 o In some OAuth 2.0 deployments, the resource server and 87 authorization server are operated by the same organization and 88 deployed in the same domain, but many resource servers share a 89 single authorization server (a security token service (STS) 90 component). Thus, even though the trust between these two is 91 typically tightly bound, there is value in defining a singular 92 standardized resource protection communications interface between 93 the authorization server and each of the resource servers. 95 o In some deployments of OpenID Connect [OpenIDConnect], which has a 96 dependency on OAuth 2.0, the OpenID Provider (OP) component is a 97 specialized version of an OAuth authorization server that brokers 98 availability of user attributes by dealing with an ecosystem of 99 attribute providers (APs). These APs effectively function as 100 third-party resource servers. Thus, there is value in defining a 101 mechanism by which all of the third-party APs can communicate with 102 a central OP, as well as ensuring that trust between the 103 authorization server and resource servers is able to be 104 established in a dynamic, loosely coupled fashion. 106 o In some deployments of User-Managed Access [UMA], which has a 107 dependency on OAuth 2.0, an end-user resource owner (the "user" in 108 UMA) may choose their own authorization server as an independent 109 cloud-based service, along with using any number of resource 110 servers that make up their "personal cloud". Thus, there is value 111 in defining a mechanism by which all of the third-party resource 112 servers can outsource resource protection (and potentially 113 discovery) to a central authorization server, as well as ensuring 114 that trust between the authorization server and resource servers 115 is able to be established by the resource owner in a dynamic, 116 loosely coupled fashion. 118 This specification defines an API through which the resource server 119 can register information about resource sets with the authorization 120 server. 122 1.1. Notational Conventions 124 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 125 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 126 document are to be interpreted as described in [RFC2119]. 128 Unless otherwise noted, all protocol properties and values are case 129 sensitive. JSON [JSON] data structures defined by this specification 130 MAY contain extension properties that are not defined in this 131 specification. Any entity receiving or retrieving a JSON data 132 structure SHOULD ignore extension properties it is unable to 133 understand. Extension names that are unprotected from collisions are 134 outside the scope of this specification. 136 1.2. Terminology 138 This specification introduces the following new terms and 139 enhancements of OAuth term definitions. 141 resource set One or more resources that the resource server manages 142 as a set, abstractly. A resource set may be a single API 143 endpoint, a set of API endpoints, a classic web resource such 144 as an HTML page, and so on. Defining this concept enables 145 registering data about it, including, most importantly, scopes 146 but also other data. 148 scope A bounded extent of access that is possible to perform on a 149 resource set. In authorization policy terminology, a scope is 150 one of the potentially many "verbs" that can logically apply to 151 a resource set ("object"). This specification enhances the 152 OAuth concept of a "scope" by defining scopes as applying to 153 particular registered resource sets, rather than leaving the 154 relevant resources (such as API endpoints or URIs) implicit. A 155 resource set can have any number of scopes, which together 156 describe the universe of actions that _can be_ taken on this 157 protected resource set. For example, a resource set 158 representing a status update API might have scopes that include 159 adding an update or reading updates. A resource set 160 representing a photo album might have scopes that include 161 viewing a slideshow or printing the album. The resource server 162 registers resource sets and their scopes when there is not yet 163 any particular client in the picture. 165 resource set registration endpoint The endpoint defined by this 166 specification at which the resource server registers resource 167 sets it wants the authorization server to know about. The 168 operations available at this endpoint constitute a resource set 169 registration API (see Section 2.3). 171 1.3. Authorization Server Configuration Data 173 If the authorization server declares its endpoints and any other 174 configuration data in a machine-readable form, it SHOULD convey its 175 resource set registration endpoint in this fashion as well. 177 2. Resource Set Registration 179 This specification defines a resource set registration API. The 180 endpoint for this API SHOULD also require some form of authentication 181 to access this endpoint, such as Client Authentication as described 182 in [OAuth2] or a separate OAuth access token. The methods of 183 managing and validating these authentication credentials are out of 184 scope of this specification. 186 For any of the resource owner's sets of resources this authorization 187 server needs to be aware of, the resource server MUST register these 188 resource sets at the authorization server's registration endpoint. 190 2.1. Scope Descriptions 192 A scope description is a JSON document with the following properties: 194 name REQUIRED. A human-readable string describing some scope 195 (extent) of access. This name MAY be used by the authorization 196 server in any user interface it presents to the resource owner. 198 icon_uri OPTIONAL. A URI for a graphic icon representing the scope. 199 The referenced icon MAY be used by the authorization server in any 200 user interface it presents to the resource owner. 202 For example, this scope description characterizes a scope that 203 involves reading or viewing resources (vs. creating them or editing 204 them in some fashion): 206 { 207 "name" : "View", 208 "icon_uri" : "http://www.example.com/icons/reading-glasses" 209 } 211 See Section 7 for a long-form example of scope descriptions used in 212 resource set registration. 214 2.2. Resource Set Descriptions 216 The resource server defines a resource set that the authorization 217 server needs to be aware of by registering a resource set description 218 at the authorization server. This registration process results in a 219 unique identifier for the resource set that the resource server can 220 later use for managing its description. 222 The resource server is free to use its own methods of describing 223 resource sets. A resource set description is a JSON document with 224 the following properties: 226 name REQUIRED. A human-readable string describing a set of one or 227 more resources. This name MAY be used by the authorization server 228 in its resource owner user interface for the resource owner. 230 uri OPTIONAL. A URI that provides the network location for the 231 resource set being registered. For example, if the resource set 232 corresponds to a digital photo, the value of this property could 233 be an HTTP-based URI identifying the location of the photo on the 234 web. The authorization server can use this information in various 235 ways to inform clients about a resource set's location. 237 type OPTIONAL. A string uniquely identifying the semantics of the 238 resource set. For example, if the resource set consists of a 239 single resource that is an identity claim that leverages 240 standardized claim semantics for "verified email address", the 241 value of this property could be an identifying URI for this claim. 243 scopes REQUIRED. An array of strings, any of which MAY be a URI, 244 indicating the available scopes for this resource set. URIs MUST 245 resolve to scope descriptions as defined in Section 2.1. 246 Published scope descriptions MAY reside anywhere on the web; a 247 resource server is not required to self-host scope descriptions 248 and may wish to point to standardized scope descriptions residing 249 elsewhere. It is the resource server's responsibility to ensure 250 that scope description documents are accessible to authorization 251 servers through GET calls to support any user interface 252 requirements. The resource server and authorization server are 253 presumed to have separately negotiated any required interpretation 254 of scope handling not conveyed through scope descriptions. 256 icon_uri OPTIONAL. A URI for a graphic icon representing the 257 resource set. The referenced icon MAY be used by the 258 authorization server in its resource owner user interface for the 259 resource owner. 261 For example, this description characterizes a resource set (a photo 262 album) that can potentially be only viewed, or alternatively to which 263 full access can be granted; the URIs point to scope descriptions as 264 defined in Section 2.1: 266 { 267 "name" : "Photo Album", 268 "icon_uri" : "http://www.example.com/icons/flower.png", 269 "scopes" : [ 270 "http://photoz.example.com/dev/scopes/view", 271 "http://photoz.example.com/dev/scopes/all" 272 ], 273 "type" : "http://www.example.com/rsets/photoalbum" 274 } 276 2.3. Resource Set Registration API 278 The resource server uses the RESTful API at the authorization 279 server's resource set registration endpoint to create, read, update, 280 and delete resource set descriptions, along with retrieving lists of 281 such descriptions. 283 (Note carefully the similar but distinct senses in which the word 284 "resource" is used in this section. The resource set descriptions 285 are themselves managed as web resources at the authorization server 286 through this API.) 288 The authorization server MUST present an API for registering resource 289 set descriptions at a set of URIs with the following structure: 291 {rsreguri}/resource_set 293 The {rsreguri} component is the authorization server's resource set 294 registration endpoint as advertised in its configuration data (see 295 Section 1.3). Following is a summary of the five registration 296 operations the authorization server is REQUIRED to support, where the 297 ellipsis represents whatever path segments might appear before the 298 required path structure. Each is defined in its own section below. 299 All other methods are unsupported. 301 o Create resource set description: POST .../resource_set 303 o Read resource set description: GET .../resource_set/{rsid} 305 o Update resource set description: PUT .../resource_set/{rsid} 307 o Delete resource set description: DELETE .../resource_set/{rsid} 309 o List resource set descriptions: GET .../resource_set 311 The {rsid} is the authorization server-assigned identifier for the 312 web resource corresponding to the resource set as returned in the 313 Location header. 315 Within the JSON body of a successful response, the authorization 316 server includes common properties, possibly in addition to method- 317 specific properties, as follows: 319 _id REQUIRED (except for the List method). A string value repeating 320 the {rsid} as appearing in the Location header. Its appearance in 321 both locations allows specialized header and body client software 322 to avoid extra parsing. 324 user_access_policy_uri OPTIONAL. A URI that allows the resource 325 server to redirect an end-user resource owner to a specific user 326 interface within the authorization server where the resource owner 327 can immediately set or modify access policies subsequent to the 328 resource set registration action just completed. The 329 authorization server is free to choose the targeted user 330 interface, for example, in the case of a deletion action, enabling 331 the resource server to direct the end-user to a policy-setting 332 interface for an overall "folder" of resource sets where the 333 deleted resource set once resided. 335 If the request to the resource set registration endpoint is 336 incorrect, then the authorization server instead responds with an 337 error message by including one of the following error codes with the 338 response (see Section 3): 340 unsupported_method_type The resource server request used an 341 unsupported HTTP method. The authorization server MUST respond 342 with the HTTP 405 (Method Not Allowed) status code and MUST fail 343 to act on the request. 345 not_found The resource set requested from the authorization server 346 cannot be found. The authorization server MUST respond with HTTP 347 404 (Not Found) status code. 349 2.3.1. Create Resource Set Description 351 Adds a new resource set description using the POST method. If the 352 request is successful, the authorization server MUST respond with a 353 status message that includes an _id property. 355 Form of a create request, with an access token in the header: 357 POST /rs/resource_set HTTP/1.1 358 Content-Type: application/json 359 Authorization: Bearer 204c69636b6c69 360 ... 362 (body contains JSON resource set description to be created) 364 Form of a successful response: 366 HTTP/1.1 201 Created 367 Content-Type: application/json 368 Location: /rs/resource_set/12345 369 ... 371 { 372 "_id" : 12345, 373 "user_access_policy_uri" : "http://as.example.com/rs/222/resource/333/policy" 374 } 375 2.3.2. Read Resource Set Description 377 Reads a previously registered resource set description using the GET 378 method. If the request is successful, the authorization server MUST 379 respond with a status message that includes a body containing the 380 referenced resource set description, along with an "_id" property. 382 Form of a read request, with an access token in the header: 384 GET /rs/resource_set/12345 HTTP/1.1 385 Authorization: Bearer 204c69636b6c69 386 ... 388 Form of a successful response: 390 HTTP/1.1 200 OK 391 Content-Type: application/json 392 ... 394 (body contains _id and resource set description) 396 If the referenced resource does not exist, the authorization server 397 MUST produce an error response with an error property value of 398 "not_found", as defined in Section 2.3. 400 2.3.3. Update Resource Set Description 402 Updates a previously registered resource set description using the 403 PUT method. If the request is successful, the authorization server 404 MUST respond with a status message that includes an "_id" property. 406 Form of an update request, with an access token in the header: 408 PUT /rs/resource_set/12345 HTTP/1.1 409 Content-Type: application/json 410 Authorization: Bearer 204c69636b6c69 411 ... 413 (body contains JSON resource set description to be updated) 414 Form of a successful response: 416 HTTP/1.1 200 OK 417 ... 419 { 420 _"id": "12345" 421 } 423 2.3.4. Delete Resource Set Description 425 Deletes a previously registered resource set description using the 426 DELETE method, thereby removing it from the authorization server's 427 protection regime. 429 Form of a delete request, with an access token in the header: 431 DELETE /rs/resource_set/12345 432 Authorization: Bearer 204c69636b6c69 433 ... 435 Form of a successful response: 437 HTTP/1.1 204 No content 438 ... 440 As defined in Section 2.3, if the referenced resource does not exist 441 the authorization server MUST produce an error response with an error 442 property value of "not_found". 444 2.3.5. List Resource Set Descriptions 446 Lists all previously registered resource set identifiers for this 447 user using the GET method. The authorization server MUST return the 448 list in the form of a JSON array of {rsid} string values. 450 The resource server uses this method as a first step in checking 451 whether its understanding of protected resources is in full 452 synchronization with the authorization server's understanding. 454 Form of a list request, with an access token in the header: 456 GET /rs/resource_set HTTP/1.1 457 Authorization: Bearer 204c69636b6c69 458 ... 460 Form of a successful response: 462 HTTP/1.1 200 OK 463 ... 465 (body contains JSON array of {rsid} values) 467 3. Error Messages 469 When a resource server attempts to access the resource set 470 registration endpoint at the authorization server, if the request is 471 successfully authenticated by OAuth means, but is invalid for another 472 reason, the authorization server produces an error response by adding 473 the following properties to the entity body of the HTTP response: 475 error REQUIRED. A single error code, as noted in the API 476 definition. Value for this property is defined in the specific 477 authorization server endpoint description. 479 error_description OPTIONAL. A human-readable text providing 480 additional information, used to assist in the understanding and 481 resolution of the error occurred. 483 error_uri OPTIONAL. A URI identifying a human-readable web page 484 with information about the error, used to provide the end-user 485 with additional information about the error. 487 4. Security Considerations 489 This specification largely relies on OAuth for API security and 490 shares its security and vulnerability considerations. 492 The resource server itself is presumed to have a trust relationship 493 with the authorization server in question, and it registers resource 494 sets in the context of a particular resource owner. A malicious 495 resource server could register a bad icon URI at an authorization 496 server, "infecting" the authorization server either when the icon is 497 retrieved or by confusing a human resource owner about the nature of 498 the resource set being protected. To accomplish this, the resource 499 server would likely have to deceive a resource owner into authorizing 500 it to, first, dynamically registering for client credentials at the 501 authorization server, and second, outsourcing protection to the 502 authorization server. 504 An authorization server could mitigate this threat by not displaying 505 scope or resource set icons of a dynamically registered resource 506 server until such time as it establishes sufficient trust. A less- 507 trusted resource server could increase the likelihood of an 508 authorization server displaying its icons by choosing icons that are 509 well-known and standardized by third parties. 511 5. Privacy Considerations 513 The communication between the authorization server and resource 514 server may expose personally identifiable information of a resource 515 owner. The context in which this API is used SHOULD account for its 516 own unique privacy considerations. 518 6. IANA Considerations 520 This document makes no request of IANA. 522 7. Example of Registering Resource Sets 524 The following example illustrates the intent and usage of resource 525 set descriptions and scope descriptions as part of resource set 526 registration in the context of [UMA]. 528 This example contains some steps that are exclusively in the realm of 529 user experience rather than web protocol, to achieve realistic 530 illustration. These steps are labeled "user experience only". Some 531 other steps are exclusively internal to the operation of the entity 532 being discussed. These are labeled "internal only". 534 A resource owner, Alice Adams, has just uploaded a photo of her new 535 puppy to a resource server, Photoz.example.com, and wants to ensure 536 that this specific photo is not publicly accessible. 538 Alice has already introduced this resource server to her 539 authorization server, CopMonkey.example.com. However, Alice has not 540 previously instructed Photoz to use CopMonkey to protect any photos 541 of hers. 543 Alice has previously visited CopMonkey to map a default "do not share 544 with anyone" policy to any resource sets registered by Photoz, until 545 such time as she maps some other more permissive policies to those 546 resources. (User experience only. This may have been done at the 547 time Alice introduced the resource server to the authorization 548 server, and/or it could have been a global or resource server- 549 specific preference setting. A different constraint or no constraint 550 at all might be associated with newly protected resources.) Other 551 kinds of policies she may eventually map to particular photos or 552 albums might be "Share only with husband@email.example.net" or "Share 553 only with people in my 'family' group". 555 Photoz itself has a publicly documented application-specific API that 556 offers two dozen different methods that apply to single photos, such 557 as "addTags" and "getSizes", but rolls them up into two photo-related 558 scopes of access: "view" (consisting of various read-only operations) 559 and "all" (consisting of various reading, editing, and printing 560 operations). It defines two scope descriptions that represent these 561 scopes, which it is able to reuse for all of its users (not just 562 Alice), and ensures that these scope description documents are 563 available through HTTP GET requests that may be made by authorization 564 servers. 566 The "name" property values are intended to be seen by Alice when she 567 maps authorization constraints to specific resource sets and actions 568 while visiting CopMonkey, such that Alice would see the strings "View 569 Photo and Related Info" and "All Actions", likely accompanied by the 570 referenced icons, in the CopMonkey interface. (Other users of Photoz 571 might similarly see the same labels at CopMonkey or whatever other 572 authorization server they use. Photoz could distinguish natural- 573 language labels per user if it wishes, by pointing to scopes with 574 differently translated names.) 576 Example of the viewing-related scope description document available 577 at http://photoz.example.com/dev/scopes/view: 579 { 580 "name" : "View Photo and Related Info", 581 "icon_uri" : "http://www.example.com/icons/reading-glasses.png" 582 } 584 Example of the broader scope description document available at 585 http://photoz.example.com/dev/scopes/all: 587 { 588 "name" : "All Actions", 589 "icon_uri" : "http://www.example.com/icons/galaxy.png" 590 } 592 While visiting Photoz, Alice selects a link or button that instructs 593 the site to "Protect" or "Share" this single photo (user experience 594 only; Photoz could have made this a default or preference setting). 596 As a result, Photoz defines for itself a resource set that represents 597 this photo (internal only; Photoz is the only application that knows 598 how to map a particular photo to a particular resource set). Photoz 599 also prepares the following resource set description, which is 600 specific to Alice and her photo. The "name" property value is 601 intended to be seen by Alice in mapping authorization policies to 602 specific resource sets and actions when she visits CopMonkey. Alice 603 would see the string "Steve the puppy!", likely accompanied by the 604 referenced icon, in the CopMonkey interface. The possible scopes of 605 access on this resource set are indicated with URI references to the 606 scope descriptions, as shown just above. 608 { 609 "name" : "Steve the puppy!", 610 "icon_uri" : "http://www.example.com/icons/flower", 611 "scopes" : [ 612 "http://photoz.example.com/dev/scopes/view", 613 "http://photoz.example.com/dev/scopes/all" 614 ] 615 } 617 Photoz uses the Create method of CopMonkey's standard OAuth resource 618 set registration API, presenting its Alice-specific access token to 619 use the API to register and assign an identifier to the resource set 620 description. 622 PUT /rs/resource_set HTTP/1.1 623 Content-Type: application/json 624 ... 626 { 627 "name" : "Steve the puppy!", 628 "icon_uri" : "http://www.example.com/icons/flower.png", 629 "scopes" : [ 630 "http://photoz.example.com/dev/scopes/view", 631 "http://photoz.example.com/dev/scopes/all" 632 ] 633 } 635 If the registration attempt succeeds, CopMonkey responds in the 636 following fashion. 638 HTTP/1.1 201 Created 639 Content-Type: application/json 640 ... 642 { 643 "_id" : "112210f47de98100" 644 } 646 At the time Alice indicates she would like this photo protected, 647 Photoz can choose to redirect Alice to CopMonkey for further policy 648 setting, access auditing, and other authorization server-related 649 tasks (user experience only). 651 Once it has successfully registered this description, Photoz is 652 responsible for outsourcing protection to CopMonkey for access 653 attempts made to this photo. 655 Over time, as Alice uploads other photos and creates and organizes 656 photo albums, Photoz can use additional methods of the resource set 657 registration API to ensure that CopMonkey's understanding of Alice's 658 protected resources matches its own. 660 For example, if Photoz suspects that somehow its understanding of the 661 resource set has gotten out of sync with CopMonkey's, it can ask to 662 read the resource set description as follows. 664 GET /rs/resource_set/112210f47de98100 HTTP/1.1 665 Host: as.example.com 666 ... 668 CopMonkey responds with the full content of the resource set 669 description, including its _id, as follows: 671 Example of an HTTP response to a "read resource set description" 672 request, containing a resource set description from the authorization 673 server: 675 HTTP/1.1 200 OK 676 Content-Type: application/json 677 ... 679 { 680 "_id" : "112210f47de98100", 681 "name" : "Photo album", 682 "icon_uri" : "http://www.example.com/icons/flower.png", 683 "scopes" : [ 684 "http://photoz.example.com/dev/scopes/view", 685 "http://photoz.example.com/dev/scopes/all" 686 ] 687 } 689 If for some reason Photoz and CopMonkey have gotten dramatically out 690 of sync, Photoz can ask for the list of resource set identifiers 691 CopMonkey currently knows about: 693 GET /rs/resource_set HTTP/1.1 694 Host: as.example.com 695 ... 697 CopMonkey's response might look as follows: 699 HTTP/1.1 200 OK 700 ... 702 [ "112210f47de98100", "34234df47eL95300" ] 704 If Alice later changes the photo's title (user experience only) on 705 Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz 706 would use the Update method to ensure that Alice's experience of 707 policy-setting at CopMonkey remains consistent with what she sees at 708 Photoz. Following is an example of this request. 710 PUT /rs/resource_set/112210f47de98100 HTTP/1.1 711 Content-Type: application/json 712 Host: as.example.com 713 ... 715 { 716 "name" : "Steve on October 14, 2011", 717 "icon_uri" : "http://www.example.com/icons/flower.png", 718 "scopes" : [ 719 "http://photoz.example.com/dev/scopes/view", 720 "http://photoz.example.com/dev/scopes/all" 721 ] 722 } 724 CopMonkey would respond as follows. 726 HTTP/1.1 201 Created 727 Content-Type: application/json 728 ... 730 { 731 "_id" : "112210f47de98100" 732 } 734 There are other reasons Photoz might want to update resource set 735 descriptions, having nothing to do with Alice's actions or wishes. 736 For example, it might extend its API to include new features, and 737 want to add new scopes to all of Alice's and other users' resource 738 set descriptions. 740 if Alice later decides to entirely remove sharing protection (user 741 experience only) on this photo while visiting Photoz, ensuring that 742 the public can get access without any protection, Photoz is 743 responsible for deleting the relevant resource set registration, as 744 follows: 746 DELETE /rs/resource_set/112210f47de98100 HTTP/1.1 747 Host: as.example.com 748 ... 750 8. Acknowledgments 752 The following people made significant text contributions to the 753 specification: 755 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 757 o Mark Dobrinic, Cozmanova 759 o George Fletcher, AOL 761 o Lukasz Moren, Cloud Identity Ltd 763 o Christian Scholz, COMlounge GmbH (former editor) 765 o Mike Schwartz, Gluu 767 o Jacek Szpot, Newcastle University 769 Additional contributors to this specification include the Kantara UMA 770 Work Group participants, a list of whom can be found at 771 [UMAnitarians]. 773 9. References 775 9.1. Normative References 777 [JSON] Bray, T., "The JavaScript Object Notation (JSON) Data 778 Interchange Format", March 2014, 779 . 781 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 782 October 2012, . 784 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 785 Requirement Levels", BCP 14, RFC 2119, March 1997. 787 9.2. Informative References 789 [OpenIDConnect] 790 Sakimura, N., "OpenID Connect Core 1.0 incorporating 791 errata set 1", November 2014, 792 . 794 [UMA] Hardjono, T., "User-Managed Access (UMA) Profile of OAuth 795 2.0", December 2014, 796 . 799 [UMAnitarians] 800 Maler, E., "UMA Participant Roster", December 2014, 801 . 804 Authors' Addresses 806 Thomas Hardjono (editor) 807 MIT 809 Email: hardjono@mit.edu 811 Eve Maler 812 ForgeRock 814 Email: eve.maler@forgerock.com 816 Maciej Machulak 817 Cloud Identity 819 Email: maciej.machulak@cloudidentity.co.uk 821 Domenico Catalano 822 Oracle 824 Email: domenico.catalano@oracle.com