idnits 2.17.1 draft-hardjono-oauth-umacore-06.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 3 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 (December 27, 2012) is 4136 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-resource-reg' -- 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'UMA-obligations' Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Hardjono, Ed. 3 Internet-Draft MIT 4 Intended status: Standards Track December 27, 2012 5 Expires: June 30, 2013 7 User-Managed Access (UMA) Profile of OAuth 2.0 8 draft-hardjono-oauth-umacore-06 10 Abstract 12 User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how 13 resource owners can control access to their protected resources made 14 by clients operated by arbitrary rquesting parties, where the 15 resources reside on any number of resource servers, and where a 16 centralized authorization server governs access based on resource 17 owner policy. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on June 30, 2013. 36 Copyright Notice 38 Copyright (c) 2012 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 7 55 1.2. Basic Terminology . . . . . . . . . . . . . . . . . . . . 7 56 1.3. Endpoints, Endpoint Protection, and Tokens . . . . . . . . 8 57 1.4. Scope Types, Resource Sets, Permissions, and 58 Authorization . . . . . . . . . . . . . . . . . . . . . . 10 59 1.5. Authorization Server Configuration Data . . . . . . . . . 12 60 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 15 61 2.1. Resource Server Obtains PAT . . . . . . . . . . . . . . . 15 62 2.2. Resource Server Registers Sets of Resources to Be 63 Protected . . . . . . . . . . . . . . . . . . . . . . . . 16 64 3. Getting Authorization and Accessing a Resource . . . . . . . . 16 65 3.1. Client Attempts to Access Protected Resource . . . . . . . 18 66 3.1.1. Client Presents No RPT . . . . . . . . . . . . . . . . 19 67 3.1.2. Client Presents an RPT That Has Insufficient 68 Authorization Data . . . . . . . . . . . . . . . . . . 19 69 3.1.3. Client Presents a Valid RPT with Sufficient 70 Authorization Data . . . . . . . . . . . . . . . . . . 20 71 3.2. Resource Server Registers a Permission With 72 Authorization Server . . . . . . . . . . . . . . . . . . . 20 73 3.3. Resource Server Determines the RPT Status . . . . . . . . 22 74 3.3.1. UMA Bearer Token Profile . . . . . . . . . . . . . . . 22 75 3.4. Client Asks Authorization Server for RPT and 76 Authorization Data . . . . . . . . . . . . . . . . . . . . 24 77 3.4.1. Client Obtains AAT . . . . . . . . . . . . . . . . . . 25 78 3.4.2. Client Obtains RPT . . . . . . . . . . . . . . . . . . 26 79 3.4.3. Client Asks for Authorization Data . . . . . . . . . . 27 80 3.5. Claims-Gathering Flows . . . . . . . . . . . . . . . . . . 29 81 3.5.1. Claims-Gathering Flow for Clients Operated by 82 End-Users . . . . . . . . . . . . . . . . . . . . . . 30 83 3.5.1.1. OpenID Connect Claim Profile . . . . . . . . . . . 31 84 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . . 32 85 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 32 86 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 32 87 5. Specification of Additional Profiles . . . . . . . . . . . . . 33 88 5.1. Specifying Profiles of UMA . . . . . . . . . . . . . . . . 34 89 5.2. Specifying RPT Profiles . . . . . . . . . . . . . . . . . 34 90 5.3. Specifying Claim Profiles . . . . . . . . . . . . . . . . 35 91 6. Security Considerations . . . . . . . . . . . . . . . . . . . 36 92 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 37 93 8. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 37 94 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 95 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 37 96 11. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 97 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 38 98 12.1. Normative References . . . . . . . . . . . . . . . . . . . 38 99 12.2. Informative References . . . . . . . . . . . . . . . . . . 39 100 Appendix A. Document History . . . . . . . . . . . . . . . . . . 40 101 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 41 103 1. Introduction 105 User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2]. UMA 106 defines how resource owners can control access to their protected 107 resources made by clients operated by arbitrary requesting parties, 108 where the resources reside on any number of resource servers, and 109 where a centralized authorization server governs access based on 110 resource owner policy. Resource owners configure authorization 111 servers with access policies that serve as implicit authorization 112 grants. Thus, the UMA profile of OAuth includes an authorization 113 grant flow. 115 UMA serves numerous use cases where a resource owner outsources 116 authorization for access to their resources, potentially even without 117 the run-time presence of the resource owner. A typical example is 118 the following: a web user (an end-user resource owner) can authorize 119 a web app (client) to gain one-time or ongoing access to a protected 120 resource containing his home address stored at a "personal data 121 store" service (resource server), by telling the resource server to 122 respect access entitlements issued by his authorization service 123 (authorization server). The requesting party operating the client 124 might be the resource owner himself, using a web or native app run by 125 an e-commerce company that needs to know where to ship a purchased 126 item, or it might be his friend who is using an online address book 127 service to collect contact information, or it might be a survey 128 company that uses an autonomous web service to compile population 129 demographics. A variety of scenarios and use cases can be found in 130 [UMA-usecases] and [UMA-casestudies]. 132 Practical control of access among loosely coupled parties requires 133 more than just messaging protocols. This specification defines only 134 the technical "contract" between UMA-conforming entities; its 135 companion Binding Obligations specification [UMA-obligations] defines 136 the expected behaviors of parties operating and using these entities. 137 Parties operating entities that claim to be UMA-conforming MUST 138 provide documentation affirmatively stating their acceptance of the 139 binding obligations contractual framework defined in the Binding 140 Obligations specification. 142 In enterprise settings, application access management often involves 143 letting back-office applications serve only as policy enforcement 144 points (PEPs), depending entirely on access decisions coming from a 145 central policy decision point (PDP) to govern the access they give to 146 requesters. This separation eases auditing and allows policy 147 administration to scale in several dimensions. UMA makes use of a 148 separation similar to this, letting the resource owner serve as a 149 policy administrator crafting authorization strategies for resources 150 under their control. 152 The UMA protocol can be considered an advanced profile of [OAuth2]. 153 In order to increase interoperable communication among the 154 authorization server, resource server, and client, it defines several 155 purpose-built APIs related to the outsourcing of authorization, 156 themselves protected by OAuth in embedded fashion. 158 The UMA protocol has three broad phases, as shown in Figure 1. 160 The Three Phases of the UMA Profile of OAuth 161 +--------------+ 162 | resource | 163 +---------manage (A)------------ | owner | 164 | +--------------+ 165 | Phase 1: | 166 | protect a control (B) 167 | resource | 168 v v 169 +------------+ +----------+--------------+ 170 | | |protection| | 171 | resource | | API | authorization| 172 | server |<-protect (C)--| (needs | server | 173 | | | PAT) | | 174 +------------+ +----------+--------------+ 175 | protected | | authorization| 176 | resource | | API | 177 |(needs RPT) | | (needs AAT) | 178 +------------+ +--------------+ 179 ^ | 180 | Phases 2 and 3: authorize (D) 181 | get authorization, | 182 | access a resource v 183 | +--------------+ 184 +---------access (E)-------------| client | 185 +--------------+ 187 requesting party 189 Figure 1 191 In broad strokes, the phases are as follows: 193 1. Protect a resource (described in Section 2). 195 2. Get authorization (described in Section 3). 197 3. Access a resource (described along with Phase 2 in Section 3). 199 In more detail, the phases work as follows: 201 1. _Protect a resource:_ This phase accomplishes trust establishment 202 among the resource owner, resource server, and authorization 203 server, as well as enabling the resource server to register with 204 the authorization server descriptions of the resources to be 205 protected. This specification uses [OAuth-resource-reg] to 206 enable dynamic introduction and resource registration. In these 207 circumstances, where the resource owner has chosen to use a 208 resource server for managing online resources ("A"), the resource 209 owner introduces this resource server to an authorization server 210 using an OAuth-mediated interaction that results in the 211 authorization server giving the resource server a protection API 212 token (PAT). The resource server then uses the authorization 213 server's protection API to register sets of resources for which 214 protection is being outsourced ("C"). (Out of band of the UMA 215 protocol, the resource owner instructs the authorization server 216 what policies to associated with the registered resource sets 217 ("B").) 219 2. _Get authorization:_ This phase involves the client (along with 220 its operator, the "requesting party") for the first time. The 221 client approaches the resource server seeking access to a 222 protected resource ("E"). In order to access it, the client must 223 first obtain a requesting party token (RPT) from the 224 authorization server on behalf of its requesting party. The 225 client and requesting party are then redirected to the 226 authorization server to ask for appropriate authorization data 227 (the form of this data depends on the RPT profile in use). In 228 doing so, the requesting party must demonstrate to the 229 authorization server that it satisfies the resource owner's 230 policy governing the sought-for resource and scope ("D"). To use 231 the authorization server's authorization API in the first place, 232 the requesting party has to agree to communication with this 233 server for the purpose of seeking authorization, which results in 234 the client obtaining an authorization API token (AAT). 236 3. _Access a resource:_ This phase involves the client successfully 237 presenting an RPT that has sufficient authorization data 238 associated with it to the resource server in order to gain access 239 to the desired resource ("E"). In this sense, it is the "happy 240 path" within phase 2. 242 In deploying UMA, implementers are expected to develop one or more 243 profiles of UMA (described in Section 5) that specify and restrict 244 the various UMA protocol options, according to the deployment 245 conditions. 247 1.1. Notational Conventions 249 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 250 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 251 document are to be interpreted as described in [RFC2119]. 253 Unless otherwise noted, all the protocol properties and values are 254 case sensitive. 256 1.2. Basic Terminology 258 UMA introduces the following new terms and enhancements of OAuth term 259 definitions. 261 resource owner 262 The "user" in User-Managed Access; an OAuth resource owner. 263 This is typically an end-user (a natural person) but it can 264 also be a corporation or other legal person. 266 requesting party 267 An end-user, or a corporation or other legal person, that uses 268 a client to seek access to a protected resource. The 269 requesting party may or may not be the same party as the 270 resource owner. 272 client 273 An application making protected resource requests with the 274 resource owner's authorization and on the requesting party's 275 behalf. 277 claim 278 A statement of the value or values of one or more identity 279 attributes of a requesting party. A requesting party may need 280 to provide claims to an authorization server in order to 281 satisfy policy and gain permission for access to a protected 282 resource. 284 resource set A set of one or more protected resources. In 285 authorization policy terminology, a resource set is the 286 "object" being protected. 288 scope type A bounded extent of access that is possible to perform on 289 a resource set. In authorization policy terminology, a scope 290 type is one of the potentially many "verbs" that can logically 291 apply to a resource set ("object"). UMA associates scope types 292 with labeled resource sets. 294 authorization data Data associated with a requesting party token 295 that enables some combination of the authorization server and 296 resource server to determine the correct extent of access to 297 allow to a client. Authorization data is a key part of the 298 definition of an RPT profile. 300 permission A scope of access over a particular resource set at a 301 particular resource server that is being asked for by, or being 302 granted to, a requesting party. In authorization policy 303 terminology, a permission is an entitlement that includes a 304 "subject" (requesting party), "verbs" (one or more scopes of 305 access), and an "object" (resource set). A permission is one 306 example of authorization data that an authorization server may 307 grant. 309 permission ticket A correlation handle that is conveyed from an 310 authorization server to a resource server, from a resource 311 server to a client, and ultimately from a client to an 312 authorization server, to enable the authorization server to 313 assess the correct resource owner policies to apply to a 314 request for an authorization grant. 316 1.3. Endpoints, Endpoint Protection, and Tokens 318 Various UMA entities present protected APIs for other entities to 319 use. These APIs are as follows: 321 o The authorization server presents a _protection API_ to the 322 resource server, which encompasses the resource registration API 323 defined by the OAuth introduction specification 324 [OAuth-resource-reg], as well as additional functions standardized 325 by this specification. This API is OAuth-protected, requiring a 326 resource server to obtain from the authorization server an OAuth 327 access token called a _protection API token (PAT)_. 329 o The authorization server presents an _authorization API_ to the 330 client, as defined wholly by this specification. This API is 331 OAuth-protected, requiring a client and its requesting party to 332 obtain from the authorization server an OAuth access token, 333 referred to in this specification as an _authorization API token 334 (AAT)_ to distinguish it from other tokens with other purposes. 336 o The resource server presents a _protected resource_ to the client, 337 which can be considered an application-specific or proprietary 338 API. This API is protected by the UMA profile of OAuth, requiring 339 a client to obtain from the authorization server an OAuth access 340 token, referred to in this specification as a _requesting party 341 token (RPT)_ to distinguish it from other tokens with other 342 purposes. 344 The authorization server presents standard OAuth endpoints for token 345 issuance and resource owner authorization in protecting its own UMA 346 APIs, as follows. Resource servers asking to use the protection API 347 would be issued a PAT. Clients and requesting parties asking to use 348 the authorization API would be issued an AAT. 350 token endpoint Part of standard OAuth, as profiled by UMA. The 351 endpoint at which the resource server asks for a PAT on the 352 resource owner's behalf. Also the endpoint at which the client 353 asks for an AAT on the requesting party's behalf. (The 354 authorization server may also choose to issue a refresh token.) 355 This specification makes the OAuth token profile "bearer" 356 mandatory for the authorization server to implement. It can 357 declare its ability to handle other token profiles. 359 user authorization endpoint Part of standard OAuth, as profiled by 360 UMA; used when the authorization code grant type (REQUIRED for 361 the authorization server to implement) is being used. The 362 endpoint to which the resource server redirects an end-user 363 resource owner to authorize the former to use this 364 authorization server in outsourcing resource protection. Also 365 the endpoint to which the client redirects the end-user 366 requesting party to authorize the former to use this 367 authorization server in seeking access. 369 The authorization server presents the following endpoints to the 370 resource server as part of its protection API; these endpoints MUST 371 be OAuth-protected and require a PAT for access, for which the 372 "http://docs.kantarainitiative.org/uma/scopes/prot.json" OAuth scope 373 is required: 375 resource set registration endpoint The endpoint at which the 376 resource server registers resource sets it wants the 377 authorization server to protect, as defined by 378 [OAuth-resource-reg]. The 379 "http://docs.kantarainitiative.org/uma/scopes/prot.json" scope 380 is a superset of the scope that governs usage of the resource 381 set registration endpoint. 383 permission registration endpoint The endpoint at which the resource 384 server registers permissions that it anticipates a client will 385 shortly be asking for from the authorization server. 387 introspection endpoint The endpoint at which the resource server 388 forwards an RPT that has accompanied an access request to learn 389 what authorization data is associated with it, as defined by 390 [OAuth-introspection]. This specification defines an RPT 391 profile, "bearer", which is mandatory for the authorization 392 server to implement and which, if used, REQUIRES the resource 393 server to use this endpoint (see Section 3.3). The 394 "http://docs.kantarainitiative.org/uma/scopes/prot.json" scope 395 is a superset of the scope that governs usage of the token 396 introspection endpoint. 398 The authorization server presents the following endpoints to the 399 client as part of its authorization API; these endpoints are OAuth- 400 protected and require an AAT for access, for which the 401 "http://docs.kantarainitiative.org/uma/scopes/authorization" OAuth 402 scope is required: 404 RPT endpoint The endpoint at which the client asks the authorization 405 server for the issuance of an RPT relating to this requesting 406 party, resource server, and authorization server. 408 permission request endpoint The endpoint at which the client asks 409 for authorization data to be associated with an RPT to enable 410 authorized access. 412 The resource server presents one or more protected resource endpoints 413 to the client; these endpoints are protected by the UMA profile of 414 OAuth and require an RPT with sufficient authorization data to permit 415 access: 417 protected resource endpoint An application-specific endpoint at 418 which a client attempts to access resources. This can be a 419 singular API endpoint, one of a set of API endpoints, a URI 420 corresponding to an HTML document, or any other URI. 422 The authorization server has the opportunity to manage the validity 423 periods of the access tokens, the corresponding refresh tokens where 424 applicable, and even the client credentials that it issues. 425 Different lifetime strategies may be suitable for different resources 426 and scopes of access, and the authorization server has the 427 opportunity to give the resource owner control through policy. These 428 options are all outside the scope of this specification. 430 1.4. Scope Types, Resource Sets, Permissions, and Authorization 432 UMA extends the OAuth concept of a "scope" by defining scope types as 433 applying to labeled resource sets, rather than leaving the relevant 434 resources (such as API endpoints or URIs) implicit. A resource set 435 can have any number of scope types, which together describe the 436 universe of actions that _can be_ taken on this protected resource 437 set. For example, a resource set representing a status update API 438 might have scopes that include adding an update or reading updates. 439 A resource set representing a photo album might have scopes that 440 include viewing a slideshow or printing the album. Resource servers 441 register resource sets and their scope types when there is not yet 442 any particular requesting party or client in the picture. 444 Resource sets and scope types have meaning only to resource servers 445 and their users, in the same way that application-specific protected 446 resource APIs have meaning only to these entities. The authorization 447 server is merely a conveyor of labels and descriptions for these 448 constructs, to help the resource owner set policies that guide 449 eventual authorization processes. 451 A permission, in contrast to a scope type, reflects an _actual_ 452 entitlement to access a resource set using one or more scope types, 453 as the result of an authorization process undergone by a specific 454 requesting party. A resource server registers a permission request 455 with an authorization server on behalf of a client (and its 456 requesting partie) that has attempted access, and transmits the 457 resulting permission ticket to the client. The client subsequently 458 asks the authorization server for authorization data to be associated 459 with its RPT. If the RPT profile is in use, the authorization server 460 grants (or denies) the permission to the requesting party. (If 461 another token profile is in use, the authorization server might 462 generate a different type of authorization data, such as an 463 authorization decision or a package of the claims it has collected.) 465 An RPT is bound to a requesting party, the client being used by that 466 party, the resource server at which protected resources of interest 467 reside, and the authorization server that protects those resources. 468 It becomes associated with as many pieces of authorization data as 469 are appropriate for gaining authorized access to resources protected 470 at that resource server by any single authorization server (even if 471 that data applies to resources managed by two or more different 472 resource owners at the same resource server using the same 473 authorization server). 475 In the case of the UMA "bearer" token profile, each individual 476 permission is associated with the resource owner whose policies drove 477 the authorization process. This enables meaningful, auditable, and 478 potentially legally enforceable authorization for access (see 479 [UMA-obligations]). Permissions have a validity period that the 480 authorization server has the opportunity to control (independently or 481 with input from the resource owner). These control options are 482 outside the scope of this specification. 484 1.5. Authorization Server Configuration Data 486 The authorization server MUST provide configuration data to other 487 entities it interacts with in aJSON [RFC4627] document that resides 488 in an /uma-configuration directory at at its hostmeta [RFC6415] 489 location. The configuration data documents major conformance options 490 supported by the authorization server (described further in 491 Section 8) and protection and authorization API endpoints (as 492 described in Section 1.3). (At the appropriate time, this section 493 will instead profile whatever self-describing metadata specification 494 OAuth adopts, for example, [OAuth-linktypes] or [OAuth-meta].) 496 The configuration data has the following properties. All endpoint 497 URIs supplied SHOULD require the use of a transport-layer security 498 mechanism such as TLS. 500 version 501 REQUIRED. The version of the UMA core protocol to which this 502 authorization server conforms. The value MUST be the string 503 "1.0". 505 issuer 506 REQUIRED. A URI indicating the party operating the 507 authorization server. 509 dynamic_client_endpoint 510 OPTIONAL. The endpoint to use for performing dynamic client 511 registration through . [DynClientReg] 513 oauth_token_profiles_supported 514 REQUIRED. PAT and AAT profiles produced by this authorization 515 server. The property value is an array of string values. 516 Currently the only string value for this property defined by 517 this specification is "bearer", corresponding to the OAuth 518 bearer token profile [OAuth-bearer]. The authorization server 519 is REQUIRED to support this profile, and to supply this string 520 value explicitly. The authorization server MAY declare its 521 support for additional access token profiles by providing a 522 unique absolute URI in a string value in the array for each 523 one. 525 uma_token_profiles_supported 526 REQUIRED. RPT types produced by this authorization server. 527 The property value is an array of string values. Currently the 528 only string value for this property defined by this 529 specification is "bearer", whose associations the resource 530 server MUST determine through a token introspection interaction 531 with the authorization server (see Section 3.3 for the 532 definition of this profile). The authorization server is 533 REQUIRED to support the UMA bearer token profile, and to supply 534 this string value explicitly. The authorization server MAY 535 declare its support for RPTs using additional RPT profiles by 536 providing a unique absolute URI in a string value in the array 537 for each one. 539 oauth_grant_types_supported 540 REQUIRED. OAuth grant types supported by this authorization 541 server in issuing PATs and AATs. The property value is an 542 array of string values. Each string value MUST be one of the 543 grant_type values defined in [OAuth2], or alternatively an 544 extension grant type indicated by a unique absolute URI. 546 claim_profiles_supported 547 OPTIONAL. Claim formats and associated sub-protocols for 548 gathering claims from requesting parties, as supported by this 549 authorization server. The property value is an array of string 550 values. Currently the only string value for this property 551 defined by this specification is "openid", for which details 552 are supplied in Section 3.5.1.1. The authorization server MAY 553 declare its support for additional claim profiles by assigning 554 a unique absolute URI in a string value in the array for each 555 one. 557 token_endpoint 558 REQUIRED. The endpoint URI at which the resource server or 559 client asks the authorization server for a PAT or AAT, 560 respectively. A requested scope of 561 "http://docs.kantarainitiative.org/uma/scopes/prot.json" 562 results in a PAT. A requested scope of 563 "http://docs.kantarainitiative.org/uma/scopes/authorization" 564 results in an AAT. Available HTTP methods are as defined by 565 [OAuth2] for a token endpoint. 567 user_endpoint 568 REQUIRED. The endpoint URI at which the resource server 569 gathers the consent of the end-user resource owner or the 570 client gathers the consent of the end-user requesting party, if 571 the "authorization_code" grant type is used. Available HTTP 572 methods are as defined by [OAuth2] for an end-user 573 authorization endpoint. 575 permission_registration_endpoint 576 REQUIRED. The endpoint URI at which the resource server 577 registers permissions with the authorization server for which a 578 client will be seeking authorization on its requesting party's 579 behalf (see Section 3.2). A PAT MUST accompany requests to 580 this protected endpoint. 582 rpt_endpoint 583 REQUIRED. The endpoint URI at which the client ask the 584 authorization server for an RPT. An AAT token MUST accompany 585 requests to this protected endpoint. 587 rpt_status_endpoint 588 REQUIRED. The endpoint URI at which the resource server 589 introspects an RPT presented to it by a client (see 590 Section 3.3). A PAT MUST accompany requests to this protected 591 endpoint. 593 permission_request_endpoint 594 REQUIRED. The endpoint URI at which the client asks, on its 595 requesting party's behalf, to have authorization data 596 associated with its RPT. An AAT MUST accompany requests to 597 this protected endpoint. 599 Example of authorization server configuration data that resides at 600 https://example.com/.well-known/uma-configuration (note the use of 601 https: for endpoints throughout): 602 { 603 "version":"1.0", 604 "issuer":"https://example.com", 605 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", 606 "oauth_token_profiles_supported":[ 607 "bearer" 608 ], 609 "uma_token_profiles_supported":[ 610 "bearer" 611 ], 612 "oauth_grant_types_supported":[ 613 "authorization_code" 614 ], 615 "claim_profiles_supported":[ 616 "openid" 617 ], 618 "token_endpoint":"https://as.example.com/token_uri", 619 "user_endpoint":"https://as.example.com/user_uri", 620 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri", 621 "rpt_status_endpoint":"https://as.example.com/rs/status_uri", 622 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri", 623 "rpt_endpoint":"https://as.example.com/client/rpt_uri", 624 "permission_request_endpoint":"https://as.example.com/client/perm_uri" 625 } 627 Authorization server configuration data MAY contain extension 628 properties that are not defined in this specification. Extension 629 names that are unprotected from collisions are outside the scope of 630 the current specification. 632 2. Protecting a Resource 634 Phase 1 of UMA is protecting a resource. The resource owner, 635 resource server, and authorization server perform the following steps 636 to successfully complete Phase 1 (assuming that the resource server 637 has discovered the authorization server's configuration data and 638 endpoints as needed): 640 o The resource server and authorization server establish mutual 641 trust through the issuance of client credentials to the resource 642 server. It is OPTIONAL for the client credentials to be provided 643 dynamically through [DynClientReg]); alternatively, they MAY use a 644 static process. 646 o The resource owner, resource server, and authorization server 647 establish three-way trust through the issuance of a PAT. See 648 Section 2.1 for additional details. 650 o The resource server registers any resource sets with the 651 authorization server that are intended to be protected. See 652 Section 2.2 for additional details. 654 2.1. Resource Server Obtains PAT 656 In this step, the resource server acquires a PAT from the 657 authorization server. The token represents the approval of the 658 resource owner for this resource server to trust this authorization 659 server for protecting resources belonging to this resource owner. It 660 is OPTIONAL for the resource owner to introduce the resource server 661 to the authorization server dynamically through the process defined 662 in [OAuth-resource-reg]); alternatively, they MAY use a static 663 process that may or may not directly involve the resource owner at 664 introduction time. 666 The resource server MUST use OAuth 2.0 [OAuth2] to obtain the PAT. 667 Here the resource server acts in the role of an OAuth client 668 requesting the 669 "http://docs.kantarainitiative.org/uma/scopes/prot.json" scope, which 670 authorizes it to use the authorization server's resource set 671 registration endpoint (as defined in [OAuth-resource-reg]) as well as 672 additional protection API endpoints. Once the resource server has 673 obtained its PAT, it presents it to the authorization server at 674 various protection API endpoints. 676 (NOTE: The "http://docs.kantarainitiative.org/uma/scopes/prot.json" 677 scope keyword is a URI that resolves to a JSON-encoded scope 678 description, in the fashion of UMA scope types. This scope 679 description is non-normative.) 681 The authorization server MAY support the use of any OAuth grant type 682 for PAT issuance, but MUST support the authorization_code grant type, 683 and SHOULD support the SAML bearer token grant type [OAuth-SAML] 684 (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates 685 working with resource servers that are operating in environments 686 where the use of SAML is prevalent. The authorization server MUST 687 indicate all grant types it supports for PAT issuance in its 688 configuration data. 690 2.2. Resource Server Registers Sets of Resources to Be Protected 692 Once the resource server has received a PAT, for any of the resource 693 owner's sets of resources that are to be protected by this 694 authorization server, it registers these resource sets in a timely 695 fashion. To do this, the resource server uses the resource set 696 registration API defined in [OAuth-resource-reg]. 698 Note: The resource server is free to offer the option to protect any 699 subset of the resource owner's resources using different 700 authorization servers or other means entirely, or to protect some 701 resources and not others. Additionally, the choice of protection 702 regimes can be made explicitly by the resource owner or implicitly by 703 the resource server. Any such partitioning by the resource server or 704 owner is outside the scope of this specification. 706 On successfully registering a resource set, the RS MUST use access 707 control mechanisms to limit access to any resources corresponding to 708 this resource set, relying on the AS to supply currently valid 709 permissions for authorized access. The RS MUST outsource protection 710 to the AS according to the currently registered state of a resource 711 set. This requirement holds true so long as the RS has one or more 712 registsred resource sets. 714 3. Getting Authorization and Accessing a Resource 716 Phase 2 of UMA is getting authorization, and phase 3 is accessing a 717 resource. In these phases, an authorization server orchestrates and 718 controls clients' access (on their requesting parties' behalf) to a 719 resource owner's protected resources at a resource server, under 720 conditions dictated by that resource owner. 722 Phase 3 is merely the successful completion of a client's access 723 attempt that initially involved several embedded interactions among 724 the client, requesting party, authorization server, and resource 725 server in phase 2. Phase 2 always begins with the client attempting 726 access at a protected resource endpoint at the resource server. How 727 the client came to learn about this endpoint is out of scope for this 728 specification. The resource owner might, for example, have 729 advertised its availability publicly on a blog or other website, 730 listed it in a discovery service, or emailed a link to a particular 731 intended requesting party. 733 The resource server responds to the client's access request in one of 734 several ways depending on the circumstances of the request, either 735 immediately or having first performed one or more embedded 736 interactions with the authorization server. Depending on the nature 737 of the resource server's response to an failed access attempt, the 738 client and its operator engage in embedded interactions with the 739 authorization server before re-attempting access. 741 The interactions are as follows. Each interaction MAY be the last, 742 if the client chooses not to continue pursuing the access attempt or 743 the resource server chooses not to continue facilitating it. 745 1. The client attempts access at a particular protected resource at 746 a resource server (see Section 3.1). 748 A. If the access attempt is unaccompanied by an RPT, the 749 resource server responds immediately with an HTTP 401 750 (Unauthorized) response and instructions on where to go to 751 obtain one (see Section 3.4.2). 753 B. If the access attempt was accompanied by an RPT, the resource 754 server checks the RPT's status (see Section 3.3). 756 1. If the RPT is invalid (for example, it is not applicable 757 to this resource server), the resource server responds to 758 the client with an HTTP 401 (Unauthorized) response and 759 instructions on where to go to obtain a token (see 760 Section 3.4.2). 762 2. If the RPT is valid but has insufficient permission, the 763 resource server registers a suitable permission request 764 on the client's behalf at the authorization server (see 765 Section 3.2), and then responds to the client with an 766 HTTP 403 (Forbidden) response and instructions on where 767 to go to ask for authorization (see Section 3.1.2). 769 3. If the RPT is valid, and if the authorization data 770 associated with the token is consistent with allowing 771 access, the resource server responds to the client's 772 access attempt with an HTTP 200 (OK) response and a 773 representation of the resource (see Section 3.1.3). 775 2. If the client (possessing no RPT or an invalid RPT) received a 776 401 response and an RPT endpoint, it then requests an RPT from 777 that endpoint (see Section 3.4.2). 779 3. If the client (posessing a valid RPT) received a 403 response and 780 a permission ticket, it then asks the authorization server for 781 authorization data that matches the ticket (Section 3.4.3). If 782 the authorization server needs requesting party claims in order 783 to assess this client's authorization, it engages in a claims- 784 gathering flow with the requesting party (see Section 3.5). 786 A. If the client does not already have an AAT at the appropriate 787 authorization server to be able to use its permission request 788 endpoint, it first obtains one (see Section 3.4.1). 790 The interactions are described in detail in the following sections. 792 3.1. Client Attempts to Access Protected Resource 794 This interaction assumes that the resource server has previously 795 registered with an authorization server one or more resource sets 796 that correspond to the resource to which access is being attempted, 797 such that the resource server considers this resource to be protected 798 by a particular authorization server. 800 The client typically attempts to access the desired resource at the 801 resource server directly (for example, when an end-user requesting 802 party clicks on a thumbnail representation of the resource). The 803 client is expected to discover, or be provisioned or configured with, 804 knowledge of the protected resource and its location out of band. 805 Further, the client is expected to acquire its own knowledge about 806 the application-specific methods made available by the resource 807 server for operating on this protected resource (such as viewing it 808 with a GET method, or transforming it with some complex API call) and 809 the possible scopes of access. 811 Example of a request carrying no RPT: 813 GET /album/photo.jpg HTTP/1.1 814 Host: photoz.example.com 815 ... 817 Example of a request carrying an RPT using the UMA "bearer" token 818 profile: 820 GET /album/photo.jpg HTTP/1.1 821 Authorization: Bearer vF9dft4qmT 822 Host: photoz.example.com 823 ... 825 The resource server responds in one of the following ways. 827 3.1.1. Client Presents No RPT 829 If the client does not present any access token with the request, the 830 resource server MUST return an HTTP 401 (Unauthorized) status code, 831 along with providing the authorization server's URI in an "as_uri" 832 property to facilitate authorization server configuration data 833 discovery, including discovery of the endpoint where the client can 834 request an RPT (Section 3.4.2). 836 For example: 838 HTTP/1.1 401 Unauthorized 839 WWW-Authenticate: UMA realm="example", 840 host_id="photoz.example.com", 841 as_uri="http://am.example.com" 842 ... 844 3.1.2. Client Presents an RPT That Has Insufficient Authorization Data 846 If the client presents an RPT with its request, the resource server 847 SHOULD determine the RPT's status (see Section 3.3). If the RPT is 848 invalid, the resource server redirects the client to the RPT endpoint 849 at the authorization server to obtain a correct RPT (see 850 Section 3.4.2). 852 If the RPT is valid but has insufficient permission for the type of 853 access sought, the resource server SHOULD register a permission with 854 the authorization server that would suffice for that scope of access 855 (see Section 3.2), and then respond to the client with the HTTP 403 856 (Forbidden) status code, along with providing the authorization 857 server's URI in the header of the message and the permission ticket 858 it just received from the authorization server in the body in JSON 859 form. 861 Example of the host's response: 863 HTTP/1.1 403 Forbidden 864 WWW-Authenticate: UMA realm="example", 865 host_id="photoz.example.com", 866 as_uri="http://am.example.com" 867 error="insufficient_scope" 869 { 870 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 871 } 873 3.1.3. Client Presents a Valid RPT with Sufficient Authorization Data 875 If the RPT's status is associated with authorization data that is 876 consistent with authorized access of the scope sought by the client 877 (see Section 3.3), the resource server MUST give access to the 878 desired resource. 880 Example of the resource server's response: 882 HTTP/1.1 200 OK 883 Content-Type: image/jpeg 884 ... 886 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 887 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 888 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 889 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 891 This response constitutes the conclusion of [hase 3 of UMA. 893 The resource server MUST NOT give access where the token's status is 894 not associated with sufficient authorization data for the attempted 895 scope of access. 897 3.2. Resource Server Registers a Permission With Authorization Server 899 In response to receiving an access request accompanied by an RPT that 900 is invalid or has insufficient authorization data, the resource 901 server SHOULD register a permission with the authorization server 902 that would be sufficient for the type of access sought. The 903 authorization server returns a permission ticket for the resource 904 server to give to the client in its response. 906 The permission ticket is a short-lived opaque structure whose form is 907 determined by the authorization server. The ticket value MUST be 908 securely random (for example, not merely part of a predictable 909 sequential series), to avoid denial-of-service attacks. Since the 910 ticket is an opaque structure from the point of view of the client, 911 the authorization server is free to include information regarding 912 expiration time within the opaque ticket for its own consumption. 913 When the client subsequently asks the authorization server for 914 authorization data to be associated with its RPT, it will submit this 915 ticket to the authorization server. 917 The resource server registers the permission using the POST method at 918 the authorization server's permission registration endpoint. The 919 resource server MUST provide its valid PAT in order to get access to 920 this endpoint. The body of the HTTP request message contains a JSON 921 document providing the requested permission. 923 The requested scope is an object with the name "requested_permission" 924 and the following properties: 926 resource_set_id REQUIRED. The identifier for a resource set, access 927 to which this client is seeking access. The identifier MUST 928 correspond to a resource set that was previously registered. 930 scopes REQUIRED. An array referencing one or more identifiers of 931 scope types to which access is needed for this resource set. Each 932 scope type identifier MUST correspond to a scope type that was 933 registered by this resource server for the referenced resource 934 set. 936 Example of an HTTP request that registers a permission at the 937 authorization server's permission registration endpoint: 939 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 940 Content-Type: application/json 941 Host: am.example.com 943 { 944 "resource_set_id": "112210f47de98100", 945 "scopes": [ 946 "http://photoz.example.com/dev/actions/view", 947 "http://photoz.example.com/dev/actions/all" 948 ] 949 } 951 If the registration request is successful, the authorization server 952 responds with an HTTP 201 (Created) status code and includes the 953 Location header in its response as well as the "ticket" property in 954 the JSON-formatted body. 956 For example: 958 HTTP/1.1 201 Created 959 Content-Type: application/uma-permission-ticket+json 960 Location: https://am.example.com/permreg/host/photoz.example.com/5454345rdsaa4543 961 ... 963 { 964 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 965 } 967 If the registration request is authenticated properly but fails due 968 to other reasons, the authorization server responds with an HTTP 400 969 (Bad Request) status code and includes one of the following UMA error 970 codes (see Section 4.2): 972 invalid_resource_set_id The provided resource set identifier was not 973 found at the authorization server. 975 invalid_scope At least one of the scopes included in the request was 976 not registered previously by this resource server. 978 3.3. Resource Server Determines the RPT Status 980 On receiving an RPT, the resource server MUST ascertain its status 981 before granting or denying access to the client. An RPT is 982 associated with a set of authorization data that governs whether the 983 client is authorized for access. The token's nature and format are 984 dictated by its profile; the profile might allow it to be self- 985 contained, such that the resource server is able to ascertain its 986 status locally, or might require or allow the resource server to make 987 a run-time introspection request of the authorization server that 988 issued the token using [OAuth-introspection]. 990 This specification makes one type of RPT mandatory to implement: the 991 UMA bearer token profile, as defined in Section 3.3.1. Alternate RPT 992 profiles MAY define their own unique token formats and MAY require, 993 allow, or prohibit use of the token introspection endpoint. 995 3.3.1. UMA Bearer Token Profile 997 This section defines the format and protocol requirements for the UMA 998 bearer token profile. An authorization server MUST support the UMA 999 bearer token profile and MUST indicate its support in the 1000 "uma_token_profiles_supported" property in its configuration data 1001 (see Section 1.5). 1003 On receiving an RPT of the "Bearer" type in an authorization header 1004 from a client making an access attempt, the resource server MUST use 1005 the authorization server's token introspection endpoint 1006 [OAuth-introspection] to retrieve the RPT's associated authorization 1007 data. In order to ask the authorization server for an RPT's status, 1008 the host makes the request to the authorization server with a POST 1009 request to the authorization server's token introspection endpoint. 1010 The body of the HTTP request message contains a JSON document 1011 providing the RPT. The host MUST provide its own PAT in the request 1012 in order to gain access to the RPT status endpoint. 1014 Example of a request to the RPT status endpoint that provides the PAT 1015 in the header: 1017 POST /token_status HTTP/1.1 1018 Host: am.example.com 1019 Authorization: Bearer vF9dft4qmT 1020 ... 1022 { 1023 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1024 "resource_set_id": "112210f47de98100", 1025 "host_id": "photoz.example.com" 1026 } 1028 The authorization server returns the RPT's status in an HTTP response 1029 using the 200 OK status code, containing a JSON document supplying 1030 the RPT's associated permissions. The RPT status description either 1031 contains all of the permissions that are currently valid for this RPT 1032 or indicates that the RPT is invalid (see Section 1.4). The 1033 authorization server MAY set a cache period for the returned RPT 1034 status description that allows the host to reuse it over some period 1035 of time when it later sees the same RPT. 1037 The status description for a valid RPT is a JSON array of zero or 1038 more permission objects, each with the following properties (this 1039 needs to be synced up with the token introspection spec): 1041 resource_set_id REQUIRED. A string that uniquely identifies the 1042 resource set, access to which has been granted to this client on 1043 behalf of this requesting party. The identifier MUST correspond 1044 to a resource set that was previously registered as protected. 1046 scopes REQUIRED. An array referencing one or more URIs of scopes to 1047 which access was granted for this resource set. Each scope MUST 1048 correspond to a scope that was registered by this host for the 1049 referenced resource set. 1051 exp REQUIRED. An integer representing the expiration time on or 1052 after which the permission MUST NOT be accepted for authorized 1053 access. The processing of the exp property requires that the 1054 current date/time MUST be before the expiration date/time listed 1055 in the exp claim. Host implementers MAY provide for some small 1056 leeway, usually no more than a few minutes, to account for clock 1057 skew. 1059 Example: 1061 HTTP/1.1 200 OK 1062 Content-Type: application/json 1063 Cache-Control: no-store 1064 ... 1066 [ 1067 { 1068 "resource_set_id": "112210f47de98100", 1069 "scopes": [ 1070 "http://photoz.example.com/dev/actions/view", 1071 "http://photoz.example.com/dev/actions/all" 1072 ], 1073 "exp": 1300819380 1074 } 1075 ] 1077 The token status description for an invalid RPT is a JSON structure, 1078 as follows. 1080 HTTP/1.1 200 OK 1081 Content-Type: application/json 1082 ... 1084 { 1085 "rpt_status": "invalid" 1086 } 1088 3.4. Client Asks Authorization Server for RPT and Authorization Data 1090 A client making an access attempt accompanied by no RPT or by an 1091 invalid RPT will receive a 401 response back from the resource 1092 server, along with the authorization server's location from which it 1093 can learn the RPT endpoint. In this case, the client must obtain a 1094 valid RPT from the authorization server's RPT endpoint provided in 1095 the response (see Section 3.4.2). 1097 A client making an access attempt with a valid RPT that has 1098 insufficient authorization data associated with it will receive a 403 1099 response back from the resource server, along with a permission 1100 ticket and the authorization server's location from which it can 1101 learn the permission request endpoint. In this case, the client uses 1102 the permission ticket to ask for the necessary authorization data to 1103 be associated with its RPT. This process necessarily involves the 1104 requesting party because the authorization is sought on this party's 1105 behalf. 1107 The client takes action in the following ways (assuming that it has 1108 discovered the authorization server's configuration data and 1109 endpoints as required): 1111 o The client and authorization server establish mutual trust through 1112 the issuance of client credentials to the client. It is OPTIONAL 1113 for the client credentials to be provided dynamically through 1114 [DynClientReg]); alternatively, they MAY use a static process. 1116 o The requesting party, client, and authorization server establish 1117 three-way trust through the issuance of an AAT. See Section 3.4.1 1118 for additional details. 1120 o The client obtains an RPT. See Section 3.4.2 for additional 1121 details. 1123 3.4.1. Client Obtains AAT 1125 In this step, the client acquires an AAT from the authorization 1126 server on the requesting party's behalf. The token represents the 1127 approval of this requesting party for this client to engage with this 1128 authorization server to supply claims, ask for authorization, and 1129 perform any other tasks needed for obtaining authorization for access 1130 to resources at all resource servers that use this authorization 1131 server. It is OPTIONAL for the requesting party to introduce the 1132 client to the authorization server dynamically through the process 1133 defined in [OAuth-resource-reg]); alternatively, they MAY use a 1134 static process that does not directly involve the requesting party. 1136 The client MUST use OAuth 2.0 [OAuth2] to obtain the AAT. Here the 1137 client requests the 1138 "http://docs.kantarainitiative.org/uma/scopes/authz.json" scope. 1139 Once the client has obtained its AAT, it presents it to the 1140 authorization server at the permission request endpoint. 1142 (NOTE: The "http://docs.kantarainitiative.org/uma/scopes/authz.json" 1143 scope keyword is a URI that resolves to a JSON-encoded scope 1144 description, in the fashion of UMA scope types. This scope 1145 description is non-normative.) 1146 The authorization server MAY support the use of any OAuth grant type 1147 for AAT issuance, but MUST support the authorization_code grant type, 1148 and SHOULD support the SAML bearer token grant type [OAuth-SAML] 1149 (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates 1150 working with clients that are operating in environments where the use 1151 of SAML is prevalent. The authorization server MUST indicate all 1152 grant types it supports for AAT issuance in its configuration data. 1154 By virtue of being able to identify this client/requesting party pair 1155 uniquely across all resource servers whose resources it protects, the 1156 authorization server is able to manage the process of authorization 1157 and claims-gathering efficiently. These management processes are 1158 outside the scope of this specification. 1160 3.4.2. Client Obtains RPT 1162 In this step, if the client needs an RPT that applies to this 1163 requesting party for this resource server and this authorization 1164 server, it obtains an RPT. On first issuance the RPT is associated 1165 with no authorization data and thus does not convey any 1166 authorizations for access. 1168 The clieint performs a POST on the RPT endpoint. It MUST provide its 1169 own AAT in the header. 1171 Example of a request message containing an AAT: 1172 POST /rpt HTTP/1.1 1173 Host: am.example.com 1174 Authorization: Bearer jwfLG53^sad$#f 1175 ... 1177 The authorization server responds with an HTTP 201 (Created) status 1178 code and provides a new RPT. 1180 For example: 1182 HTTP/1.1 201 Created 1183 Content-Type: application/uma-rpt+json 1185 { 1186 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1187 } 1189 If the content-type of the request is not recognized by the 1190 authorization server, the latter MUST produce an HTTP error. 1192 The client might need an RPT if it has never before requested an RPT 1193 for this combination of requesting party, resource server, and 1194 authorization server, or if it has lost control of a previously 1195 issued RPT and needs a refreshed one. If the AAT provided in the 1196 header is the same as one provided for a previously issued RPT by 1197 this authorization server, the authorization server invalidates the 1198 old RPT and issues a new one. 1200 If the request fails due to missing or invalid parameters, or is 1201 otherwise malformed, the authorization server SHOULD inform the 1202 client of the error by sending an HTTP error response. 1204 If the request fails due to an invalid, missing, or expired AAT or 1205 requires higher privileges at this endpoint than provided by the AAT, 1206 the authorization server responds with an OAuth error (see 1207 Section 4.1). 1209 For example: 1211 HTTP/1.1 401 Unauthorized 1212 WWW-Authenticate: Bearer realm="example", 1213 error="invalid_token", 1214 error_description="The access token expired" 1216 3.4.3. Client Asks for Authorization Data 1218 Once in possession of an AAT for this authorization server, an RPT 1219 that applies to this requesting party for this resource server and 1220 this authorization server, and a permission ticket, the client asks 1221 the authorization server to give it suitable authorization data for 1222 the sought-for access. The client performs a POST on the permission 1223 request endpoint, supplying the items below. The client MUST provide 1224 its own AAT in the header. 1226 o The permission ticket it received from the resource server 1228 o Its RPT for this resource server 1230 o Its own AAT in the header 1231 Example of a request message containing a permission ticket and RPT: 1232 POST /token_status HTTP/1.1 1233 Host: am.example.com 1234 Authorization: Bearer jwfLG53^sad$#f 1235 ... 1237 { 1238 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1239 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1240 } 1242 In this interaction, the client uses the authorization server's 1243 permission request endpoint. 1245 The authorization server uses the ticket to look up the details of 1246 the previously registered permission, maps the requested permission 1247 to operative resource owner policies, undergoes any authorization 1248 flows required (see Section 3.5), and ultimately responds to the 1249 request positively or negatively. The resource owner's policies at 1250 the authorization server amount to an implicit authorization grant in 1251 governing the issuance of authorization data. (The authorization 1252 server is also free to enable resource owners to set policies that 1253 require them to provide a run-time explicit authorization grant 1254 mediated by the authorization server. This setting of policies and 1255 gathering of authorization grants is outside the scope of this 1256 specification.) 1258 If the request fails due to an invalid, missing, or expired AAT (or 1259 RPT) or requires higher privileges at this endpoint than provided by 1260 the AAT, the authorization server responds with an OAuth error (see 1261 Section 4.1). 1263 For example: 1265 HTTP/1.1 401 Unauthorized 1266 WWW-Authenticate: Bearer realm="example", 1267 error="invalid_token", 1268 error_description="The access token expired" 1270 If the authorization server does not add the requested authorization 1271 data, it responds using the appropriate HTTP status code (typically 1272 400 or 403), and includes one of the following error codes in the 1273 response (see Section 4.2): 1275 invalid_requester_ticket The provided ticket was not found at the 1276 authorization server. The authorization server SHOULD respond 1277 with the HTTP 400 (Bad Request) status code. 1279 expired_requester_ticket The provided ticket has expired. The 1280 authorization server SHOULD respond with the HTTP 400 (Bad 1281 Request) status code. 1283 not_authorized_permission The client is definitively not authorized 1284 for this authorization according to user policy. The 1285 authorization server SHOULD respond with the HTTP 403 (Forbidden) 1286 status code. 1288 need_claims The authorization server is unable to determine whether 1289 the client is authorized for this permission without gathering 1290 claims from the requesting party. The authorization server SHOULD 1291 respond with the HTTP 403 (Forbidden) status code. The client is 1292 therefore not authorized, but has the opportunity to engage its 1293 operator -- the requesting party -- in a claims-gathering flow 1294 with the authorization server (see Section 3.5) to potentially 1295 become authorized. 1297 For example: 1299 HTTP/1.1 400 Bad Request 1300 Content-Type: application/uma-status+json 1301 Cache-Control: no-store 1302 ... 1304 { 1305 "status": "error", 1306 "error": "expired_requester_ticket" 1307 } 1309 3.5. Claims-Gathering Flows 1311 The authorization server MUST base the addition of authorization data 1312 to RPTs on user policies. The nature of these policies is outside 1313 the scope of UMA, but generally speaking, they can be thought of as 1314 either independent of requesting-party features (for example, time of 1315 day) or dependent on requesting-party features (for example, whether 1316 they are over 18). This latter case requires the requesting party to 1317 transmit identity claims to the AM in some fashion. 1319 The process for requesting and providing claims is extensible and may 1320 have a variety of dependencies on the type of requesting party (for 1321 example, natural person or legal person) and the type of client (for 1322 example, browser, native app, or autonomously running web service). 1323 UMA provides a framework for handling end-user-driven clients and an 1324 optional solution for gathering standardized claims from such an end- 1325 user, and allows for extensions to support other solutions for this 1326 use case and other use cases. The authorization server SHOULD 1327 document its claims-handling ability in its configuration data 1328 through the claim_profiles_supported property (see Section 1.5). For 1329 the business-level and legal implications of different technical 1330 authorization flows, see [UMA-obligations]. 1332 3.5.1. Claims-Gathering Flow for Clients Operated by End-Users 1334 A client, whether web-based or native, is operated by an end-user in 1335 one of two typical situations: 1337 o The requesting party is a natural person (for example, a friend of 1338 the resource owner); the requesting party may even be the resource 1339 owner herself. 1341 o The requesting party is a legal person such as a corporation, and 1342 the end-user operating the client is acting as an agent of that 1343 legal person (for example, a customer support specialist 1344 representing a credit card company). 1346 For convenience, this specification refers to the end-user as a 1347 "requesting end-user" to cover both cases, which differ only at the 1348 level of business agreements (and potentially law), rather than 1349 technology. The authorization server has a variety of options at 1350 this point for satisfying the resource owner's policy; this 1351 specification does not dictate a single answer. For example, the 1352 authorization server could require the requesting end-user to 1353 register for and/or log in to a local authorization server account, 1354 or to fill in a questionnaire, or to complete a purchase. It could 1355 even require several of these operations, where the order is treated 1356 as significant. A variety of claim profiling can be defined to 1357 achieve these effects. 1359 An end-user-driven client MUST redirect the requesting end-user to 1360 the authorization server to complete the process of authorization. 1361 The redirection MUST include a URI query parameter with the name 1362 "ticket" whose value conveys the permission ticket for which the 1363 need_claims error was received; for example, "ticket=016f84e8-f9b9- 1364 11e0-bd6f-0021cc6004de". Each claim profile MUST provide the 1365 following capabilities: 1367 redirect URI A means by which the client MUST supply the URI to 1368 which the authorization server MUST redirect the requesting end- 1369 user at the end of the claims-gathering process. 1371 callback URI A means by which the client OPTIONALLY supplies a 1372 callback URI for the authorization server to use. 1374 state A means by which the client SHOULD supply an opaque value used 1375 to maintain state between the request and the callback; this 1376 serves as a protection against XSRF attacks. 1378 An authorization server MAY support any number of claim profiles. 1379 One potential such profile is defined in this specification: the 1380 "openid" claim profile, which leverages OpenID Connect for gathering 1381 generally useful identity claims (see Section 3.5.1.1). 1383 3.5.1.1. OpenID Connect Claim Profile 1385 This section defines the OpenID Connect claim profile for UMA. 1386 Following is a summary: 1388 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 1389 uma-claim-openid-1.0 1391 o Profile author and contact information: Thomas Hardjono 1392 (hardjono@mit.edu) 1394 o Updates or obsoletes: None; this profile is new. 1396 o Authorization server configuration data: To indicate support, 1397 supply the keyword "openid" in the "claim_profiles_supported" 1398 property value. 1400 o Syntax and semantics of claim data: As defined below. The claim 1401 data format leverages the OpenID Connect protocol and the reserved 1402 claims defined in that specification. 1404 o Claims gathering method: As defined below. 1406 o Error states: None additional. 1408 o Security and privacy considerations: None additional. 1410 o Binding obligations: Binding obligations that apply to the use of 1411 this claim profile are documented in [UMA-obligations]. 1413 If an authorization server supports the OpenID Connect claim profile, 1414 it MUST supply the "openid" value for one of its 1415 "claim_profiles_supported" values in its configuration data. 1417 To conform to this option, the authorization server MUST do the 1418 following: 1420 o Serve as a conforming OpenID Relying Party and Claims Client 1421 according to [OCStandard] 1423 o Be able to utilize at least all of the reserved claims defined in 1424 [OCMessages] in assessing policy and granting permissions 1426 o Use the OpenID Connect "redirect_uri" and "state" request 1427 parameters as appropriate 1429 The authorization server can then use any conforming OpenID Connect 1430 mechanisms and typical user interfaces for engaging with the UserInfo 1431 endpoints of OpenID Providers and Claims Providers, potentially 1432 allowing for the delivery of "trusted claims" (such as a verified 1433 email address or a date or birth) on which authorization policy may 1434 depend. 1436 4. Error Messages 1438 Ultimately the resource server is responsible for either granting the 1439 access the client attempted, or returning an error response to the 1440 client with a reason for the failure. [OAuth2] defines several error 1441 responses for a resource server to return. UMA makes use of these 1442 error responses, but requires the resource server to "outsource" the 1443 determination of some error conditions to the authorization server. 1444 UMA defines its own additional error responses that the authorization 1445 server may give to the resource server and client as they interact 1446 with it, and that the resource server may give to the client. 1448 4.1. OAuth Error Responses 1450 When a resource server or client attempts to access one of the 1451 authorization server endpoints Section 1.5 or a client attempts to 1452 access a protected resource at the resource server, it has to make an 1453 authenticated request by including an OAuth access token in the HTTP 1454 request as described in [OAuth2] Section 7. 1456 If the request failed authentication, the authorization server or the 1457 resource server responds with an OAuth error message as described 1458 throughout Section 2 and Section 3. 1460 4.2. UMA Error Responses 1462 When a resource server or client attempts to access one of the 1463 authorization server endpoints Section 1.5 or a client attempts to 1464 access a protected resource at the resource server, if the request is 1465 successfully authenticated by OAuth means, but is invalid for another 1466 reason, the authorization server or resource server responds with an 1467 UMA error response by adding the following properties to the entity 1468 body of the HTTP response: 1470 error REQUIRED. A single error code. Value for this property is 1471 defined in the specific authorization server endpoint description. 1473 error_description OPTIONAL. Human-readable text providing 1474 additional information, used to assist in the understanding and 1475 resolution of the error occurred. 1477 error_uri OPTIONAL. A URI identifying a human-readable web page 1478 with information about the error, used to provide the end-user 1479 with additional information about the error. 1481 Common error codes: 1483 invalid_request The request is missing a required parameter or is 1484 otherwise malformed. The authorization server MUST respond with 1485 the HTTP 400 (Bad Request) status code. 1487 For example: 1489 HTTP/1.1 400 Bad Request 1490 Content-Type: application/uma-status+json 1491 Cache-Control: no-store 1492 ... 1494 { 1495 "status": "error", 1496 "error": "invalid_request", 1497 "error_description": "There is already a resource with this identifier.", 1498 "error_uri": "http://am.example.com/errors/resource_exists" 1499 } 1501 5. Specification of Additional Profiles 1503 This specification defines a protocol that has optional features in 1504 it. For interoperability and deployment purposes to serve particular 1505 use cases, third parties may want to define profiles of the UMA core 1506 protocol that restrict these options. 1508 Further, this specification has two modular and extensible elements 1509 of its design that are specified in terms of specific kinds of 1510 profiles: 1512 o RPT token formats and associated sub-protocol flows: These are 1513 specified in terms of RPT profiles. 1515 o Claims-gathering sub-protocol flows and specific claim types: 1516 These are specified in terms of claim profiles. 1518 Likewise, third parties may want to define additional token and claim 1519 profiles to achieve interoperability and deployment success for 1520 particular use cases. It is not practical for this specification to 1521 standardize all of these additional profiles. However, to serve 1522 overall interoperability goals, the following sections provide 1523 guidelines for third parties that wish to specify profiles of UMA. 1525 5.1. Specifying Profiles of UMA 1527 It is STRONGLY RECOMMENDED that profiles of UMA document the 1528 following information: 1530 1. Specify a URI that uniquely identifies the profile. 1532 2. Identify the responsible author and provide postal or electronic 1533 contact information. 1535 3. Supply references to previously defined profiles that the profile 1536 updates or obsoletes. 1538 4. Specify relevant authorization server configuration data defined 1539 and/or utilized by the profile. 1541 5. Specify the set of interactions between endpoint entites involved 1542 in the profile, calling out any restrictions on ordinary UMA- 1543 conformant operations and any extension properties used in 1544 message formats. 1546 6. Identify the legally responsible parties involved in each 1547 interaction and any new obligations imposed, in the fashion of 1548 [UMA-obligations]. 1550 7. Define any additional or changed error states. 1552 8. Supply any additional security and privacy considerations, 1553 including analysis of threats and description of countermeasures. 1555 5.2. Specifying RPT Profiles 1557 It is STRONGLY RECOMMENDED that RPT profiles document the following 1558 information: 1560 1. Specify a URI that uniquely identifies the token profile. 1562 2. Identify the responsible author and provide postal or electronic 1563 contact information. 1565 3. Supply references to previously defined token profiles that the 1566 token profile updates or obsoletes. 1568 4. Specify the keyword to be used in HTTP Authorization headers 1569 with tokens conforming to this profile. 1571 5. Specify relevant authorization server configuration data defined 1572 and/or utilized by the token profile. At a minimum, specify the 1573 keyword for an authorization server to supply in the value of 1574 the "uma_token_profiles_supported" property to advertise its 1575 support for this token profile. 1577 6. Specify the syntax and semantics of the data that the 1578 authorization server associates with the token. 1580 7. Specify how the token data is associated with, contained within, 1581 and/or retrieved by means of, the on-the-wire token string. 1583 8. Specify processing rules for token data. 1585 9. Identify any restrictions on grant types to be used with the 1586 token profile. 1588 10. Define any additional or changed error states. 1590 11. Supply any additional security and privacy considerations. 1592 12. Specify any obligations specific to the token profile, in the 1593 fashion of [UMA-obligations]. 1595 See Section 3.3.1 for an example. 1597 5.3. Specifying Claim Profiles 1599 It is STRONGLY RECOMMENDED that claim profiles document the following 1600 information: 1602 1. Specify a URI that uniquely identifies the claim profile. 1604 2. Identify the responsible author and provide postal or electronic 1605 contact information. 1607 3. Supply references to previously defined claim profiles that the 1608 claim profile updates or obsoletes. 1610 4. Specify relevant authorization server configuration data defined 1611 and/or utilized by the claim profile. At a minimum, specify the 1612 keyword for an authorization server to supply in the value of the 1613 "claim_profiles_supported" property to advertise its support for 1614 this claim profile. 1616 5. Specify the syntax and semantics of claim data and requests for 1617 claim data. 1619 6. Specify how an authorization server gathers the claims. 1621 7. Define any additional or changed error states. 1623 8. Supply any additional security and privacy considerations. 1625 9. Specify any obligations specific to the claim profile, in the 1626 fashion of [UMA-obligations]. 1628 See Section 3.5.1.1 for an example. 1630 6. Security Considerations 1632 This specification relies mainly on OAuth security mechanisms for 1633 protecting the host registration endpoint at the authorization server 1634 so that only a properly authorized host can access it on behalf of 1635 the intended user. For example, the host needs to use a valid 1636 protection API token (PAT) issued through a user authorization 1637 process at the endpoint, and the interaction SHOULD take place over 1638 TLS. It is expected that the host will protect its client secret (if 1639 it was issued one) and its PAT, particularly if used in "bearer 1640 token" fashion. 1642 In addition, this specification dictates a binding between the PAT 1643 and the host-specific registration area on the authorization server 1644 to prevent a host from interacting with a registration area not its 1645 own. 1647 This specification defines a number of JSON-based data formats. As a 1648 subset of the JavaScript scripting language, JSON data SHOULD be 1649 consumed through a process that does not dynamically execute it as 1650 code, to avoid malicious code execution. One way to achieve this is 1651 to use a JavaScript interpreter rather than the built-in JavaScript 1652 eval() function. 1654 For information about the technical, operational, and legal elements 1655 of trust establishment between UMA entities and parties, which 1656 affects security considerations, see [UMA-obligations]. 1658 7. Privacy Considerations 1660 The authorization server comes to be in possession of resource set 1661 information (such as names and icons) that may reveal information 1662 about the user, which the authorization server's trust relationship 1663 with the host is assumed to accommodate. However, the client is a 1664 less-trusted party (in fact, entirely untrustworthy until it acquires 1665 permissions for an RPT in UMA protocol phase 2. This specification 1666 recommends obscuring resource set identifiers in order to avoid 1667 leaking personally identifiable information to clients through the 1668 "scope" mechanism. 1670 For information about the technical, operational, and legal elements 1671 of trust establishment between UMA entities and parties, which 1672 affects privacy considerations, see [UMA-obligations]. 1674 8. Conformance 1676 This section outlines conformance requirements for various entities 1677 implementing UMA endpoints. 1679 This specification has dependencies on other specifications, as 1680 referenced under the normative references listed in this 1681 specification. Its dependencies on some specifications, such as 1682 OpenID Connect ([OCStandard] and [OCMessages]), are optional 1683 depending on whether the feature in question is used in the 1684 implementation. 1686 The authorization server's configuration data provides a machine- 1687 readable method for it to indicate certain of the conformance options 1688 it has chosen. Several of the configuration data properties allow 1689 for indicating extension features. Where this specification does not 1690 already require optional features to be documented, it is RECOMMENDED 1691 that authorization server developers and deployers document any 1692 profiled or extended features explicitly and use configuration data 1693 to indicate their usage. See Section 1.5 for information about 1694 providing and extending the configuration data. 1696 9. IANA Considerations 1698 This document makes no request of IANA. 1700 10. Acknowledgments 1702 The current editor of this specification is Thomas Hardjono of MIT. 1704 The following people are co-authors: 1706 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 1708 o Domenico Catalano, Oracle Corp. 1710 o George Fletcher, AOL 1712 o Maciej Machulak, Newcastle University 1714 o Eve Maler, XMLgrrl.com 1716 o Lukasz Moren, Newcastle University 1718 o Christian Scholz, COMlounge GmbH (former editor) 1720 o Jacek Szpot, Newcastle University 1722 Additional contributors to this specification include the Kantara UMA 1723 Work Group participants, a list of whom can be found at 1724 [UMAnitarians]. 1726 11. Issues 1728 All issues are now captured at the project's GitHub site 1729 (). 1731 12. References 1733 12.1. Normative References 1735 [DynClientReg] 1736 Richer, J., "OAuth Dynamic Client Registration Protocol", 1737 November 2012, . 1740 [OAuth-SAML] 1741 Campbell, B., "SAML 2.0 Bearer Assertion Profiles for 1742 OAuth 2.0", November 2012, 1743 . 1746 [OAuth-bearer] 1747 "The OAuth 2.0 Authorization Framework: Bearer Token 1748 Usage", October 2012, 1749 . 1751 [OAuth-introspection] 1752 Richer, J., "OAuth Token Introspection", November 2012, . 1756 [OAuth-resource-reg] 1757 Hardjono, T., "OAuth 2.0 Resource Set Registration", 1758 December 2012. 1760 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 1761 October 2012, . 1763 [OCMessages] 1764 Sakimura, N., "OpenID Connect Messages 1.0", 1765 September 2011, 1766 . 1769 [OCStandard] 1770 Sakimura, N., "OpenID Connect Standard 1.0", 1771 September 2011, 1772 . 1775 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1776 Requirement Levels", BCP 14, RFC 2119, March 1997. 1778 [RFC4627] Crockford, D., "The application/json Media Type for 1779 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1781 [RFC6415] Hammer-Lahav, E., "Web Host Metadata", October 2011, 1782 . 1784 [UMA-obligations] 1785 Maler, E., "Binding Obligations on UMA Participants", 1786 April 2012, . 1789 12.2. Informative References 1791 [OAuth-linktypes] 1792 Mills, W., "Link Type Registrations for OAuth 2", 1793 October 2012, 1794 . 1796 [OAuth-meta] 1797 Sakimura, N., "JSON Metadata for OAuth Responses", 1798 December 2012, 1799 . 1801 [UMA-casestudies] 1802 Maler, E., "UMA Case Studies", December 2012, . 1806 [UMA-usecases] 1807 Maler, E., "UMA Scenarios and Use Cases", October 2010, . 1811 [UMAnitarians] 1812 Maler, E., "UMA Participant Roster", 2012, . 1816 Appendix A. Document History 1818 NOTE: To be removed by RFC editor before publication as an RFC. 1820 From I-D rev 03 to rev 04, the following major changes have been 1821 made: 1823 o The requirement to support the client_credentials flow has been 1824 removed. 1826 o The requester access token has been split into two tokens, and all 1827 of the tokens have been renamed. The host access token is now the 1828 PAT. The requester access token used at the AM's API is now the 1829 AAT, and consists of vanilla OAuth. The requester access token 1830 used at the host is now the RPT. 1832 o The token and user authorization endpoints for the different APIs 1833 at the AM have been joined together, and are now distinguished 1834 through the 1835 "http://docs.kantarainitiative.org/uma/scopes/prot.json" scope 1836 (for the protection API) and the 1837 "http://docs.kantarainitiative.org/uma/scopes/authz.json" scope 1838 (for the authorization API). 1840 o The token status description format and JSON media type, and the 1841 RPT/permission delivery response, have been updated to reflect the 1842 RPT naming. 1844 o The configuration data format has changed to reflect the changes 1845 above. 1847 o The Phase 2/3 flow has changed and been simplified to match the 1848 requirements of the new AAT and RPT. 1850 o Token types are now called token profiles, and this is reflected 1851 in the configuration parameter names. Claim types are now called 1852 claim profiles, and this is also reflected in the configuration 1853 parameter name. 1855 o The requester now asks for permission in a back-channel 1856 interaction, and the AM now produces a need_claims error that 1857 instructs the requester to use a claims-gathering flow (renamed 1858 from "authorization flow"). 1860 o Named subsections for token and claim profiles have been added so 1861 that they show up in the TOC. 1863 From I-D rev 04 to rev 05, the following major changes have been 1864 made: 1866 o The RPT-getting flow and the permission-requesting flow have been 1867 separated back out, with two distinct endpoints, RPT and 1868 permission request. 1870 o The configuration data format has changed to reflect the changes 1871 above. 1873 Author's Address 1875 Thomas Hardjono (editor) 1876 MIT 1878 Email: hardjono@mit.edu