idnits 2.17.1 draft-hardjono-oauth-umacore-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 : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 9 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 29, 2012) is 4382 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. 'OAuth-bearer' -- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth2' -- Possible downref: Non-RFC (?) normative reference: ref. 'OCDynClientReg' -- Possible downref: Non-RFC (?) normative reference: ref. 'OCMessages' -- Possible downref: Non-RFC (?) normative reference: ref. 'OCStandard' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 6 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 March 29, 2012 5 Expires: September 30, 2012 7 User-Managed Access (UMA) Core Protocol 8 draft-hardjono-oauth-umacore-04 10 Abstract 12 This specification defines the User-Managed Access (UMA) core 13 protocol. This protocol provides a method for users to control 14 access to their protected resources, residing on any number of host 15 sites, through an authorization manager that governs access decisions 16 based on user policy. 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 September 30, 2012. 35 Copyright Notice 37 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 6 54 1.2. Basic Terminology . . . . . . . . . . . . . . . . . . . . 6 55 1.3. Endpoints, Endpoint Protection, and Tokens . . . . . . . . 8 56 1.4. Scopes, Resource Sets, Permissions, and Authorization . . 10 57 1.5. AM Configuration Data . . . . . . . . . . . . . . . . . . 11 58 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 13 59 2.1. Host Looks Up AM Configuration Data . . . . . . . . . . . 14 60 2.2. Host Registers with AM . . . . . . . . . . . . . . . . . . 15 61 2.3. Host Obtains Protection API Token . . . . . . . . . . . . 15 62 2.4. Host Registers Sets of Resources to Be Protected . . . . . 15 63 2.4.1. Scope Descriptions . . . . . . . . . . . . . . . . . . 16 64 2.4.2. Resource Set Descriptions . . . . . . . . . . . . . . 17 65 2.4.3. Resource Set Registration API . . . . . . . . . . . . 18 66 2.4.3.1. Create Resource Set Description . . . . . . . . . 19 67 2.4.3.2. Read Resource Set Description . . . . . . . . . . 20 68 2.4.3.3. Update Resource Set Description . . . . . . . . . 21 69 2.4.3.4. Delete Resource Set Description . . . . . . . . . 22 70 2.4.3.5. List Resource Set Descriptions . . . . . . . . . . 22 71 3. Getting Authorization and Accessing a Resource . . . . . . . . 23 72 3.1. Requester-Host: Attempt Access at Protected Resource . . . 24 73 3.1.1. Requester Presents No Requester Permission Token . . . 25 74 3.1.2. Requester Presents a Requester Permission Token 75 That Is Invalid Or Has Insufficient Permission . . . . 25 76 3.1.3. Requester Presents a Valid Requester Permission 77 Token . . . . . . . . . . . . . . . . . . . . . . . . 26 78 3.2. Host-AM: Register a Permission . . . . . . . . . . . . . . 26 79 3.3. Host-AM: Ask for Requester Permission Token Status . . . . 28 80 3.3.1. UMA Bearer Token Profile . . . . . . . . . . . . . . . 28 81 3.4. Requester-AM: Ask for Permission and Requester 82 Permission Token . . . . . . . . . . . . . . . . . . . . . 30 83 3.4.1. Requester Looks Up AM Configuration Data . . . . . . . 31 84 3.4.2. Requester Registers with AM . . . . . . . . . . . . . 31 85 3.4.3. Requester Obtains Authorization API Token . . . . . . 31 86 3.4.4. Requester-AM: Request Authorization to Add 87 Permission . . . . . . . . . . . . . . . . . . . . . . 32 88 3.5. Claims-Gathering Flows . . . . . . . . . . . . . . . . . . 34 89 3.5.1. Claims-Gathering Flow for Requester Apps Operated 90 by End-Users . . . . . . . . . . . . . . . . . . . . . 34 91 3.5.1.1. OpenID Connect Claim Profile . . . . . . . . . . . 35 92 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . . 36 93 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 36 94 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 36 95 5. Security Considerations . . . . . . . . . . . . . . . . . . . 37 96 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 38 97 7. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 38 98 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 99 9. Example of Registering Resource Sets . . . . . . . . . . . . . 39 100 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 101 11. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 102 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 103 12.1. Normative References . . . . . . . . . . . . . . . . . . . 45 104 12.2. Informative References . . . . . . . . . . . . . . . . . . 46 105 Appendix A. Document History . . . . . . . . . . . . . . . . . . 47 106 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 48 108 1. Introduction 110 The User-Managed Access (UMA) core protocol provides a method based 111 on OAuth 2.0 [OAuth2] for users to control access to their protected 112 resources, residing on any number of host sites, through a single 113 authorization manager (AM) that governs access decisions based on 114 user policy. 116 There are numerous use cases for UMA, where a resource owner elects 117 to have a third party to control access to these resources 118 potentially without the real-time presence of the resource owner. A 119 typical example is the following: a web user (authorizing user) can 120 authorize a web app (requester) to gain one-time or ongoing access to 121 a resource containing his home address stored at a "personal data 122 store" service (host), by telling the host to act on access decisions 123 made by his authorization decision-making service (authorization 124 manager or AM). The requesting party might be an e-commerce company 125 whose site is acting on behalf of the user himself to assist him/her 126 in arranging for shipping a purchased item, or it might be his friend 127 who is using an online address book service to collect addresses, or 128 it might be a survey company that uses an online service to compile 129 population demographics. Other scenarios and use cases for UMA usage 130 can be found in [UMA-usecases] and [UMA-userstories]. 132 In enterprise settings, application access management often involves 133 letting back-office applications serve only as policy enforcement 134 points (PEPs), depending entirely on access decisions coming from a 135 central policy decision point (PDP) to govern the access they give to 136 requesters. This separation eases auditing and allows policy 137 administration to scale in several dimensions. UMA makes use of a 138 separation similar to this, letting the authorizing user serve as a 139 policy administrator crafting authorization strategies on his or her 140 own behalf. 142 The UMA protocol can be considered an advanced application of 143 [OAuth2] in that it profiles, extends, and embeds OAuth in various 144 ways. In the big picture, an AM can be thought of as an enhanced 145 OAuth authorization server; a host as an enhanced resource server; 146 and a requester as an enhanced client, acquiring an access token and 147 the requisite authorization to access a protected resource at the 148 host. 150 The UMA protocol has three broad phases, as shown in Figure 1. 152 The Three Phases of the UMA Protocol 153 +-----+----------------+ 154 | UA | authorizing | 155 +-------Manage (A)--| | user | 156 | +-----+----------------+ 157 | Phase 1: | UA | 158 | protect a +----------------+ 159 | resource | 160 | Control (B) 161 | | 162 v v 163 +-----------+ +-----+----------------+ 164 | host |<-Protect-(C)-|prot | authorization | 165 | | | API | manager (AM) | 166 +-----------+ +-----+----------------+ 167 | protected | | authorization | 168 | resource | | API | 169 +-----------+ +----------------+ 170 ^ | 171 | Phases 2 and 3: Authorize (D) 172 | get authz and | 173 | access a resource v 174 | +----------------+ 175 +-------Access (E)--------| requester | 176 +----------------+ 177 (requesting party) 179 Figure 1 181 In broad strokes, the phases are as follows: 183 1. Protect a resource (described in Section 2). 185 2. Get authorization (described in Section 3). 187 3. Access a resource (described along with Phase 2 in Section 3). 189 In more detail, the phases work as follows: 191 1. _Protect a resource:_ The authorizing user has chosen to use a 192 host for managing online resources ("A"), and introduces this 193 host to an AM using an OAuth-mediated interaction that results in 194 the AM giving the host a protection API token (PAT). The host 195 uses AM's protection API to tell the AM what sets of resources to 196 protect ("C"). Out of band of the UMA protocol, the authorizing 197 user instructs the AM what policies to attach to the registered 198 resource sets ("B"). Requesters are not yet in the picture. 200 2. _Get authorization:_ This phase involves the requester (along 201 with its operator, the requesting party or that party's human 202 agent), host, and AM. It may also involve synchronous action by 203 the authorizing user if this person is the same person as the 204 requesting party. This phase is dominated by a loop of activity 205 in which the requester approaches the host seeking access to a 206 protected resource ("E"). In order to access the protected 207 resource at the host, the requester must obtain a requester 208 permission token (RPT) from the AM. The requester is then 209 directed to the AM ask for authorization for the permissions it 210 seeks. In doing so, it must demonstrate to the AM that it 211 satisfies the resource owner's authorization policy governing the 212 sought-for resource and scope of access if it does not already 213 have the required access permission ("D"). To use the AM's 214 authorization API in the first place, the requesting party has to 215 consent to deal with the AM in providing claims, which results in 216 the requester obtaining an authorization API token (AAT) from the 217 AM. 219 3. _Access a resource:_ This phase involves the requester 220 successfully presenting an RPT that has sufficient permission 221 associated with it to the host in order to gain access to the 222 desired resource ("E"). In this sense, it is the "happy path" 223 within phase 2. 225 1.1. Notational Conventions 227 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 228 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 229 document are to be interpreted as described in [RFC2119]. 231 Unless otherwise noted, all the protocol properties and values are 232 case sensitive. 234 1.2. Basic Terminology 236 UMA introduces the following terms, utilizing OAuth and other 237 identity and access management concepts. 239 authorizing user 240 The "user" in User-Managed Access. An UMA-defined variant of 241 an OAuth resource owner, typically a web user who configures an 242 authorization manager with policies that control how it assigns 243 access permissions to requesters for a protected resource. The 244 authorizing user can also be corporation or other legal person. 246 authorization manager (AM) 247 An UMA-defined variant of an OAuth authorization server that 248 carries out an authorizing user's policies governing access to 249 a protected resource. 251 protected resource 252 An access-restricted resource at a host, which is being policy- 253 protected by an AM. 255 host 256 An UMA-defined variant of an OAuth resource server that 257 enforces access to the protected resources it hosts, as 258 governed by an authorization manager. 260 claim 261 A statement of the value or values of one or more identity 262 attributes of a requesting party. A requesting party may need 263 to provide claims to an authorization manager in order to 264 satisfy policy and gain permission for access to a protected 265 resource. 267 requester 268 An UMA-defined variant of an OAuth client that seeks access to 269 a protected resource. 271 requesting party 272 A web user, or a corporation or other legal person, that uses a 273 requester to seek access to a protected resource. The 274 requesting party may or may not be the same person as the 275 authorizing user. 277 resource set A host-managed set of one or more resources to be AM- 278 protected. In authorization policy terminology, a resource set 279 is the "object" being protected. 281 scope A bounded extent of access that is possible to perform on a 282 resource set. In authorization policy terminology, a scope is 283 one of the potentially many "verbs" that can logically apply to 284 a resource set. Whereas OAuth scopes apply to resource sets 285 that are implicit, UMA associates scopes with explicitly 286 labeled resource sets ("objects"). 288 permission A scope of access over a particular resource set at a 289 particular host that is being asked for by, or being granted 290 to, a requester. In authorization policy terminology, a 291 permission includes a "subject" (requesting party), "verbs" 292 (one or more scopes of access), and an "object" (resource set). 294 1.3. Endpoints, Endpoint Protection, and Tokens 296 Various UMA entities present protected APIs for other UMA entities to 297 use. These APIs are as follows: 299 o The AM presents a _protection API_ to the host, as standardized by 300 this specification. This API is OAuth-protected, requiring a host 301 to obtain from the AM an OAuth access token, referred to in this 302 specification as a _protection API token (PAT)_ to distinguish it 303 from other tokens with other purposes. The host must present the 304 PAT for successful use of OAuth-protected endpoints at this API. 306 o The AM presents an _authorization API_ to the requester, as 307 standardized by this specification. This API is OAuth-protected, 308 requiring a requester to obtain from the AM an OAuth access token, 309 referred to in this specification as an _authorization API token 310 (AAT)_ to distinguish it from other tokens with other purposes. 311 The requester must present the AAT for successful use of OAuth- 312 protected endpoints at this API. 314 o The host presents a _protected resource_ to the requester, which 315 can be considered an application-specific or proprietary API. 316 This API is UMA-protected, requiring a requester to obtain from 317 the AM an UMA-specific token referred to in this specification as 318 a _requester permission token (RPT)_ to distinguish it from other 319 tokens with other purposes. The requester must present the RPT 320 with sufficient permissions (also issued by the AM) for successful 321 access to an UMA-protected resource. 323 The AM presents standard OAuth endpoints for token issuance and user 324 authorization in protecting its own UMA APIs, as follows. Hosts 325 asking to use the protection API would be issued a PAT. Requesters 326 asking to use the authorization API would be issued an AAT. 328 token endpoint Part of standard OAuth, as profiled by UMA. The 329 endpoint at which the host asks for a PAT and the requester 330 asks for an AAT. (The AM may also choose to issue a refresh 331 token.) This specification makes the OAuth token profile 332 "bearer" mandatory for the AM to implement. The AM can declare 333 its ability to handle other token profiles. 335 user authorization endpoint Part of standard OAuth, as profiled by 336 UMA. The endpoint to which the host or requester redirects an 337 authorizing user or end-user requesting party, respectively, to 338 authorize it to use this AM in resource protection or 339 authorization, if the OAuth authorization code grant type 340 (mandatory for the AM to implement) is being used. 342 The AM presents the following endpoints to the host as part of its 343 protection API; these endpoints are OAuth-protected and require a PAT 344 for access, for which the "protection" OAuth scope is required: 346 resource set registration endpoint The endpoint at which the host 347 registers resource sets it wants the AM to protect. The 348 operations available at this endpoint constitute a resource set 349 registration API that is a subset of the protection API (see 350 Section 2.4.3). 352 permission registration endpoint The endpoint at which the host 353 registers permissions that it anticipates a requester will 354 shortly be asking for from the AM. 356 RPT status endpoint The endpoint at which the host submits 357 (forwards) an RPT that has accompanied an access request, to 358 learn what currently valid permissions are associated with it. 359 This specification defines an UMA token profile, "bearer", 360 which is mandatory for the AM to implement and which, if used, 361 REQUIRES the host to use this endpoint (see Section 3.3). 363 The AM presents the following endpoint to the requester as part of 364 its authorization API; this endpoint is OAuth-protected and requires 365 an AAT for access, for which the "authorization" OAuth scope is 366 required: 368 permission request endpoint The endpoint at which the requester asks 369 for authorization to have permissions associated with an RPT 370 and, as necessary, asks for issuance of an RPT. 372 The host presents one or more protected resource endpoints to the 373 requester; these endpoints are UMA-protected and require an RPT with 374 sufficient permissions for access: 376 protected resource endpoint An application-specific endpoint at 377 which a requester attempts to access resources. This can be a 378 singular API endpoint, one of a set of API endpoints, a URI 379 corresponding to an HTML document, or any other URI. 381 Similarly to OAuth authorization servers, an UMA AM has the 382 opportunity to manage the validity periods of the access tokens, the 383 corresponding refresh tokens (in the case of the PAT and AAT), and 384 even the client credentials that it issues. Different lifetime 385 strategies may be suitable for different resources and scopes of 386 access, and the AM has the opportunity to give the authorizing user 387 control through policy. These options are all outside the scope of 388 this specification. 390 1.4. Scopes, Resource Sets, Permissions, and Authorization 392 UMA extends the OAuth concept of a "scope" by defining scopes as 393 applying to particular labeled resource sets, rather than leaving the 394 relevant resources (such as API endpoints or URIs) implicit. A 395 resource set can have any number of scopes, which together describe 396 the universe of actions that _can be_ taken on this protected 397 resource set. For example, a resource set representing a status 398 update API might have scopes that include adding an update or reading 399 updates. A resource set representing a photo album might have scopes 400 that include viewing a slideshow or printing the album. Hosts 401 register resource sets and their scopes when there is not yet any 402 particular requesting party or requester in the picture. 404 Resource sets and scopes have meaning only to hosts and their users, 405 in the same way that application-specific host APIs have meaning only 406 to these entities. The AM is merely a conveyor of labels and 407 descriptions for these constructs, to help the authorizing user set 408 policies that guide eventual authorization processes. 410 In contrast to an UMA scope, an UMA permission reflects an _actual_ 411 result of an authorization process for a specific requester (on 412 behalf of a specific requesting party) to access a particular 413 resource set in a scoped (bounded) manner. Hosts register permission 414 requests with AMs on behalf of requesters that have attempted access 415 there and transmit the resulting temporary permission tickets to 416 requesters. Requesters subsequently ask AMs for permissions to be 417 associated with their RPTs. AMs grant (or deny) permissions to 418 requesters. 420 An RPT is bound to a requesting party, the requester (client) being 421 used by that party, the host at which protected resources of interest 422 reside, and the AM that protects those resources. It becomes 423 associated with as many permissions as are appropriate for gaining 424 authorized access to resources protected at that host by any single 425 AM (even if those permissions apply to resources managed by two or 426 more different authorizing users at the same host using the same AM). 427 Each individual permission is associated, in addition, with the 428 authorizing user whose policies drove the authorization process. 429 This enables meaningful, auditable, and potentially legally 430 enforceable authorization for access (see [UMA-trustmodel]). 432 Unlike UMA scopes (but similarly to tokens themselves; see 433 Section 1.3), permissions have a validity period that the AM has the 434 opportunity to control independently or with input from the 435 authorizing user. These options are outside the scope of this 436 specification. 438 1.5. AM Configuration Data 440 The AM MUST provide configuration data to other entities it interacts 441 with in aJSON [RFC4627] document that resides in an /uma- 442 configuration directory at at its hostmeta [RFC6415] location. The 443 configuration data documents major conformance options supported by 444 the AM (described further in Section 7) and protection and 445 authorization API endpoints (as described in Section 1.3). 447 The configuration data has the following properties and a Content- 448 Type of application/uma-configuration+json. All endpoint URIs 449 supplied SHOULD require the use of a transport-layer security 450 mechanism such as TLS. 452 version 453 REQUIRED. The version of the UMA core protocol to which this 454 AM conforms. The value MUST be the string "1.0". 456 issuer 457 REQUIRED. A URI indicating the party operating the AM. 459 dynamic_client_registration_supported 460 OPTIONAL. Whether dynamic client registration, such as through 461 [OCDynClientReg], is supported for both hosts and requesters. 462 The value, if this property is present, the value MUST be the 463 string "yes" (dynamic registration is supported, using an 464 unspecified method) or "no" (it is not supported; hosts and 465 requesters are required to pre-register). The default is AM- 466 specific. This property is not currently extensible. (This 467 conformance option is largely a placeholder for now.) 469 oauth_token_profiles_supported 470 REQUIRED. PAT and AAT profiles produced by this AM. The 471 property value is an array of string values. Currently the 472 only string value for this property defined by this 473 specification is "bearer", corresponding to the OAuth bearer 474 token profile [OAuth-bearer]. The AM is REQUIRED to support 475 this profile, and to supply this string value explicitly. The 476 AM MAY declare its support for additional access token profiles 477 by providing a unique absolute URI in a string value in the 478 array for each one. 480 uma_token_profiles_supported 481 REQUIRED. RPT types produced by this AM. The property value 482 is an array of string values. Currently the only string value 483 for this property defined by this specification is "bearer", 484 whose associations the host MUST determine through a token 485 status interaction with the AM (see Section 3.3 for the 486 definition of this profile). The AM is REQUIRED to support the 487 UMA bearer token profile, and to supply this string value 488 explicitly. The AM MAY declare its support for RPTs using 489 additional UMA token profiles by providing a unique absolute 490 URI in a string value in the array for each one. 492 oauth_grant_types_supported 493 REQUIRED. OAuth grant types supported by this AM in issuing 494 PATs and AATs. The property value is an array of string 495 values. Each string value MUST be one of the grant_type values 496 defined in [OAuth2], or alternatively an extension grant type 497 indicated by a unique absolute URI. 499 claim_profiles_supported 500 OPTIONAL. Claim formats and associated sub-protocols for 501 gathering claims from requesting parties, as supported by this 502 AM. The property value is an array of string values. 503 Currently the only string value for this property defined by 504 this specification is "openid", for which details are supplied 505 in Section 3.5.1.1. The AM MAY declare its support for 506 additional claim profiles by assigning a unique absolute URI in 507 a string value in the array for each one. 509 token_endpoint 510 REQUIRED. The endpoint URI at which the host or requester asks 511 the AM for a PAT or AAT, respectively. A requested scope of 512 "protection" results in a PAT. A requested scope of 513 "authorization" results in an AAT. Available HTTP methods are 514 as defined by [OAuth2] for a token endpoint. 516 user_endpoint 517 REQUIRED. The endpoint URI at which the host gathers the 518 consent of the authorizing user or end-user requesting party, 519 if the "authorization_code" grant type is used. Available HTTP 520 methods are as defined by [OAuth2] for an end-user 521 authorization endpoint. 523 resource_set_registration_endpoint 524 REQUIRED. The endpoint URI at which the host registers 525 resource sets with the AM to put them under its protection (see 526 Section 2.4.3). A PAT MUST accompany requests to this 527 protected endpoint. 529 permission_registration_endpoint 530 REQUIRED. The endpoint URI at which the host registers 531 permissions with the AM for which a requester will be seeking 532 authorization (see Section 3.2). A PAT MUST accompany requests 533 to this protected endpoint. 535 rpt_status_endpoint 536 REQUIRED. The endpoint URI at which the host requests the 537 status of an RPT presented to it by a requester (see 538 Section 3.3). A PAT MUST accompany requests to this protected 539 endpoint. 541 permission_request_endpoint 542 REQUIRED. The endpoint URI at which the requester asks for 543 authorization to have a new permission associated with its RPT 544 (possibly assigned dynamically if it had not existed before). 545 An AAT MUST accompany requests to this protected endpoint. 547 Example of AM configuration data that resides at 548 https://example.com/.well-known/uma-configuration (note the use of 549 https: for endpoints throughout): 550 { 551 "version":"1.0", 552 "issuer":"https://example.com", 553 "dynamic_client_registration_supported":"yes", 554 "oauth_token_profiles_supported":[ 555 "bearer" 556 ], 557 "uma_token_profiles_supported":[ 558 "bearer" 559 ], 560 "oauth_grant_types_supported":[ 561 "authorization_code" 562 ], 563 "claim_profiles_supported":[ 564 "openid" 565 ], 566 "token_endpoint":"https://am.example.com/token_uri", 567 "user_endpoint":"https://am.example.com/user_uri", 568 "resource_set_registration_endpoint":"https://am.example.com/host/rsrc_uri", 569 "rpt_status_endpoint":"https://am.example.com/host/status_uri", 570 "permission_registration_endpoint":"https://am.example.com/host/perm_uri", 571 "permission_request_endpoint":"https://am.example.com/requester/perm_uri" 572 } 574 AM configuration data MAY contain extension properties that are not 575 defined in this specification. Extension names that are unprotected 576 from collisions are outside the scope of the current specification. 578 2. Protecting a Resource 580 Phase 1 of UMA is protecting a resource. The user, host, and AM 581 perform the following steps in order to successfully complete Phase 582 1: 584 1. The host (having learned the general location of the relevant AM 585 out of band) looks up the AM's configuration data and learns 586 about its relevant endpoints and supported formats. 588 2. If the host has not yet obtained a unique OAuth client identifier 589 and optional secret from the AM, it registers with the AM as 590 required. It MAY do this using [OCDynClientReg], if the AM 591 supports it. 593 3. The host obtains a protection API token (PAT) from the AM with 594 the authorizing user's consent, by asking for the "protection" 595 scope. 597 4. The host registers any resource sets with the AM that are 598 intended to be protected. (This step is repeated when and as 599 needed.) 601 If the host undertakes these actions successfully, the results are as 602 follows: 604 o The host has received configuration data about the AM, such as 605 endpoints it needs to use in interacting with the AM. 607 o The host has received a PAT that represents this authorizing 608 user's approval for the host to work with the AM in protecting 609 resources. 611 o The AM has acquired information about resource sets at this host 612 that it is supposed to protect on behalf of this authorizing user. 614 2.1. Host Looks Up AM Configuration Data 616 The host needs to learn the AM's protection API endpoints before they 617 can begin interacting. To get the host started in this process, the 618 authorizing user might provide the AM's location to it, for example, 619 by typing a URL into a web form field or clicking a button. 620 Alternatively, the host might already be configured to work with a 621 single AM without requiring any user input. The exact process is 622 beyond the scope of this specification, and it is up to the host to 623 choose a method to learn the AM's general location. 625 From the data provided, discovered, or configured, the host MUST 626 retrieve the AM's configuration data document, as described in 627 Section 2 of hostmeta [RFC6415]. For example, if the user supplied 628 "example.com" as the Authorization Manager's domain, the host creates 629 the URL "https://example.com/.well-known/uma-configuration" and 630 performs a GET request on it. The AM MUST return content that 631 includes UMA protection API endpoints as defined in Section 1.5. 633 2.2. Host Registers with AM 635 If the host has not already obtained an OAuth client identifier and 636 optional secret from this AM, in this step it MUST do so in order to 637 engage in OAuth-based interactions with the AM. It MAY do this using 638 [OCDynClientReg], if the AM supports it (see Section 1.5 for how the 639 AM MAY indicate support). 641 2.3. Host Obtains Protection API Token 643 In this step, the host acquires a PAT from the AM. The token 644 represents the approval of the authorizing user for this host to 645 trust this AM for protecting resources belonging to this user. 647 The host MUST use OAuth 2.0 [OAuth2] to obtain the protection API 648 token. Here the host acts in the role of an OAuth client requesting 649 the "protection" scope; the authorizing user acts in the role of an 650 OAuth end-user resource owner; and the AM acts in the role of an 651 OAuth authorization server. Once the host has obtained its PAT, it 652 presents it to the AM at various protection API endpoints; in 653 presenting these endpoints the AM acts in the role of a resource 654 server. 656 The AM MAY support the use of any grant type, but MUST support the 657 authorization_code grant type, and SHOULD support the SAML bearer 658 token grant type [OAuth-SAML] 659 (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates 660 working with hosts that are operating in environments where the use 661 of SAML is prevalent. The AM MUST indicate all grant types it 662 supports in its configuration data, as defined in Section 1.5. 664 The host has completed this step successfully when it possesses a PAT 665 it can use to get access to the AM's protection API on this user's 666 behalf. 668 2.4. Host Registers Sets of Resources to Be Protected 670 Once the host has received a PAT, for any of the user's sets of 671 resources that are to be protected by this AM, it MUST register these 672 resource sets at the AM's registration endpoint. 674 Note that the host is free to offer the option to protect any subset 675 of the user's resources using different AMs or other means entirely, 676 or to protect some resources and not others. Additionally, the 677 choice of protection regimes can be made explicitly by the user or 678 implicitly by the host. Any such partitioning by the host or user is 679 outside the scope of this specification. 681 See Section 9 for an extended example of registering resource sets. 683 2.4.1. Scope Descriptions 685 A scope is a bounded extent of access that is possible to perform on 686 a resource set. A scope description is a JSON document with the 687 following properties and a Content-Type of application/ 688 uma-scope+json: 690 name REQUIRED. A human-readable string describing some scope 691 (extent) of access. This name is intended for ultimate use in the 692 AM's user interface to assist the user in setting policies for 693 protected resource sets that have this available scope. 695 icon_uri OPTIONAL. A URI for a graphic icon representing the scope. 696 The referenced icon is intended for ultimate use in the AM's user 697 interface to assist the user in setting policies for protected 698 resource sets that have this available scope. 700 For example, this description characterizes a scope that involves 701 reading or viewing resources (vs. creating them or editing them in 702 some fashion): 704 { 705 "name": "View", 706 "icon_uri": "http://www.example.com/icons/reading-glasses" 707 } 709 Scope descriptions MAY contain extension properties that are not 710 defined in this specification. Extension names that are unprotected 711 from collisions are outside the scope of the current specification. 713 A host MUST list a resource set's available scopes using URI 714 references (as defined in Section 2.4.2). The scopes available for 715 use at any one host MUST have unique URI references so that the 716 host's scope descriptions are uniquely distinguishable. A scope URI 717 reference MAY include a fragment identifier. Scope descriptions MAY 718 reside anywhere. The host is not required to self-host scope 719 descriptions and may wish to point to standardized scope descriptions 720 residing elsewhere. Scope description documents MUST be accessible 721 to AMs through GET calls made to these URI references 723 See Section 1.4 for further discussion of scope-related concepts, and 724 Section 9 for a long-form example of scopes used in resource set 725 registration. 727 2.4.2. Resource Set Descriptions 729 The host defines a resource set that needs protection by registering 730 a resource set description at the AM. The host registers the 731 description and manages its lifecycle at the AM's host resource set 732 registration endpoint by using the resource set registration API, as 733 defined in Section 2.4.3. 735 A resource set description is a JSON document with the following 736 properties and a Content-Type of application/uma-resource-set+json: 738 name REQUIRED. A human-readable string describing a set of one or 739 more resources. The AM SHOULD use the name in its user interface 740 to assist the user in setting policies for protecting this 741 resource set. 743 icon_uri OPTIONAL. A URI for a graphic icon representing the 744 resource set. If provided, the AM SHOULD use the referenced icon 745 in its user interface to assist the user in setting policies for 746 protecting this resource set. 748 scopes REQUIRED. An array providing the URI references of scope 749 descriptions that are available for this resource set. The AM 750 SHOULD use the scope names and any icons defined as part of the 751 referenced scopes in its user interface to assist the user in 752 setting policies for protecting this resource set. 754 For example, this description characterizes a resource set (a photo 755 album) that can potentially be only viewed, or alternatively to which 756 full access can be granted; the URIs point to scope descriptions as 757 defined in Section 2.4.1: 759 { 760 "name": "Photo Album", 761 "icon_uri": "http://www.example.com/icons/flower.png", 762 "scopes": [ 763 "http://photoz.example.com/dev/scopes/view", 764 "http://photoz.example.com/dev/scopes/all" 765 ] 766 } 768 Resource set descriptions MAY contain extension properties that are 769 not defined in this specification. Extension names that are 770 unprotected from collisions are outside the scope of the current 771 specification. 773 When a host creates or updates a resource set description (see 774 Section 2.4.3), the AM MUST attempt to retrieve the referenced scope 775 descriptions. It MAY cache such descriptions as long as indicated in 776 the HTTP cache-control header for the scope description resource 777 unless the resource set description is subsequently updated within 778 the validity period. At the beginning of an authorizing user's login 779 session at the AM, the AM MUST attempt to re-retrieve scope 780 descriptions applying to that user whose cached versions have 781 expired. 783 2.4.3. Resource Set Registration API 785 The host uses the RESTful API at the AM's resource set registration 786 endpoint to create, read, update, and delete resource set 787 descriptions, along with listing groups of such descriptions. The 788 host MUST use its valid PAT obtained previously to gain access to 789 this endpoint. The resource set registration API is a subset of the 790 protection API. 792 (Note carefully the similar but distinct senses in which the word 793 "resource" is used in this section. UMA resource set descriptions 794 are themselves managed as web resources at the AM through this API.) 796 The AM MUST present an API for registering resource set descriptions 797 at a set of URIs with the structure "{rsreguri}/resource_set/{rsid}", 798 where the PAT provides sufficient context to distinguish between 799 identical resource set identifiers assigned by different hosts. 801 The components of these URIs are defined as follows: 803 {rsreguri} The AM's resource set registration endpoint as advertised 804 in its configuration data (see Section 1.5). 806 {rsid} An identifier for a resource set description. 808 Without a specific resource set identifier path component, the URI 809 applies to the set of resource set descriptions already registered. 811 Following is a summary of the five registration operations the AM is 812 REQUIRED to support. Each is defined in its own section below. All 813 other methods are unsupported. This API uses ETag and If-Match to 814 ensure the desired resource at the AM is targeted. 816 o Create resource set description: PUT /resource_set/{rsid} 818 o Read resource set description: GET /resource_set/{rsid} 820 o Update resource set description: PUT /resource_set/{rsid} with If- 821 Match 823 o Delete resource set description: DELETE /resource_set/{rsid} 825 o List resource set descriptions: GET /resource_set/ with If-Match 827 If the request to the resource set registration endpoint is 828 incorrect, then the AM responds with an error message (see 829 Section 4.2) by including one of the following error codes with the 830 response: 832 unsupported_method_type The host request used an unsupported HTTP 833 method. The AM MUST respond with the HTTP 405 (Method Not 834 Allowed) status code and MUST fail to act on the request. 836 not_found The resource set requested from the AM cannot be found. 837 The AM MUST respond with HTTP 404 (Not Found) status code. 839 precondition_failed The resource set that was requested to be 840 deleted or updated at the AM did not match the If-Match value 841 present in the request. The AM MUST respond with HTTP 412 842 (Precondition Failed) status code and MUST fail to act on the 843 request. 845 2.4.3.1. Create Resource Set Description 847 Adds a new resource set description using the PUT method, thereby 848 putting it under the AM's protection. If the request is successful, 849 the AM MUST respond with a status message that includes an ETag 850 header and _id and _rev properties for managing resource set 851 description versioning. 853 The host is free to use its own methods of identifying and describing 854 resource sets. The AM MUST treat them as opaque for the purpose of 855 authorizing access, other than associating them with the authorizing 856 user represented by the PAT used to access the API. On successfully 857 registering a resource set, the host MUST use UMA mechanisms to limit 858 access to any resources corresponding to this resource set, relying 859 on the AM to supply currently valid permissions for authorized 860 access. 862 Form of a "create resource set description" HTTP request: 864 PUT /resource_set/{rsid} HTTP/1.1 865 Content-Type: application/uma-resource-set+json 866 ... 868 (body contains JSON resource set description to be created) 869 Form of a successful HTTP response: 871 HTTP/1.1 201 Created 872 Content-Type: application/uma-status+json 873 ETag: (matches "_rev" property in returned object) 874 ... 876 { 877 "status": "created", 878 "_id": (id of created resource set), 879 "_rev": (ETag of created resource set) 880 } 882 On successful registration, the AM MAY return a redirect policy URI 883 to the host in a property with the name "policy_uri". This URI 884 allows the host to redirect the user to a specific user interface 885 within the AM where the user can immediately set or modify access 886 policies for the resource set that was just registered. 888 Form of a successful HTTP response: 890 HTTP/1.1 201 Created 891 Content-Type: application/uma-status+json 892 ETag: (matches "_rev" property in returned object) 893 ... 895 { 896 "status": "created", 897 "_id": (id of created resource set), 898 "_rev": (ETag of created resource set) 899 "policy_uri":"http://am.example.com/host/222/resource/333/policy" 900 } 902 2.4.3.2. Read Resource Set Description 904 Reads a previously registered resource set description using the GET 905 method. If the request is successful, the AM MUST respond with a 906 status message that includes an ETag header and _id and _rev 907 properties for managing resource set description versioning. 909 Form of a "read resource set description" HTTP request: 911 GET /resource_set/{rsid} HTTP/1.1 912 ... 914 Form of a successful HTTP response: 916 HTTP/1.1 200 OK 917 Content-Type: application/uma-resource-set+json 918 ... 920 (body contains JSON resource set description, including _id and _rev) 922 If the referenced resource does not exist, the AM MUST produce an 923 error response with an error property value of "not_found", as 924 defined in Section 2.4.3. 926 On successful read, the AM MAY return a redirect policy URI to the 927 host in a property with the name "policy_uri". This URI allows the 928 host to redirect the user to a specific user interface within the AM 929 where the user can immediately set or modify access policies for the 930 resource set that was read. 932 2.4.3.3. Update Resource Set Description 934 Updates a previously registered resource set description using the 935 PUT method, thereby changing the resource set's protection 936 characteristics. If the request is successful, the AM MUST respond 937 with a status message that includes an ETag header and _id and _rev 938 properties for managing resource set description versioning. 940 Form of an "update resource set description" HTTP request: 942 PUT /resource_set/{rsid} HTTP/1.1 943 Content-Type: application/resource-set+json 944 If-Match: (entity tag of resource) 945 ... 947 (body contains JSON resource set description to be updated) 949 Form of a successful HTTP response: 951 HTTP/1.1 204 No Content 952 ETag: "2" 953 ... 955 If the entity tag does not match, the AM MUST produce an error 956 response with an error property value of "precondition_failed", as 957 defined in Section 2.4.3. 959 On successful update, the AM MAY return a redirect policy URI to the 960 host in a property with the name "policy_uri". This URI allows the 961 host to redirect the user to a specific user interface within the AM 962 where the user can immediately set or modify access policies for the 963 resource set that was just updated. 965 2.4.3.4. Delete Resource Set Description 967 Deletes a previously registered resource set description using the 968 DELETE method, thereby removing it from the AM's protection regime. 970 Form of a "delete resource set description" HTTP request: 972 DELETE /resource_set/{rsid} 973 If-Match: (entity tag of resource) 974 ... 976 Form of a successful HTTP response: 978 HTTP/1.1 204 No content 979 ... 981 As defined in Section 2.4.3, if the referenced resource does not 982 exist the AM MUST produce an error response with an error property 983 value of "not_found", and if the entity tag does not match the AM 984 MUST produce an error response with an error property value of 985 "precondition_failed". 987 2.4.3.5. List Resource Set Descriptions 989 Lists all previously registered resource set identifiers for this 990 user using the GET method. The AM MUST return the list in the form 991 of a JSON array of {rsid} values. 993 The host uses this method as a first step in checking whether its 994 understanding of protected resources is in full synchronization with 995 the AM's understanding. 997 Form of a "list resource set descriptions" HTTP request: 999 GET /resource_set HTTP/1.1 1000 ... 1002 HTTP response: 1004 HTTP/1.1 200 OK 1005 Content-Type: application/json 1006 ... 1008 (body contains JSON array of {rsid} values) 1010 3. Getting Authorization and Accessing a Resource 1012 Phase 2 of UMA is getting authorization, and Phase 3 is accessing a 1013 resource. In these phases, an AM orchestrates and controls 1014 requesting parties' access to an authorizing user's protected 1015 resources at a host, under conditions dictated by that user. 1017 Phase 3 is merely the successful completion of a requester's access 1018 attempt that initially involved several embedded interactions among 1019 the requester, AM, and host in Phase 2. Phase 2 always begins with 1020 the requester attempting access at a protected resource endpoint at 1021 the host. How the requester came to learn about this endpoint is out 1022 of scope for this specification. The authorizing user might, for 1023 example, have advertised its availability publicly on a blog or other 1024 website, listed it in a discovery service, or emailed a link to a 1025 particular intended requesting party. 1027 The host responds to the requester's access request in one of several 1028 ways depending on the circumstances of the request, either 1029 immediately or having first performed one or more embedded 1030 interactions with the AM. Depending on the nature of the host's 1031 response to an failed access attempt, the requester itself engages in 1032 embedded interactions with the AM before re-attempting access. 1034 The interactions are as follows. Each interaction MAY be the last, 1035 if the requester chooses not to continue pursuing the access attempt 1036 or the host chooses not to continue facilitating it. 1038 1. The requester attempts access at a particular protected resource 1039 at a host (see Section 3.1). 1041 A. If the access attempt is unaccompanied by a requester 1042 permission token (RPT) (see Section 3.1.1), the host 1043 registers a suitable permission request with the AM (see 1044 Section 3.2). On receiving a permission ticket from the AM, 1045 the host delivers it to the requester through an HTTP 401 1046 (Unauthorized) response message with instructions on where to 1047 go to obtain the permission (and, necessarily, an RPT). 1049 B. If the access attempt was accompanied by an RPT, the host 1050 checks the token's status (see Section 3.3). 1052 1. If the RPT is invalid (for example, not applicable to 1053 this host or expired), or has insufficient permissions 1054 (see Section 3.1.2), the host registers a suitable 1055 permission request at the AM (see Section 3.2) and then 1056 responds to the requester with an HTTP 403 (Forbidden) 1057 response and instructions on where to go to request 1058 authorization for that permission (and, as required, a 1059 valid RPT for this host). 1061 2. If the RPT is valid, and at least one of the permissions 1062 associated with the token matches the scope of attempted 1063 access, the host responds to the requester's access 1064 attempt with an HTTP 200 (OK) response and a 1065 representation of the resource (see Section 3.1.3). 1067 2. If the requester received a permission ticket, it requests the 1068 permission (and a valid RPT for the host in question, as 1069 necessary) from the AM (Section 3.4). The AM MAY then engage in 1070 a claims-gathering flow with the requesting party prior to 1071 authorizing a new permission to be associated with an RPT (see 1072 Section 3.5). 1074 A. If the requester does not already have an AAT at the 1075 appropriate AM to be able to use its permission request 1076 endpoint, it first engages in an OAuth grant flow to obtain 1077 one (see Section 3.4.3). 1079 The interactions are described in detail in the following sections. 1081 3.1. Requester-Host: Attempt Access at Protected Resource 1083 This interaction assumes that the host has previously registered with 1084 an AM one or more resource sets that correspond to the resource to 1085 which access is being attempted, such that the host considers this 1086 resource to be UMA-protected by a particular AM. 1088 The requester typically attempts to access the desired resource at 1089 the host directly (for example, when a human operator of the 1090 requester software clicks on a thumbnail representation of the 1091 resource). The requester is expected to discover, or be provisioned 1092 or configured with, knowledge of the protected resource and its 1093 location out of band. Further, the requester is expected to acquire 1094 its own knowledge about the application-specific methods made 1095 available by the host for operating on this protected resource (such 1096 as viewing it with a GET method, or transforming it with some complex 1097 API call) and the possible scopes of access. 1099 Example of a request carrying no RPT: 1101 GET /album/photo.jpg HTTP/1.1 1102 Host: photoz.example.com 1103 ... 1105 Example of a request carrying an RPT: 1107 GET /album/photo.jpg HTTP/1.1 1108 Authorization: Bearer vF9dft4qmT 1109 Host: photoz.example.com 1110 ... 1112 The host responds in one of the following ways. 1114 3.1.1. Requester Presents No Requester Permission Token 1116 If the requester does not present an RPT with the request, the Host 1117 SHOULD register a permission with the AM that would suffice for that 1118 scope of access (see Section 3.2), and then respond to the requester 1119 with the HTTP 401 (Unauthorized) status code, along with providing 1120 the AM's URI in the header of the message and the permission ticket 1121 it just received from the AM in the body in JSON form. 1123 Example of the host's response: 1125 HTTP/1.1 401 Unauthorized 1126 WWW-Authenticate: UMA realm="example", 1127 host_id="photoz.example.com", 1128 am_uri="http://am.example.com" 1130 { 1131 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1132 } 1134 3.1.2. Requester Presents a Requester Permission Token That Is Invalid 1135 Or Has Insufficient Permission 1137 If the requester presents an RPT with its request, the host SHOULD 1138 determine the RPT's status (see Section 3.3). If the token is 1139 invalid or has insufficient permission for the type of access sought, 1140 the Host SHOULD register a permission with the AM that would suffice 1141 for that scope of access (see Section 3.2), and then respond to the 1142 requester with the HTTP 403 (Forbidden) status code, along with 1143 providing the AM's URI in the header of the message and the 1144 permission ticket it just received from the AM in the body in JSON 1145 form. 1147 Example of the host's response: 1149 HTTP/1.1 403 Forbidden 1150 WWW-Authenticate: UMA realm="example", 1151 host_id="photoz.example.com", 1152 am_uri="http://am.example.com" 1154 { 1155 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1156 } 1158 3.1.3. Requester Presents a Valid Requester Permission Token 1160 If the RPT's status is associated with at least one currently valid 1161 permission that applies to the scope of access attempted by the 1162 requester (see Section 3.3), the host MUST give access to the desired 1163 resource. 1165 Example of the host's response: 1167 HTTP/1.1 200 OK 1168 Content-Type: image/jpeg 1169 ... 1171 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 1172 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 1173 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 1174 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 1176 This response constitutes the conclusion of Phase 3 of UMA. 1178 The host MUST NOT give access where the token's status is not 1179 associated with at least one currently active permission that 1180 suffices for that scope of access. 1182 3.2. Host-AM: Register a Permission 1184 In response to receiving an access request unaccompanied by an RPT or 1185 accompanied by an RPT that is invalid or has insufficient 1186 permissions, the host SHOULD register a permission with the AM that 1187 would be sufficient for the type of access sought. The AM returns a 1188 permission ticket for the host to give to the requester in its 1189 response. 1191 The permission ticket is a short-lived opaque structure whose form is 1192 determined by the AM. The ticket value MUST be securely random (for 1193 example, not merely part of a predictable sequential series), to 1194 avoid denial-of-service attacks. Since the ticket is an opaque 1195 structure from the point of view of the requester, the AM is free to 1196 include information regarding expiration time within the opaque 1197 ticket for its own consumption. When the requester subsequently asks 1198 the AM to add permissions to its RPT, it will submit this ticket to 1199 the AM. 1201 The host registers the permission using the POST method at the AM's 1202 permission registration endpoint, providing its PAT to get access to 1203 this endpoint. The body of the HTTP request message contains a JSON 1204 document providing the requested permission. 1206 The requested scope is an object with the name "requested_permission" 1207 and the following properties: 1209 resource_set_id REQUIRED. The identifier for a resource set, access 1210 to which this requester is seeking access. The identifier MUST 1211 correspond to a resource set that was previously registered. 1213 scopes REQUIRED. An array referencing one or more identifiers of 1214 scopes to which access is needed for this resource set. Each 1215 scope identifier MUST correspond to a scope that was registered by 1216 this host for the referenced resource set. 1218 Example of an HTTP request that registers a permission at the AM's 1219 permission registration endpoint: 1221 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 1222 Content-Type: application/uma-requested-permission+json 1223 Host: am.example.com 1225 { 1226 "resource_set_id": "112210f47de98100", 1227 "scopes": [ 1228 "http://photoz.example.com/dev/actions/view", 1229 "http://photoz.example.com/dev/actions/all" 1230 ] 1231 } 1233 If the registration request is successful, the AM responds with an 1234 HTTP 201 (Created) status code and includes the Location header in 1235 its response as well as the "ticket" property in the JSON-formatted 1236 body. 1238 For example: 1240 HTTP/1.1 201 Created 1241 Content-Type: application/uma-permission-ticket+json 1242 Location: https://am.example.com/permreg/host/photoz.example.com/5454345rdsaa4543 1243 ... 1245 { 1246 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1247 } 1249 If the registration request is authenticated properly but fails due 1250 to other reasons, the AM responds with an HTTP 400 (Bad Request) 1251 status code and includes one of the following UMA error codes (see 1252 Section 4.2): 1254 invalid_resource_set_id The provided resource set identifier was not 1255 found at the AM. 1257 invalid_scope At least one of the scopes included in the request was 1258 not registered previously by this host. 1260 3.3. Host-AM: Ask for Requester Permission Token Status 1262 On receiving an RPT, the host MUST ascertain its status before 1263 granting or denying access to the requester. An RPT that a requester 1264 provides to a host in order to get access is associated with a set of 1265 permissions that govern whether the requester is authorized for 1266 access. The token's nature and format are dictated by its defined 1267 profile; the profile might allow it to be self-contained, such that 1268 the host is able to ascertain its status locally, or might require or 1269 allow the host to make a run-time status request of the AM that 1270 issued the token. 1272 This specification makes one type of RPT mandatory to implement: the 1273 UMA bearer token profile, as defined in Section 3.3.1. Alternate RPT 1274 profiles MAY define their own unique token formats and MAY require, 1275 allow, or prohibit use of the RPT status endpoint. 1277 3.3.1. UMA Bearer Token Profile 1279 This section defines the format and protocol requirements for the UMA 1280 bearer token profile. An AM MUST support the UMA bearer token 1281 profile and must indicate its support in the 1282 "uma_token_profiles_supported" property in the configuration data 1283 (see Section 1.5). 1285 On receiving an RPT of the "Bearer" type in an authorization header 1286 from a requester making an access attempt, the host MUST ask the AM 1287 for the RPT's status unless it has an unexpired cached status 1288 description for this RPT, which it MAY use instead. In order to ask 1289 the AM for an RPT's status, the host makes the request to the AM with 1290 a POST request to the AM's RPT status endpoint. The body of the HTTP 1291 request message contains a JSON document providing the RPT. The host 1292 gains access to the RPT status endpoint by presenting its own PAT in 1293 the request. 1295 Note that although the host's request is a safe operation, which 1296 normally would use the GET operation, this specification dictates the 1297 use of POST because it is advantageous for security of bearer tokens. 1298 Since the host provides its own PAT in the authorization header of 1299 the request, the RPT appears in the request body. A GET operation 1300 would expose the message to being recorded in AM access logs. 1302 Example of a request to the RPT status endpoint that provides the PAT 1303 in the header: 1305 POST /token_status HTTP/1.1 1306 Host: am.example.com 1307 Authorization: Bearer vF9dft4qmT 1308 Content-Type: application/json 1309 ... 1311 { 1312 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1313 "resource_set_id": "112210f47de98100", 1314 "host_id": "photoz.example.com" 1315 } 1317 The AM returns the RPT's status in an HTTP response using the 200 OK 1318 status code, containing a JSON document supplying the RPT status 1319 description. The RPT status description either contains all of the 1320 permissions that are currently valid for this RPT or indicates that 1321 the RPT is invalid (see Section 1.4). The AM MAY set a cache period 1322 for the returned RPT status description that allows the host to reuse 1323 it over some period of time when it later sees the same RPT. 1325 The status description for a valid RPT is a JSON array of zero or 1326 more permission objects, each with the following properties: 1328 resource_set_id REQUIRED. A string that uniquely identifies the 1329 resource set, access to which has been granted to this requester 1330 on behalf of this requesting party. The identifier MUST 1331 correspond to a resource set that was previously registered as 1332 protected. 1334 scopes REQUIRED. An array referencing one or more URIs of scopes to 1335 which access was granted for this resource set. Each scope MUST 1336 correspond to a scope that was registered by this host for the 1337 referenced resource set. 1339 exp REQUIRED. An integer representing the expiration time on or 1340 after which the permission MUST NOT be accepted for authorized 1341 access. The processing of the exp property requires that the 1342 current date/time MUST be before the expiration date/time listed 1343 in the exp claim. Host implementers MAY provide for some small 1344 leeway, usually no more than a few minutes, to account for clock 1345 skew. 1347 Example: 1349 HTTP/1.1 200 OK 1350 Content-Type: application/uma-rpt-status+json 1351 Cache-Control: no-store 1352 ... 1354 [ 1355 { 1356 "resource_set_id": "112210f47de98100", 1357 "scopes": [ 1358 "http://photoz.example.com/dev/actions/view", 1359 "http://photoz.example.com/dev/actions/all" 1360 ], 1361 "exp": 1300819380 1362 } 1363 ] 1365 The token status description for an invalid RPT is a JSON structure, 1366 as follows. 1368 HTTP/1.1 200 OK 1369 Content-Type: application/uma-rpt-status+json 1370 ... 1372 { 1373 "rpt_status": "invalid" 1374 } 1376 3.4. Requester-AM: Ask for Permission and Requester Permission Token 1378 If a requester has received a permission ticket in an Unauthorized or 1379 Forbidden response to an access attempt, this means that the 1380 requester originally presented no RPT, or presented an RPT that was 1381 invalid, or presented a valid RPT that had insufficient permissions 1382 associated with it. The requester uses the permission ticket to ask 1383 for the necessary permission -- and an RPT with which to associate 1384 it, as required -- from the AM's permission request endpoint. This 1385 process necessarily involves the requesting party (the natural or 1386 legal person who is operating the requester). 1388 The requester takes action in the following ways. 1390 3.4.1. Requester Looks Up AM Configuration Data 1392 The requester needs to learn the AM's permission request endpoint 1393 before they can begin interacting. From the "am_uri" information 1394 provided in the host's previous response containing the permission 1395 ticket, the requester MUST retrieve the AM's configuration data 1396 document, as described in Section 2 of hostmeta [RFC6415]. For 1397 example, if the "am_uri" is "example.com", the requester creates the 1398 URL "https://example.com/.well-known/uma-configuration" and performs 1399 a GET request on it. The AM MUST return content that includes UMA 1400 authorization API endpoints as defined in Section 1.5. 1402 3.4.2. Requester Registers with AM 1404 If the requester has not already obtained an OAuth client identifier 1405 and optional secret from this AM, in this step it MUST do so in order 1406 to engage in OAuth-based interactions with the AM. It MAY do this 1407 using [OCDynClientReg], if the AM supports it (see Section 1.5 for 1408 how the AM MAY indicate support). 1410 3.4.3. Requester Obtains Authorization API Token 1412 In this step, the requester acquires an AAT from the AM. The token 1413 represents the approval of this requesting party for this requester 1414 to engage with this AM for to supply claims, ask for permissions, and 1415 perform any other tasks needed for obtaining authorization for access 1416 to resources at all hosts that use this AM. 1418 The requester MUST use OAuth 2.0 [OAuth2] to obtain the AAT. Here 1419 the requester acts in the role of an OAuth client requesting the 1420 "authorization" scope; the requesting party acts in the role of an 1421 OAuth resource owner; and the AM acts in the role of an OAuth 1422 authorization server. Once the requester has obtained its AAT, it 1423 presents it to the AM at the permission request API endpoint; in 1424 presenting this endpoint the AM acts in the role of a resource 1425 server. 1427 By virtue of being able to identify this requester/requesting party 1428 pair uniquely across all hosts, the AM is able to manage the process 1429 of authorization and claims-gathering efficiently. These management 1430 processes are outside the scope of this specificaiton. 1432 The AM MAY support the use of any grant type, but MUST support the 1433 authorization_code grant type, and SHOULD support the SAML bearer 1434 token grant type [OAuth-SAML] 1435 (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates 1436 working with requesters that are operating in environments where the 1437 use of SAML is prevalent. The AM MUST indicate all grant types it 1438 supports in its configuration data, as defined in Section 1.5. 1440 The requester has completed this step successfully when it possesses 1441 a AAT it can use to get access to the AM's authorization API on the 1442 requesting party's behalf. 1444 3.4.4. Requester-AM: Request Authorization to Add Permission 1446 Once in possession of a permission ticket and an AAT, the requester 1447 asks the AM to authorize it to have the permission for the sought-for 1448 access. The requester performs a POST on the permission endpoint, 1449 supplying: 1451 o The permission ticket it received from the host 1453 o Its RPT for this host, if it already has one 1455 o Its own AAT in the header in order to gain access to the 1456 permission endpoint 1458 Example of a request message containing a permission ticket and RPT: 1459 POST /token_status HTTP/1.1 1460 Host: am.example.com 1461 Authorization: Bearer jwfLG53^sad$#f 1462 Content-Type: application/json 1463 ... 1465 { 1466 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1467 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1468 } 1470 In this interaction, the requester uses the AM's permission request 1471 endpoint. The AM uses the ticket to look up the previously 1472 registered permission, maps the requested permission to operative 1473 user policies, undergoes any authorization flows required (see 1474 Section 3.5), and ultimately responds to the request positively or 1475 negatively. 1477 If the AM determines that the requesting party meets the 1478 authorization criteria set out by the authorizing user's policy (see 1479 Section 3.5), it responds with an HTTP 201 (Created) status code and 1480 provides a new or updated RPT: 1482 For example: 1484 HTTP/1.1 201 Created 1485 Content-Type: application/uma-rpt+json 1487 { 1488 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1489 } 1491 If the content-type of the request is not recognized by the AM, the 1492 AM MUST produce an HTTP error. 1494 If the request fails due to missing or invalid parameters, or is 1495 otherwise malformed, the AM SHOULD inform the requester of the error 1496 by sending an HTTP error response. 1498 If the request fails due to an invalid, missing, or expired AAT or 1499 requires higher privileges at this endpoint than provided by the AAT, 1500 the AM responds with an OAuth error (see Section 4.1). 1502 For example: 1504 HTTP/1.1 401 Unauthorized 1505 WWW-Authenticate: Bearer realm="example", 1506 error="invalid_token", 1507 error_description="The access token expired" 1509 If the AM does not add the requested permission, it responds using 1510 the appropriate HTTP status code (typically 400 or 403), and includes 1511 one of the following error codes in the response (see Section 4.2): 1513 invalid_requester_ticket The provided ticket was not found at the 1514 AM. The AM SHOULD respond with the HTTP 400 (Bad Request) status 1515 code. 1517 expired_requester_ticket The provided ticket has expired. The AM 1518 SHOULD respond with the HTTP 400 (Bad Request) status code. 1520 not_authorized_permission The requester is definitively not 1521 authorized for this permission according to user policy. The AM 1522 SHOULD respond with the HTTP 403 (Forbidden) status code. 1524 need_claims The AM is unable to determine whether the requester is 1525 authorized for this permission without gathering claims from the 1526 requesting party. The AM SHOULD respond with the HTTP 403 1527 (Forbidden) status code. The requester is therefore not 1528 authorized, but has the opportunity to engage the requesting party 1529 in a claims-gathering flow with the AM (see Section 3.5) to 1530 potentially become authorized. 1532 For example: 1534 HTTP/1.1 400 Bad Request 1535 Content-Type: application/uma-status+json 1536 Cache-Control: no-store 1537 ... 1539 { 1540 "status": "error", 1541 "error": "expired_requester_ticket" 1542 } 1544 3.5. Claims-Gathering Flows 1546 The AM MUST base its decisions to add permissions to RPTs on user 1547 policies. The nature of these policies is outside the scope of UMA, 1548 but generally speaking, they can be thought of as either independent 1549 of requesting-party features (for example, time of day) or dependent 1550 on requesting-party features (for example, whether they are over 18). 1551 This latter case requires the requesting party to transmit identity 1552 claims to the AM in some fashion. 1554 The process for requesting and providing claims is extensible and may 1555 have a variety of dependencies on the type of requesting party (for 1556 example, natural person or legal person) and the type of requester 1557 application (for example, browser, native app, or autonomously 1558 running web service). UMA currently provides a framework for 1559 handling human-driven requester apps and an optional solution for 1560 gathering standardized claims from that end-user, and allows for 1561 extensions to support other solutions for this use case and other use 1562 cases. The AM SHOULD document its claims-handling ability in its 1563 configuration data through the claim_profiles_supported property (see 1564 Section 1.5). For the business-level and legal implications of 1565 different technical authorization flows, see [UMA-trustmodel]. 1567 3.5.1. Claims-Gathering Flow for Requester Apps Operated by End-Users 1569 A requester app, whether browser-based or native, is operated by a 1570 natural person (human end-user) in one of two typical situations: 1572 o The requesting party is a natural person (for example, a friend of 1573 the authorizing user); the requesting party may even be the 1574 authorizing user herself. 1576 o The requesting party is a legal person such as a corporation, and 1577 the human being operating the requester app is acting as an agent 1578 of that legal person (for example, a customer support specialist 1579 representing a credit card company). 1581 For convenience, this specification refers to the human end-user as a 1582 "requesting end-user" to cover both cases, which differ only at the 1583 level of business agreements (and potentially law), rather than 1584 technology. The AM has a variety of options at this point for 1585 satisfying the authorizing user's policy; this specification does not 1586 dictate a single answer. For example, the AM could require the 1587 requesting end-user to register for and/or log in to a local AM 1588 account, or to fill in a questionnaire, or to complete a purchase. 1589 It could even require several of these operations, where the order is 1590 significant. 1592 An end-user-driven requester app MUST redirect the end-user to the AM 1593 to complete the process of authorization. The redirection MUST 1594 include a URI query parameter with the name "ticket" whose value 1595 conveys the permission ticket for which the need_claims error was 1596 received; for example, "ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de". 1597 Each claim profile MUST provide the following capabilities: 1599 redirect URI A means by which the requester MUST supply the URI to 1600 which the AM MUST redirect the requesting end-user at the end of 1601 the claims-gathering process. 1603 callback URI A means by which the requester OPTIONALLY supplies a 1604 callback URI for the AM to use. 1606 state A means by which the requester SHOULD supply an opaque value 1607 used to maintain state between the request and the callback; 1608 serves as a protection against XSRF attacks. 1610 An AM MAY support any number of claim profiles. One potential such 1611 profile is defined in this specification: the "openid" claim profile, 1612 which leverages OpenID Connect for gathering generally useful user 1613 claims (see Section 3.5.1.1). 1615 3.5.1.1. OpenID Connect Claim Profile 1617 If an AM supports the OpenID Connect claim profile, it MUST supply 1618 the "openid" value for one of its claim_profiles_supported values in 1619 its AM configuration data (see Section 1.5 for how to formulate this 1620 data). 1622 To conform to this option, the AM MUST do the following: 1624 o Serve as a conforming OpenID Relying Party and Claims Client 1625 according to [OCStandard] 1627 o Be able to utilize at least all of the reserved claims defined in 1628 [OCMessages] in assessing policy and granting permissions 1630 o Use the OpenID Connect "redirect_uri" and "state" request 1631 parameters as appropriate 1633 The AM can then use any conforming OpenID Connect mechanisms and 1634 typical user interfaces for engaging with the UserInfo endpoints of 1635 OpenID Providers and Claims Providers, potentially allowing for the 1636 delivery of "trusted claims" (such as a verified email address or a 1637 date or birth) on which authorization policy may depend. 1639 4. Error Messages 1641 Ultimately the host is responsible for either granting the access the 1642 requester attempted, or returning an error response to the requester 1643 with a reason for the failure. [OAuth2] defines several error 1644 responses for a resource server to return. UMA makes use of these 1645 error responses, but requires the host to "outsource" the 1646 determination of some error conditions to the AM. UMA defines its 1647 own additional error responses that the AM may give to the host and 1648 requester as they interact with it, and that the host may give to the 1649 requester. 1651 4.1. OAuth Error Responses 1653 When a client (host or requester) attempts to access one of the AM 1654 endpoints Section 1.5 or a client (requester) attempts to access a 1655 protected resource at the host, it has to make an authenticated 1656 request by including an OAuth access token in the HTTP request as 1657 described in [OAuth2] Section 7. 1659 If the client's request failed authentication, the AM or the host 1660 responds with an OAuth error message as described throughout 1661 Section 2 and Section 3. 1663 4.2. UMA Error Responses 1665 When a client (host or requester) attempts to access one of the AM 1666 endpoints Section 1.5 or a client (requester) attempts to access a 1667 protected resource at the host, if the client request is successfully 1668 authenticated by OAuth means, but is invalid for another reason, the 1669 AM or host responds with an UMA error response by adding the 1670 following properties to the entity body of the HTTP response using 1671 the "application/json" media type: 1673 error REQUIRED. A single error code. Value for this property is 1674 defined in the specific AM endpoint description. 1676 error_description OPTIONAL. A human-readable text providing 1677 additional information, used to assist in the understanding and 1678 resolution of the error occurred. 1680 error_uri OPTIONAL. A URI identifying a human-readable web page 1681 with information about the error, used to provide the end-user 1682 with additional information about the error. 1684 Common error codes: 1686 invalid_request The request is missing a required parameter or is 1687 otherwise malformed. The AM MUST respond with the HTTP 400 (Bad 1688 Request) status code. 1690 For example: 1692 HTTP/1.1 400 Bad Request 1693 Content-Type: application/uma-status+json 1694 Cache-Control: no-store 1695 ... 1697 { 1698 "status": "error", 1699 "error": "invalid_request", 1700 "error_description": "There is already a resource with this identifier.", 1701 "error_uri": "http://am.example.com/errors/resource_exists" 1702 } 1704 5. Security Considerations 1706 This specification relies mainly on OAuth security mechanisms for 1707 protecting the host registration endpoint at the AM so that only a 1708 properly authorized host can access it on behalf of the intended 1709 user. For example, the host needs to use a valid protection API 1710 token (PAT) issued through a user authorization process at the 1711 endpoint, and the interaction SHOULD take place over TLS. It is 1712 expected that the host will protect its client secret (if it was 1713 issued one) and its PAT, particularly if used in "bearer token" 1714 fashion. 1716 In addition, this specification dictates a binding between the PAT 1717 and the host-specific registration area on the AM to prevent a host 1718 from interacting with a registration area not its own. 1720 This specification defines a number of JSON-based data formats. As a 1721 subset of the JavaScript scripting language, JSON data SHOULD be 1722 consumed through a process that does not dynamically execute it as 1723 code, to avoid malicious code execution. One way to achieve this is 1724 to use a JavaScript interpreter rather than the built-in JavaScript 1725 eval() function. 1727 For information about the technical, operational, and legal elements 1728 of trust establishment between UMA entities and parties, which 1729 affects security considerations, see [UMA-trustmodel]. 1731 6. Privacy Considerations 1733 The AM comes to be in possession of resource set information (such as 1734 names and icons) that may reveal information about the user, which 1735 the AM's trust relationship with the host is assumed to accommodate. 1736 However, the requester is a less-trusted party (in fact, entirely 1737 untrustworthy until it acquires permissions for an RPT in UMA 1738 protocol phase 2. This specification recommends obscuring resource 1739 set identifiers in order to avoid leaking personally identifiable 1740 information to requesters through the "scope" mechanism. 1742 For information about the technical, operational, and legal elements 1743 of trust establishment between UMA entities and parties, which 1744 affects privacy considerations, see [UMA-trustmodel]. 1746 7. Conformance 1748 This section outlines conformance requirements for various entities 1749 implementing UMA endpoints. 1751 This specification has dependencies on other specifications, as 1752 follows: 1754 o OAuth 2.0: AMs, hosts, and requesters MUST support [OAuth2] 1755 features named in this specification for conformance. For 1756 example, AMs MUST support the authorization_code and 1757 client_credentials grant types. 1759 o hostmeta: AMs, hosts, and requesters MUST support the [RFC6415] 1760 features named in this specification. 1762 o OpenID Connect: AMs MAY support [OCDynClientReg], and MAY choose 1763 to conform to the "openid" claim format option, corresponding to 1764 the OpenID Connect RP role defined in [OCStandard] and support for 1765 OpenID Connect reserved claims defined in [OCMessages]. 1767 The AM's configuration data provides a machine-readable method for an 1768 AM to indicate certain of the conformance options it has chosen. 1769 Several of the data properties allow for extensibility. Where this 1770 specification does not already require optional features to be 1771 documented, it is RECOMMENDED that AM developers and deployers 1772 document any profiled or extended features explicitly and use 1773 configuration data to indicate their usage. See Section 1.5 for 1774 information about providing and extending AM configuration data. 1776 8. IANA Considerations 1778 Several UMA-specific JSON-based media types are being proposed, as 1779 follows: (TBS) 1781 9. Example of Registering Resource Sets 1783 The following example illustrates the intent and usage of resource 1784 set descriptions and scope descriptions as part of resource set 1785 registration. 1787 This example contains some steps that are exclusively in the realm of 1788 user experience rather than web protocol, to achieve realistic 1789 illustration. These steps are labeled "User experience only". Some 1790 other steps are exclusively internal to the operation of the entity 1791 being discussed. These are labeled "Internal only". 1793 An authorizing user, Alice Adams, has just uploaded a photo of her 1794 new puppy to a host, Photoz.example.com, and wants to ensure that 1795 this specific photo is not publicly accessible. 1797 Alice has already introduced this host to her AM, 1798 CopMonkey.example.com, and thus Photoz has already obtained a PAT 1799 from CopMonkey. However, Alice has not previously instructed Photoz 1800 to use CopMonkey to protect any other photos of hers. 1802 Alice has previously visited CopMonkey to map a default "do not share 1803 with anyone" policy to any resource sets registered by Photoz, until 1804 such time as she maps some other more permissive policies to those 1805 resources. (User experience only. This may have been done at the 1806 time Alice introduced the host to the AM, and/or it could have been a 1807 global or host-specific preference setting. A different constraint 1808 or no constraint at all might be associated with newly protected 1809 resources.) Other kinds of policies she may eventually map to 1810 particular photos or albums might be "Share only with 1811 husband@email.example.net" or "Share only with people in my 'family' 1812 group". 1814 Photoz itself has a publicly documented application-specific API that 1815 offers two dozen different methods that apply to single photos, such 1816 as "addTags" and "getSizes", but rolls them up into two photo-related 1817 scopes of access: "view" (consisting of various read-only operations) 1818 and "all" (consisting of various reading, editing, and printing 1819 operations). It defines two scope descriptions that represent these 1820 scopes, which it is able to reuse for all of its users (not just 1821 Alice), and ensures that these scope description documents are 1822 available through HTTP GET requests that may be made by AMs. 1824 The "name" property values are intended to be seen by Alice when she 1825 maps authorization constraints to specific resource sets and actions 1826 while visiting CopMonkey, such that Alice would see the strings "View 1827 Photo and Related Info" and "All Actions", likely accompanied by the 1828 referenced icons, in the CopMonkey interface. (Other users of Photoz 1829 might similarly see the same labels at CopMonkey or whatever other AM 1830 they use. Photoz could distinguish natural-language labels per user 1831 if it wishes, by pointing to scopes with differently translated 1832 names.) 1834 Example of the viewing-related scope description document available 1835 at http://photoz.example.com/dev/scopes/view with a Content-Type of 1836 application/uma-scope+json: 1838 { 1839 "name": "View Photo and Related Info", 1840 "icon_uri": "http://www.example.com/icons/reading-glasses.png" 1841 } 1843 Example of the broader scope description document available at 1844 http://photoz.example.com/dev/scopes/all, likewise with a Content- 1845 Type of application/uma-scope+json: 1847 { 1848 "name": "All Actions", 1849 "icon_uri": "http://www.example.com/icons/galaxy.png" 1850 } 1852 While visiting Photoz, Alice selects a link or button that instructs 1853 the site to "Protect" or "Share" this single photo (user experience 1854 only; Photoz could have made this a default or preference setting). 1856 As a result, Photoz defines for itself a resource set that represents 1857 this photo (internal only; Photoz is the only application that knows 1858 how to map a particular photo to a particular resource set). Photoz 1859 also prepares the following resource set description, which is 1860 specific to Alice and her photo. The "name" property value is 1861 intended to be seen by Alice in mapping authorization policies to 1862 specific resource sets and actions when she visits CopMonkey. Alice 1863 would see the string "Steve the puppy!", likely accompanied by the 1864 referenced icon, in the CopMonkey interface. The possible scopes of 1865 access on this resource set are indicated with URI references to the 1866 scope descriptions, as shown just above. 1868 { 1869 "name": "Steve the puppy!", 1870 "icon_uri": "http://www.example.com/icons/flower", 1871 "scopes": [ 1872 "http://photoz.example.com/dev/scopes/view", 1873 "http://photoz.example.com/dev/scopes/all" 1874 ] 1875 } 1877 Photoz uses the "create resource set description" method of 1878 CopMonkey's standard UMA resource set registration API, presenting 1879 its Alice-specific PAT there, to register and assign an identifier to 1880 the resource set description. 1882 PUT /resource_set/112210f47de98100 HTTP/1.1 1883 Content-Type: application/uma-resource-set+json 1884 ... 1886 { 1887 "name": "Steve the puppy!", 1888 "icon_uri": "http://www.example.com/icons/flower.png", 1889 "scopes": [ 1890 "http://photoz.example.com/dev/scopes/view", 1891 "http://photoz.example.com/dev/scopes/all" 1892 ] 1893 } 1895 If the registration attempt succeeds, CopMonkey responds in the 1896 following fashion. 1898 HTTP/1.1 201 Created 1899 Content-Type: application/uma-status+json 1900 ETag: "1" 1901 ... 1903 { 1904 "status": "created", 1905 "_id": "112210f47de98100", 1906 "_rev": "1" 1907 } 1909 At the time Alice indicates she would like this photo protected, 1910 Photoz can choose to redirect Alice to CopMonkey for further policy 1911 setting, access auditing, and other AM-related tasks (user experience 1912 only). 1914 Once it has successfully registered this description, Photoz is 1915 responsible for outsourcing to CopMonkey all questions of 1916 authorization for access attempts made to this photo. 1918 Over time, as Alice uploads other photos and creates and organizes 1919 photo albums, and as Photoz makes new action functionality available, 1920 Photoz can use additional methods of the resource set registration 1921 API to ensure that CopMonkey's understanding of Alice's protected 1922 resources matches its own. 1924 For example, if Photoz suspects that somehow its understanding of the 1925 resource set has gotten out of sync with CopMonkey's, it can ask to 1926 read the resource set description as follows. 1928 GET /resource_set/112210f47de98100 HTTP/1.1 1929 Host: am.example.com 1930 ... 1932 CopMonkey responds with the full content of the resource set 1933 description, including its _id and its current _rev, as follows: 1935 Example of an HTTP response to a "read resource set description" 1936 request, containing a resource set description from the AM: 1938 HTTP/1.1 200 OK 1939 Content-Type: application/uma-resource-set+json 1940 ETag: "1" 1941 ... 1943 { 1944 "_id": "112210f47de98100", 1945 "_rev": "1", 1946 "name": "Photo album", 1947 "icon_uri": "http://www.example.com/icons/flower.png", 1948 "scopes": [ 1949 "http://photoz.example.com/dev/scopes/view", 1950 "http://photoz.example.com/dev/scopes/all" 1951 ] 1952 } 1954 If for some reason Photoz and CopMonkey have gotten dramatically out 1955 of sync, Photoz can ask for the list of resource set identifiers 1956 CopMonkey currently knows about: 1958 GET /resource_set HTTP/1.1 1959 Host: am.example.com 1960 ... 1962 CopMonkey's response might look as follows: 1964 HTTP/1.1 200 OK 1965 Content-Type: application/json 1966 ... 1968 [ "112210f47de98100", "34234df47eL95300" ] 1970 If Alice later changes the photo's title (user experience only) on 1971 Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz 1972 would use the "update resource set description" method to ensure that 1973 Alice's experience of policy-setting at CopMonkey remains consistent 1974 with what she sees at Photoz. Following is an example of this 1975 request. 1977 PUT /resource_set/112210f47de98100 HTTP/1.1 1978 Content-Type: application/uma-resource-set+json 1979 Host: am.example.com 1980 If-Match: "1" 1981 ... 1983 { 1984 "name": "Steve on October 14, 2011", 1985 "icon_uri": "http://www.example.com/icons/flower.png", 1986 "scopes": [ 1987 "http://photoz.example.com/dev/scopes/view", 1988 "http://photoz.example.com/dev/scopes/all" 1989 ] 1990 } 1992 CopMonkey would respond as follows. 1994 HTTP/1.1 201 Created 1995 Content-Type: application/uma-status+json 1996 ETag: "2" 1997 ... 1999 { 2000 "status": "updated", 2001 "_id": "112210f47de98100", 2002 "_rev": "2" 2003 } 2005 There are other reasons Photoz might want to update resource set 2006 descriptions, having nothing to do with Alice's actions or wishes. 2007 For example, it might extend its API to include new features, and 2008 want to add new scopes to all of Alice's and other users' resource 2009 set descriptions. 2011 if Alice later decides to entirely remove sharing protection (user 2012 experience only) on this photo while visiting Photoz, ensuring that 2013 the public can get access without any UMA-based protection, Photoz is 2014 responsible for deleting the relevant resource set registration, as 2015 follows: 2017 DELETE /resource_set/112210f47de98100 HTTP/1.1 2018 Host: am.example.com 2019 If-Match: "2" 2020 ... 2022 10. Acknowledgments 2024 The current editor of this specification is Thomas Hardjono of MIT. 2025 The following people are co-authors: 2027 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 2029 o Domenico Catalano, Oracle Corp. 2031 o George Fletcher, AOL 2033 o Maciej Machulak, Newcastle University 2035 o Eve Maler, XMLgrrl.com 2037 o Lukasz Moren, Newcastle University 2039 o Christian Scholz, COMlounge GmbH (former editor) 2041 o Jacek Szpot, Newcastle University 2043 Additional contributors to this specification include the Kantara UMA 2044 Work Group participants, a list of whom can be found at 2045 [UMAnitarians]. 2047 11. Issues 2049 All issues are now captured at the project's GitHub site 2050 (). 2052 12. References 2054 12.1. Normative References 2056 [OAuth-SAML] 2057 Campbell, B., "SAML 2.0 Bearer Assertion Grant Type 2058 Profile for OAuth 2.0", August 2011, 2059 . 2062 [OAuth-bearer] 2063 "The OAuth 2.0 Authorization Protocol: Bearer Tokens", 2064 March 2012, 2065 . 2067 [OAuth2] Hammer-Lahav, E., "The OAuth 2.0 Protocol", 2068 September 2011, 2069 . 2071 [OCDynClientReg] 2072 Sakimura, N., "OpenID Connect Dynamic Client Registration 2073 1.0", September 2011, . 2076 [OCMessages] 2077 Sakimura, N., "OpenID Connect Messages 1.0", 2078 September 2011, 2079 . 2082 [OCStandard] 2083 Sakimura, N., "OpenID Connect Standard 1.0", 2084 September 2011, 2085 . 2088 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2089 Requirement Levels", BCP 14, RFC 2119, March 1997. 2091 [RFC4627] Crockford, D., "The application/json Media Type for 2092 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2094 [RFC6415] Hammer-Lahav, E., "Web Host Metadata", October 2011, 2095 . 2097 12.2. Informative References 2099 [UMA-trustmodel] 2100 Maler, E., "UMA Trust Model", February 2011, . 2104 [UMA-usecases] 2105 Maler, E., "UMA Scenarios and Use Cases", October 2010, . 2109 [UMA-userstories] 2110 Maler, E., "UMA User Stories", November 2010, . 2114 [UMAnitarians] 2115 Maler, E., "UMA Participant Roster", 2012, . 2119 Appendix A. Document History 2121 NOTE: To be removed by RFC editor before publication as an RFC. 2123 From I-D rev 03 to rev 04, the following major changes have been 2124 made: 2126 o The requirement to support the client_credentials flow has been 2127 removed. 2129 o The requester access token has been split into two tokens, and all 2130 of the tokens have been renamed. The host access token is now the 2131 PAT. The requester access token used at the AM's API is now the 2132 AAT, and consists of vanilla OAuth. The requester access token 2133 used at the host is now the RPT. 2135 o The token and user authorization endpoints for the different APIs 2136 at the AM have been joined together, and are now distinguished 2137 through the "protection" scope (for the protection API) and the 2138 "authorization" scope (for the authorization API). 2140 o The token status description format and JSON media type, and the 2141 RPT/permission delivery response, have been updated to reflect the 2142 RPT naming. 2144 o The configuration data format has changed to reflect the changes 2145 above. 2147 o The Phase 2/3 flow has changed and been simplified to match the 2148 requirements of the new AAT and RPT. 2150 o Token types are now called token profiles, and this is reflected 2151 in the configuration parameter names. Claim types are now called 2152 claim profiles, and this is also reflected in the configuration 2153 parameter name. 2155 o The requester now asks for permission in a back-channel 2156 interaction, and the AM now produces a need_claims error that 2157 instructs the requester to use a claims-gathering flow (renamed 2158 from "authorization flow"). 2160 o Named subsections for token and claim profiles have been added so 2161 that they show up in the TOC. 2163 Author's Address 2165 Thomas Hardjono (editor) 2166 MIT 2168 Email: hardjono@mit.edu