idnits 2.17.1 draft-hardjono-oauth-resource-reg-04.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 (January 5, 2015) is 3389 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) -- Looks like a reference, but probably isn't: '1' on line 853 ** Obsolete normative reference: RFC 7159 (ref. 'JSON') (Obsoleted by RFC 8259) -- No information found for draft-uma-core - is the name correct? Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Hardjono, Ed. 3 Internet-Draft MIT 4 Intended status: Standards Track E. Maler 5 Expires: July 9, 2015 ForgeRock 6 M. Machulak 7 Cloud Identity 8 D. Catalano 9 Oracle 10 January 5, 2015 12 OAuth 2.0 Resource Set Registration 13 draft-hardjono-oauth-resource-reg-04 15 Abstract 17 This specification defines a resource set registration mechanism 18 between an OAuth 2.0 authorization server and resource server. The 19 resource server registers information about the semantics and 20 discovery properties of its resources with the authorization server. 21 This revision of the specification is part of the UMA "candidate 22 V1.0" process. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on July 9, 2015. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.3. Authorization Server Configuration Data . . . . . . . . . 4 62 2. Resource Set Registration . . . . . . . . . . . . . . . . . . 4 63 2.1. Scope Descriptions . . . . . . . . . . . . . . . . . . . 5 64 2.2. Resource Set Descriptions . . . . . . . . . . . . . . . . 5 65 2.3. Resource Set Registration API . . . . . . . . . . . . . . 7 66 2.3.1. Create Resource Set Description . . . . . . . . . . . 8 67 2.3.2. Read Resource Set Description . . . . . . . . . . . . 9 68 2.3.3. Update Resource Set Description . . . . . . . . . . . 10 69 2.3.4. Delete Resource Set Description . . . . . . . . . . . 11 70 2.3.5. List Resource Set Descriptions . . . . . . . . . . . 11 71 3. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 12 72 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 73 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12 74 6. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 12 75 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 76 8. Example of Registering Resource Sets . . . . . . . . . . . . 13 77 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 78 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 79 10.1. Normative References . . . . . . . . . . . . . . . . . . 18 80 10.2. Informative References . . . . . . . . . . . . . . . . . 19 81 Appendix A. Document History . . . . . . . . . . . . . . . . . . 19 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 84 1. Introduction 86 There are various circumstances under which an OAuth 2.0 [OAuth2] 87 resource server may need to communicate information about its 88 protected resources to its authorization server: 90 o In some OAuth 2.0 deployments, the resource server and 91 authorization server are operated by the same organization and 92 deployed in the same domain, but many resource servers share a 93 single authorization server (a security token service (STS) 94 component). Thus, even though the trust between these two is 95 typically tightly bound, there is value in defining a singular 96 standardized resource protection communications interface between 97 the authorization server and each of the resource servers. 99 o In some deployments of OpenID Connect [OpenIDConnect], which has a 100 dependency on OAuth 2.0, the OpenID Provider (OP) component is a 101 specialized version of an OAuth authorization server that brokers 102 availability of user attributes by dealing with an ecosystem of 103 attribute providers (APs). These APs effectively function as 104 third-party resource servers. Thus, there is value in defining a 105 mechanism by which all of the third-party APs can communicate with 106 a central OP, as well as ensuring that trust between the 107 authorization server and resource servers is able to be 108 established in a dynamic, loosely coupled fashion. 110 o In some deployments of User-Managed Access [UMA], which has a 111 dependency on OAuth 2.0, an end-user resource owner (the "user" in 112 UMA) may choose their own authorization server as an independent 113 cloud-based service, along with using any number of resource 114 servers that make up their "personal cloud". Thus, there is value 115 in defining a mechanism by which all of the third-party resource 116 servers can outsource resource protection (and potentially 117 discovery) to a central authorization server, as well as ensuring 118 that trust between the authorization server and resource servers 119 is able to be established by the resource owner in a dynamic, 120 loosely coupled fashion. 122 This specification defines an API through which the resource server 123 can register information about resource sets with the authorization 124 server. 126 1.1. Notational Conventions 128 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 129 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 130 document are to be interpreted as described in [RFC2119]. 132 Unless otherwise noted, all protocol properties and values are case 133 sensitive. JSON [JSON] data structures defined by this specification 134 MAY contain extension properties that are not defined in this 135 specification. Any entity receiving or retrieving a JSON data 136 structure SHOULD ignore extension properties it is unable to 137 understand. Extension names that are unprotected from collisions are 138 outside the scope of this specification. 140 1.2. Terminology 142 This specification introduces the following new terms and 143 enhancements of OAuth term definitions. 145 resource set One or more resources that the resource server manages 146 as a set, abstractly. A resource set may be a single API 147 endpoint, a set of API endpoints, a classic web resource such 148 as an HTML page, and so on. Defining this concept enables 149 registering data about it, including, most importantly, scopes 150 but also other data. 152 scope A bounded extent of access that is possible to perform on a 153 resource set. In authorization policy terminology, a scope is 154 one of the potentially many "verbs" that can logically apply to 155 a resource set ("object"). This specification enhances the 156 OAuth concept of a "scope" by defining scopes as applying to 157 particular registered resource sets, rather than leaving the 158 relevant resources (such as API endpoints or URIs) implicit. A 159 resource set can have any number of scopes, which together 160 describe the universe of actions that _can be_ taken on this 161 protected resource set. For example, a resource set 162 representing a status update API might have scopes that include 163 adding an update or reading updates. A resource set 164 representing a photo album might have scopes that include 165 viewing a slideshow or printing the album. The resource server 166 registers resource sets and their scopes when there is not yet 167 any particular client in the picture. 169 resource set registration endpoint The endpoint defined by this 170 specification at which the resource server registers resource 171 sets it wants the authorization server to know about. The 172 operations available at this endpoint constitute a resource set 173 registration API (see Section 2.3). 175 1.3. Authorization Server Configuration Data 177 If the authorization server declares its endpoints and any other 178 configuration data in a machine-readable form, it SHOULD convey its 179 resource set registration endpoint in this fashion as well. 181 2. Resource Set Registration 183 This specification defines a resource set registration API. The 184 endpoint for this API SHOULD also require some form of authentication 185 to access this endpoint, such as Client Authentication as described 186 in [OAuth2] or a separate OAuth access token. The methods of 187 managing and validating these authentication credentials are out of 188 scope of this specification. 190 For any of the resource owner's sets of resources this authorization 191 server needs to be aware of, the resource server MUST register these 192 resource sets at the authorization server's registration endpoint. 194 2.1. Scope Descriptions 196 A scope description is a JSON document with the following properties: 198 name REQUIRED. A human-readable string describing some scope 199 (extent) of access. This name MAY be used by the authorization 200 server in any user interface it presents to the resource owner. 202 icon_uri OPTIONAL. A URI for a graphic icon representing the scope. 203 The referenced icon MAY be used by the authorization server in any 204 user interface it presents to the resource owner. 206 For example, this scope description characterizes a scope that 207 involves reading or viewing resources (vs. creating them or editing 208 them in some fashion): 210 { 211 "name" : "View", 212 "icon_uri" : "http://www.example.com/icons/reading-glasses" 213 } 215 See Section 8 for a long-form example of scope descriptions used in 216 resource set registration. 218 2.2. Resource Set Descriptions 220 The resource server defines a resource set that the authorization 221 server needs to be aware of by registering a resource set description 222 at the authorization server. This registration process results in a 223 unique identifier for the resource set that the resource server can 224 later use for managing its description. 226 The resource server is free to use its own methods of describing 227 resource sets. A resource set description is a JSON document with 228 the following properties: 230 name REQUIRED. A human-readable string describing a set of one or 231 more resources. This name MAY be used by the authorization server 232 in its resource owner user interface for the resource owner. 234 uri OPTIONAL. A URI that provides the network location for the 235 resource set being registered. For example, if the resource set 236 corresponds to a digital photo, the value of this property could 237 be an HTTP-based URI identifying the location of the photo on the 238 web. The authorization server can use this information in various 239 ways to inform clients about a resource set's location. 241 type OPTIONAL. A string uniquely identifying the semantics of the 242 resource set. For example, if the resource set consists of a 243 single resource that is an identity claim that leverages 244 standardized claim semantics for "verified email address", the 245 value of this property could be an identifying URI for this claim. 247 scopes REQUIRED. An array of strings, any of which MAY be a URI, 248 indicating the available scopes for this resource set. URIs MUST 249 resolve to scope descriptions as defined in Section 2.1. 250 Published scope descriptions MAY reside anywhere on the web; a 251 resource server is not required to self-host scope descriptions 252 and may wish to point to standardized scope descriptions residing 253 elsewhere. It is the resource server's responsibility to ensure 254 that scope description documents are accessible to authorization 255 servers through GET calls to support any user interface 256 requirements. The resource server and authorization server are 257 presumed to have separately negotiated any required interpretation 258 of scope handling not conveyed through scope descriptions. 260 icon_uri OPTIONAL. A URI for a graphic icon representing the 261 resource set. The referenced icon MAY be used by the 262 authorization server in its resource owner user interface for the 263 resource owner. 265 For example, this description characterizes a resource set (a photo 266 album) that can potentially be only viewed, or alternatively to which 267 full access can be granted; the URIs point to scope descriptions as 268 defined in Section 2.1: 270 { 271 "name" : "Photo Album", 272 "icon_uri" : "http://www.example.com/icons/flower.png", 273 "scopes" : [ 274 "http://photoz.example.com/dev/scopes/view", 275 "http://photoz.example.com/dev/scopes/all" 276 ], 277 "type" : "http://www.example.com/rsets/photoalbum" 278 } 280 2.3. Resource Set Registration API 282 The resource server uses the RESTful API at the authorization 283 server's resource set registration endpoint to create, read, update, 284 and delete resource set descriptions, along with retrieving lists of 285 such descriptions. 287 (Note carefully the similar but distinct senses in which the word 288 "resource" is used in this section. The resource set descriptions 289 are themselves managed as web resources at the authorization server 290 through this API.) 292 The authorization server MUST present an API for registering resource 293 set descriptions at a set of URIs with the following structure: 295 {rsreguri}/resource_set/{rsid} 297 The method of authentication that the resource server uses SHOULD 298 sufficient context to distinguish between identical resource set 299 identifiers assigned by different resource servers. 301 The components of these URIs are defined as follows: 303 {rsreguri} The authorization server's resource set registration 304 endpoint as advertised in its configuration data (see 305 Section 1.3). 307 {rsid} An identifier for a resource set description. It is 308 RECOMMENDED to obscure resource set identifiers in order to avoid 309 leaking personally identifiable information to clients in case a 310 client is exposed to resource set or scope description 311 information. 313 Following is a summary of the five registration operations the 314 authorization server is REQUIRED to support. Each is defined in its 315 own section below. All other methods are unsupported. This API uses 316 ETag and If-Match to ensure the desired resource at the authorization 317 server is targeted. 319 o Create resource set description: PUT /resource_set/{rsid} 321 o Read resource set description: GET /resource_set/{rsid} 323 o Update resource set description: PUT /resource_set/{rsid} with If- 324 Match 326 o Delete resource set description: DELETE /resource_set/{rsid} 327 o List resource set descriptions: GET /resource_set/ with If-Match 329 If the request to the resource set registration endpoint is 330 incorrect, then the authorization server responds with an error 331 message by including one of the following error codes with the 332 response (see Section 3): 334 unsupported_method_type The resource server request used an 335 unsupported HTTP method. The authorization server MUST respond 336 with the HTTP 405 (Method Not Allowed) status code and MUST fail 337 to act on the request. 339 not_found The resource set requested from the authorization server 340 cannot be found. The authorization server MUST respond with HTTP 341 404 (Not Found) status code. 343 precondition_failed The resource set that was requested to be 344 deleted or updated at the authorization server did not match the 345 If-Match value present in the request. The authorization server 346 MUST respond with HTTP 412 (Precondition Failed) status code and 347 MUST fail to act on the request. 349 2.3.1. Create Resource Set Description 351 Adds a new resource set description using the PUT method. If the 352 request is successful, the authorization server MUST respond with a 353 status message that includes an ETag header and an _id property for 354 managing resource set description versioning. 356 Form of a "create resource set description" HTTP request, with an 357 access token in the header: 359 PUT /resource_set/{rsid} HTTP/1.1 360 Content-Type: application/json 361 Authorization: Bearer 204c69636b6c69 362 ... 364 (body contains JSON resource set description to be created) 365 Form of a successful HTTP response: 367 HTTP/1.1 201 Created 368 Content-Type: application/json 369 ETag: ... 370 ... 372 { 373 "_id" : (id of created resource set) 374 } 376 On successful registration, the authorization server MAY return a 377 redirect policy URI to the resource server in a property with the 378 name "policy_uri". This URI allows the resource server to redirect 379 the resource owner to a specific user interface within the 380 authorization server where the resource owner can immediately set or 381 modify access policies for the resource set that was just registered. 383 Form of a successful HTTP response: 385 HTTP/1.1 201 Created 386 Content-Type: application/json 387 ETag: ... 388 ... 390 { 391 "_id" : (id 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 an _id 400 property for managing resource set description versioning. 402 Form of a "read resource set description" HTTP request, with an 403 access token in the header: 405 GET /resource_set/{rsid} HTTP/1.1 406 Authorization: Bearer 204c69636b6c69 407 ... 409 Form of a successful HTTP response: 411 HTTP/1.1 200 OK 412 Content-Type: application/json 413 ... 415 (body contains JSON resource set description, including _id) 417 If the referenced resource does not exist, the authorization server 418 MUST produce an error response with an error property value of 419 "not_found", as defined in Section 2.3. 421 On successful read, the authorization server MAY return a redirect 422 policy URI to the resource server in a property with the name 423 "policy_uri". This URI allows the resource server to redirect the 424 resource owner to a specific user interface within the authorization 425 server where the resource owner can immediately set or modify access 426 policies for the resource set that was read. 428 2.3.3. Update Resource Set Description 430 Updates a previously registered resource set description using the 431 PUT method. If the request is successful, the authorization server 432 MUST respond with a status message that includes an ETag header and 433 _id and _rev properties for managing resource set description 434 versioning. 436 Form of an "update resource set description" HTTP request, with an 437 access token in the header: 439 PUT /resource_set/{rsid} HTTP/1.1 440 Content-Type: application/json 441 If-Match: (entity tag of resource) 442 Authorization: Bearer 204c69636b6c69 443 ... 445 (body contains JSON resource set description to be updated) 447 Form of a successful HTTP response: 449 HTTP/1.1 204 No Content 450 ETag: "2" 451 ... 453 If the entity tag does not match, the authorization server MUST 454 produce an error response with an error property value of 455 "precondition_failed", as defined in Section 2.3. 457 On successful update, the authorization server MAY return a redirect 458 policy URI to the resource server in a property with the name 459 "policy_uri". This URI allows the resource server to redirect the 460 user to a specific user interface within the authorization server 461 where the user can immediately set or modify access policies for the 462 resource set that was just updated. 464 2.3.4. Delete Resource Set Description 466 Deletes a previously registered resource set description using the 467 DELETE method, thereby removing it from the authorization server's 468 protection regime. 470 Form of a "delete resource set description" HTTP request, with an 471 access token in the header: 473 DELETE /resource_set/{rsid} 474 If-Match: (entity tag of resource) 475 Authorization: Bearer 204c69636b6c69 476 ... 478 Form of a successful HTTP response: 480 HTTP/1.1 204 No content 481 ... 483 As defined in Section 2.3, if the referenced resource does not exist 484 the authorization server MUST produce an error response with an error 485 property value of "not_found", and if the entity tag does not match 486 the authorization server MUST produce an error response with an error 487 property value of "precondition_failed". 489 2.3.5. List Resource Set Descriptions 491 Lists all previously registered resource set identifiers for this 492 user using the GET method. The authorization server MUST return the 493 list in the form of a JSON array of {rsid} values. 495 The resource server uses this method as a first step in checking 496 whether its understanding of protected resources is in full 497 synchronization with the authorization server's understanding. 499 Form of a "list resource set descriptions" HTTP request, with an 500 access token in the header: 502 GET /resource_set HTTP/1.1 503 Authorization: Bearer 204c69636b6c69 504 ... 506 HTTP response: 508 HTTP/1.1 200 OK 509 ... 511 (body contains JSON array of {rsid} values) 513 3. Error Messages 515 When a resource server attempts to access the resource set 516 registration endpoint at the authorization server, if the request is 517 successfully authenticated by OAuth means, but is invalid for another 518 reason, the authorization server produces an error response by adding 519 the following properties to the entity body of the HTTP response: 521 error REQUIRED. A single error code, as noted in the API 522 definition. Value for this property is defined in the specific 523 authorization server endpoint description. 525 error_description OPTIONAL. A human-readable text providing 526 additional information, used to assist in the understanding and 527 resolution of the error occurred. 529 error_uri OPTIONAL. A URI identifying a human-readable web page 530 with information about the error, used to provide the end-user 531 with additional information about the error. 533 4. Security Considerations 535 This specification relies on OAuth for API security and shares its 536 security and vulnerability considerations. 538 5. Privacy Considerations 540 The communication between the authorization server and resource 541 server may expose personally identifiable information. The context 542 in which this API is used SHOULD deal with its own unique privacy 543 considerations. 545 6. Conformance 547 This specification makes optional normative reference to [OAuth2] for 548 API protection. This specification is anticipated to be used as a 549 module in higher-order specifications, where additional constraints 550 and profiling may appear. 552 7. IANA Considerations 554 This document makes no request of IANA. 556 8. Example of Registering Resource Sets 558 The following example illustrates the intent and usage of resource 559 set descriptions and scope descriptions as part of resource set 560 registration in the context of [UMA]. 562 This example contains some steps that are exclusively in the realm of 563 user experience rather than web protocol, to achieve realistic 564 illustration. These steps are labeled "user experience only". Some 565 other steps are exclusively internal to the operation of the entity 566 being discussed. These are labeled "internal only". 568 A resource owner, Alice Adams, has just uploaded a photo of her new 569 puppy to a resource server, Photoz.example.com, and wants to ensure 570 that this specific photo is not publicly accessible. 572 Alice has already introduced this resource server to her 573 authorization server, CopMonkey.example.com. However, Alice has not 574 previously instructed Photoz to use CopMonkey to protect any photos 575 of hers. 577 Alice has previously visited CopMonkey to map a default "do not share 578 with anyone" policy to any resource sets registered by Photoz, until 579 such time as she maps some other more permissive policies to those 580 resources. (User experience only. This may have been done at the 581 time Alice introduced the resource server to the authorization 582 server, and/or it could have been a global or resource server- 583 specific preference setting. A different constraint or no constraint 584 at all might be associated with newly protected resources.) Other 585 kinds of policies she may eventually map to particular photos or 586 albums might be "Share only with husband@email.example.net" or "Share 587 only with people in my 'family' group". 589 Photoz itself has a publicly documented application-specific API that 590 offers two dozen different methods that apply to single photos, such 591 as "addTags" and "getSizes", but rolls them up into two photo-related 592 scopes of access: "view" (consisting of various read-only operations) 593 and "all" (consisting of various reading, editing, and printing 594 operations). It defines two scope descriptions that represent these 595 scopes, which it is able to reuse for all of its users (not just 596 Alice), and ensures that these scope description documents are 597 available through HTTP GET requests that may be made by authorization 598 servers. 600 The "name" property values are intended to be seen by Alice when she 601 maps authorization constraints to specific resource sets and actions 602 while visiting CopMonkey, such that Alice would see the strings "View 603 Photo and Related Info" and "All Actions", likely accompanied by the 604 referenced icons, in the CopMonkey interface. (Other users of Photoz 605 might similarly see the same labels at CopMonkey or whatever other 606 authorization server they use. Photoz could distinguish natural- 607 language labels per user if it wishes, by pointing to scopes with 608 differently translated names.) 610 Example of the viewing-related scope description document available 611 at http://photoz.example.com/dev/scopes/view: 613 { 614 "name" : "View Photo and Related Info", 615 "icon_uri" : "http://www.example.com/icons/reading-glasses.png" 616 } 618 Example of the broader scope description document available at 619 http://photoz.example.com/dev/scopes/all: 621 { 622 "name" : "All Actions", 623 "icon_uri" : "http://www.example.com/icons/galaxy.png" 624 } 626 While visiting Photoz, Alice selects a link or button that instructs 627 the site to "Protect" or "Share" this single photo (user experience 628 only; Photoz could have made this a default or preference setting). 630 As a result, Photoz defines for itself a resource set that represents 631 this photo (internal only; Photoz is the only application that knows 632 how to map a particular photo to a particular resource set). Photoz 633 also prepares the following resource set description, which is 634 specific to Alice and her photo. The "name" property value is 635 intended to be seen by Alice in mapping authorization policies to 636 specific resource sets and actions when she visits CopMonkey. Alice 637 would see the string "Steve the puppy!", likely accompanied by the 638 referenced icon, in the CopMonkey interface. The possible scopes of 639 access on this resource set are indicated with URI references to the 640 scope descriptions, as shown just above. 642 { 643 "name" : "Steve the puppy!", 644 "icon_uri" : "http://www.example.com/icons/flower", 645 "scopes" : [ 646 "http://photoz.example.com/dev/scopes/view", 647 "http://photoz.example.com/dev/scopes/all" 648 ] 649 } 651 Photoz uses the "create resource set description" method of 652 CopMonkey's standard OAuth resource set registration API, presenting 653 its Alice-specific access token to use the API to register and assign 654 an identifier to the resource set description. 656 PUT /resource_set/112210f47de98100 HTTP/1.1 657 Content-Type: application/json 658 ... 660 { 661 "name" : "Steve the puppy!", 662 "icon_uri" : "http://www.example.com/icons/flower.png", 663 "scopes" : [ 664 "http://photoz.example.com/dev/scopes/view", 665 "http://photoz.example.com/dev/scopes/all" 666 ] 667 } 669 If the registration attempt succeeds, CopMonkey responds in the 670 following fashion. 672 HTTP/1.1 201 Created 673 Content-Type: application/json 674 ETag: "1" 675 ... 677 { 678 "_id" : "112210f47de98100" 679 } 681 At the time Alice indicates she would like this photo protected, 682 Photoz can choose to redirect Alice to CopMonkey for further policy 683 setting, access auditing, and other authorization server-related 684 tasks (user experience only). 686 Once it has successfully registered this description, Photoz is 687 responsible for outsourcing protection to CopMonkey for access 688 attempts made to this photo. 690 Over time, as Alice uploads other photos and creates and organizes 691 photo albums, Photoz can use additional methods of the resource set 692 registration API to ensure that CopMonkey's understanding of Alice's 693 protected resources matches its own. 695 For example, if Photoz suspects that somehow its understanding of the 696 resource set has gotten out of sync with CopMonkey's, it can ask to 697 read the resource set description as follows. 699 GET /resource_set/112210f47de98100 HTTP/1.1 700 Host: as.example.com 701 ... 703 CopMonkey responds with the full content of the resource set 704 description, including its _id, as follows: 706 Example of an HTTP response to a "read resource set description" 707 request, containing a resource set description from the authorization 708 server: 710 HTTP/1.1 200 OK 711 Content-Type: application/json 712 ETag: "1" 713 ... 715 { 716 "_id" : "112210f47de98100", 717 "name" : "Photo album", 718 "icon_uri" : "http://www.example.com/icons/flower.png", 719 "scopes" : [ 720 "http://photoz.example.com/dev/scopes/view", 721 "http://photoz.example.com/dev/scopes/all" 722 ] 723 } 725 If for some reason Photoz and CopMonkey have gotten dramatically out 726 of sync, Photoz can ask for the list of resource set identifiers 727 CopMonkey currently knows about: 729 GET /resource_set HTTP/1.1 730 Host: as.example.com 731 ... 733 CopMonkey's response might look as follows: 735 HTTP/1.1 200 OK 736 ... 738 [ "112210f47de98100", "34234df47eL95300" ] 740 If Alice later changes the photo's title (user experience only) on 741 Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz 742 would use the "update resource set description" method to ensure that 743 Alice's experience of policy-setting at CopMonkey remains consistent 744 with what she sees at Photoz. Following is an example of this 745 request. 747 PUT /resource_set/112210f47de98100 HTTP/1.1 748 Content-Type: application/json 749 Host: as.example.com 750 If-Match: "1" 751 ... 753 { 754 "name" : "Steve on October 14, 2011", 755 "icon_uri" : "http://www.example.com/icons/flower.png", 756 "scopes" : [ 757 "http://photoz.example.com/dev/scopes/view", 758 "http://photoz.example.com/dev/scopes/all" 759 ] 760 } 762 CopMonkey would respond as follows. 764 HTTP/1.1 201 Created 765 Content-Type: application/json 766 ETag: "2" 767 ... 769 { 770 "_id" : "112210f47de98100" 771 } 773 There are other reasons Photoz might want to update resource set 774 descriptions, having nothing to do with Alice's actions or wishes. 775 For example, it might extend its API to include new features, and 776 want to add new scopes to all of Alice's and other users' resource 777 set descriptions. 779 if Alice later decides to entirely remove sharing protection (user 780 experience only) on this photo while visiting Photoz, ensuring that 781 the public can get access without any protection, Photoz is 782 responsible for deleting the relevant resource set registration, as 783 follows: 785 DELETE /resource_set/112210f47de98100 HTTP/1.1 786 Host: as.example.com 787 If-Match: "2" 788 ... 790 9. Acknowledgments 792 The following people made significant text contributions to the 793 specification: 795 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 797 o Mark Dobrinic, Cozmanova 799 o George Fletcher, AOL 801 o Lukasz Moren, Cloud Identity Ltd 803 o Christian Scholz, COMlounge GmbH (former editor) 805 o Mike Schwartz, Gluu 807 o Jacek Szpot, Newcastle University 809 Additional contributors to this specification include the Kantara UMA 810 Work Group participants, a list of whom can be found at 811 [UMAnitarians]. 813 10. References 815 10.1. Normative References 817 [JSON] Bray, T., "The JavaScript Object Notation (JSON) Data 818 Interchange Format", March 2014, 819 . 821 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 822 October 2012, . 824 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 825 Requirement Levels", BCP 14, RFC 2119, March 1997. 827 10.2. Informative References 829 [OpenIDConnect] 830 Sakimura, N., "OpenID Connect Core 1.0 incorporating 831 errata set 1", November 2014, 832 . 834 [UMA] Hardjono, T., "User-Managed Access (UMA) Profile of OAuth 835 2.0", December 2014, 836 . 839 [UMAnitarians] 840 Maler, E., "UMA Participant Roster", December 2014, 841 . 844 10.3. URIs 846 [1] http://kantarainitiative.org/confluence/display/uma/ 847 UMA+1.0+Core+Protocol 849 Appendix A. Document History 851 NOTE: To be removed by RFC editor before publication as an RFC. 853 See [1] for a list of code-breaking and other major changes made to 854 this specification at various revision points. 856 Authors' Addresses 858 Thomas Hardjono (editor) 859 MIT 861 Email: hardjono@mit.edu 863 Eve Maler 864 ForgeRock 866 Email: eve.maler@forgerock.com 868 Maciej Machulak 869 Cloud Identity 871 Email: maciej.machulak@cloudidentity.co.uk 872 Domenico Catalano 873 Oracle 875 Email: domenico.catalano@oracle.com