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