idnits 2.17.1 draft-hardjono-oauth-resource-reg-05.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 (February 23, 2015) is 3351 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: August 27, 2015 ForgeRock 6 M. Machulak 7 Cloud Identity 8 D. Catalano 9 Oracle 10 February 23, 2015 12 OAuth 2.0 Resource Set Registration 13 draft-hardjono-oauth-resource-reg-05 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 August 27, 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 . . . . . . . . . . . . 8 66 2.3.3. Update Resource Set Description . . . . . . . . . . . 9 67 2.3.4. Delete Resource Set Description . . . . . . . . . . . 9 68 2.3.5. List Resource Set Descriptions . . . . . . . . . . . 10 69 3. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 10 70 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 71 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11 72 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 73 7. Example of Registering Resource Sets . . . . . . . . . . . . 12 74 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 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. Each is 297 defined in its own section below. All other methods are unsupported. 299 o Create resource set description: POST /resource_set 301 o Read resource set description: GET /resource_set/{rsid} 303 o Update resource set description: PUT /resource_set/{rsid} 305 o Delete resource set description: DELETE /resource_set/{rsid} 307 o List resource set descriptions: GET /resource_set 309 The {rsid} is the authorization server-assigned identifier for the 310 web resource corresponding to the resource set as returned in the 311 Location header. 313 Within the JSON body of a successful response, the authorization 314 server includes common properties, possibly in addition to method- 315 specific properties, as follows: 317 _id REQUIRED (except for the List method). A string value repeating 318 the {rsid} as appearing in the Location header. Its appearance in 319 both locations allows specialized header and body client software 320 to avoid extra parsing. 322 user_access_policy_uri OPTIONAL. A URI that allows the resource 323 server to redirect an end-user resource owner to a specific user 324 interface within the authorization server where the resource owner 325 can immediately set or modify access policies subsequent to the 326 resource set registration action just completed. The 327 authorization server is free to choose the targeted user 328 interface, for example, in the case of a deletion action, enabling 329 the resource server to direct the end-user to a policy-setting 330 interface for an overall "folder" of resource sets where the 331 deleted resource set once resided. 333 If the request to the resource set registration endpoint is 334 incorrect, then the authorization server instead responds with an 335 error message by including one of the following error codes with the 336 response (see Section 3): 338 unsupported_method_type The resource server request used an 339 unsupported HTTP method. The authorization server MUST respond 340 with the HTTP 405 (Method Not Allowed) status code and MUST fail 341 to act on the request. 343 not_found The resource set requested from the authorization server 344 cannot be found. The authorization server MUST respond with HTTP 345 404 (Not Found) status code. 347 2.3.1. Create Resource Set Description 349 Adds a new resource set description using the POST method. If the 350 request is successful, the authorization server MUST respond with a 351 status message that includes an _id property. 353 Form of a create request, with an access token in the header: 355 POST /resource_set HTTP/1.1 356 Content-Type: application/json 357 Authorization: Bearer 204c69636b6c69 358 ... 360 (body contains JSON resource set description to be created) 362 Form of a successful response: 364 HTTP/1.1 201 Created 365 Content-Type: application/json 366 Location: /resource_set/12345 367 ... 369 { 370 "_id" : 12345, 371 "user_access_policy_uri" : "http://as.example.com/rs/222/resource/333/policy" 372 } 374 2.3.2. Read Resource Set Description 376 Reads a previously registered resource set description using the GET 377 method. If the request is successful, the authorization server MUST 378 respond with a status message that includes a body containing the 379 referenced resource set description, along with an "_id" property. 381 Form of a read request, with an access token in the header: 383 GET /resource_set/12345 HTTP/1.1 384 Authorization: Bearer 204c69636b6c69 385 ... 387 Form of a successful response: 389 HTTP/1.1 200 OK 390 Content-Type: application/json 391 ... 393 (body contains _id and resource set description) 395 If the referenced resource does not exist, the authorization server 396 MUST produce an error response with an error property value of 397 "not_found", as defined in Section 2.3. 399 2.3.3. Update Resource Set Description 401 Updates a previously registered resource set description using the 402 PUT method. If the request is successful, the authorization server 403 MUST respond with a status message that includes an "_id" property. 405 Form of an update request, with an access token in the header: 407 PUT /resource_set/12345 HTTP/1.1 408 Content-Type: application/json 409 Authorization: Bearer 204c69636b6c69 410 ... 412 (body contains JSON resource set description to be updated) 414 Form of a successful response: 416 HTTP/1.1 204 No Content 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 /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 /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 resources 494 in the context of a particular resource owner. A malicious resource 495 server could register a bad icon URI at an authorization server, 496 "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 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 could mitigate this threat by not displaying scope 505 or resource set icons of a dynamically registered resource server 506 until such time as it establishes sufficient trust. A less-trusted 507 resource server could increase the likelihood of an authorization 508 server displaying its icons by choosing icons that are well-known and 509 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 } 616 Photoz uses the Create method of CopMonkey's standard OAuth resource 617 set registration API, presenting its Alice-specific access token to 618 use the API to register and assign an identifier to the resource set 619 description. 621 PUT /resource_set HTTP/1.1 622 Content-Type: application/json 623 ... 625 { 626 "name" : "Steve the puppy!", 627 "icon_uri" : "http://www.example.com/icons/flower.png", 628 "scopes" : [ 629 "http://photoz.example.com/dev/scopes/view", 630 "http://photoz.example.com/dev/scopes/all" 631 ] 632 } 634 If the registration attempt succeeds, CopMonkey responds in the 635 following fashion. 637 HTTP/1.1 201 Created 638 Content-Type: application/json 639 ... 641 { 642 "_id" : "112210f47de98100" 643 } 645 At the time Alice indicates she would like this photo protected, 646 Photoz can choose to redirect Alice to CopMonkey for further policy 647 setting, access auditing, and other authorization server-related 648 tasks (user experience only). 650 Once it has successfully registered this description, Photoz is 651 responsible for outsourcing protection to CopMonkey for access 652 attempts made to this photo. 654 Over time, as Alice uploads other photos and creates and organizes 655 photo albums, Photoz can use additional methods of the resource set 656 registration API to ensure that CopMonkey's understanding of Alice's 657 protected resources matches its own. 659 For example, if Photoz suspects that somehow its understanding of the 660 resource set has gotten out of sync with CopMonkey's, it can ask to 661 read the resource set description as follows. 663 GET /resource_set/112210f47de98100 HTTP/1.1 664 Host: as.example.com 665 ... 667 CopMonkey responds with the full content of the resource set 668 description, including its _id, as follows: 670 Example of an HTTP response to a "read resource set description" 671 request, containing a resource set description from the authorization 672 server: 674 HTTP/1.1 200 OK 675 Content-Type: application/json 676 ... 678 { 679 "_id" : "112210f47de98100", 680 "name" : "Photo album", 681 "icon_uri" : "http://www.example.com/icons/flower.png", 682 "scopes" : [ 683 "http://photoz.example.com/dev/scopes/view", 684 "http://photoz.example.com/dev/scopes/all" 685 ] 686 } 688 If for some reason Photoz and CopMonkey have gotten dramatically out 689 of sync, Photoz can ask for the list of resource set identifiers 690 CopMonkey currently knows about: 692 GET /resource_set HTTP/1.1 693 Host: as.example.com 694 ... 696 CopMonkey's response might look as follows: 698 HTTP/1.1 200 OK 699 ... 701 [ "112210f47de98100", "34234df47eL95300" ] 703 If Alice later changes the photo's title (user experience only) on 704 Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz 705 would use the Update method to ensure that Alice's experience of 706 policy-setting at CopMonkey remains consistent with what she sees at 707 Photoz. Following is an example of this request. 709 PUT /resource_set/112210f47de98100 HTTP/1.1 710 Content-Type: application/json 711 Host: as.example.com 712 ... 714 { 715 "name" : "Steve on October 14, 2011", 716 "icon_uri" : "http://www.example.com/icons/flower.png", 717 "scopes" : [ 718 "http://photoz.example.com/dev/scopes/view", 719 "http://photoz.example.com/dev/scopes/all" 720 ] 721 } 723 CopMonkey would respond as follows. 725 HTTP/1.1 201 Created 726 Content-Type: application/json 727 ... 729 { 730 "_id" : "112210f47de98100" 731 } 733 There are other reasons Photoz might want to update resource set 734 descriptions, having nothing to do with Alice's actions or wishes. 735 For example, it might extend its API to include new features, and 736 want to add new scopes to all of Alice's and other users' resource 737 set descriptions. 739 if Alice later decides to entirely remove sharing protection (user 740 experience only) on this photo while visiting Photoz, ensuring that 741 the public can get access without any protection, Photoz is 742 responsible for deleting the relevant resource set registration, as 743 follows: 745 DELETE /resource_set/112210f47de98100 HTTP/1.1 746 Host: as.example.com 747 ... 749 8. Acknowledgments 751 The following people made significant text contributions to the 752 specification: 754 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 756 o Mark Dobrinic, Cozmanova 757 o George Fletcher, AOL 759 o Lukasz Moren, Cloud Identity Ltd 761 o Christian Scholz, COMlounge GmbH (former editor) 763 o Mike Schwartz, Gluu 765 o Jacek Szpot, Newcastle University 767 Additional contributors to this specification include the Kantara UMA 768 Work Group participants, a list of whom can be found at 769 [UMAnitarians]. 771 9. References 773 9.1. Normative References 775 [JSON] Bray, T., "The JavaScript Object Notation (JSON) Data 776 Interchange Format", March 2014, 777 . 779 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 780 October 2012, . 782 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 783 Requirement Levels", BCP 14, RFC 2119, March 1997. 785 9.2. Informative References 787 [OpenIDConnect] 788 Sakimura, N., "OpenID Connect Core 1.0 incorporating 789 errata set 1", November 2014, 790 . 792 [UMA] Hardjono, T., "User-Managed Access (UMA) Profile of OAuth 793 2.0", December 2014, 794 . 797 [UMAnitarians] 798 Maler, E., "UMA Participant Roster", December 2014, 799 . 802 Authors' Addresses 804 Thomas Hardjono (editor) 805 MIT 807 Email: hardjono@mit.edu 809 Eve Maler 810 ForgeRock 812 Email: eve.maler@forgerock.com 814 Maciej Machulak 815 Cloud Identity 817 Email: maciej.machulak@cloudidentity.co.uk 819 Domenico Catalano 820 Oracle 822 Email: domenico.catalano@oracle.com