idnits 2.17.1 draft-hardjono-oauth-resource-reg-01.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 : ---------------------------------------------------------------------------- No issues found here. 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 (June 29, 2013) is 3946 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth2' Summary: 0 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 June 29, 2013 5 Expires: December 31, 2013 7 OAuth 2.0 Resource Set Registration 8 draft-hardjono-oauth-resource-reg-01 10 Abstract 12 This specification defines a resource set registration mechanism 13 between an OAuth 2.0 authorization server and resource server. The 14 resource server registers information about the semantics and 15 discovery properties of its resources with the authorization server. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on December 31, 2013. 34 Copyright Notice 36 Copyright (c) 2013 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.3. Authorization Server Configuration Data . . . . . . . . . 4 55 2. Resource Set Registration . . . . . . . . . . . . . . . . . . 4 56 2.1. Scope Descriptions . . . . . . . . . . . . . . . . . . . 4 57 2.2. Resource Set Descriptions . . . . . . . . . . . . . . . . 5 58 2.3. Resource Set Registration API . . . . . . . . . . . . . . 6 59 2.3.1. Create Resource Set Description . . . . . . . . . . . 8 60 2.3.2. Read Resource Set Description . . . . . . . . . . . . 9 61 2.3.3. Update Resource Set Description . . . . . . . . . . . 10 62 2.3.4. Delete Resource Set Description . . . . . . . . . . . 10 63 2.3.5. List Resource Set Descriptions . . . . . . . . . . . 11 64 3. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 11 65 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 66 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12 67 6. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 69 8. Example of Registering Resource Sets . . . . . . . . . . . . 12 70 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 71 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 72 10.1. Normative References . . . . . . . . . . . . . . . . . . 18 73 10.2. Informative References . . . . . . . . . . . . . . . . . 18 74 Appendix A. Document History . . . . . . . . . . . . . . . . . . 19 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 77 1. Introduction 79 There are various circumstances under which an OAuth 2.0 [OAuth2] 80 resource server may need to communicate to its authorization server 81 information about its protected resources: 83 o In some OAuth 2.0 deployments, the resource server and 84 authorization server are operated by the same organization and 85 deployed in the same domain, but many resource servers share a 86 single authorization server (a security token service (STS) 87 component). Thus, even though the trust between these two is 88 typically tightly bound, there is value in defining a singular 89 standardized resource protection communications interface between 90 the authorization server and each of the resource servers. 92 o In some deployments of OpenID Connect [OpenIDConnect], which has a 93 dependency on OAuth 2.0, the OpenID Provider (OP) component is a 94 specialized version of an OAuth authorization server that brokers 95 availability of user attributes by dealing with an ecosystem of 96 attribute providers (APs). These APs effectively function as 97 third-party resource servers. Thus, there is value in defining a 98 mechanism by which all of the third-party APs can communicate with 99 a central OP, as well as ensuring that trust between the 100 authorization server and resource servers is able to be 101 established in a dynamic, loosely coupled fashion. 103 o In some deployments of User-Managed Access [UMA], which has a 104 dependency on OAuth 2.0, an end-user resource owner (the "user" in 105 UMA) may choose their own authorization server as an independent 106 "CloudOS" authorization service, along with using any number of 107 resource servers that make up their "personal cloud". Thus, there 108 is value in defining a mechanism by which all of the third-party 109 resource servers can outsource resource protection (and 110 potentially discovery) to a central authorization server, as well 111 as ensuring that trust between the authorization server and 112 resource servers is able to be established by the resource owner 113 in a dynamic, loosely coupled fashion. 115 This specification defines an API through which the resource server 116 can register information about resource sets with the authorization 117 server. 119 1.1. Notational Conventions 121 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 122 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 123 document are to be interpreted as described in [RFC2119]. 125 Unless otherwise noted, all the protocol properties and values are 126 case sensitive. 128 1.2. Terminology 130 This specification introduces the following new terms and 131 enhancements of OAuth term definitions. 133 resource set One or more resources that the resource server manages 134 as a set. 136 scope A bounded extent of access that is possible to perform on a 137 resource set. In authorization policy terminology, a scope is 138 one of the potentially many "verbs" that can logically apply to 139 a resource set ("object"). This specification enhances the 140 OAuth concept of a "scope" by defining scopes as applying to 141 particular labeled resource sets, rather than leaving the 142 relevant resources (such as API endpoints or URIs) implicit. A 143 resource set can have any number of scopes, which together 144 describe the universe of actions that _can be_ taken on this 145 protected resource set. For example, a resource set 146 representing a status update API might have scopes that include 147 adding an update or reading updates. A resource set 148 representing a photo album might have scopes that include 149 viewing a slideshow or printing the album. The resource server 150 registers resource sets and their scopes when there is not yet 151 any particular client in the picture. 153 resource set registration endpoint The endpoint at which the 154 resource server registers resource sets it wants the 155 authorization server to know about. The operations available 156 at this endpoint constitute a resource set registration API 157 (see Section 2.3). 159 1.3. Authorization Server Configuration Data 161 If the authorization server declares its endpoints and any other 162 configuration data in a machine-readable form, for example 163 [OAuth-linktypes] or [OAuth-meta], it SHOULD convey its resource set 164 registration endpoint in this fashion as well. 166 2. Resource Set Registration 168 This specification defines a resource set registration API. The 169 endpoint for this API SHOULD also require some form of authentication 170 to access this endpoint, such as Client Authentication as described 171 in [OAuth2] or a separate OAuth access token. The methods of 172 managing and validating these authentication credentials are out of 173 scope of this specification. 175 For any of the resource owner's sets of resources this authorization 176 server needs to be aware of, the resource server MUST register these 177 resource sets at the authorization server's registration endpoint. 179 2.1. Scope Descriptions 181 A scope is a bounded extent of access that is possible to perform on 182 a resource set. A scope description is a JSON document with the 183 following properties: 185 name REQUIRED. A human-readable string describing some scope 186 (extent) of access. This name MAY be used by the authorization 187 server in its resource owner user interface for the resource 188 owner. 190 icon_uri OPTIONAL. A URI for a graphic icon representing the scope. 191 The referenced icon MAY be used by the authorization server in its 192 resource owner user interface for the resource owner. 194 For example, this description characterizes a scope that involves 195 reading or viewing resources (vs. creating them or editing them in 196 some fashion): 198 { 199 "name": "View", 200 "icon_uri": "http://www.example.com/icons/reading-glasses" 201 } 203 scope descriptions MAY contain extension properties that are not 204 defined in this specification. Extension names that are unprotected 205 from collisions are outside the scope of the current specification. 207 A resource server MUST list a resource set's available scopes using 208 URI references (as defined in Section 2.2). The scopes available for 209 use at any one resource server MUST have unique URI references so 210 that the resource server's scope descriptions are uniquely 211 distinguishable. A scope URI reference MAY include a fragment 212 identifier. Scope descriptions MAY reside anywhere. The resource 213 server is not required to self-host scope descriptions and may wish 214 to point to standardized scope descriptions residing elsewhere. 215 Scope description documents MUST be accessible to authorization 216 servers through GET calls made to these URI references. 218 See Section 8 for a long-form example of scopes used in resource set 219 registration. 221 2.2. Resource Set Descriptions 223 The resource server defines a resource set that the authorization 224 server needs to be aware of by registering a resource set description 225 at the authorization server. This registration process results in a 226 unique identifier for the resource set that the resource server can 227 later use for managing its description. 229 The resource server is free to use its own methods of describing 230 resource sets. A resource set description is a JSON document with 231 the following properties: 233 name REQUIRED. A human-readable string describing a set of one or 234 more resources. This name MAY be used by the authorization server 235 in its resource owner user interface for the resource owner. 237 icon_uri OPTIONAL. A URI for a graphic icon representing the 238 resource set. The referenced icon MAY be used by the 239 authorization server in its resource owner user interface for the 240 resource owner. 242 scopes REQUIRED. An array providing the URI references of scope 243 descriptions that are available for this resource set. 245 type OPTIONAL. A string uniquely identifying the semantics of the 246 resource set. For example, if the resource set consists of a 247 single resource that is an identity claim that leverages 248 standardized claim semantics for "verified email address", the 249 value of this property could be an identifying URI for this claim. 251 For example, this description characterizes a resource set (a photo 252 album) that can potentially be only viewed, or alternatively to which 253 full access can be granted; the URIs point to scope descriptions as 254 defined in Section 2.1: 256 { 257 "name": "Photo Album", 258 "icon_uri": "http://www.example.com/icons/flower.png", 259 "scopes": [ 260 "http://photoz.example.com/dev/scopes/view", 261 "http://photoz.example.com/dev/scopes/all" 262 ], 263 "type": "http://www.example.com/rsets/photoalbum" 264 } 266 Resource set descriptions MAY contain extension properties that are 267 not defined in this specification. Extension names that are 268 unprotected from collisions are outside the scope of the current 269 specification. 271 When a resource server creates or updates a resource set description 272 (see Section 2.3), the authorization server MUST attempt to retrieve 273 the referenced scope descriptions so that it can present fresh data 274 in any resource owner interactions. 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.) 287 The authorization server MUST present an API for registering resource 288 set descriptions at a set of URIs with the following structure: 290 {rsreguri}/resource_set/{rsid} 292 The method of authentication that the resource server uses SHOULD 293 sufficient context to distinguish between identical resource set 294 identifiers assigned by different resource servers. 296 The components of these URIs are defined as follows: 298 {rsreguri} The authorization server's resource set registration 299 endpoint as advertised in its configuration data (see 300 Section 1.3). 302 {rsid} An identifier for a resource set description. It is 303 RECOMMENDED to obscure resource set identifiers in order to avoid 304 leaking personally identifiable information to clients that are 305 exposed to scope information. 307 Following is a summary of the five registration operations the 308 authorization server is REQUIRED to support. Each is defined in its 309 own section below. All other methods are unsupported. This API uses 310 ETag and If-Match to ensure the desired resource at the authorization 311 server is targeted. 313 o Create resource set description: PUT /resource_set/{rsid} 315 o Read resource set description: GET /resource_set/{rsid} 317 o Update resource set description: PUT /resource_set/{rsid} with If- 318 Match 320 o Delete resource set description: DELETE /resource_set/{rsid} 322 o List resource set descriptions: GET /resource_set/ with If-Match 324 If the request to the resource set registration endpoint is 325 incorrect, then the authorization server responds with an error 326 message by including one of the following error codes with the 327 response (see Section 3): 329 unsupported_method_type The resource server request used an 330 unsupported HTTP method. The authorization server MUST respond 331 with the HTTP 405 (Method Not Allowed) status code and MUST fail 332 to act on the request. 334 not_found The resource set requested from the authorization server 335 cannot be found. The authorization server MUST respond with HTTP 336 404 (Not Found) status code. 338 precondition_failed The resource set that was requested to be 339 deleted or updated at the authorization server did not match the 340 If-Match value present in the request. The authorization server 341 MUST respond with HTTP 412 (Precondition Failed) status code and 342 MUST fail to act on the request. 344 2.3.1. Create Resource Set Description 346 Adds a new resource set description using the PUT method. If the 347 request is successful, the authorization server MUST respond with a 348 status message that includes an ETag header and _id and _rev 349 properties for managing resource set description versioning. 351 Form of a "create resource set description" HTTP request: 353 PUT /resource_set/{rsid} HTTP/1.1 354 Content-Type: application/json 355 ... 357 (body contains JSON resource set description to be created) 359 Form of a successful HTTP response: 361 HTTP/1.1 201 Created 362 Content-Type: application/json 363 ETag: (matches "_rev" property in returned object) 364 ... 366 { 367 "status": "created", 368 "_id": (id of created resource set), 369 "_rev": (ETag of created resource set) 370 } 372 On successful registration, the authorization server MAY return a 373 redirect policy URI to the resource server in a property with the 374 name "policy_uri". This URI allows the resource server to redirect 375 the resource owner to a specific user interface within the 376 authorization server where the resource owner can immediately set or 377 modify access policies for the resource set that was just registered. 379 Form of a successful HTTP response: 381 HTTP/1.1 201 Created 382 Content-Type: application/json 383 ETag: (matches "_rev" property in returned object) 384 ... 386 { 387 "status": "created", 388 "_id": (id of created resource set), 389 "_rev": (ETag of created resource set) 390 "policy_uri":"http://as.example.com/rs/222/resource/333/policy" 391 } 393 2.3.2. Read Resource Set Description 395 Reads a previously registered resource set description using the GET 396 method. If the request is successful, the authorization server MUST 397 respond with a status message that includes an ETag header and _id 398 and _rev properties for managing resource set description versioning. 400 Form of a "read resource set description" HTTP request: 402 GET /resource_set/{rsid} HTTP/1.1 403 ... 405 Form of a successful HTTP response: 407 HTTP/1.1 200 OK 408 Content-Type: application/json 409 ... 411 (body contains JSON resource set description, including _id and _rev) 413 If the referenced resource does not exist, the authorization server 414 MUST produce an error response with an error property value of 415 "not_found", as defined in Section 2.3. 417 On successful read, the authorization server MAY return a redirect 418 policy URI to the resource server in a property with the name 419 "policy_uri". This URI allows the resource server to redirect the 420 resource owner to a specific user interface within the authorization 421 server where the resource owner can immediately set or modify access 422 policies for the resource set that was read. 424 2.3.3. Update Resource Set Description 426 Updates a previously registered resource set description using the 427 PUT method. If the request is successful, the authorization server 428 MUST respond with a status message that includes an ETag header and 429 _id and _rev properties for managing resource set description 430 versioning. 432 Form of an "update resource set description" HTTP request: 434 PUT /resource_set/{rsid} HTTP/1.1 435 Content-Type: application/json 436 If-Match: (entity tag of resource) 437 ... 439 (body contains JSON resource set description to be updated) 441 Form of a successful HTTP response: 443 HTTP/1.1 204 No Content 444 ETag: "2" 445 ... 447 If the entity tag does not match, the authorization server MUST 448 produce an error response with an error property value of 449 "precondition_failed", as defined in Section 2.3. 451 On successful update, the authorization server MAY return a redirect 452 policy URI to the resource server in a property with the name 453 "policy_uri". This URI allows the resource server to redirect the 454 user to a specific user interface within the authorization server 455 where the user can immediately set or modify access policies for the 456 resource set that was just updated. 458 2.3.4. Delete Resource Set Description 460 Deletes a previously registered resource set description using the 461 DELETE method, thereby removing it from the authorization server's 462 protection regime. 464 Form of a "delete resource set description" HTTP request: 466 DELETE /resource_set/{rsid} 467 If-Match: (entity tag of resource) 468 ... 470 Form of a successful HTTP response: 472 HTTP/1.1 204 No content 473 ... 475 As defined in Section 2.3, if the referenced resource does not exist 476 the authorization server MUST produce an error response with an error 477 property value of "not_found", and if the entity tag does not match 478 the authorization server MUST produce an error response with an error 479 property value of "precondition_failed". 481 2.3.5. List Resource Set Descriptions 483 Lists all previously registered resource set identifiers for this 484 user using the GET method. The authorization server MUST return the 485 list in the form of a JSON array of {rsid} values. 487 The resource server uses this method as a first step in checking 488 whether its understanding of protected resources is in full 489 synchronization with the authorization server's understanding. 491 Form of a "list resource set descriptions" HTTP request: 493 GET /resource_set HTTP/1.1 494 ... 496 HTTP response: 498 HTTP/1.1 200 OK 499 ... 501 (body contains JSON array of {rsid} values) 503 3. Error Messages 505 When a resource server attempts to access the resource set 506 registration endpoint at the authorization server, if the request is 507 successfully authenticated by OAuth means, but is invalid for another 508 reason, the authorization server produces an error response by adding 509 the following properties to the entity body of the HTTP response: 511 error REQUIRED. A single error code, as noted in the API 512 definition. Value for this property is defined in the specific 513 authorization server endpoint description. 515 error_description OPTIONAL. A human-readable text providing 516 additional information, used to assist in the understanding and 517 resolution of the error occurred. 519 error_uri OPTIONAL. A URI identifying a human-readable web page 520 with information about the error, used to provide the end-user 521 with additional information about the error. 523 4. Security Considerations 525 This specification relies on OAuth for API security and shares its 526 security and vulnerability considerations. 528 5. Privacy Considerations 530 The communication between the authorization server and resource 531 server may expose personally identifiable information. The context 532 in which this API is used SHOULD deal with its own unique privacy 533 considerations. 535 6. Conformance 537 This specification makes optional normative reference to [OAuth2] for 538 API protection. This specification is anticipated to be used as a 539 module in higher-order specifications, where additional constraints 540 and profiling may appear. 542 7. IANA Considerations 544 This document makes no request of IANA. 546 8. Example of Registering Resource Sets 548 The following example illustrates the intent and usage of resource 549 set descriptions and scope descriptions as part of resource set 550 registration for the purposes of [UMA]. 552 This example contains some steps that are exclusively in the realm of 553 user experience rather than web protocol, to achieve realistic 554 illustration. These steps are labeled "User experience only". Some 555 other steps are exclusively internal to the operation of the entity 556 being discussed. These are labeled "Internal only". 558 A resource owner, Alice Adams, has just uploaded a photo of her new 559 puppy to a resource server, Photoz.example.com, and wants to ensure 560 that this specific photo is not publicly accessible. 562 Alice has already introduced this resource server to her 563 authorization server, CopMonkey.example.com. However, Alice has not 564 previously instructed Photoz to use CopMonkey to protect any photos 565 of hers. 567 Alice has previously visited CopMonkey to map a default "do not share 568 with anyone" policy to any resource sets registered by Photoz, until 569 such time as she maps some other more permissive policies to those 570 resources. (User experience only. This may have been done at the 571 time Alice introduced the resource server to the authorization 572 server, and/or it could have been a global or resource server- 573 specific preference setting. A different constraint or no constraint 574 at all might be associated with newly protected resources.) Other 575 kinds of policies she may eventually map to particular photos or 576 albums might be "Share only with husband@email.example.net" or "Share 577 only with people in my 'family' group". 579 Photoz itself has a publicly documented application-specific API that 580 offers two dozen different methods that apply to single photos, such 581 as "addTags" and "getSizes", but rolls them up into two photo-related 582 scopes of access: "view" (consisting of various read-only operations) 583 and "all" (consisting of various reading, editing, and printing 584 operations). It defines two scope descriptions that represent these 585 scopes, which it is able to reuse for all of its users (not just 586 Alice), and ensures that these scope description documents are 587 available through HTTP GET requests that may be made by authorization 588 servers. 590 The "name" property values are intended to be seen by Alice when she 591 maps authorization constraints to specific resource sets and actions 592 while visiting CopMonkey, such that Alice would see the strings "View 593 Photo and Related Info" and "All Actions", likely accompanied by the 594 referenced icons, in the CopMonkey interface. (Other users of Photoz 595 might similarly see the same labels at CopMonkey or whatever other 596 authorization server they use. Photoz could distinguish natural- 597 language labels per user if it wishes, by pointing to scopes with 598 differently translated names.) 600 Example of the viewing-related scope description document available 601 at http://photoz.example.com/dev/scopes/view: 603 { 604 "name": "View Photo and Related Info", 605 "icon_uri": "http://www.example.com/icons/reading-glasses.png" 606 } 607 Example of the broader scope description document available at http:/ 608 /photoz.example.com/dev/scopes/all: 610 { 611 "name": "All Actions", 612 "icon_uri": "http://www.example.com/icons/galaxy.png" 613 } 615 While visiting Photoz, Alice selects a link or button that instructs 616 the site to "Protect" or "Share" this single photo (user experience 617 only; Photoz could have made this a default or preference setting). 619 As a result, Photoz defines for itself a resource set that represents 620 this photo (internal only; Photoz is the only application that knows 621 how to map a particular photo to a particular resource set). Photoz 622 also prepares the following resource set description, which is 623 specific to Alice and her photo. The "name" property value is 624 intended to be seen by Alice in mapping authorization policies to 625 specific resource sets and actions when she visits CopMonkey. Alice 626 would see the string "Steve the puppy!", likely accompanied by the 627 referenced icon, in the CopMonkey interface. The possible scopes of 628 access on this resource set are indicated with URI references to the 629 scope descriptions, as shown just above. 631 { 632 "name": "Steve the puppy!", 633 "icon_uri": "http://www.example.com/icons/flower", 634 "scopes": [ 635 "http://photoz.example.com/dev/scopes/view", 636 "http://photoz.example.com/dev/scopes/all" 637 ] 638 } 640 Photoz uses the "create resource set description" method of 641 CopMonkey's standard OAuth resource set registration API, presenting 642 its Alice-specific access token to use the API to register and assign 643 an identifier to the resource set description. 645 PUT /resource_set/112210f47de98100 HTTP/1.1 646 Content-Type: application/json 647 ... 649 { 650 "name": "Steve the puppy!", 651 "icon_uri": "http://www.example.com/icons/flower.png", 652 "scopes": [ 653 "http://photoz.example.com/dev/scopes/view", 654 "http://photoz.example.com/dev/scopes/all" 655 ] 656 } 658 If the registration attempt succeeds, CopMonkey responds in the 659 following fashion. 661 HTTP/1.1 201 Created 662 Content-Type: application/json 663 ETag: "1" 664 ... 666 { 667 "status": "created", 668 "_id": "112210f47de98100", 669 "_rev": "1" 670 } 672 At the time Alice indicates she would like this photo protected, 673 Photoz can choose to redirect Alice to CopMonkey for further policy 674 setting, access auditing, and other authorization server-related 675 tasks (user experience only). 677 Once it has successfully registered this description, Photoz is 678 responsible for outsourcing protection to CopMonkey for access 679 attempts made to this photo. 681 Over time, as Alice uploads other photos and creates and organizes 682 photo albums, Photoz can use additional methods of the resource set 683 registration API to ensure that CopMonkey's understanding of Alice's 684 protected resources matches its own. 686 For example, if Photoz suspects that somehow its understanding of the 687 resource set has gotten out of sync with CopMonkey's, it can ask to 688 read the resource set description as follows. 690 GET /resource_set/112210f47de98100 HTTP/1.1 691 Host: as.example.com 692 ... 694 CopMonkey responds with the full content of the resource set 695 description, including its _id and its current _rev, as follows: 697 Example of an HTTP response to a "read resource set description" 698 request, containing a resource set description from the authorization 699 server: 701 HTTP/1.1 200 OK 702 Content-Type: application/json 703 ETag: "1" 704 ... 706 { 707 "_id": "112210f47de98100", 708 "_rev": "1", 709 "name": "Photo album", 710 "icon_uri": "http://www.example.com/icons/flower.png", 711 "scopes": [ 712 "http://photoz.example.com/dev/scopes/view", 713 "http://photoz.example.com/dev/scopes/all" 714 ] 715 } 717 If for some reason Photoz and CopMonkey have gotten dramatically out 718 of sync, Photoz can ask for the list of resource set identifiers 719 CopMonkey currently knows about: 721 GET /resource_set HTTP/1.1 722 Host: as.example.com 723 ... 725 CopMonkey's response might look as follows: 727 HTTP/1.1 200 OK 728 ... 730 [ "112210f47de98100", "34234df47eL95300" ] 732 If Alice later changes the photo's title (user experience only) on 733 Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz 734 would use the "update resource set description" method to ensure that 735 Alice's experience of policy-setting at CopMonkey remains consistent 736 with what she sees at Photoz. Following is an example of this 737 request. 739 PUT /resource_set/112210f47de98100 HTTP/1.1 740 Content-Type: application/json 741 Host: as.example.com 742 If-Match: "1" 743 ... 745 { 746 "name": "Steve on October 14, 2011", 747 "icon_uri": "http://www.example.com/icons/flower.png", 748 "scopes": [ 749 "http://photoz.example.com/dev/scopes/view", 750 "http://photoz.example.com/dev/scopes/all" 751 ] 752 } 754 CopMonkey would respond as follows. 756 HTTP/1.1 201 Created 757 Content-Type: application/json 758 ETag: "2" 759 ... 761 { 762 "status": "updated", 763 "_id": "112210f47de98100", 764 "_rev": "2" 765 } 767 There are other reasons Photoz might want to update resource set 768 descriptions, having nothing to do with Alice's actions or wishes. 769 For example, it might extend its API to include new features, and 770 want to add new scopes to all of Alice's and other users' resource 771 set descriptions. 773 if Alice later decides to entirely remove sharing protection (user 774 experience only) on this photo while visiting Photoz, ensuring that 775 the public can get access without any protection, Photoz is 776 responsible for deleting the relevant resource set registration, as 777 follows: 779 DELETE /resource_set/112210f47de98100 HTTP/1.1 780 Host: as.example.com 781 If-Match: "2" 782 ... 784 9. Acknowledgments 785 The current editor of this specification is Thomas Hardjono of MIT. 786 The following people are co-authors: 788 o Paul C. Bryan, ForgeRock US, Inc. 790 o Domenico Catalano, Oracle Corp. 792 o George Fletcher, AOL 794 o Maciej Machulak, Newcastle University 796 o Eve Maler, XMLgrrl.com 798 o Lukasz Moren, Newcastle University 800 o Christian Scholz, COMlounge GmbH 802 o Nat Sakimura, NRI 804 o Jacek Szpot, Newcastle University 806 10. References 808 10.1. Normative References 810 [OAuth2] Hammer-Lahav, E., "The OAuth 2.0 Protocol", September 811 2011, . 813 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 814 Requirement Levels", BCP 14, RFC 2119, March 1997. 816 10.2. Informative References 818 [OAuth-linktypes] 819 Richer, J., "Link Type Registrations for OAuth 2", October 820 2012, 821 . 823 [OAuth-meta] 824 Sakimura, N., "JSON Metadata for OAuth Responses", 825 December 2012, 826 . 828 [OpenIDConnect] 829 Sakimura, N., "OpenID Connect Standard 1.0 - draft 07", 830 December 2011, . 833 [UMA] Hardjono, T., "User-Managed Access (UMA) Profile of OAuth 834 2.0", December 2012, 835 . 837 Appendix A. Document History 839 NOTE: To be removed by RFC editor before publication as an RFC. 841 At I-D rev 00: 843 o Broken out of draft-oauth-umacore (post-rev 05) I-D and made 844 generic to apply to a variety of OAuth-based use cases. 846 From rev 00 to 01: 848 o Made editorial changes based on comments from Amanda Anganes. 850 o Removed previously overlooked references to UMA-specific 851 constructs in the normative section. 853 Author's Address 855 Thomas Hardjono (editor) 856 MIT 858 Email: hardjono@mit.edu