idnits 2.17.1 draft-hardjono-oauth-resource-reg-00.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 (December 27, 2012) is 4137 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 December 27, 2012 5 Expires: June 30, 2013 7 OAuth 2.0 Resource Set Registration 8 draft-hardjono-oauth-resource-reg-00 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 June 30, 2013. 34 Copyright Notice 36 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.3. Authorization Server Configuration Data . . . . . . . . . 4 55 2. Resource Set Registration . . . . . . . . . . . . . . . . . . 4 56 2.1. Scope Type Descriptions . . . . . . . . . . . . . . . . . 5 57 2.2. Resource Set Descriptions . . . . . . . . . . . . . . . . 6 58 2.3. Resource Set Registration API . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . 11 63 2.3.5. List Resource Set Descriptions . . . . . . . . . . . . 11 64 3. Error Messages . . . . . . . . . . . . . . . . . . . . . . . . 12 65 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 66 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 12 67 6. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 69 8. Example of Registering Resource Sets . . . . . . . . . . . . . 13 70 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 71 10. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 72 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 73 11.1. Normative References . . . . . . . . . . . . . . . . . . . 18 74 11.2. Informative References . . . . . . . . . . . . . . . . . . 19 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 needs to communicate to its authorization server 82 information about its protected resources. A resource server and 83 authorization server may need to communicate with each other about 84 resources in one of several circumstances: 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, which has a dependency on 96 OAuth 2.0, the OpenID Provider (OP) component is a specialized 97 version of an OAuth authorization server that brokers availability 98 of user attributes by dealing with with an ecosystem of attribute 99 providers (APs). These APs effectively function as third-party 100 resource servers. Thus, there is value in defining a mechanism by 101 which all of the third-party APs can communicate with a central 102 OP, as well as ensuring that trust between the authorization 103 server and resource servers is able to be established in a 104 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 "CloudOS" authorization service, along with using any number of 110 resource servers that make up their "personal cloud". Thus, there 111 is value in defining a mechanism by which all of the third-party 112 resource servers can outsource resource protection (and 113 potentially discovery) to a central authorization server, as well 114 as ensuring that trust between the authorization server and 115 resource servers is able to be established by the resource owner 116 in a dynamic, 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 the protocol properties and values are 129 case sensitive. 131 1.2. Terminology 133 This specification introduces the following new terms and 134 enhancements of OAuth term definitions. 136 resource set One or more resources that the resource server manages 137 as a set. 139 scope type A bounded extent of access that is possible to perform on 140 a resource set. In authorization policy terminology, a scope 141 type is one of the potentially many "verbs" that can logically 142 apply to a resource set ("object"). This specification extends 143 the OAuth concept of a "scope" by defining scope types as 144 applying to particular labeled resource sets, rather than 145 leaving the relevant resources (such as API endpoints or URIs) 146 implicit. A resource set can have any number of scope types, 147 which together describe the universe of actions that _can be_ 148 taken on this protected resource set. For example, a resource 149 set representing a status update API might have scope types 150 that include adding an update or reading updates. A resource 151 set representing a photo album might have scope types that 152 include viewing a slideshow or printing the album. The 153 resource server registers resource sets and their scope types 154 when there is not yet any particular client in the picture. 156 resource set registration endpoint The endpoint at which the 157 resource server registers resource sets it wants the 158 authorization server to know about. The operations available 159 at this endpoint constitute a resource set registration API 160 (see Section 2.3). 162 1.3. Authorization Server Configuration Data 164 If the authorization server declares its endpoints and any other 165 configuration data in a machine-readable form, for example 166 [OAuth-linktypes], it SHOULD convey its resource set registration 167 endpoint in this fashion as well. 169 2. Resource Set Registration 171 This specification defines a resource set registration API. If this 172 API is not open, it MUST be OAuth-protected. For any of the resource 173 owner's sets of resources this authorization server needs to be aware 174 of, the resource server MUST register these resource sets at the 175 authorization server's registration endpoint. 177 2.1. Scope Type Descriptions 179 A scope type is a bounded extent of access that is possible to 180 perform on a resource set. A scope type description is a JSON 181 document with the following properties: 183 name REQUIRED. A human-readable string describing some scope 184 (extent) of access. This name is intended for ultimate use in the 185 authorization server's user interface to assist the user in 186 setting policies for protected resource sets that have this 187 available scope. 189 icon_uri OPTIONAL. A URI for a graphic icon representing the scope. 190 The referenced icon is intended for ultimate use in the 191 authorization server's user interface to assist the user in 192 setting policies for protected resource sets that have this 193 available scope. 195 For example, this description characterizes a scope type that 196 involves reading or viewing resources (vs. creating them or editing 197 them in some fashion): 199 { 200 "name": "View", 201 "icon_uri": "http://www.example.com/icons/reading-glasses" 202 } 204 Scope type 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 scope types 210 available for use at any one resource server MUST have unique URI 211 references so that the resource server's scope descriptions are 212 uniquely distinguishable. A scope type URI reference MAY include a 213 fragment identifier. Scope type descriptions MAY reside anywhere. 214 The resource server is not required to self-host scope type 215 descriptions and may wish to point to standardized scope type 216 descriptions residing elsewhere. Scope type description documents 217 MUST be accessible to authorization servers through GET calls made to 218 these URI references. 220 See Section 8 for a long-form example of scope types used in resource 221 set registration. 223 2.2. Resource Set Descriptions 225 The resource server defines a resource set that the authorization 226 server needs to be aware of by registering a resource set description 227 at the authorization server. 229 A resource set description is a JSON document with the following 230 properties: 232 name REQUIRED. A human-readable string describing a set of one or 233 more resources. The authorization server SHOULD use the name in 234 its user interface to assist the user in setting policies for 235 protecting this resource set. 237 icon_uri OPTIONAL. A URI for a graphic icon representing the 238 resource set. 240 scopes REQUIRED. An array providing the URI references of scope 241 type descriptions that are available for this resource set. 243 type OPTIONAL. A string uniquely identifying the semantics of the 244 resource set. For example, if the resource set consists of a 245 single resource that is an identity claim that leverages 246 standardized claim semantics, the value of this property could be 247 an identifying URI for this claim. 249 For example, this description characterizes a resource set (a photo 250 album) that can potentially be only viewed, or alternatively to which 251 full access can be granted; the URIs point to scope descriptions as 252 defined in Section 2.1: 254 { 255 "name": "Photo Album", 256 "icon_uri": "http://www.example.com/icons/flower.png", 257 "scopes": [ 258 "http://photoz.example.com/dev/scopes/view", 259 "http://photoz.example.com/dev/scopes/all" 260 ], 261 "resource_set_type": "http://www.example.com/rsets/photoalbum" 262 } 264 Resource set descriptions MAY contain extension properties that are 265 not defined in this specification. Extension names that are 266 unprotected from collisions are outside the scope of the current 267 specification. 269 When a resource server creates or updates a resource set description 270 (see Section 2.3), the authorization server MUST attempt to retrieve 271 the referenced scope descriptions so that it can present fresh data 272 in resource owner interactions. 274 2.3. Resource Set Registration API 276 The resource server uses the RESTful API at the authorization 277 server's resource set registration endpoint to create, read, update, 278 and delete resource set descriptions, along with listing groups of 279 such descriptions. The resource server is free to use its own 280 methods of identifying and describing resource sets. 282 (Note carefully the similar but distinct senses in which the word 283 "resource" is used in this section. The resource set descriptions 284 are themselves managed as web resources at the authorization server 285 through this API.) 287 The authorization server MUST present an API for registering resource 288 set descriptions at a set of URIs with the structure "{rsreguri}/ 289 resource_set/{rsid}", where the PAT provides sufficient context to 290 distinguish between identical resource set identifiers assigned by 291 different hosts. 293 The components of these URIs are defined as follows: 295 {rsreguri} The authorization server's resource set registration 296 endpoint as advertised in its configuration data (see 297 Section 1.3). 299 {rsid} An identifier for a resource set description. 301 Without a specific resource set identifier path component, the URI 302 applies to the set of resource set descriptions already registered. 304 Following is a summary of the five registration operations the 305 authorization server is REQUIRED to support. Each is defined in its 306 own section below. All other methods are unsupported. This API uses 307 ETag and If-Match to ensure the desired resource at the authorization 308 server is targeted. 310 o Create resource set description: PUT /resource_set/{rsid} 312 o Read resource set description: GET /resource_set/{rsid} 314 o Update resource set description: PUT /resource_set/{rsid} with If- 315 Match 317 o Delete resource set description: DELETE /resource_set/{rsid} 319 o List resource set descriptions: GET /resource_set/ with If-Match 321 If the request to the resource set registration endpoint is 322 incorrect, then the authorization server responds with an error 323 message by including one of the following error codes with the 324 response: 326 unsupported_method_type The resource server request used an 327 unsupported HTTP method. The authorization server MUST respond 328 with the HTTP 405 (Method Not Allowed) status code and MUST fail 329 to act on the request. 331 not_found The resource set requested from the authorization server 332 cannot be found. The authorization server MUST respond with HTTP 333 404 (Not Found) status code. 335 precondition_failed The resource set that was requested to be 336 deleted or updated at the authorization server did not match the 337 If-Match value present in the request. The authorization server 338 MUST respond with HTTP 412 (Precondition Failed) status code and 339 MUST fail to act on the request. 341 2.3.1. Create Resource Set Description 343 Adds a new resource set description using the PUT method, thereby 344 putting it under the authorization server's protection. If the 345 request is successful, the authorization server MUST respond with a 346 status message that includes an ETag header and _id and _rev 347 properties for managing resource set description versioning. 349 Form of a "create resource set description" HTTP request: 351 PUT /resource_set/{rsid} HTTP/1.1 352 Content-Type: application/intro-resource-set+json 353 ... 355 (body contains JSON resource set description to be created) 356 Form of a successful HTTP response: 358 HTTP/1.1 201 Created 359 Content-Type: application/intro-status+json 360 ETag: (matches "_rev" property in returned object) 361 ... 363 { 364 "status": "created", 365 "_id": (id of created resource set), 366 "_rev": (ETag of created resource set) 367 } 369 On successful registration, the authorization server MAY return a 370 redirect policy URI to the resource server in a property with the 371 name "policy_uri". This URI allows the resource server to redirect 372 the user to a specific user interface within the authorization server 373 where the user can immediately set or modify access policies for the 374 resource set that was just registered. 376 Form of a successful HTTP response: 378 HTTP/1.1 201 Created 379 Content-Type: application/intro-status+json 380 ETag: (matches "_rev" property in returned object) 381 ... 383 { 384 "status": "created", 385 "_id": (id of created resource set), 386 "_rev": (ETag of created resource set) 387 "policy_uri":"http://as.example.com/rs/222/resource/333/policy" 388 } 390 2.3.2. Read Resource Set Description 392 Reads a previously registered resource set description using the GET 393 method. If the request is successful, the authorization server MUST 394 respond with a status message that includes an ETag header and _id 395 and _rev properties for managing resource set description versioning. 397 Form of a "read resource set description" HTTP request: 399 GET /resource_set/{rsid} HTTP/1.1 400 ... 402 Form of a successful HTTP response: 404 HTTP/1.1 200 OK 405 Content-Type: application/intro-resource-set+json 406 ... 408 (body contains JSON resource set description, including _id and _rev) 410 If the referenced resource does not exist, the authorization server 411 MUST produce an error response with an error property value of 412 "not_found", as defined in Section 2.3. 414 On successful read, the authorization server MAY return a redirect 415 policy URI to the resource server in a property with the name 416 "policy_uri". This URI allows the resource server to redirect the 417 user to a specific user interface within the authorization server 418 where the user can immediately set or modify access policies for the 419 resource set that was read. 421 2.3.3. Update Resource Set Description 423 Updates a previously registered resource set description using the 424 PUT method, thereby changing the resource set's protection 425 characteristics. If the request is successful, the authorization 426 server MUST respond with a status message that includes an ETag 427 header and _id and _rev properties for managing resource set 428 description versioning. 430 Form of an "update resource set description" HTTfP request: 432 PUT /resource_set/{rsid} HTTP/1.1 433 Content-Type: application/resource-set+json 434 If-Match: (entity tag of resource) 435 ... 437 (body contains JSON resource set description to be updated) 439 Form of a successful HTTP response: 441 HTTP/1.1 204 No Content 442 ETag: "2" 443 ... 445 If the entity tag does not match, the authorization server MUST 446 produce an error response with an error property value of 447 "precondition_failed", as defined in Section 2.3. 449 On successful update, the authorization server MAY return a redirect 450 policy URI to the resource server in a property with the name 451 "policy_uri". This URI allows the resource server to redirect the 452 user to a specific user interface within the authorization server 453 where the user can immediately set or modify access policies for the 454 resource set that was just updated. 456 2.3.4. Delete Resource Set Description 458 Deletes a previously registered resource set description using the 459 DELETE method, thereby removing it from the authorization server's 460 protection regime. 462 Form of a "delete resource set description" HTTP request: 464 DELETE /resource_set/{rsid} 465 If-Match: (entity tag of resource) 466 ... 468 Form of a successful HTTP response: 470 HTTP/1.1 204 No content 471 ... 473 As defined in Section 2.3, if the referenced resource does not exist 474 the authorization server MUST produce an error response with an error 475 property value of "not_found", and if the entity tag does not match 476 the authorization server MUST produce an error response with an error 477 property value of "precondition_failed". 479 2.3.5. List Resource Set Descriptions 481 Lists all previously registered resource set identifiers for this 482 user using the GET method. The authorization server MUST return the 483 list in the form of a JSON array of {rsid} values. 485 The resource server uses this method as a first step in checking 486 whether its understanding of protected resources is in full 487 synchronization with the authorization server's understanding. 489 Form of a "list resource set descriptions" HTTP request: 491 GET /resource_set HTTP/1.1 492 ... 494 HTTP response: 496 HTTP/1.1 200 OK 497 ... 499 (body contains JSON array of {rsid} values) 501 3. Error Messages 503 When a resource server attempts to access the resource set 504 registration endpoint at the authorization server, if the request is 505 successfully authenticated by OAuth means, but is invalid for another 506 reason, the authorization server produces an error response by adding 507 the following properties to the entity body of the HTTP response: 509 error REQUIRED. A single error code, as noted in the API 510 definition. Value for this property is defined in the specific 511 authorization server endpoint description. 513 error_description OPTIONAL. A human-readable text providing 514 additional information, used to assist in the understanding and 515 resolution of the error occurred. 517 error_uri OPTIONAL. A URI identifying a human-readable web page 518 with information about the error, used to provide the end-user 519 with additional information about the error. 521 4. Security Considerations 523 This specification relies on OAuth for API security and shares its 524 security and vulnerability considerations. 526 5. Privacy Considerations 528 The communication between the authorization server and resource 529 server may expose personally identifiable information. The context 530 in which this API is used SHOULD deal with its own unique privacy 531 considerations. 533 6. Conformance 535 This specification makes optional normative reference to [OAuth2] for 536 API protection. This specification is anticipated to be used as a 537 module in higher-order specifications, where additional constraints 538 and profiling may appear. 540 7. IANA Considerations 542 This document makes no request of IANA. 544 8. Example of Registering Resource Sets 546 The following example illustrates the intent and usage of resource 547 set descriptions and scope type descriptions as part of resource set 548 registration for the purposes of User-Managed Access (UMA). 550 This example contains some steps that are exclusively in the realm of 551 user experience rather than web protocol, to achieve realistic 552 illustration. These steps are labeled "User experience only". Some 553 other steps are exclusively internal to the operation of the entity 554 being discussed. These are labeled "Internal only". 556 A resource owner, Alice Adams, has just uploaded a photo of her new 557 puppy to a resource server, Photoz.example.com, and wants to ensure 558 that this specific photo is not publicly accessible. 560 Alice has already introduced this resource server to her 561 authorization server, CopMonkey.example.com, and thus Photoz has 562 already obtained a PAT from CopMonkey. However, Alice has not 563 previously instructed Photoz to use CopMonkey to protect any other 564 photos of hers. 566 Alice has previously visited CopMonkey to map a default "do not share 567 with anyone" policy to any resource sets registered by Photoz, until 568 such time as she maps some other more permissive policies to those 569 resources. (User experience only. This may have been done at the 570 time Alice introduced the resource server to the authorization 571 server, and/or it could have been a global or resource server- 572 specific preference setting. A different constraint or no constraint 573 at all might be associated with newly protected resources.) Other 574 kinds of policies she may eventually map to particular photos or 575 albums might be "Share only with husband@email.example.net" or "Share 576 only with people in my 'family' group". 578 Photoz itself has a publicly documented application-specific API that 579 offers two dozen different methods that apply to single photos, such 580 as "addTags" and "getSizes", but rolls them up into two photo-related 581 scope types of access: "view" (consisting of various read-only 582 operations) and "all" (consisting of various reading, editing, and 583 printing operations). It defines two scope type descriptions that 584 represent these scope types, which it is able to reuse for all of its 585 users (not just Alice), and ensures that these scope type description 586 documents are available through HTTP GET requests that may be made by 587 authorization servers. 589 The "name" property values are intended to be seen by Alice when she 590 maps authorization constraints to specific resource sets and actions 591 while visiting CopMonkey, such that Alice would see the strings "View 592 Photo and Related Info" and "All Actions", likely accompanied by the 593 referenced icons, in the CopMonkey interface. (Other users of Photoz 594 might similarly see the same labels at CopMonkey or whatever other 595 authorization server they use. Photoz could distinguish natural- 596 language labels per user if it wishes, by pointing to scopes with 597 differently translated names.) 599 Example of the viewing-related scope type description document 600 available at http://photoz.example.com/dev/scopes/view with a 601 Content-Type of application/intro-scope+json: 603 { 604 "name": "View Photo and Related Info", 605 "icon_uri": "http://www.example.com/icons/reading-glasses.png" 606 } 608 Example of the broader scope type description document available at 609 http://photoz.example.com/dev/scopes/all, likewise with a Content- 610 Type of application/intro-scope+json: 612 { 613 "name": "All Actions", 614 "icon_uri": "http://www.example.com/icons/galaxy.png" 615 } 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 UMA resource set registration API, presenting 644 its Alice-specific PAT there, to register and assign an identifier to 645 the resource set description. 647 PUT /resource_set/112210f47de98100 HTTP/1.1 648 Content-Type: application/intro-resource-set+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/intro-status+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 to CopMonkey all questions of 681 authorization for access attempts made to this photo. 683 Over time, as Alice uploads other photos and creates and organizes 684 photo albums, and as Photoz makes new action functionality available, 685 Photoz can use additional methods of the resource set registration 686 API to ensure that CopMonkey's understanding of Alice's protected 687 resources matches its own. 689 For example, if Photoz suspects that somehow its understanding of the 690 resource set has gotten out of sync with CopMonkey's, it can ask to 691 read the resource set description as follows. 693 GET /resource_set/112210f47de98100 HTTP/1.1 694 Host: as.example.com 695 ... 697 CopMonkey responds with the full content of the resource set 698 description, including its _id and its current _rev, as follows: 700 Example of an HTTP response to a "read resource set description" 701 request, containing a resource set description from the authorization 702 server: 704 HTTP/1.1 200 OK 705 Content-Type: application/intro-resource-set+json 706 ETag: "1" 707 ... 709 { 710 "_id": "112210f47de98100", 711 "_rev": "1", 712 "name": "Photo album", 713 "icon_uri": "http://www.example.com/icons/flower.png", 714 "scopes": [ 715 "http://photoz.example.com/dev/scopes/view", 716 "http://photoz.example.com/dev/scopes/all" 717 ] 718 } 720 If for some reason Photoz and CopMonkey have gotten dramatically out 721 of sync, Photoz can ask for the list of resource set identifiers 722 CopMonkey currently knows about: 724 GET /resource_set HTTP/1.1 725 Host: as.example.com 726 ... 728 CopMonkey's response might look as follows: 730 HTTP/1.1 200 OK 731 ... 733 [ "112210f47de98100", "34234df47eL95300" ] 735 If Alice later changes the photo's title (user experience only) on 736 Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz 737 would use the "update resource set description" method to ensure that 738 Alice's experience of policy-setting at CopMonkey remains consistent 739 with what she sees at Photoz. Following is an example of this 740 request. 742 PUT /resource_set/112210f47de98100 HTTP/1.1 743 Content-Type: application/intro-resource-set+json 744 Host: as.example.com 745 If-Match: "1" 746 ... 748 { 749 "name": "Steve on October 14, 2011", 750 "icon_uri": "http://www.example.com/icons/flower.png", 751 "scopes": [ 752 "http://photoz.example.com/dev/scopes/view", 753 "http://photoz.example.com/dev/scopes/all" 754 ] 755 } 757 CopMonkey would respond as follows. 759 HTTP/1.1 201 Created 760 Content-Type: application/intro-status+json 761 ETag: "2" 762 ... 764 { 765 "status": "updated", 766 "_id": "112210f47de98100", 767 "_rev": "2" 768 } 770 There are other reasons Photoz might want to update resource set 771 descriptions, having nothing to do with Alice's actions or wishes. 772 For example, it might extend its API to include new features, and 773 want to add new scopes to all of Alice's and other users' resource 774 set descriptions. 776 if Alice later decides to entirely remove sharing protection (user 777 experience only) on this photo while visiting Photoz, ensuring that 778 the public can get access without any UMA-based protection, Photoz is 779 responsible for deleting the relevant resource set registration, as 780 follows: 782 DELETE /resource_set/112210f47de98100 HTTP/1.1 783 Host: as.example.com 784 If-Match: "2" 785 ... 787 9. Acknowledgments 789 The current editor of this specification is Thomas Hardjono of MIT. 790 The following people are co-authors: 792 o Paul C. Bryan, ForgeRock US, Inc. 794 o Domenico Catalano, Oracle Corp. 796 o George Fletcher, AOL 798 o Maciej Machulak, Newcastle University 800 o Eve Maler, XMLgrrl.com 802 o Lukasz Moren, Newcastle University 804 o Christian Scholz, COMlounge GmbH 806 o Nat Sakimura, NRI 808 o Jacek Szpot, Newcastle University 810 10. Issues 812 All issues are now captured at the project's GitHub site 813 (). 815 11. References 817 11.1. Normative References 819 [OAuth2] Hammer-Lahav, E., "The OAuth 2.0 Protocol", 820 September 2011, 821 . 823 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 824 Requirement Levels", BCP 14, RFC 2119, March 1997. 826 11.2. Informative References 828 [OAuth-linktypes] 829 Richer, J., "Link Type Registrations for OAuth 2", 830 October 2012, 831 . 833 Appendix A. Document History 835 NOTE: To be removed by RFC editor before publication as an RFC. 837 From I-D rev 00: 839 o Broken out of draft-oauth-umacore (post-rev 05) I-D and made 840 generic to apply to a variety of OAuth-based use cases. 842 Author's Address 844 Thomas Hardjono (editor) 845 MIT 847 Email: hardjono@mit.edu