idnits 2.17.1 draft-hardjono-oauth-umacore-07.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 6 instances of too long lines in the document, the longest one being 12 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. 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 (June 29, 2013) is 3953 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 1541 -- Looks like a reference, but probably isn't: '2' on line 1636 -- Possible downref: Non-RFC (?) normative reference: ref. 'DynClientReg' -- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth-SAML' -- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth-introspection' -- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth-resource-reg' ** Downref: Normative reference to an Informational RFC: RFC 6819 (ref. 'OAuth-threat') -- 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: 3 errors (**), 0 flaws (~~), 3 warnings (==), 10 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 June 29, 2013 5 Expires: December 31, 2013 7 User-Managed Access (UMA) Profile of OAuth 2.0 8 draft-hardjono-oauth-umacore-07 10 Abstract 12 User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how 13 resource owners can control protected-resource access by clients 14 operated by arbitrary requesting parties, where the resources reside 15 on any number of resource servers, and where a centralized 16 authorization server governs access based on resource owner 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 December 31, 2013. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 5 54 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.3. APIs and Protection . . . . . . . . . . . . . . . . . . . 7 56 1.3.1. Protection and Authorization APIs at the 57 Authorization Server . . . . . . . . . . . . . . . . 7 58 1.3.2. API at the Resource Server . . . . . . . . . . . . . 8 59 1.4. Authorization Server Configuration Data . . . . . . . . . 9 60 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 12 61 3. Getting Authorization and Accessing a Resource . . . . . . . 13 62 3.1. Client Attempts to Access Protected Resource . . . . . . 15 63 3.1.1. Client Presents No RPT . . . . . . . . . . . . . . . 15 64 3.1.2. Client Presents RPT . . . . . . . . . . . . . . . . . 16 65 3.2. Resource Server Registers Requested Permission With 66 Authorization Server . . . . . . . . . . . . . . . . . . 17 67 3.3. Resource Server Determines RPT's Status . . . . . . . . . 19 68 3.3.1. Token Introspection . . . . . . . . . . . . . . . . . 19 69 3.3.2. RPT Profile: Bearer . . . . . . . . . . . . . . . . . 20 70 3.4. Client Seeks Authorization for Access . . . . . . . . . . 22 71 3.4.1. Client Obtains RPT . . . . . . . . . . . . . . . . . 23 72 3.4.2. Client Asks for Authorization Data . . . . . . . . . 23 73 3.5. Claims-Gathering Flows . . . . . . . . . . . . . . . . . 25 74 3.5.1. Claims-Gathering Flow for Clients Operated by End- 75 Users . . . . . . . . . . . . . . . . . . . . . . . . 25 76 3.5.1.1. OpenID Connect Claim Profile . . . . . . . . . . 26 77 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 27 78 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 28 79 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 28 80 5. Specificying Additional Profiles . . . . . . . . . . . . . . 29 81 5.1. Specifying Profiles of UMA . . . . . . . . . . . . . . . 29 82 5.2. Specifying RPT Profiles . . . . . . . . . . . . . . . . . 30 83 5.3. Specifying Claim Profiles . . . . . . . . . . . . . . . . 31 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 31 85 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 33 86 8. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 33 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 88 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 33 89 11. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 90 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 91 12.1. Normative References . . . . . . . . . . . . . . . . . . 34 92 12.2. Informative References . . . . . . . . . . . . . . . . . 35 93 Appendix A. Document History . . . . . . . . . . . . . . . . . . 36 94 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 36 96 1. Introduction 97 User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2]. UMA 98 defines how resource owners can control protected-resource access by 99 clients operated by arbitrary requesting parties, where the resources 100 reside on any number of resource servers, and where a centralized 101 authorization server governs access based on resource owner policy. 102 Resource owners configure authorization servers with access policies 103 that serve as implicit authorization grants. Thus, the UMA profile 104 of OAuth can be considered to encompass an authorization grant flow. 106 UMA serves numerous use cases where a resource owner outsources 107 authorization for access to their resources, potentially even without 108 the run-time presence of the resource owner. A typical example is 109 the following: a web user (an end-user resource owner) can authorize 110 a web app (client) to gain one-time or ongoing access to a protected 111 resource containing his home address stored at a "personal data 112 store" service (resource server), by telling the resource server to 113 respect access entitlements issued by his chosen cloud-based 114 authorization service (authorization server). The requesting party 115 operating the client might be the resource owner himself, using a web 116 or native app run by an e-commerce company that needs to know where 117 to ship a purchased item, or it might be his friend who is using an 118 online address book service to collect contact information, or it 119 might be a survey company that uses an autonomous web service to 120 compile population demographics. A variety of scenarios and use 121 cases can be found in [UMA-usecases] and [UMA-casestudies]. 123 Practical control of access among loosely coupled parties requires 124 more than just messaging protocols. This specification defines only 125 the technical "contract" between UMA-conforming entities; its 126 companion Binding Obligations specification [UMA-obligations] defines 127 the expected behaviors of parties operating and using these entities. 128 Parties operating entities that claim to be UMA-conforming MUST 129 provide documentation affirmatively stating their acceptance of the 130 binding obligations contractual framework defined in the Binding 131 Obligations specification. 133 In enterprise settings, application access management sometimes 134 involves letting back-office applications serve only as policy 135 enforcement points (PEPs), depending entirely on access decisions 136 coming from a central policy decision point (PDP) to govern the 137 access they give to requesters. This separation eases auditing and 138 allows policy administration to scale in several dimensions. UMA 139 makes use of a separation similar to this, letting the resource owner 140 serve as a policy administrator crafting authorization strategies for 141 resources under their control. 143 In order to increase interoperable communication among the 144 authorization server, resource server, and client, UMA defines 145 several purpose-built APIs related to the outsourcing of 146 authorization, themselves protected by OAuth in embedded fashion. 148 The UMA protocol has three broad phases, as shown in Figure 1. 150 The Three Phases of the UMA Profile of OAuth 152 +--------------+ 153 | resource | 154 +---------manage (A)------------ | owner | 155 | +--------------+ 156 | Phase 1: | 157 | protect a control (B) 158 | resource | 159 v v 160 +------------+ +----------+--------------+ 161 | | |protection| | 162 | resource | | API | authorization| 163 | server |<-protect (C)--| (needs | server | 164 | | | PAT) | | 165 +------------+ +----------+--------------+ 166 | protected | | authorization| 167 | resource | | API | 168 |(needs RPT) | | (needs AAT) | 169 +------------+ +--------------+ 170 ^ | 171 | Phases 2 and 3: authorize (D) 172 | get authorization, | 173 | access a resource v 174 | +--------------+ 175 +---------access (E)-------------| client | 176 +--------------+ 178 requesting party 180 Figure 1 182 The phases work as follows: 184 Protect a resource (Described in Section 2.) The resource owner, 185 who manages online resources at the resource server ("A"), 186 introduces it to the authorization server so that the latter can 187 begin controlling the resources' protection. To accomplish this 188 protection, the authorization server presents a protection API 189 ("C") to the resource server. This API is OAuth-protected and 190 requires a protection API token (PAT) for access. The API 191 consists of an OAuth resource set registration endpoint as defined 192 by [OAuth-resource-reg], an endpoint for registering client- 193 requested permissions, and an OAuth token introspection endpoint 194 as defined by [OAuth-introspection]. Out of band, the resource 195 owner configures the authorization server with policies associated 196 with the registered resource sets ("B"). 198 Get authorization (Described in Section 3.) The client approaches 199 the resource server seeking access to a protected resource. In 200 order to access it successfully, the client must first use the 201 authorization server's authorization API ("D") to obtain a 202 requesting party token (RPT) on behalf of its requesting party, 203 and the requesting party must supply to the authorization server 204 any identity claims needed in order for the server to associate 205 sufficient authorization data with that RPT. The API is OAuth- 206 protected and requires an authorization API token (AAT) for 207 access. The API consists of an RPT issuance endpoint and an 208 authorization request endpoint. 210 Access a resource (Described along with Phase 2 in Section 3.) The 211 client successfully presents an RPT that has sufficient 212 authorization data associated with it to the resource server, 213 gaining access to the desired resource ("E"). In this sense, this 214 phase is the "happy path" within phase 2. The nature of the 215 authorization data varies according to the RPT profile in use. 217 Implementers are anticipated to develop profiles (see Section 5) that 218 specify and restrict various UMA protocol, RPT, and identity claim 219 options, according to deployment and usage conditions. 221 1.1. Notational Conventions 223 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 224 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 225 document are to be interpreted as described in [RFC2119]. 227 Unless otherwise noted, all the protocol properties and values are 228 case sensitive. 230 1.2. Terminology 232 UMA introduces the following new terms and enhancements of OAuth term 233 definitions. 235 resource owner 236 An OAuth resource that is the "user" in User-Managed Access. 237 This is typically an end-user (a natural person) but it can 238 also be a corporation or other legal person. 240 requesting party 241 An end-user, or a corporation or other legal person, that uses 242 a client to seek access to a protected resource. The 243 requesting party may or may not be the same party as the 244 resource owner. 246 client 247 An application making protected resource requests with the 248 resource owner's authorization and on the requesting party's 249 behalf. 251 claim 252 A statement of the value or values of one or more identity 253 attributes of a requesting party. A requesting party may need 254 to provide claims to an authorization server in order to 255 satisfy policy and gain permission for access to a protected 256 resource. 258 resource set A set of one or more protected resources. In 259 authorization policy terminology, a resource set is the 260 "object" being protected. 262 scope A bounded extent of access that is possible to perform on a 263 resource set. In authorization policy terminology, a scope is 264 one of the potentially many "verbs" that can logically apply to 265 a resource set ("object"). UMA associates scopes with labeled 266 resource sets. 268 authorization data Data associated with a requesting party token 269 that enables some combination of the authorization server and 270 resource server to determine the correct extent of access to 271 allow to a client. Authorization data is a key part of the 272 definition of an RPT profile. 274 permission A scope of access over a particular resource set at a 275 particular resource server that is being requested by, or 276 granted to, a requesting party. In authorization policy 277 terminology, a permission is an entitlement that includes a 278 "subject" (requesting party), "verbs" (one or more scopes of 279 access), and an "object" (resource set). A permission is one 280 example of authorization data that an authorization server may 281 issue. 283 permission ticket A correlation handle that is conveyed from an 284 authorization server to a resource server, from a resource 285 server to a client, and ultimately from a client to an 286 authorization server, to enable the authorization server to 287 assess the correct resource owner policies to apply to a 288 request for an authorization grant. 290 1.3. APIs and Protection 292 UMA involves three APIs, all of which are protected. 294 The authorization server has the opportunity to manage the validity 295 periods of access tokens that it issues, their corresponding refresh 296 tokens where applicable, the individual data components associated 297 with RPTs where applicable, and even the client credentials that it 298 issues. Different time-to-live strategies may be suitable for 299 different resources and scopes of access, and the authorization 300 server has the opportunity to give the resource owner control over 301 lifetimes of tokens and authorization data issued on their behalf 302 through policy. These options are all outside the scope of this 303 specification. 305 1.3.1. Protection and Authorization APIs at the Authorization Server 307 The authorization server presents a protection API to the resource 308 server and an authorization API to the client. These APIs MUST be 309 OAuth-protected; thus, the authorization server has an OAuth token 310 endpoint and user authorization endpoint, and has the option to issue 311 an OAuth refresh token along with any access tokens issued for these 312 APIs. 314 The protection API consists of an OAuth resource set registration 315 endpoint as defined by [OAuth-resource-reg], an endpoint for 316 registering client-requested permissions, and an OAuth token 317 introspection endpoint as defined by [OAuth-introspection]. This 318 specification profiles the endpoints defined by these other 319 specifications. 321 The authorization API consists of an RPT issuance endpoint and an 322 authorization request endpoint. 324 All endpoint URIs SHOULD require the use of a transport-layer 325 security mechanism such as TLS. The authorization server MUST 326 declare all of its endpoints in its configuration data (see 327 Section 1.4). 329 An entity seeking protection API access MUST request the scope "http: 330 //docs.kantarainitiative.org/uma/scopes/prot.json", and an access 331 token with at least this scope is called a protection API token 332 (PAT). An entity seeking authorization API access MUST request the 333 scope "http://docs.kantarainitiative.org/uma/scopes/authz.json", and 334 an access token with at least this scope is called an authorization 335 API token (AAT). The same entity can serve in both roles, so that an 336 OAuth access token might be considered both a PAT and an AAT if it 337 has both scopes. If a request to an endpoint fails due to an 338 invalid, missing, or expired PAT or AAT, or requires higher 339 privileges at this endpoint than provided by the PAT or AAT, the 340 authorization server responds with an OAuth error. 342 Note: These scope keywords are URIs that resolve to JSON-encoded 343 scope descriptions, as defined in [OAuth-resource-reg]. These scope 344 descriptions are non-normative for the purposes of PATs and AATs. 346 The authorization server is REQUIRED to support the OAuth bearer 347 token profile for PAT and AAT issuance, and MAY support other OAuth 348 token profiles for these purposes. It MUST declare all supported 349 token profiles for PAT and AAT issuance in its configuration data. 350 The authorization server MAY support the use of any OAuth grant type 351 for PAT and AAT issuance, but MUST support the authorization_code 352 grant type, and SHOULD support the SAML bearer token grant type 353 [OAuth-SAML] (urn:ietf:params:oauth:grant-type:saml2-bearer) if it 354 anticipates working with entities that are operating in environments 355 where the use of SAML is prevalent. It MUST declare its supported 356 grant types for PAT and AAT issuance in its configuration data. 358 A PAT binds a resource owner, a resource server the owner uses for 359 resource management, and an authorization server the owner uses for 360 protection of resources at this resource server. It is not specific 361 to any client or requesting party. The issuance of a PAT represents 362 the approval of the resource owner for this resource server to trust 363 this authorization server for protecting its resources belonging to 364 this resource owner. 366 An AAT binds a requesting party, a client being used by that party, 367 and an authorization server that protects resources this client is 368 seeking access to on this requesting party's behalf. It is not 369 specific to any resource server or resource owner. The issuance of 370 an AAT represents the approval of this requesting party for this 371 client to engage with this authorization server to supply claims, ask 372 for authorization, and perform any other tasks needed for obtaining 373 authorization for access to resources at all resource servers that 374 use this authorization server. The authorization server is able to 375 manage future processes of authorization and claims-caching 376 efficiently for this client/requesting party pair across all resource 377 servers they try to access. These management processes are outside 378 the scope of this specification, however. 380 1.3.2. API at the Resource Server 382 The resource server presents one or more protected resource endpoints 383 to the client; these endpoints are protected by the UMA profile of 384 OAuth and require a requesting party token (RPT) with sufficient 385 authorization data for access. This specification defines one RPT 386 profile, call "bearer" (see Section 3.3.2), which is REQUIRED for the 387 authorization server to support. It MAY support additional RPT 388 profiles. It MUST declare all supported RPT profiles in its 389 configuration data. 391 An RPT represents a binding of a requesting party, the client being 392 used by that party, the resource server at which protected resources 393 of interest reside, and the authorization server that protects those 394 resources. It is not specific to a single resource owner, though its 395 internal components are likely to be bound to individual resource 396 owners, depending on the RPT profile in use. 398 1.4. Authorization Server Configuration Data 400 The authorization server MUST provide configuration data in a JSON 401 [RFC4627] document that resides in an /uma-configuration directory at 402 at its hostmeta [hostmeta] location. The configuration data 403 documents conformance options and endpoints supported by the 404 authorization server. (At the appropriate time, this section will 405 instead profile whatever self-describing metadata specification OAuth 406 adopts, for example, [OAuth-linktypes] or [OAuth-meta].) 408 The configuration data has the following properties. 410 version 411 REQUIRED. The version of the UMA core protocol to which this 412 authorization server conforms. The value MUST be the string 413 "1.0". 415 issuer 416 REQUIRED. A URI indicating the party operating the 417 authorization server. 419 pat_profiles_supported 420 REQUIRED. Access token profiles supported by this 421 authorization server for PAT issuance. The property value is 422 an array of string values, where each string value is either a 423 reserved keyword defined in this specification or a URI 424 identifying an access token profile defined elsewhere. The 425 reserved keyword "bearer" as a value for this property stands 426 for the OAuth bearer token profile [OAuth-bearer]. The 427 authorization server is REQUIRED to support this profile, and 428 to supply this string value explicitly. The authorization 429 server MAY declare its support for additional access token 430 profiles for PATs. 432 aat_profiles_supported 433 REQUIRED. Access token profiles supported by this 434 authorization server for AAT issuance. The property value is 435 an array of string values, where each string value is either a 436 reserved keyword defined in this specification or a URI 437 identifying an access token profile defined elsewhere. The 438 reserved keyword "bearer" as a value for this property stands 439 for the OAuth bearer token profile [OAuth-bearer]. The 440 authorization server is REQUIRED to support this profile, and 441 to supply this string value explicitly. The authorization 442 server MAY declare its support for additional access token 443 profiles for AATs. 445 rpt_profiles_supported 446 REQUIRED. Access token profiles supported by this 447 authorization server for RPT issuance. The property value is 448 an array of string values, where each string value is either a 449 reserved keyword defined in this specification or a URI 450 identifying an access token profile defined elsewhere. The 451 reserved keyword "bearer" as a value for this property stands 452 for the UMA bearer RPT profile defined in [OAuth-bearer]. The 453 authorization server is REQUIRED to support this profile, and 454 to supply this string value explicitly. The authorization 455 server MAY declare its support for additional access token 456 profiles for RPTs. 458 pat_grant_types_supported 459 REQUIRED. OAuth grant types supported by this authorization 460 server in issuing PATs. The property value is an array of 461 string values. Each string value MUST be one of the grant_type 462 values defined in [OAuth2], or alternatively a URI identifying 463 a grant type defined elsewhere. 465 aat_grant_types_supported 466 REQUIRED. OAuth grant types supported by this authorization 467 server in issuing AATs. The property value is an array of 468 string values. Each string value MUST be one of the grant_type 469 values defined in [OAuth2], or alternatively a URI identifying 470 a grant type defined elsewhere. 472 claim_profiles_supported 473 OPTIONAL. Claim formats and associated sub-protocols for 474 gathering claims from requesting parties, as supported by this 475 authorization server. The property value is an array of string 476 values, which each string value is either a reserved keyword 477 defined in this specification or a URI identifying a claim 478 profile defined elsewhere. The reserved keyword "openid" as a 479 value for this property stands for the UMA OpenID Connect claim 480 profile defined in Section 3.5.1.1. 482 dynamic_client_endpoint 483 OPTIONAL. The endpoint to use for performing dynamic client 484 registration. Usage is defined by [DynClientReg]. The 485 presence of this property indicates authorization server 486 support for the dynamic client registration feature and its 487 absent indicates a lack of support. 489 token_endpoint 490 REQUIRED. The endpoint URI at which the resource server or 491 client asks the authorization server for a PAT or AAT, 492 respectively. A requested scope of "http:// 493 docs.kantarainitiative.org/uma/scopes/prot.json" results in a 494 PAT. A requested scope of "http://docs.kantarainitiative.org/ 495 uma/scopes/authorization" results in an AAT. Usage is defined 496 by [OAuth2]. 498 user_endpoint 499 REQUIRED. The endpoint URI at which the resource server 500 gathers the consent of the end-user resource owner or the 501 client gathers the consent of the end-user requesting party, if 502 the "authorization_code" grant type is used. Usage is defined 503 by [OAuth2]. 505 introspection_endpoint 506 REQUIRED. The endpoint URI at which the resource server 507 introspects an RPT presented to it by a client. Usage is 508 defined by [OAuth-introspection] and Section 3.3.1. A valid 509 PAT MUST accompany requests to this protected endpoint. 511 resource_set_registration_endpoint 512 REQUIRED. The endpoint URI at which the resource server 513 registers resource sets to put them under authorization manager 514 protection. Usage is defined by [OAuth-resource-reg] and 515 Section 2. A valid PAT MUST accompany requests to this 516 protected endpoint. 518 permission_registration_endpoint 519 REQUIRED. The endpoint URI at which the resource server 520 registers a client-requested permission with the authorization 521 server. Usage is defined by Section 3.2. A valid PAT MUST 522 accompany requests to this protected endpoint. 524 rpt_endpoint 525 REQUIRED. The endpoint URI at which the client asks the 526 authorization server for an RPT. Usage is defined by 527 Section 3.4.1. A valid AAT MUST accompany requests to this 528 protected endpoint. 530 authorization_request_endpoint 531 REQUIRED. The endpoint URI at which the client asks to have 532 authorization data associated with its RPT. Usage is defined 533 in Section 3.4.2. A valid AAT MUST accompany requests to this 534 protected endpoint. 536 Example of authorization server configuration data that resides at 537 https://example.com/.well-known/uma-configuration (note the use of 538 https: for endpoints throughout): 540 { 541 "version":"1.0", 542 "issuer":"https://example.com", 543 "pat_profiles_supported":["bearer"], 544 "aat_profiles_supported":["bearer"], 545 "rpt_profiles_supported":["bearer"], 546 "pat_grant_types_supported":["authorization_code"], 547 "aat_grant_types_supported":["authorization_code"], 548 "claim_profiles_supported":["openid"], 549 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", 550 "token_endpoint":"https://as.example.com/token_uri", 551 "user_endpoint":"https://as.example.com/user_uri", 552 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri", 553 "introspection_endpoint":"https://as.example.com/rs/status_uri", 554 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri", 555 "rpt_endpoint":"https://as.example.com/client/rpt_uri", 556 "authorization_request_endpoint":"https://as.example.com/client/perm_uri" 557 } 559 Authorization server configuration data MAY contain extension 560 properties that are not defined in this specification. Extension 561 names that are unprotected from collisions are outside the scope of 562 this specification. 564 2. Protecting a Resource 566 The resource owner, resource server, and authorization server perform 567 the following actions to put resources under protection. This list 568 assumes that the resource server has discovered the authorization 569 server's configuration data and endpoints as needed. 571 1. The authorization server issues client credentials to the 572 resource server. It is OPTIONAL for the client credentials to be 573 provided dynamically through [DynClientReg]); alternatively, they 574 MAY use a static process. 576 2. The resource server acquires a PAT from the authorization server 577 in order to use the resource set registration endpoint (and 578 later, other protection API endpoints). It is OPTIONAL for the 579 resource owner to introduce the resource server to the 580 authorization server dynamically (for example, through a 581 "NASCAR"-style user interface where the resource owner selects a 582 chosen authorization server); alternatively, they MAY use a 583 static process that may or may not directly involve the resource 584 owner at introduction time. 586 3. In an ongoing fashion, the resource server registers any resource 587 sets with the authorization server for which it intends to 588 outsource protection, using the process defined by 589 [OAuth-resource-reg]. 591 Note: The resource server is free to offer the option to protect any 592 subset of the resource owner's resources using different 593 authorization servers or other means entirely, or to protect some 594 resources and not others. Additionally, the choice of protection 595 regimes can be made explicitly by the resource owner or implicitly by 596 the resource server. Any such partitioning by the resource server or 597 owner is outside the scope of this specification. 599 Once a resource set has been placed under authorization server 600 protection through the registration of a resource set description for 601 it, and until such a description's deletion by the resource server, 602 the resource server MUST limit access to corresponding resources, 603 respecting authorization data associated with client-presented RPTs 604 by the authorization server as appropriate (see Section 3.1.2). 606 3. Getting Authorization and Accessing a Resource 608 An authorization server orchestrates and controls clients' access (on 609 their requesting parties' behalf) to a resource owner's protected 610 resources at a resource server, under conditions dictated by that 611 resource owner. 613 The process of getting authorization and accessing a resource always 614 begins with the client attempting access at a protected resource 615 endpoint at the resource server. How the client came to learn about 616 this endpoint is out of scope for this specification. The resource 617 owner might, for example, have advertised its availability publicly 618 on a blog or other website, listed it in a discovery service, or 619 emailed a link to a particular intended requesting party. 621 The resource server responds to the client's access request with 622 whatever its application-specific interface defines as a success 623 response, either immediately or having first performed one or more 624 embedded interactions with the authorization server. Depending on 625 the nature of the resource server's response to an failed access 626 attempt, the client and its requesting party engage in embedded 627 interactions with the authorization server before re-attempting 628 access. 630 The interactions are as follows. Each interaction MAY be the last, 631 if the client chooses not to continue pursuing the access attempt or 632 the resource server chooses not to continue facilitating it. 634 o The client attempts to access a protected resource. 636 * If the access attempt is unaccompanied by an RPT, the resource 637 server responds immediately with an HTTP 401 (Unauthorized) 638 response and instructions on where to go to obtain one. 640 * If the access attempt was accompanied by an RPT, the resource 641 server checks the RPT's status. 643 + If the RPT is invalid, the resource server responds with an 644 HTTP 401 (Unauthorized) response and instructions on where 645 to go to obtain a token. 647 + If the RPT is valid but has insufficient authorization data, 648 the resource server registers a suitable requested 649 permission on the client's behalf at the authorization 650 server, and then responds to the client with an HTTP 403 651 (Forbidden) response and instructions on where to go to ask 652 for authorization. 654 + If the RPT is valid, and if the authorization data 655 associated with the token is sufficient for allowing access, 656 the resource server responds with an HTTP 2xx (Success) 657 response and a representation of the resource. 659 o If the client (possessing no RPT or an invalid RPT) received a 401 660 response and an authorization server's location, after looking up 661 its configuration data and endpoints as necessary, it requests an 662 RPT from the RPT endpoint. 664 o If the client (posessing a valid RPT) received a 403 response and 665 a permission ticket, it asks the authorization server for 666 authorization data that matches the ticket. If the authorization 667 server needs requesting party claims in order to assess this 668 client's authorization, it engages in a claims-gathering flow with 669 the requesting party. 671 * If the client does not already have an AAT at the appropriate 672 authorization server to be able to use its authorization API, 673 it first obtains one. 675 The interactions are described in detail in the following sections. 677 3.1. Client Attempts to Access Protected Resource 679 This interaction assumes that the resource server has previously 680 registered one or more resource sets that correspond to the resource 681 to which access is being attempted. 683 The client attempts to access a protected resource (for example, when 684 an end-user requesting party clicks on a thumbnail representation of 685 the resource to retrieve a larger version). It is expected to 686 discover, or be provisioned or configured with, knowledge of the 687 protected resource and its location out of band. Further, the client 688 is expected to acquire its own knowledge about the application- 689 specific methods made available by the resource server for operating 690 on this protected resource (such as viewing it with a GET method, or 691 transforming it with some complex API call) and the possible scopes 692 of access. 694 The access attempt either is or is not accompanied by an RPT. 696 3.1.1. Client Presents No RPT 698 Example of a request carrying no RPT: 700 GET /album/photo.jpg HTTP/1.1 701 Host: photoz.example.com 702 ... 704 If the client does not present an RPT with the request, the resource 705 server MUST return an HTTP 401 (Unauthorized) status code, along with 706 providing the authorization server's URI in an "as_uri" property to 707 facilitate authorization server configuration data discovery, 708 including discovery of the endpoint where the client can request an 709 RPT (Section 3.4.1). 711 For example: 713 HTTP/1.1 401 Unauthorized 714 WWW-Authenticate: UMA realm="example", 715 host_id="photoz.example.com", 716 as_uri="https://as.example.com" 717 ... 719 3.1.2. Client Presents RPT 721 Example of a request carrying an RPT using the UMA bearer RPT 722 profile: 724 GET /album/photo.jpg HTTP/1.1 725 Authorization: Bearer vF9dft4qmT 726 Host: photoz.example.com 727 ... 729 If the client presents an RPT with its request, the resource server 730 MUST determine the RPT's status (see Section 3.3) before responding. 732 If the RPT is invalid, the resource server MUST return an HTTP 401 733 (Unauthorized) status code, along with providing the authorization 734 server's URI in an "as_uri" property in the header, similarly to the 735 case where no RPT was presented. 737 If the RPT is valid but has insufficient authorization data for the 738 type of access sought, the resource server SHOULD register a 739 requested permission with the authorization server that would suffice 740 for that scope of access (see Section 3.2), and then respond with the 741 HTTP 403 (Forbidden) status code, along with providing the 742 authorization server's URI in an "as_uri" property in the header, and 743 the permission ticket it just received from the AM in the body in a 744 JSON-encoded "ticket" property. 746 Example of the host's response after having registered a requested 747 permission and received a ticket: 749 HTTP/1.1 403 Forbidden 750 WWW-Authenticate: UMA realm="example", 751 host_id="photoz.example.com", 752 as_uri="https://as.example.com" 753 error="insufficient_scope" 755 { 756 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 757 } 759 If the RPT's status is associated with authorization data that is 760 consistent with authorized access of the scope sought by the client, 761 the resource server MUST give access to the desired resource. 763 Example of the resource server's response after having determineed 764 that the RPT is valid and associated with sufficient authorization 765 data: 767 HTTP/1.1 200 OK 768 Content-Type: image/jpeg 769 ... 771 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 772 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 773 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 774 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 776 The resource server MUST NOT give access where the token's status is 777 not associated with sufficient authorization data for the attempted 778 scope of access. 780 3.2. Resource Server Registers Requested Permission With Authorization 781 Server 783 In response to receiving an access request accompanied by an RPT that 784 has insufficient authorization data, the resource server registers a 785 permission with the authorization server that would be sufficient for 786 the type of access sought. The authorization server returns a 787 permission ticket for the resource server to give to the client in 788 its response. 790 The resource server MUST provide its valid PAT in order to get access 791 to this endpoint. Note that this PAT implicitly identifies the 792 resource owner ("subject") to which the permission applies. 794 The permission ticket is a short-lived opaque structure whose form is 795 determined by the authorization server. The ticket value MUST be 796 securely random (for example, not merely part of a predictable 797 sequential series), to avoid denial-of-service attacks. Since the 798 ticket is an opaque structure from the point of view of the client, 799 the authorization server is free to include information regarding 800 expiration time within the opaque ticket for its own consumption. 801 When the client subsequently asks the authorization server for 802 authorization data to be associated with its RPT, it will submit this 803 ticket to the authorization server. 805 The resource server registers the requested permission using the POST 806 method at the authorization server's permission registration 807 endpoint. The resource server MUST provide its valid PAT in order to 808 get access to this endpoint. The body of the HTTP request message 809 contains a JSON object providing the requested permission, using a 810 format derived from the scope description format specified in 811 [OAuth-resource-reg], as follows. The object has the following 812 properties: 814 resource_set_id REQUIRED. The identifier for a resource set, access 815 to which this client is seeking access. The identifier MUST 816 correspond to a resource set that was previously registered. 818 scopes REQUIRED. An array referencing one or more identifiers of 819 scopes to which access is needed for this resource set. Each 820 scope identifier MUST correspond to a scope that was registered by 821 this resource server for the referenced resource set. 823 Example of an HTTP request that registers a requested permission at 824 the authorization server's permission registration endpoint: 826 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 827 Content-Type: application/json 828 Host: as.example.com 830 { 831 "resource_set_id": "112210f47de98100", 832 "scopes": [ 833 "http://photoz.example.com/dev/actions/view", 834 "http://photoz.example.com/dev/actions/all" 835 ] 836 } 837 If the registration request is successful, the authorization server 838 responds with an HTTP 201 (Created) status code and includes the 839 Location header in its response as well as the "ticket" property in 840 the JSON-formatted body. 842 For example: 844 HTTP/1.1 201 Created 845 Content-Type: application/json 846 Location: https://as.example.com/permreg/host/photoz.example.com/5454345rdsaa4543 847 ... 849 { 850 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 851 } 853 If the registration request is authenticated properly but fails due 854 to other reasons, the authorization server responds with an HTTP 400 855 (Bad Request) status code and includes one of the following UMA error 856 codes (see Section 4.2): 858 invalid_resource_set_id The provided resource set identifier was not 859 found at the authorization server. 861 invalid_scope At least one of the scopes included in the request was 862 not registered previously by this resource server. 864 3.3. Resource Server Determines RPT's Status 866 The resource server determines a received RPT's status, including 867 both its validity and, if valid, its associated authorization data, 868 before giving or refusing access to the client. An RPT is associated 869 with a set of authorization data that governs whether the client is 870 authorized for access. The token's nature and format are dictated by 871 its profile; the profile might allow it to be self-contained, such 872 that the resource server is able to determine its status locally, or 873 might require or allow the resource server to make a run-time 874 introspection request of the authorization server that issued the 875 token. 877 This specification makes one type of RPT mandatory to implement: the 878 UMA bearer token profile, as defined in Section 3.3.2. Implementers 879 MAY define and use other RPT profiles. 881 3.3.1. Token Introspection 882 Within any RPT profile, when a resource server needs to introspect a 883 token in a non-self-contained way to determine its status, it MUST 884 use the authorization server's OAuth introspection endpoint, defined 885 by [OAuth-introspection]. Any UMA token profile MAY require, allow, 886 or prohibit use of the token introspection endpoint, and MAY profile 887 its usage. The authorization server MUST OAuth-protect this endpoint 888 and require a PAT from the resource server for access to it. The 889 resource server MUST use the POST method in interacting with the 890 endpoint, not the GET method also defined by [OAuth-introspection]. 892 3.3.2. RPT Profile: Bearer 894 This section defines the UMA bearer token profile. Following is a 895 summary: 897 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 898 uma-token-bearer-1.0 900 o Profile author and contact information: Thomas Hardjono 901 (hardjono@mit.edu) 903 o Updates or obsoletes: None; this profile is new. 905 o Keyword in HTTP Authorization header: "Bearer". 907 o Syntax and semantics of token data: As defined below. The token 908 data format mainly involves time-bounded permissions. 910 o Token data association: The data associated to the on-the-wire 911 token by reference and retrieved at run time by the resource 912 server through profiled use of the OAuth token introspection 913 endpoint [OAuth-introspection], as defined below. 915 o Token data processing: As defined in this section and throughout 916 Section 3 of this specification. 918 o Grant type restrictions: None. 920 o Error states: As defined below. 922 o Security and privacy considerations: As defined in this section 923 and throughout Section 3 of this specification. 925 o Binding obligations: Because this RPT profile is mandatory for 926 authorization servers to implement, binding obligations related to 927 the use of this token profile are documented in [UMA-obligations]. 929 On receiving an RPT of the "Bearer" type in an authorization header 930 from a client making an access attempt, the resource server MUST 931 introspect the token by using the authorization server's token 932 introspection endpoint. The PAT used by the resource server to make 933 the introspection request provides resource-owner context to the 934 authorization server. 936 The authorization server responds with a JSON object with the 937 structure dictated by [OAuth-introspection]. If the valid property 938 has a "true" value, then the JSON object MUST also contain an 939 extension property with the name "permissions" that contains an array 940 of zero or more values, each of which is an object consisting of 941 these properties: 943 resource_set_id REQUIRED. A string that uniquely identifies the 944 resource set, access to which has been granted to this client on 945 behalf of this requesting party. The identifier MUST correspond 946 to a resource set that was previously registered as protected. 948 scopes REQUIRED. An array referencing one or more URIs of scopes to 949 which access was granted for this resource set. Each scope MUST 950 correspond to a scope that was registered by this host for the 951 referenced resource set. 953 expires_at REQUIRED. Integer timestamp, measured in the number of 954 seconds since January 1 1970 UTC, indicating when this permission 955 will expire. 957 issued_at OPTIONAL. Integer timestamp, measured in the number of 958 seconds since January 1 1970 UTC, indicating when this permission 959 was originally issued. 961 Example: 963 HTTP/1.1 200 OK 964 Content-Type: application/json 965 Cache-Control: no-store 967 { 968 "valid": true, 969 "expires_at": "1256953732", 970 "issued_at": "1256912345", 971 "permissions": [ 972 { 973 "resource_set_id": "112210f47de98100", 974 "scopes": [ 975 "http://photoz.example.com/dev/actions/view", 976 "http://photoz.example.com/dev/actions/all" 977 ], 978 "expires_at" : "1256923456" 979 } 980 ] 981 } 983 3.4. Client Seeks Authorization for Access 985 In order to access a protected resource successfully, a client needs 986 to present a valid RPT with sufficient authorization data for access. 987 To get to this stage requires a number of previously successful 988 steps: 990 1. The authorization server issues client credentials to the client. 991 It is OPTIONAL for the client credentials to be provided 992 dynamically through [DynClientReg]); alternatively, they MAY use 993 a static process. 995 2. The client acquires an AAT. This enables it to use authorization 996 API endpoints. 998 3. The client acquires an RPT from the RPT endpoint. See 999 Section 3.4.1 for more detail. 1001 4. The client asks for authorization at the authorization request 1002 endpoint, providing the permission ticket it got from the 1003 resource server. The authorization server associates 1004 authorization data with the client's RPT based on the permission 1005 ticket, the resource owner's operative policies, and the results 1006 of any claims-gathering flows with the requesting party. See 1007 Section 3.4.2 for more detail. 1009 3.4.1. Client Obtains RPT 1011 The client might need an RPT if it has never before requested an RPT 1012 for this combination of requesting party, resource server, and 1013 authorization server, or if it has lost control of a previously 1014 issued RPT and needs a refreshed one. It obtains an RPT by 1015 performing a POST on the RPT endpoint. It MUST provide its own valid 1016 AAT in the header. 1018 Example of a request message containing an AAT: 1020 POST /rpt HTTP/1.1 1021 Host: as.example.com 1022 Authorization: Bearer jwfLG53^sad$#f 1023 ... 1025 The authorization server responds with an HTTP 201 (Created) status 1026 code and provides a new RPT. 1028 For example: 1030 HTTP/1.1 201 Created 1031 Content-Type: application/json 1033 { 1034 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1035 } 1037 If the AAT provided in the header is the same as one provided for a 1038 previously issued still-valid RPT by this authorization server, the 1039 authorization server invalidates the old RPT and issues a new one. 1041 On first issuance, the RPT is associated with no authorization data 1042 and thus does not convey any authorizations for access. 1044 3.4.2. Client Asks for Authorization Data 1046 Once in possession of an AAT for this authorization server, an RPT 1047 that applies to this requesting party for this resource server and 1048 this authorization server, and a permission ticket, the client asks 1049 the authorization server to give it suitable authorization data for 1050 the sought-for access. It performs a POST on the authorization 1051 request endpoint, supplying its own AAT in the header and its RPT and 1052 the permission ticket in a JSON object with properties "rpt" and 1053 ticket", respectively. 1055 Example of a request message containing an AAT, an RPT, and a 1056 permission ticket: 1058 POST /token_status HTTP/1.1 1059 Host: as.example.com 1060 Authorization: Bearer jwfLG53^sad$#f 1061 ... 1063 { 1064 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1065 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1066 } 1068 The authorization server uses the ticket to look up the details of 1069 the previously registered requested permission, maps the requested 1070 permission to operative resource owner policies based on the resource 1071 set identifier and scopes in it, undergoes any claims-gathering flows 1072 required (see Section 3.5), and ultimately responds to the request. 1073 The resource owner's policies at the authorization server amount to 1074 an implicit authorization grant in governing the issuance of 1075 authorization data. (The authorization server is also free to enable 1076 the resource owner to set policies that require the owner to provide 1077 a run-time authorization grant in the form of a consent interaction, 1078 mediated by the authorization server. This setting of policies and 1079 gathering of consent is outside the scope of this specification.) 1081 The authorization server MUST base the addition of authorization data 1082 to RPTs on user policies. The nature of these policies is outside 1083 the scope of UMA, but generally speaking, they can be thought of as 1084 either independent of requesting-party features (for example, time of 1085 day) or dependent on requesting-party features (for example, whether 1086 they are over 18). Such requesting-party features can potentially be 1087 collected in a claims-gathering flow. If the authorization server 1088 does not add the requested authorization data, it responds using the 1089 appropriate HTTP status code and UMA error code (see Section 4.2): 1091 invalid_ticket The provided ticket was not found at the 1092 authorization server. The authorization server SHOULD respond 1093 with the HTTP 400 (Bad Request) status code. 1095 expired_ticket The provided ticket has expired. The authorization 1096 server SHOULD respond with the HTTP 400 (Bad Request) status code. 1098 not_authorized_permission The client is definitively not authorized 1099 for this authorization according to user policy. The 1100 authorization server SHOULD respond with the HTTP 403 (Forbidden) 1101 status code. 1103 need_claims The authorization server is unable to determine whether 1104 the client is authorized for this permission without gathering 1105 claims from the requesting party. The authorization server SHOULD 1106 respond with the HTTP 403 (Forbidden) status code. The client is 1107 therefore not authorized, but has the opportunity to engage its 1108 operator -- the requesting party -- in a claims-gathering flow 1109 with the authorization server (see Section 3.5) to continue 1110 seeking authorization. 1112 For example: 1114 HTTP/1.1 400 Bad Request 1115 Content-Type: application/json 1116 Cache-Control: no-store 1117 ... 1119 { 1120 "status": "error", 1121 "error": "expired_ticket" 1122 } 1124 3.5. Claims-Gathering Flows 1126 The process for requesting and providing claims is extensible and may 1127 have a variety of dependencies on the type of requesting party (for 1128 example, natural person or legal person) and the type of client (for 1129 example, browser, native app, or autonomously running web service). 1130 This specification provides a framework for handling end-user-driven 1131 clients and an optional "openid" claim profile, based on OpenID 1132 Connect, for gathering standardized claims from such an end-user. It 1133 also allows for the definition of additional claim profiles. The 1134 authorization server MAY support any number of claim profiles, and 1135 SHOULD document the claim profiles it supports its configuration 1136 data. For the business-level and legal implications of different 1137 claim profiles, see [UMA-obligations]. 1139 3.5.1. Claims-Gathering Flow for Clients Operated by End-Users 1141 A client, whether web-based or native, is operated by an end-user in 1142 one of two typical situations: 1144 o The requesting party is a natural person (for example, a friend of 1145 the resource owner); the requesting party may even be the resource 1146 owner herself. 1148 o The requesting party is a legal person such as a corporation, and 1149 the end-user operating the client is acting as an agent of that 1150 legal person (for example, a customer support specialist 1151 representing a credit card company). 1153 For convenience, this specification refers to the end-user as a 1154 "requesting end-user" to cover both cases, which differ only at the 1155 level of business agreements (and potentially law), rather than 1156 technology. The authorization server has a variety of options at 1157 this point for satisfying the resource owner's policy; this 1158 specification does not dictate a single answer. For example, the 1159 authorization server could require the requesting end-user to 1160 register for and/or log in to a local authorization server account, 1161 or fill in a questionnaire, or complete a purchase. It could even 1162 require several of these operations, where the order is treated as 1163 significant for evaluating resource owner policies. A variety of 1164 claim profiling can be defined to achieve these effects. 1166 An end-user-driven client MUST redirect the requesting end-user to 1167 the authorization server in order to continue the process of seeking 1168 authorization, including a URI query parameter with the name "ticket" 1169 whose value conveys the permission ticket for which the need_claims 1170 error was received; for example, "ticket=016f84e8-f9b9-11e0-bd6f- 1171 0021cc6004de". 1173 Each claim profile MUST provide the following capabilities: 1175 redirect URI A means by which the client MUST supply the URI to 1176 which the authorization server MUST redirect the requesting end- 1177 user at the end of the claims-gathering process. 1179 callback URI A means by which the client OPTIONALLY supplies a 1180 callback URI for the authorization server to use. 1182 state A means by which the client SHOULD supply an opaque value used 1183 to maintain state between the request and the callback; this 1184 serves as a protection against XSRF attacks. 1186 3.5.1.1. OpenID Connect Claim Profile 1188 This section defines the OpenID Connect claim profile for UMA. 1189 Following is a summary: 1191 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 1192 uma-claim-openid-1.0 1194 o Profile author and contact information: Thomas Hardjono 1195 (hardjono@mit.edu) 1197 o Updates or obsoletes: None; this profile is new. 1199 o Syntax and semantics of claim data: As defined below. The claim 1200 data format leverages the OpenID Connect protocol and the reserved 1201 claims defined in that specification. 1203 o Claims gathering method: As defined below. 1205 o Error states: None additional. 1207 o Security and privacy considerations: None additional. 1209 o Binding obligations: Binding obligations that apply to the use of 1210 this claim profile are documented in [UMA-obligations]. 1212 If an authorization server supports the OpenID Connect claim profile, 1213 it MUST supply the "openid" value for one of its 1214 "claim_profiles_supported" values in its configuration data. 1216 To conform to this option, the authorization server MUST do the 1217 following: 1219 o Serve as a conforming OpenID Relying Party and Claims Client 1220 according to [OCStandard] 1222 o Be able to utilize at least all of the reserved claims defined in 1223 [OCMessages] in evaluating policy and adding authorization data to 1224 RPTs 1226 o Use the OpenID Connect "redirect_uri" and "state" request 1227 parameters as appropriate 1229 The authorization server can then use any conforming OpenID Connect 1230 mechanisms and typical user interfaces for engaging with the UserInfo 1231 endpoints of OpenID Providers and Claims Providers, potentially 1232 allowing for the delivery of "trusted claims" (such as a verified 1233 email address or a date or birth) on which authorization policy for 1234 access may depend. 1236 4. Error Messages 1237 Ultimately the resource server is responsible for either granting the 1238 access the client attempted, or returning an error response to the 1239 client with a reason for the failure. [OAuth2] defines several error 1240 responses for a resource server to return. UMA makes use of these 1241 error responses, but requires the resource server to "outsource" the 1242 determination of some error conditions to the authorization server. 1243 This specification defines additional UMA-specific error responses 1244 that the authorization server may give to the resource server and 1245 client as they interact with it, and that the resource server may 1246 give to the client. 1248 4.1. OAuth Error Responses 1250 When a resource server or client attempts to access one of the 1251 authorization server endpoints or a client attempts to access a 1252 protected resource at the resource server, it has to make an 1253 authenticated request by including an OAuth access token in the HTTP 1254 request as described in [OAuth2] Section 7.2. 1256 If the request failed authentication, the authorization server or the 1257 resource server responds with an OAuth error message as described 1258 throughout Section 2 and Section 3. 1260 4.2. UMA Error Responses 1262 When a resource server or client attempts to access one of the 1263 authorization server endpoints or a client attempts to access a 1264 protected resource at the resource server, if the request is 1265 successfully authenticated by OAuth means, but is invalid for another 1266 reason, the authorization server or resource server responds with an 1267 UMA error response by adding the following properties to the entity 1268 body of the HTTP response: 1270 error REQUIRED. A single error code. Values for this property are 1271 defined throughout this specification. 1273 error_description OPTIONAL. Human-readable text providing 1274 additional information. 1276 error_uri OPTIONAL. A URI identifying a human-readable web page 1277 with information about the error. 1279 The following is a common error code that applies to several UMA- 1280 specified request messages: 1282 invalid_request The request is missing a required parameter, 1283 includes an invalid parameter value, includes a parameter more 1284 than once, or is otherwise malformed. The authorization server 1285 MUST respond with the HTTP 400 (Bad Request) status code. 1287 For example: 1289 HTTP/1.1 400 Bad Request 1290 Content-Type: application/json 1291 Cache-Control: no-store 1292 ... 1294 { 1295 "status": "error", 1296 "error": "invalid_request", 1297 "error_description": "There is already a resource with this identifier.", 1298 "error_uri": "http://as.example.com/errors/resource_exists" 1299 } 1301 5. Specificying Additional Profiles 1303 This specification defines a protocol that has optional features. 1304 For interoperability and to serve particular deployment scenarios, 1305 including sector-specific ones such as healthcare or e-government, 1306 third parties may want to define profiles of UMA that restrict these 1307 options. 1309 Further, this specification creates extensibility points for RPT 1310 profiles and claim profiles, and third parties may likewise want to 1311 define their own. Different RPT profile could be used, for example, 1312 to change the dividing line between authorization server and resource 1313 server responsibilities in controlling access. Different claim 1314 profiles could be used to customize sector-specific or population- 1315 specific (individual vs. employee) claim types that drive the types 1316 of policies resource owners could set. 1318 It is not practical for this specification to standardize all desired 1319 profiles. However, to serve overall interoperability goals, the 1320 following sections provide guidelines for third parties that wish to 1321 specify UMA-related profiles. 1323 5.1. Specifying Profiles of UMA 1325 It is RECOMMENDED that profiles of UMA document the following 1326 information: 1328 1. Specify a URI that uniquely identifies the profile. 1330 2. Identify the responsible author and provide postal or electronic 1331 contact information. 1333 3. Supply references to previously defined profiles that the profile 1334 updates or obsoletes. 1336 4. Specify the set of interactions between endpoint entites involved 1337 in the profile, calling out any restrictions on ordinary UMA- 1338 conformant operations and any extension properties used in 1339 message formats. 1341 5. Identify the legally responsible parties involved in each 1342 interaction and any new obligations imposed, in the fashion of 1343 [UMA-obligations]. 1345 6. Define any additional or changed error states. 1347 7. Supply any additional security and privacy considerations, 1348 including analysis of threats and description of countermeasures. 1350 5.2. Specifying RPT Profiles 1352 It is RECOMMENDED that RPT profiles document the following 1353 information: 1355 1. Specify a URI that uniquely identifies the token profile. 1357 2. Identify the responsible author and provide postal or electronic 1358 contact information. 1360 3. Supply references to previously defined token profiles that the 1361 token profile updates or obsoletes. 1363 4. Specify the keyword to be used in HTTP Authorization headers 1364 with tokens conforming to this profile. 1366 5. Specify the syntax and semantics of the data that the 1367 authorization server associates with the token. 1369 6. Specify how the token data is associated with, contained within, 1370 and/or retrieved by means of, the on-the-wire token string. 1372 7. Specify processing rules for token data. 1374 8. Identify any restrictions on grant types to be used with the 1375 token profile. 1377 9. Define any additional or changed error states. 1379 10. Supply any additional security and privacy considerations. 1381 11. Specify any obligations specific to the token profile, in the 1382 fashion of [UMA-obligations]. 1384 See Section 3.3.2 for an example. 1386 5.3. Specifying Claim Profiles 1388 It is RECOMMENDED that claim profiles document the following 1389 information: 1391 1. Specify a URI that uniquely identifies the claim profile. 1393 2. Identify the responsible author and provide postal or electronic 1394 contact information. 1396 3. Supply references to previously defined claim profiles that the 1397 claim profile updates or obsoletes. 1399 4. Specify the syntax and semantics of claim data and requests for 1400 claim data. 1402 5. Specify how an authorization server gathers the claims. 1404 6. Define any additional or changed error states. 1406 7. Supply any additional security and privacy considerations. 1408 8. Specify any obligations specific to the claim profile, in the 1409 fashion of [UMA-obligations]. 1411 See Section 3.5.1.1 for an example. 1413 6. Security Considerations 1415 This specification relies mainly on OAuth security mechanisms as well 1416 as transport-level encryption for protecting the protection and 1417 authorization API endpoints. Most PATs and AATs are likely to use 1418 OAuth bearer tokens. See [OAuth-threat] for more information. 1420 This specification defines a number of JSON-based data formats. As a 1421 subset of the JavaScript scripting language, JSON data SHOULD be 1422 consumed through a process that does not dynamically execute it as 1423 code, to avoid malicious code execution. One way to achieve this is 1424 to use a JavaScript interpreter rather than the built-in JavaScript 1425 eval() function. 1427 The issue of impersonation is a crucial aspect in UMA, particularly 1428 when entities are wielding bearer tokens that preclude proof-of- 1429 possession (of a secret or a cryptographic key). As such, one way to 1430 mitigate this risk is for the resource owner to require stronger 1431 claims to accompany any access request. For example, consider the 1432 case where Alice sets policies at the authorization server governing 1433 access to her resources by Bob. When Bob first seeks access and must 1434 obtain an RPT (for which the default RPT profile specifies a bearer 1435 token), Alice could set policies demanding that Bob prove his 1436 identity by providing a set of strong claims issued by a trusted 1437 attrribute provider in order to get authorization data associated 1438 with that token. 1440 Another issue concerns the use of the [OAuth2] implicit flow. In 1441 this case, Bob will have exposure to the token, and may maliciously 1442 pass the token to an unauthorized party. To mitigate this weakness 1443 and others, we recommend considering the following steps: 1445 o Require that the Requesting Party (as defined in 1446 [UMA-obligations]) legitimately represent the wielder of the 1447 bearer token. This solution is based on a legal or contractual 1448 approach, and therefore does not reduce the risk from the 1449 technical perspective. 1451 o The authorization server, possibly with input from the resource 1452 owner, can implement tighter time-to-live (TTL) strategies around 1453 the authorization data in RPTs. This is a classic approach with 1454 bearer tokens that helps to limit a malicious party's ability to 1455 intercept and use the bearer token. In the same vein, the 1456 authorization server could require claims to have a reasonable 1457 degree of freshness (which would require a custom claims profile). 1459 o The strongest strategy is to disallow bearer-type RPTs within the 1460 UMA profile being deployed, by providing or requiring an RPT 1461 profile that requires use of a holder-of-key (HOK) approach. In 1462 this way, the wielder of the token must engage in a live session 1463 for proof-of-possession. 1465 For information about the additional technical, operational, and 1466 legal elements of trust establishment between UMA entities and 1467 parties, which affects security considerations, see 1468 [UMA-obligations]. 1470 7. Privacy Considerations 1472 The authorization server comes to be in possession of resource set 1473 information (such as names and icons) that may reveal information 1474 about the resource owner, which the authorization server's trust 1475 relationship with the resource server is assumed to accommodate. 1476 However, the client is a less-trusted party -- in fact, entirely 1477 untrustworthy until authorization data is associated with its RPT. 1478 This specification depends on [OAuth-resource-reg], which recommends 1479 obscuring resource set identifiers in order to avoid leaking 1480 personally identifiable information to clients through the scope 1481 mechanism. 1483 (More privacy considerations information to come.) 1485 For information about the technical, operational, and legal elements 1486 of trust establishment between UMA entities and parties, which 1487 affects privacy considerations, see [UMA-obligations]. 1489 8. Conformance 1491 This section outlines conformance requirements for various entities 1492 implementing UMA endpoints. 1494 This specification has dependencies on other specifications, as 1495 referenced under the normative references listed in this 1496 specification. Its dependencies on some specifications, such as 1497 OpenID Connect ([OCStandard] and [OCMessages]), are optional 1498 depending on whether the feature in question is used in the 1499 implementation. 1501 The authorization server's configuration data provides a machine- 1502 readable method for it to indicate certain of the conformance options 1503 it has chosen or supports. Several of the configuration data 1504 properties allow for indicating extension features. Where this 1505 specification does not already require optional features to be 1506 documented, it is RECOMMENDED that authorization server developers 1507 and deployers document any profiled or extended features explicitly 1508 and use configuration data to indicate their usage. See Section 1.4 1509 for information about providing and extending the configuration data. 1511 9. IANA Considerations 1513 This document makes no request of IANA. 1515 10. Acknowledgments 1516 The current editor of this specification is Thomas Hardjono of MIT. 1517 The following people are co-authors: 1519 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 1521 o Domenico Catalano, Oracle Corp. 1523 o George Fletcher, AOL 1525 o Maciej Machulak, Newcastle University 1527 o Eve Maler, XMLgrrl.com 1529 o Lukasz Moren, Newcastle University 1531 o Christian Scholz, COMlounge GmbH (former editor) 1533 o Jacek Szpot, Newcastle University 1535 Additional contributors to this specification include the Kantara UMA 1536 Work Group participants, a list of whom can be found at 1537 [UMAnitarians]. 1539 11. Issues 1541 All issues are now captured at the project's GitHub site ([1]). 1543 12. References 1545 12.1. Normative References 1547 [DynClientReg] 1548 Richer, J., "OAuth Dynamic Client Registration Protocol", 1549 March 2013, . 1552 [OAuth-SAML] 1553 Campbell, B., "SAML 2.0 Bearer Assertion Profiles for 1554 OAuth 2.0", March 2013, . 1557 [OAuth-bearer] 1558 , "The OAuth 2.0 Authorization Framework: Bearer Token 1559 Usage", October 2012, 1560 . 1562 [OAuth-introspection] 1563 Richer, J., "OAuth Token Introspection", February 2013, 1564 . 1567 [OAuth-resource-reg] 1568 Hardjono, T., "OAuth 2.0 Resource Set Registration", 1569 December 2012, . 1572 [OAuth-threat] 1573 Lodderstedt, T., "OAuth 2.0 Threat Model and Security 1574 Considerations", January 2013, 1575 . 1577 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 1578 October 2012, . 1580 [OCMessages] 1581 Sakimura, N., "OpenID Connect Messages 1.0", March 2013, 1582 . 1585 [OCStandard] 1586 Sakimura, N., "OpenID Connect Standard 1.0", March 2013, 1587 . 1590 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1591 Requirement Levels", BCP 14, RFC 2119, March 1997. 1593 [RFC4627] Crockford, D., "The application/json Media Type for 1594 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1596 [UMA-obligations] 1597 Maler, E., "Binding Obligations on UMA Participants", 1598 January 2013, . 1601 [hostmeta] 1602 Hammer-Lahav, E., "Web Host Metadata", October 2011, 1603 . 1605 12.2. Informative References 1607 [OAuth-linktypes] 1608 Mills, W., "Link Type Registrations for OAuth 2", February 1609 2013, 1610 . 1612 [OAuth-meta] 1613 Sakimura, N., "JSON Metadata for OAuth Responses", 1614 February 2013, 1615 . 1617 [UMA-casestudies] 1618 Maler, E., "UMA Case Studies", March 2013, . 1622 [UMA-usecases] 1623 Maler, E., "UMA Scenarios and Use Cases", October 2010, 1624 . 1627 [UMAnitarians] 1628 Maler, E., "UMA Participant Roster", April 2013, . 1632 Appendix A. Document History 1634 NOTE: To be removed by RFC editor before publication as an RFC. 1636 See [2] for a list of code-breaking and other major changes made to 1637 this specification at various revision points. 1639 Author's Address 1641 Thomas Hardjono (editor) 1642 MIT 1644 Email: hardjono@mit.edu