idnits 2.17.1 draft-hardjono-oauth-umacore-09.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 4 instances of too long lines in the document, the longest one being 9 characters in excess of 72. == There are 2 instances 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 (March 6, 2014) is 3676 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 1839 -- Looks like a reference, but probably isn't: '2' on line 1848 -- 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. 'OIDCCore' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- Possible downref: Non-RFC (?) normative reference: ref. 'UMA-obligations' -- Possible downref: Non-RFC (?) normative reference: ref. 'UMAclaims' Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Hardjono, Ed. 3 Internet-Draft MIT 4 Intended status: Standards Track March 6, 2014 5 Expires: September 7, 2014 7 User-Managed Access (UMA) Profile of OAuth 2.0 8 draft-hardjono-oauth-umacore-09 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 17 policy.Met at advisory in Feb 2014. 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 September 7, 2014. 36 Copyright Notice 38 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 5 55 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.3. Achieving Distributed Protection Through APIs and Tokens 7 57 1.3.1. Protection API . . . . . . . . . . . . . . . . . . . 7 58 1.3.2. Authorization API . . . . . . . . . . . . . . . . . . 8 59 1.3.3. Protected Resource Interface . . . . . . . . . . . . 9 60 1.3.4. Time-to-Live Considerations . . . . . . . . . . . . . 9 61 1.4. Authorization Server Configuration Data . . . . . . . . . 10 62 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 13 63 3. Getting Authorization and Accessing a Resource . . . . . . . 14 64 3.1. Client Attempts to Access Protected Resource . . . . . . 16 65 3.1.1. Client Presents No RPT . . . . . . . . . . . . . . . 16 66 3.1.2. Client Presents RPT . . . . . . . . . . . . . . . . . 16 67 3.2. Resource Server Registers Requested Permission With 68 Authorization Server . . . . . . . . . . . . . . . . . . 18 69 3.3. Resource Server Determines RPT's Status . . . . . . . . . 20 70 3.3.1. Token Introspection . . . . . . . . . . . . . . . . . 20 71 3.3.2. RPT Profile: Bearer . . . . . . . . . . . . . . . . . 20 72 3.4. Client Seeks Authorization for Access . . . . . . . . . . 22 73 3.4.1. Client Obtains RPT . . . . . . . . . . . . . . . . . 23 74 3.4.2. Client Asks for Authorization Data . . . . . . . . . 23 75 3.5. Claims-Gathering Flows . . . . . . . . . . . . . . . . . 26 76 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 26 77 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 27 78 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 27 79 5. Profiles for API Extensibility . . . . . . . . . . . . . . . 28 80 5.1. Protection API Extensibility Profile . . . . . . . . . . 29 81 5.2. Authorization API Extensibility Profile . . . . . . . . . 30 82 5.3. Resource Interface Extensibility Profile . . . . . . . . 31 83 6. Specifying Additional Profiles . . . . . . . . . . . . . . . 32 84 6.1. Specifying Profiles of UMA . . . . . . . . . . . . . . . 33 85 6.2. Specifying RPT Profiles . . . . . . . . . . . . . . . . . 33 86 6.3. Specifying Claim Profiles . . . . . . . . . . . . . . . . 34 87 7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 88 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36 89 9. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 36 90 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 91 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 37 92 12. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 93 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 94 13.1. Normative References . . . . . . . . . . . . . . . . . . 37 95 13.2. Informative References . . . . . . . . . . . . . . . . . 39 96 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 39 97 Appendix A. Document History . . . . . . . . . . . . . . . . . . 40 98 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 40 100 1. Introduction 102 User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2]. UMA 103 defines how resource owners can control protected-resource access by 104 clients operated by arbitrary requesting parties, where the resources 105 reside on any number of resource servers, and where a centralized 106 authorization server governs access based on resource owner policy. 107 Resource owners configure authorization servers with access policies 108 that serve as implicit authorization grants. Thus, the UMA profile 109 of OAuth can be considered to encompass an authorization grant flow. 111 UMA serves numerous use cases where a resource owner outsources 112 authorization for access to their resources, potentially even without 113 the run-time presence of the resource owner. A typical example is 114 the following: a web user (an end-user resource owner) can authorize 115 a web app (client) to gain one-time or ongoing access to a protected 116 resource containing his home address stored at a "personal data 117 store" service (resource server), by telling the resource server to 118 respect access entitlements issued by his chosen cloud-based 119 authorization service (authorization server). The requesting party 120 operating the client might be the resource owner himself, using a web 121 or native app run by an e-commerce company that needs to know where 122 to ship a purchased item, or it might be his friend who is using an 123 online address book service to collect contact information, or it 124 might be a survey company that uses an autonomous web service to 125 compile population demographics. A variety of scenarios and use 126 cases can be found in [UMA-usecases] and [UMA-casestudies]. 128 Practical control of access among loosely coupled parties requires 129 more than just messaging protocols. This specification defines only 130 the technical "contract" between UMA-conforming entities; its 131 companion Binding Obligations specification [UMA-obligations] defines 132 the expected behaviors of parties operating and using these entities. 133 Parties operating entities that claim to be UMA-conforming MUST 134 provide documentation affirmatively stating their acceptance of the 135 binding obligations contractual framework defined in the Binding 136 Obligations specification. 138 In enterprise settings, application access management sometimes 139 involves letting back-office applications serve only as policy 140 enforcement points (PEPs), depending entirely on access decisions 141 coming from a central policy decision point (PDP) to govern the 142 access they give to requesters. This separation eases auditing and 143 allows policy administration to scale in several dimensions. UMA 144 makes use of a separation similar to this, letting the resource owner 145 serve as a policy administrator crafting authorization strategies for 146 resources under their control. 148 In order to increase interoperable communication among the 149 authorization server, resource server, and client, UMA defines 150 several purpose-built APIs related to the outsourcing of 151 authorization, themselves protected by OAuth in embedded fashion. 153 The UMA protocol has three broad phases, as shown in Figure 1. 155 The Three Phases of the UMA Profile of OAuth 157 +--------------+ 158 | resource | 159 +---------manage (A)------------ | owner | 160 | +--------------+ 161 | Phase 1: | 162 | protect a control (B) 163 | resource | 164 v v 165 +------------+ +----------+--------------+ 166 | | |protection| | 167 | resource | | API | authorization| 168 | server |<-protect (C)--| (needs | server | 169 | | | PAT) | | 170 +------------+ +----------+--------------+ 171 | protected | | authorization| 172 | resource | | API | 173 |(needs RPT) | | (needs AAT) | 174 +------------+ +--------------+ 175 ^ | 176 | Phases 2 and 3: authorize (D) 177 | get authorization, | 178 | access a resource v 179 | +--------------+ 180 +---------access (E)-------------| client | 181 +--------------+ 183 requesting party 185 Figure 1 187 The phases work as follows: 189 Protect a resource (Described in Section 2.) The resource owner, 190 who manages online resources at the resource server ("A"), 191 introduces it to the authorization server so that the latter can 192 begin controlling the resources' protection. To accomplish this 193 protection, the authorization server presents a protection API 194 ("C") to the resource server. This API is OAuth-protected and 195 requires a protection API token (PAT) for access. Out of band, 196 the resource owner configures the authorization server with 197 policies associated with the registered resource sets ("B"). 199 Get authorization (Described in Section 3.) The client approaches 200 the resource server seeking access to an UMA-protected resource. 201 In order to access it successfully, the client must first use the 202 authorization server's authorization API ("D") to obtain a 203 requesting party token (RPT) on behalf of its requesting party, 204 and the requesting party must supply to the authorization server 205 any identity claims needed in order for the server to associate 206 sufficient authorization data with that RPT. The API is OAuth- 207 protected and requires an authorization API token (AAT) for 208 access. 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 have the oportunity to develop profiles (see Section 6) 218 that specify and restrict various UMA protocol, RPT, and identity 219 claim 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. Achieving Distributed Protection Through APIs and Tokens 292 UMA's authorization server, resource server, and client roles are 293 designed to work in an interoperable fashion when each is operated by 294 an entirely separate party (for example, different organizations). 295 For this reason, UMA specifies communications channels that the 296 authorization server MUST implement as HTTP-based APIs that MUST use 297 TLS and OAuth protection, and that the resource server MUST implement 298 as an HTTP-based interface. UMA's use of TLS transport-layer 299 security is governed by Section 1.6 of [OAuth2], which discusses 300 deployment and adoption characteristics of different TLS versions. 301 Three different types of access tokens are issued and used for a 302 variety of purposes as part of these inter-role interactions. 304 It is also REQUIRED, in turn, for resource servers and clients on the 305 requesting side of UMA interactions to use these channels, unless a 306 profile is being used that enables API extensibility. Profiles that 307 enable such alternatives are described in Section 5. 309 1.3.1. Protection API 311 The authorization server MUST present an TLS- and OAuth-protected, 312 HTTP-based protection API for use by resource servers. The 313 authorization server thus has an OAuth token endpoint and user 314 authorization endpoint, and has the option to issue an OAuth refresh 315 token along with any access tokens issued for these APIs. The 316 authorization server MUST declare all of its protection API endpoints 317 in its configuration data (see Section 1.4). 319 The protection API consists of three endpoints: 321 o OAuth resource set registration endpoint as defined by 322 [OAuth-resource-reg] 324 o Endpoint for registering client-requested permissions 326 o OAuth token introspection endpoint as defined by 327 [OAuth-introspection] and Section 3.3.1 329 An entity seeking protection API access MUST have the scope "http:// 330 docs.kantarainitiative.org/uma/scopes/prot.json". (This URI resolves 331 to a JSON-encoded scope description, as defined in 332 [OAuth-resource-reg]. The description is non-normative for UMA 333 purposes.) An access token with at least this scope is called a 334 protection API token (PAT) and an entity with this scope is 335 definitionally a resource server. A single entity can serve in both 336 resource server and client roles if it has the appropriate OAuth 337 scopes. If a request to an endpoint fails due to an invalid, 338 missing, or expired PAT, or requires higher privileges at this 339 endpoint than provided by the PAT, the authorization server responds 340 with an OAuth error. 342 The authorization server MUST support the OAuth bearer token profile 343 for PAT issuance, and MAY support other OAuth token profiles (for 344 example, the SAML bearer token grant type [OAuth-SAML]). It MUST 345 declare all supported token profiles and grant types for PAT issuance 346 in its configuration data. 348 A PAT binds a resource owner, a resource server the owner uses for 349 resource management, and an authorization server the owner uses for 350 protection of resources at this resource server. It is not specific 351 to any client or requesting party. The issuance of a PAT represents 352 the approval of the resource owner for this resource server to trust 353 this authorization server for protecting its resources belonging to 354 this resource owner. 356 1.3.2. Authorization API 358 The authorization server MUST present an TLS- and OAuth-protected, 359 HTTP-based authorization API for use by clients. The authorization 360 server thus has an OAuth token endpoint and user authorization 361 endpoint, and has the option to issue an OAuth refresh token along 362 with any access tokens issued for these APIs. The authorization 363 server MUST declare all of its authorization API endpoints in its 364 configuration data (see Section 1.4). 366 The authorization API consists of two endpoints: 368 o Endpoint for RPT issuance 370 o Endpoint for requesting authorization 372 An entity seeking authorization API access MUST have the scope "http: 373 //docs.kantarainitiative.org/uma/scopes/authz.json". (This URI 374 resolves to a JSON-encoded scope description, as defined in 375 [OAuth-resource-reg]. The description is non-normative for UMA 376 purposes.) An access token with at least this scope is called an 377 authorization API token (AAT) and an entity with this scope is 378 definitionally a client. A single entity can serve in both resource 379 server and client roles if it has the appropriate OAuth scopes. If a 380 request to an endpoint fails due to an invalid, missing, or expired 381 AAT, or requires higher privileges at this endpoint than provided by 382 the AAT, the authorization server responds with an OAuth error. 384 The authorization server MUST support the OAuth bearer token profile 385 for AAT issuance, and MAY support other OAuth token profiles (for 386 example, the SAML bearer token grant type [OAuth-SAML]). It MUST 387 declare all supported token profiles and grant types for AAT issuance 388 in its configuration data. 390 An AAT binds a requesting party, a client being used by that party, 391 and an authorization server that protects resources this client is 392 seeking access to on this requesting party's behalf. It is not 393 specific to any resource server or resource owner. The issuance of 394 an AAT represents the approval of this requesting party for this 395 client to engage with this authorization server to supply claims, ask 396 for authorization, and perform any other tasks needed for obtaining 397 authorization for access to resources at all resource servers that 398 use this authorization server. The authorization server is able to 399 manage future processes of authorization and claims-caching 400 efficiently for this client/requesting party pair across all resource 401 servers they try to access; however, these management processes are 402 outside the scope of this specification. 404 1.3.3. Protected Resource Interface 406 The resource server MAY present to clients whatever HTTP-based APIs 407 or endpoints it wishes. To protect any of its resources available in 408 this fashion using UMA, it MUST require a requesting party token 409 (RPT) with sufficient authorization data for access. 411 This specification defines one RPT profile, call "bearer" (see 412 Section 3.3.2), which the authorization server MUST support. It MAY 413 support additional RPT profiles, and MUST declare all supported RPT 414 profiles in its configuration data (see Section 1.4). 416 An RPT binds a requesting party, the client being used by that party, 417 the resource server at which protected resources of interest reside, 418 and the authorization server that protects those resources. It is 419 not specific to a single resource owner, though its internal 420 components are likely to be bound to individual resource owners, 421 depending on the RPT profile in use. 423 1.3.4. Time-to-Live Considerations 425 The authorization server has the opportunity to manage the validity 426 periods of access tokens that it issues, their corresponding refresh 427 tokens where applicable, the individual data components associated 428 with RPTs where applicable, and even the client credentials that it 429 issues. Different time-to-live strategies may be suitable for 430 different resources and scopes of access, and the authorization 431 server has the opportunity to give the resource owner control over 432 lifetimes of tokens and authorization data issued on their behalf 433 through policy. These options are all outside the scope of this 434 specification. 436 1.4. Authorization Server Configuration Data 438 The authorization server MUST provide configuration data in a JSON 439 [RFC4627] document that resides in an /uma-configuration directory at 440 at its hostmeta [hostmeta] location. The configuration data 441 documents conformance options and endpoints supported by the 442 authorization server. (At the appropriate time, this section will 443 instead profile whatever self-describing metadata specification OAuth 444 adopts, for example, [OAuth-linktypes] or [OAuth-meta].) 446 The configuration data has the following properties. 448 version 449 REQUIRED. The version of the UMA core protocol to which this 450 authorization server conforms. The value MUST be the string 451 "1.0". 453 issuer 454 REQUIRED. A URI indicating the party operating the 455 authorization server. 457 pat_profiles_supported 458 REQUIRED. OAuth access token profiles supported by this 459 authorization server for PAT issuance. The property value is 460 an array of string values, where each string value is either a 461 reserved keyword defined in this specification or a URI 462 identifying an access token profile defined elsewhere. The 463 reserved keyword "bearer" as a value for this property stands 464 for the OAuth bearer token profile [OAuth-bearer]. The 465 authorization server is REQUIRED to support this profile, and 466 to supply this string value explicitly. The authorization 467 server MAY declare its support for additional access token 468 profiles for PATs. 470 aat_profiles_supported 471 REQUIRED. OAuth access token profiles supported by this 472 authorization server for AAT issuance. The property value is 473 an array of string values, where each string value is either a 474 reserved keyword defined in this specification or a URI 475 identifying an access token profile defined elsewhere. The 476 reserved keyword "bearer" as a value for this property stands 477 for the OAuth bearer token profile [OAuth-bearer]. The 478 authorization server is REQUIRED to support this profile, and 479 to supply this string value explicitly. The authorization 480 server MAY declare its support for additional access token 481 profiles for AATs. 483 rpt_profiles_supported 484 REQUIRED. UMA RPT profiles supported by this authorization 485 server for RPT issuance. The property value is an array of 486 string values, where each string value is either a reserved 487 keyword defined in this specification or a URI identifying an 488 RPT profile defined elsewhere. The reserved keyword "bearer" 489 as a value for this property stands for the UMA bearer RPT 490 profile defined in [OAuth-bearer]. The authorization server is 491 REQUIRED to support this profile, and to supply this string 492 value explicitly. The authorization server MAY declare its 493 support for additional RPT profiles. 495 pat_grant_types_supported 496 REQUIRED. OAuth grant types supported by this authorization 497 server in issuing PATs. The property value is an array of 498 string values. Each string value MUST be one of the grant_type 499 values defined in [OAuth2], or alternatively a URI identifying 500 a grant type defined elsewhere. 502 aat_grant_types_supported 503 REQUIRED. OAuth grant types supported by this authorization 504 server in issuing AATs. The property value is an array of 505 string values. Each string value MUST be one of the grant_type 506 values defined in [OAuth2], or alternatively a URI identifying 507 a grant type defined elsewhere. 509 claim_profiles_supported 510 OPTIONAL. Claim formats and associated sub-protocols for 511 gathering claims from requesting parties, as supported by this 512 authorization server. The property value is an array of string 513 values, which each string value is either a reserved keyword 514 defined in this specification or a URI identifying a claim 515 profile defined elsewhere. 517 uma_profiles_supported 518 OPTIONAL. UMA profiles supported by this authorization server. 519 The property value is an array of string values, which each 520 string value is either a reserved keyword defined in this 521 specification or a URI identifying an UMA profile defined 522 elsewhere. The reserved keywords "prot-ext", "authz-ext", and 523 "rsrc-ext" as values for this property stand for the 524 extensibility profiles defined, respectively, in Section 5. 526 dynamic_client_endpoint 527 OPTIONAL. The endpoint to use for performing dynamic client 528 registration. Usage of this endpoint is defined by 529 [DynClientReg]. The presence of this property indicates 530 authorization server support for the dynamic client 531 registration feature and its absence indicates a lack of 532 support. 534 token_endpoint 535 REQUIRED. The endpoint URI at which the resource server or 536 client asks the authorization server for a PAT or AAT, 537 respectively. A requested scope of "http:// 538 docs.kantarainitiative.org/uma/scopes/prot.json" results in a 539 PAT. A requested scope of "http://docs.kantarainitiative.org/ 540 uma/scopes/authz.json" results in an AAT. Usage of this 541 endpoint is defined by [OAuth2]. 543 user_endpoint 544 REQUIRED. The endpoint URI at which the resource server 545 gathers the consent of the end-user resource owner or the 546 client gathers the consent of the end-user requesting party, if 547 the "authorization_code" grant type is used. Usage of this 548 endpoint is defined by [OAuth2]. 550 introspection_endpoint 551 REQUIRED. The endpoint URI at which the resource server 552 introspects an RPT presented to it by a client. Usage of this 553 endpoint is defined by [OAuth-introspection] and Section 3.3.1. 554 A valid PAT MUST accompany requests to this protected endpoint. 556 resource_set_registration_endpoint 557 REQUIRED. The endpoint URI at which the resource server 558 registers resource sets to put them under authorization manager 559 protection. Usage of this endpoint is defined by 560 [OAuth-resource-reg] and Section 2. A valid PAT MUST accompany 561 requests to this protected endpoint. 563 permission_registration_endpoint 564 REQUIRED. The endpoint URI at which the resource server 565 registers a client-requested permission with the authorization 566 server. Usage of this endpoint is defined by Section 3.2. A 567 valid PAT MUST accompany requests to this protected endpoint. 569 rpt_endpoint 570 REQUIRED. The endpoint URI at which the client asks the 571 authorization server for an RPT. Usage of this endpoint is 572 defined by Section 3.4.1. A valid AAT MUST accompany requests 573 to this protected endpoint. 575 authorization_request_endpoint 576 REQUIRED. The endpoint URI at which the client asks to have 577 authorization data associated with its RPT. Usage of this 578 endpoint is defined in Section 3.4.2. A valid AAT MUST 579 accompany requests to this protected endpoint. 581 Example of authorization server configuration data that resides at 582 https://example.com/.well-known/uma-configuration (note the use of 583 https: for endpoints throughout): 585 { 586 "version":"1.0", 587 "issuer":"https://example.com", 588 "pat_profiles_supported":["bearer"], 589 "aat_profiles_supported":["bearer"], 590 "rpt_profiles_supported":["bearer"], 591 "pat_grant_types_supported":["authorization_code"], 592 "aat_grant_types_supported":["authorization_code"], 593 "claim_profiles_supported":["openid"], 594 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", 595 "token_endpoint":"https://as.example.com/token_uri", 596 "user_endpoint":"https://as.example.com/user_uri", 597 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri", 598 "introspection_endpoint":"https://as.example.com/rs/status_uri", 599 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri", 600 "rpt_endpoint":"https://as.example.com/client/rpt_uri", 601 "authorization_request_endpoint":"https://as.example.com/client/perm_uri" 602 } 604 Authorization server configuration data MAY contain extension 605 properties that are not defined in this specification. Extension 606 names that are unprotected from collisions are outside the scope of 607 this specification. 609 2. Protecting a Resource 611 The resource owner, resource server, and authorization server perform 612 the following actions to put resources under protection. This list 613 assumes that the resource server has discovered the authorization 614 server's configuration data and endpoints as needed. 616 1. The authorization server issues client credentials to the 617 resource server. It is OPTIONAL for the client credentials to be 618 provided dynamically through [DynClientReg]; alternatively, they 619 MAY use a static process. 621 2. The resource server acquires a PAT from the authorization server. 622 It is OPTIONAL for the resource owner to introduce the resource 623 server to the authorization server dynamically (for example, 624 through a "NASCAR"-style user interface where the resource owner 625 selects a chosen authorization server); alternatively, they MAY 626 use a static process that may or may not directly involve the 627 resource owner at introduction time. 629 3. In an ongoing fashion, the resource server registers any resource 630 sets with the authorization server for which it intends to 631 outsource protection, using the resource set registration 632 endpoint of the protection API (see [OAuth-resource-reg]). 634 Note: The resource server is free to offer the option to protect any 635 subset of the resource owner's resources using different 636 authorization servers or other means entirely, or to protect some 637 resources and not others. Additionally, the choice of protection 638 regimes can be made explicitly by the resource owner or implicitly by 639 the resource server. Any such partitioning by the resource server or 640 owner is outside the scope of this specification. 642 Once a resource set has been placed under authorization server 643 protection through the registration of a resource set description for 644 it, and until such a description's deletion by the resource server, 645 the resource server MUST limit access to corresponding resources, 646 requiring sufficient authorization data associated with client- 647 presented RPTs by the authorization server (see Section 3.1.2). 649 3. Getting Authorization and Accessing a Resource 651 An authorization server orchestrates and controls clients' access (on 652 their requesting parties' behalf) to a resource owner's protected 653 resources at a resource server, under conditions dictated by that 654 resource owner. 656 The process of getting authorization and accessing a resource always 657 begins with the client attempting access at a protected resource 658 endpoint at the resource server. How the client came to learn about 659 this endpoint is out of scope for this specification. The resource 660 owner might, for example, have advertised its availability publicly 661 on a blog or other website, listed it in a discovery service, or 662 emailed a link to a particular intended requesting party. 664 The resource server responds to the client's access request with 665 whatever its application-specific resource interface defines as a 666 success response, either immediately or having first performed one or 667 more embedded interactions with the authorization server. Depending 668 on the nature of the resource server's response to an failed access 669 attempt, the client and its requesting party engage in embedded 670 interactions with the authorization server before re-attempting 671 access. 673 The interactions are as follows. Each interaction MAY be the last, 674 if the client chooses not to continue pursuing the access attempt or 675 the resource server chooses not to continue facilitating it. 677 o The client attempts to access a protected resource. 679 * If the access attempt is unaccompanied by an RPT, the resource 680 server responds immediately with an HTTP 401 (Unauthorized) 681 response and instructions on where to go to obtain one. 683 * If the access attempt was accompanied by an RPT, the resource 684 server checks the RPT's status. 686 + If the RPT is invalid, the resource server responds with an 687 HTTP 401 (Unauthorized) response and instructions on where 688 to go to obtain a token. 690 + If the RPT is valid but has insufficient authorization data, 691 the resource server registers a suitable requested 692 permission on the client's behalf at the authorization 693 server, and then responds to the client with an HTTP 403 694 (Forbidden) response and instructions on where to go to ask 695 for authorization. 697 + If the RPT is valid, and if the authorization data 698 associated with the token is sufficient for allowing access, 699 the resource server responds with an HTTP 2xx (Success) 700 response and a representation of the resource. 702 o If the client (possessing no RPT or an invalid RPT) received a 401 703 response and an authorization server's location, after looking up 704 its configuration data and endpoints as necessary, it requests an 705 RPT from the RPT endpoint of the authorization API. 707 o If the client (posessing a valid RPT) received a 403 response and 708 a permission ticket, it asks the authorization server for 709 authorization data that matches the ticket using the authorization 710 request endpoint of the authorization API. If the authorization 711 server needs requesting party claims in order to assess this 712 client's authorization, it engages in a claims-gathering flow. 714 * If the client does not already have an AAT at the appropriate 715 authorization server to be able to use its authorization API, 716 it first obtains one. 718 The interactions are described in detail in the following sections. 720 3.1. Client Attempts to Access Protected Resource 722 This interaction assumes that the resource server has previously 723 registered one or more resource sets that correspond to the resource 724 to which access is being attempted. 726 The client attempts to access a protected resource (for example, when 727 an end-user requesting party clicks on a thumbnail representation of 728 the resource to retrieve a larger version). It is expected to 729 discover, or be provisioned or configured with, knowledge of the 730 protected resource and its location out of band. Further, the client 731 is expected to acquire its own knowledge about the application- 732 specific methods made available by the resource server for operating 733 on this protected resource (such as viewing it with a GET method, or 734 transforming it with some complex API call). 736 The access attempt either is or is not accompanied by an RPT. 738 3.1.1. Client Presents No RPT 740 Example of a request carrying no RPT: 742 GET /album/photo.jpg HTTP/1.1 743 Host: photoz.example.com 744 ... 746 If the client does not present an RPT with the request, the resource 747 server returns an HTTP 401 (Unauthorized) status code and providing 748 the authorization server's URI in an "as_uri" property to facilitate 749 authorization server configuration data discovery, including 750 discovery of the endpoint where the client can request an RPT 751 (Section 3.4.1). 753 For example: 755 HTTP/1.1 401 Unauthorized 756 WWW-Authenticate: UMA realm="example", 757 host_id="photoz.example.com", 758 as_uri="https://as.example.com" 759 ... 761 3.1.2. Client Presents RPT 762 Example of a request carrying an RPT using the UMA bearer RPT 763 profile: 765 GET /album/photo.jpg HTTP/1.1 766 Authorization: Bearer vF9dft4qmT 767 Host: photoz.example.com 768 ... 770 If the client presents an RPT with its request, the resource server 771 MUST determine the RPT's status (see Section 3.3) before responding. 773 If the RPT is invalid, the resource server applies UMA protection by 774 returning an HTTP 401 (Unauthorized) status code and providing the 775 authorization server's URI in an "as_uri" property in the header, 776 similarly to the case where no RPT was presented. 778 If the RPT is valid but has insufficient authorization data for the 779 type of access sought, the resource server uses the protection API to 780 register a requested permission with the authorization server that 781 would suffice for that scope of access (see Section 3.2). It then 782 responds with the HTTP 403 (Forbidden) status code and providing the 783 authorization server's URI in an "as_uri" property in the header and 784 the permission ticket it just received from the AM in the body in a 785 JSON-encoded "ticket" property. 787 Example of the resource server's response after having registered a 788 requested permission and received a ticket: 790 HTTP/1.1 403 Forbidden 791 WWW-Authenticate: UMA realm="example", 792 host_id="photoz.example.com", 793 as_uri="https://as.example.com" 794 error="insufficient_scope" 796 { 797 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 798 } 800 If the RPT's status is associated with authorization data that is 801 sufficient for the access sought by the client, the resource server 802 MUST give access to the desired resource. 804 Example of the resource server's response after having determined 805 that the RPT is valid and associated with sufficient authorization 806 data: 808 HTTP/1.1 200 OK 809 Content-Type: image/jpeg 810 ... 812 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 813 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 814 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 815 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 817 The resource server MUST NOT give access where the token's status is 818 not associated with sufficient authorization data for the attempted 819 scope of access. 821 3.2. Resource Server Registers Requested Permission With Authorization 822 Server 824 In response to receiving an access request accompanied by an RPT that 825 has insufficient authorization data, the resource server uses the 826 protection API's permission registration endpoint to register a 827 permission with the authorization server that would be sufficient for 828 the type of access sought. The authorization server returns a 829 permission ticket for the resource server to give to the client in 830 its response. The PAT provided in the API request implicitly 831 identifies the resource owner ("subject") to which the permission 832 applies. 834 The resource server uses the POST method at the endpoint. The body 835 of the HTTP request message contains a JSON object providing the 836 requested permission, using a format derived from the scope 837 description format specified in [OAuth-resource-reg], as follows. 838 The object has the following properties: 840 resource_set_id REQUIRED. The identifier for a resource set to 841 which this client is seeking access. The identifier MUST 842 correspond to a resource set that was previously registered. 844 scopes REQUIRED. An array referencing one or more identifiers of 845 scopes to which access is needed for this resource set. Each 846 scope identifier MUST correspond to a scope that was registered by 847 this resource server for the referenced resource set. 849 Example of an HTTP request that registers a requested permission at 850 the authorization server's permission registration endpoint: 852 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 853 Content-Type: application/json 854 Host: as.example.com 856 { 857 "resource_set_id": "112210f47de98100", 858 "scopes": [ 859 "http://photoz.example.com/dev/actions/view", 860 "http://photoz.example.com/dev/actions/all" 861 ] 862 } 864 If the registration request is successful, the authorization server 865 responds with an HTTP 201 (Created) status code and includes the 866 Location header in its response as well as the "ticket" property in 867 the JSON-formatted body. 869 The permission ticket is a short-lived opaque structure whose form is 870 determined by the authorization server. The ticket value MUST be 871 securely random (for example, not merely part of a predictable 872 sequential series), to avoid denial-of-service attacks. Since the 873 ticket is an opaque structure from the point of view of the client, 874 the authorization server is free to include information regarding 875 expiration time within the opaque ticket for its own consumption. 876 When the client subsequently uses the authorization API to ask the 877 authorization server for authorization data to be associated with its 878 RPT, it will submit this ticket to the authorization server. 880 For example: 882 HTTP/1.1 201 Created 883 Content-Type: application/json 884 Location: https://as.example.com/permreg/host/photoz.example.com/5454345rdsaa4543 885 ... 887 { 888 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 889 } 891 If the registration request is authenticated properly but fails due 892 to other reasons, the authorization server responds with an HTTP 400 893 (Bad Request) status code and includes one of the following UMA error 894 codes (see Section 4.2): 896 invalid_resource_set_id The provided resource set identifier was not 897 found at the authorization server. 899 invalid_scope At least one of the scopes included in the request was 900 not registered previously by this resource server. 902 3.3. Resource Server Determines RPT's Status 904 The resource server MUST determine a received RPT's status, including 905 both its validity and, if valid, its associated authorization data, 906 before giving or refusing access to the client. An RPT is associated 907 with a set of authorization data that governs whether the client is 908 authorized for access. The token's nature and format are dictated by 909 its profile; the profile might allow it to be self-contained, such 910 that the resource server is able to determine its status locally, or 911 might require or allow the resource server to make a run-time 912 introspection request of the authorization server that issued the 913 token. 915 This specification makes one type of RPT REQUIRED for the 916 authorization server to support: the UMA bearer token profile, as 917 defined in Section 3.3.2. Implementers MAY define and use other RPT 918 profiles. 920 3.3.1. Token Introspection 922 Within any RPT profile, when a resource server needs to introspect a 923 token in a non-self-contained way to determine its status, it MAY 924 require, allow, or prohibit use of the OAuth token introspection 925 endpoint (defined by [OAuth-introspection]) that is part of the 926 protection API, and MAY profile its usage. The resource server MUST 927 use the POST method in interacting with the endpoint, not the GET 928 method also defined by [OAuth-introspection]. 930 3.3.2. RPT Profile: Bearer 932 This section defines the UMA bearer token profile. Following is a 933 summary: 935 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 936 uma-token-bearer-1.0 938 o Profile author and contact information: Thomas Hardjono 939 (hardjono@mit.edu) 941 o Updates or obsoletes: None; this profile is new. 943 o Keyword in HTTP Authorization header: "Bearer". 945 o Syntax and semantics of token data: As defined below. The token 946 data format mainly involves time-bounded permissions. 948 o Token data association: The data associated to the on-the-wire 949 token by reference and retrieved at run time by the resource 950 server through profiled use of the OAuth token introspection 951 endpoint [OAuth-introspection], as defined below. 953 o Token data processing: As defined in this section and throughout 954 Section 3 of this specification. 956 o Grant type restrictions: None. 958 o Error states: As defined below. 960 o Security and privacy considerations: As defined in this section 961 and throughout Section 3 of this specification. 963 o Binding obligations: Because this RPT profile is mandatory for 964 authorization servers to implement, binding obligations related to 965 the use of this token profile are documented in [UMA-obligations]. 967 On receiving an RPT of the "Bearer" type in an authorization header 968 from a client making an access attempt, the resource server 969 introspects the token by using the token introspection endpoint of 970 the protection API. The PAT used by the resource server to make the 971 introspection request provides resource-owner context to the 972 authorization server. 974 The authorization server responds with a JSON object with the 975 structure dictated by [OAuth-introspection]. If the valid property 976 has a "true" value, then the JSON object MUST also contain an 977 extension property with the name "permissions" that contains an array 978 of zero or more values, each of which is an object consisting of 979 these properties: 981 resource_set_id REQUIRED. A string that uniquely identifies the 982 resource set, access to which has been granted to this client on 983 behalf of this requesting party. The identifier MUST correspond 984 to a resource set that was previously registered as protected. 986 scopes REQUIRED. An array referencing one or more URIs of scopes to 987 which access was granted for this resource set. Each scope MUST 988 correspond to a scope that was registered by this resource server 989 for the referenced resource set. 991 expires_at REQUIRED. Integer timestamp, measured in the number of 992 seconds since January 1 1970 UTC, indicating when this permission 993 will expire. 995 issued_at OPTIONAL. Integer timestamp, measured in the number of 996 seconds since January 1 1970 UTC, indicating when this permission 997 was originally issued. 999 Example: 1001 HTTP/1.1 200 OK 1002 Content-Type: application/json 1003 Cache-Control: no-store 1005 { 1006 "valid": true, 1007 "expires_at": "1256953732", 1008 "issued_at": "1256912345", 1009 "permissions": [ 1010 { 1011 "resource_set_id": "112210f47de98100", 1012 "scopes": [ 1013 "http://photoz.example.com/dev/actions/view", 1014 "http://photoz.example.com/dev/actions/all" 1015 ], 1016 "expires_at" : "1256923456" 1017 } 1018 ] 1019 } 1021 3.4. Client Seeks Authorization for Access 1023 In order to access a protected resource successfully, a client needs 1024 to present a valid RPT with sufficient authorization data for access. 1025 To get to this stage requires a number of previously successful 1026 steps: 1028 1. The authorization server issues client credentials to the client. 1029 It is OPTIONAL for the client credentials to be provided 1030 dynamically through [DynClientReg]; alternatively, they MAY use a 1031 static process. 1033 2. The client acquires an AAT. 1035 3. The client uses the authorization API to acquire an RPT. See 1036 Section 3.4.1 for more detail. 1038 4. The client uses the authorization API to ask for authorization, 1039 providing the permission ticket it got from the resource server. 1040 The authorization server associates authorization data with the 1041 client's RPT based on the permission ticket, the resource owner's 1042 operative policies, and the results of any claims-gathering 1043 flows. See Section 3.4.2 for more detail. 1045 3.4.1. Client Obtains RPT 1047 The client might need an RPT if it has never before requested an RPT 1048 for this combination of requesting party, resource server, and 1049 authorization server, or if it has lost control of a previously 1050 issued RPT and needs a refreshed one. It obtains an RPT by using the 1051 authorization API, performing a POST on the RPT endpoint and 1052 supplying its AAT in the header. No body is expected; if a body is 1053 present, the authorization server MAY ignore it. 1055 Example of a request message containing an AAT: 1057 POST /rpt HTTP/1.1 1058 Host: as.example.com 1059 Authorization: Bearer jwfLG53^sad$#f 1060 ... 1062 The authorization server responds with an HTTP 201 (Created) status 1063 code and provides a new RPT. 1065 For example: 1067 HTTP/1.1 201 Created 1068 Content-Type: application/json 1070 { 1071 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1072 } 1074 If the AAT provided in the header is the same as one provided for a 1075 previously issued still-valid RPT by this authorization server, the 1076 authorization server invalidates the old RPT and issues a new one. 1078 On first issuance, the RPT is associated with no authorization data 1079 and thus does not convey any authorizations for access. 1081 3.4.2. Client Asks for Authorization Data 1083 Once in possession of an AAT for this authorization server, an RPT 1084 that applies to this requesting party for this resource server and 1085 this authorization server, and a permission ticket, the client uses 1086 the authorization API to ask the authorization server to give it 1087 suitable authorization data for the sought-for access. It performs a 1088 POST on the authorization request endpoint, supplying its own AAT in 1089 the header and its RPT and the permission ticket in a JSON object 1090 with properties "rpt" and "ticket", respectively. 1092 Example of a request message containing an AAT, an RPT, and a 1093 permission ticket: 1095 POST /authz_request HTTP/1.1 1096 Host: as.example.com 1097 Authorization: Bearer jwfLG53^sad$#f 1098 ... 1100 { 1101 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1102 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1103 } 1105 The authorization server uses the ticket to look up the details of 1106 the previously registered requested permission, maps the requested 1107 permission to operative resource owner policies based on the resource 1108 set identifier and scopes in it, undergoes any claims-gathering flows 1109 required (see Section 3.5), and ultimately responds to the request. 1110 The resource owner's policies at the authorization server amount to 1111 an implicit authorization grant in governing the issuance of 1112 authorization data. (The authorization server is also free to enable 1113 the resource owner to set policies that require the owner to provide 1114 a run-time authorization grant in the form of a consent interaction, 1115 mediated by the authorization server. This setting of policies and 1116 gathering of consent is outside the scope of this specification.) 1118 The authorization server MUST base the addition of authorization data 1119 to RPTs on user policies. The nature of these policies is outside 1120 the scope of UMA, but generally speaking, they can be thought of as 1121 either independent of requesting-party features (for example, 1122 dictating access based on time of day or client identity) or 1123 dependent on requesting-party features (for example, dictating access 1124 based on whether they are over 18 or present a certain identifier). 1125 Such requesting-party features can potentially be collected in a 1126 claims-gathering flow. 1128 Once the authorization server associates authorization data with the 1129 RPT, it responds with an HTTP 201 (Created) status code. If the 1130 authorization server chooses to invalidate the original RPT in 1131 response to the request and to issue a new one to be associated with 1132 the resulting authorization data, it MUST provide that refreshed RPT 1133 in the body. 1135 Example when the authorization data has been added and the RPT has 1136 been refreshed: 1138 HTTP/1.1 201 Created 1139 Content-Type: application/json 1141 { 1142 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1143 } 1145 If the authorization server does not add the requested authorization 1146 data, it responds using the appropriate HTTP status code and UMA 1147 error code (see Section 4.2): 1149 invalid_ticket The provided ticket was not found at the 1150 authorization server. The authorization server responds with the 1151 HTTP 400 (Bad Request) status code. 1153 expired_ticket The provided ticket has expired. The authorization 1154 server responds with the HTTP 400 (Bad Request) status code. 1156 not_authorized_permission The client is definitively not authorized 1157 for this authorization according to user policy. The 1158 authorization server responds with the HTTP 403 (Forbidden) status 1159 code. 1161 need_claims The authorization server is unable to determine whether 1162 the client is authorized for this permission without gathering 1163 requesting party claims. The authorization server responds with 1164 the HTTP 403 (Forbidden) status code. The client is therefore not 1165 authorized, but has the opportunity to engage in a requesting 1166 party claims-gathering flow (see Section 3.5) to continue seeking 1167 authorization. 1169 Example when the ticket has expired: 1171 HTTP/1.1 400 Bad Request 1172 Content-Type: application/json 1173 Cache-Control: no-store 1174 ... 1176 { 1177 "status": "error", 1178 "error": "expired_ticket" 1179 } 1181 3.5. Claims-Gathering Flows 1183 The authorization server has a variety of options for coming into 1184 possession of claims in order to satisfy the resource owner's policy; 1185 this specification does not dictate a single answer. For example, 1186 the authorization server could interact with the requesting party to 1187 gather claims, or could accept claims delivered by a client, or could 1188 perform a lookup in some external system. The process for requesting 1189 and providing claims is extensible and can have a variety of 1190 dependencies on the type of requesting party (for example, natural 1191 person or legal person) and the type of client (for example, browser, 1192 native app, or autonomously running web service). 1194 This specification provides a required framework for extensibility 1195 through profiling. The authorization server MAY support any number 1196 of claim profiles, and SHOULD document the claim profiles it supports 1197 in its configuration data. For the business-level and legal 1198 implications of different claim profiles, see [UMA-obligations]. 1199 Optional claim profiles are defined in [UMAclaims]. 1201 A client is operated by an end-user in one of two typical situations: 1203 o The requesting party is a natural person (for example, a friend or 1204 family member of the resource owner); the requesting party may 1205 even be the resource owner herself. 1207 o The requesting party is a legal person such as a corporation, and 1208 the end-user operating the client is acting as an agent of that 1209 legal person (for example, a customer support specialist 1210 representing a credit card company). 1212 Where a claim profile dictates end-user interaction, a further 1213 variety of options is possible. The end-user could be required to 1214 register for and/or log in to an account or personal profile, or fill 1215 in a questionnaire, or complete a purchase. Several of these 1216 operations could even be required, where the order is treated as 1217 significant for evaluating resource owner policies. 1219 4. Error Messages 1221 Ultimately the resource server is responsible for either granting the 1222 access the client attempted, or returning an error response to the 1223 client with a reason for the failure. [OAuth2] defines several error 1224 responses for a resource server to return. UMA makes use of these 1225 error responses, but requires the resource server to "outsource" the 1226 determination of some error conditions to the authorization server. 1227 This specification defines additional UMA-specific error responses 1228 that the authorization server may give to the resource server and 1229 client as they interact with it, and that the resource server may 1230 give to the client. 1232 4.1. OAuth Error Responses 1234 When a resource server or client attempts to access one of the 1235 authorization server endpoints or a client attempts to access a 1236 protected resource at the resource server, it has to make an 1237 authenticated request by including an OAuth access token in the HTTP 1238 request as described in [OAuth2] Section 7.2. 1240 If the request failed authentication, the authorization server or the 1241 resource server responds with an OAuth error message as described 1242 throughout Section 2 and Section 3. 1244 4.2. UMA Error Responses 1246 When a resource server or client attempts to access one of the 1247 authorization server endpoints or a client attempts to access a 1248 protected resource at the resource server, if the request is 1249 successfully authenticated by OAuth means, but is invalid for another 1250 reason, the authorization server or resource server responds with an 1251 UMA error response by adding the following properties to the entity 1252 body of the HTTP response: 1254 error REQUIRED. A single error code. Values for this property are 1255 defined throughout this specification. 1257 error_description OPTIONAL. Human-readable text providing 1258 additional information. 1260 error_uri OPTIONAL. A URI identifying a human-readable web page 1261 with information about the error. 1263 The following is a common error code that applies to several UMA- 1264 specified request messages: 1266 invalid_request The request is missing a required parameter, 1267 includes an invalid parameter value, includes a parameter more 1268 than once, or is otherwise malformed. The authorization server 1269 MUST respond with the HTTP 400 (Bad Request) status code. 1271 For example: 1273 HTTP/1.1 400 Bad Request 1274 Content-Type: application/json 1275 Cache-Control: no-store 1276 ... 1278 { 1279 "error": "invalid_request", 1280 "error_description": "There is already a resource with this identifier.", 1281 "error_uri": "http://as.example.com/errors/resource_exists" 1282 } 1284 5. Profiles for API Extensibility 1286 In some circumstances, it is desirable to couple UMA roles tightly. 1287 For example, an authorization server application might also need to 1288 act as a client application in order to retrieve protected resources 1289 so that it can present to resource owners a dashboard-like user 1290 interface that accurately guides the setting of policy; it might need 1291 to access itself-as-authorization server for that purpose. For 1292 another example, the same organization might operate both an 1293 authorization server and a resource server that communicate only with 1294 each other behind a firewall, and it might seek more efficient 1295 communication methods between them. 1297 This section defines profiles that allow inter-role communications 1298 channels and methods to vary in these specific circumstances. This 1299 specification still REQUIRES authorization servers to issue PATs, 1300 AATs, and RPTs and associate authorization data with RPTs, and 1301 REQUIRES resource servers to give clients access only when RPTs are 1302 associated with sufficient authorization data. This is because, 1303 although tokens might not always appear on the wire in the normal 1304 fashion in these cases, they represent binding obligations that might 1305 involve additional parties unable to take part in these optimization 1306 opportunities (see [UMA-obligations]). 1308 In circumstances where alternate communications channels are being 1309 used between independently implemented system entities, it is 1310 RECOMMENDED, for reasons of implementation interoperability, to 1311 define concrete extension profiles that build on these extensibility 1312 profiles (see Section 6.1). 1314 An authorization server using any of the opportunities afforded by 1315 the protection and/or authorization API extensibility profile MUST 1316 declare use of each profile by supplying the relevant 1317 "uma_profiles_supported" values in its configuration data (see 1318 Section 1.4). 1320 5.1. Protection API Extensibility Profile 1322 This section defines a profile for UMA where the authorization server 1323 and resource server roles either reside in the same system entity or 1324 otherwise have a privileged communications channel between them. 1325 Following is a summary: 1327 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 1328 prot-ext-1.0 1330 o Profile author and contact information: Mark Dobrinic 1331 (mdobrinic@cozmanova.com) 1333 o Updates or obsoletes: None; this profile is new. 1335 o Security considerations: If the entities do not use TLS but 1336 communicate across a transport layer as opposed to using internal 1337 same-entity communication, it is STRONGLY RECOMMENDED to use an 1338 alternate means of transport-layer security. 1340 o Privacy considerations: If the relationship between the roles is 1341 established in a manner that does not involve the resource owner 1342 at all, they each may maliciously leverage this relationship to 1343 observe the resource owner's personally identifiable information 1344 held in each system. 1346 o Error states: See below. 1348 o Binding obligations: Any applicable binding obligations are 1349 documented in [UMA-obligations]. 1351 Using this profile, the resource server MAY use means other than the 1352 TLS- and OAuth-protected HTTP-based protection API to communicate 1353 with the authorization server. This involves the following 1354 opportunities: 1356 o A PAT MAY be issued without requiring an OAuth flow to establish 1357 one. 1359 o Resource sets MAY be registered (or configured) without requiring 1360 explicit use of the resource set registration endpoint or 1361 presentation of a PAT in any registration request. 1363 o Registration of requested permissions MAY be accomplished without 1364 requiring explicit use of the permission registration endpoint or 1365 presentation of a PAT in any registration request. 1367 o RPT introspection MAY be accomplished without requiring explicit 1368 use of the token introspection endpoint or presentation of a PAT 1369 in any introspection request. 1371 o Error states MAY arise and be reported in a different fashion from 1372 any HTTP-, OAuth-, and UMA-defined errors related to the 1373 protection API. 1375 An authorization server using any of the opportunities afforded by 1376 this profile MUST declare use of this profile by supplying the "prot- 1377 ext-1.0" value for one of its "uma_profiles_supported" values in its 1378 configuration data (see Section 1.4). 1380 5.2. Authorization API Extensibility Profile 1382 This section defines a profile for UMA where the authorization server 1383 and client roles either reside in the same system entity or otherwise 1384 have a privileged communications channel between them. Following is 1385 a summary: 1387 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 1388 authz-ext-1.0 1390 o Profile author and contact information: Mark Dobrinic 1391 (mdobrinic@cozmanova.com) 1393 o Updates or obsoletes: None; this profile is new. 1395 o Security considerations: If the entities do not use TLS but 1396 communicate across a transport layer as opposed to using internal 1397 same-entity communication, it is STRONGLY RECOMMENDED to use an 1398 alternate means of transport-layer security. 1400 o Privacy considerations: If the relationship between the roles is 1401 established in a manner that does not involve the requesting party 1402 at all, they each may maliciously leverage this relationship to 1403 observe the requesting party's personally identifiable information 1404 held in each system. 1406 o Error states: See below. 1408 o Binding obligations: Any applicable binding obligations are 1409 documented in [UMA-obligations]. 1411 Using this profile, the resource server MAY use means other than the 1412 TLS- and OAuth-protected HTTP-based authorization API to communicate 1413 with the authorization server. This involves the following 1414 opportunities: 1416 o An AAT MAY be issued without requiring an OAuth flow to establish 1417 one. 1419 o An RPT MAY be issued without requiring explicit use of the RPT 1420 endpoint or presentation of an AAT in any RPT request. 1422 o Authorization data MAY be associated with the RPT without 1423 requiring explicit use of the authorization request endpoint or 1424 presentation of an AAT, RPT, or ticket in any request. 1426 o The client MAY use alternate means of initating a claims-gathering 1427 flow with the authorization server. (Any further profiling of 1428 this profile might involve a claim profile as well; see 1429 Section 6.3.) 1431 o Error states MAY arise and be reported in a different fashion from 1432 any HTTP-, OAuth-, and UMA-defined errors related to the 1433 authorization API. 1435 An authorization server using any of the opportunities afforded by 1436 this profile MUST declare use of this profile by supplying the 1437 "authz-ext-1.0" value for one of its "uma_profiles_supported" values 1438 in its configuration data (see Section 1.4). 1440 5.3. Resource Interface Extensibility Profile 1442 This section defines a profile for UMA where the resource server and 1443 client roles either reside in the same system entity or otherwise 1444 have a privileged communications channel between them. Following is 1445 a summary: 1447 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 1448 rsrc-ext-1.0 1450 o Profile author and contact information: Mark Dobrinic 1451 (mdobrinic@cozmanova.com) 1453 o Updates or obsoletes: None; this profile is new. 1455 o Security considerations: If the entities do not use TLS but 1456 communicate across a transport layer as opposed to using internal 1457 same-entity communication, it is STRONGLY RECOMMENDED to use an 1458 alternate means of transport-layer security. 1460 o Privacy considerations: If the relationship between the roles is 1461 established in a manner that does not involve the authorization 1462 server at all, they each may maliciously leverage this 1463 relationship to observe the resource owner's or requesting party's 1464 personally identifiable information held in each system. 1466 o Error states: See below. 1468 o Binding obligations: Any applicable binding obligations are 1469 documented in [UMA-obligations]. 1471 Using this profile, the resource server MAY use means other than an 1472 HTTP-based resource interface to communicate with the authorization 1473 server. This involves the following opportunities: 1475 o Resource access attempts MAY be accomplished without requiring 1476 explicit use of the HTTP-based endpoint or presentation of an RPT. 1478 o Error states MAY arise and be reported in a different fashion from 1479 any HTTP-, OAuth-, and UMA-defined errors related to the protected 1480 resource's interface. 1482 An authorization server involved in deployments where resource 1483 servers and clients are known to be using opportunities afforded by 1484 the resource interface extensibility profile MAY declare use of this 1485 profile by supplying the "rsrc-ext-1.0" value for one of its 1486 "uma_profiles_supported" values in its configuration data (see 1487 Section 1.4). 1489 6. Specifying Additional Profiles 1491 This specification defines a protocol that has optional features. 1492 For implementation interoperability and to serve particular 1493 deployment scenarios, including sector-specific ones such as 1494 healthcare or e-government, third parties may want to define profiles 1495 of UMA that restrict these options. 1497 Further, this specification creates extensibility points for RPT 1498 profiles and claim profiles, and third parties may likewise want to 1499 define their own. Different RPT profiles could be used, for example, 1500 to change the dividing line between authorization server and resource 1501 server responsibilities in controlling access. Different claim 1502 profiles could be used to customize sector-specific or population- 1503 specific (such as individual vs. employee) claim types that drive the 1504 types of policies resource owners could set. 1506 It is not practical for this specification to standardize all desired 1507 profiles. However, to serve overall interoperability goals, the 1508 following sections provide guidelines for third parties that wish to 1509 specify UMA-related profiles. 1511 6.1. Specifying Profiles of UMA 1513 It is RECOMMENDED that profiles of UMA document the following 1514 information: 1516 1. Specify a URI that uniquely identifies the profile. 1518 2. Identify the responsible author and provide postal or electronic 1519 contact information. 1521 3. Supply references to previously defined profiles that the profile 1522 updates or obsoletes. 1524 4. Specify the set of interactions between endpoint entites involved 1525 in the profile, calling out any restrictions on ordinary UMA- 1526 conformant operations and any extension properties used in 1527 message formats. 1529 5. Identify the legally responsible parties involved in each 1530 interaction and any new obligations imposed, in the fashion of 1531 [UMA-obligations]. 1533 6. Define any additional or changed error states. 1535 7. Supply any additional security and privacy considerations, 1536 including analysis of threats and description of countermeasures. 1538 8. Specify any conformance considerations. 1540 See Section 5 for examples. 1542 6.2. Specifying RPT Profiles 1544 It is RECOMMENDED that RPT profiles document the following 1545 information: 1547 1. Specify a URI that uniquely identifies the token profile. 1549 2. Identify the responsible author and provide postal or electronic 1550 contact information. 1552 3. Supply references to previously defined token profiles that the 1553 token profile updates or obsoletes. 1555 4. Specify the keyword to be used in HTTP Authorization headers 1556 with tokens conforming to this profile. 1558 5. Specify the syntax and semantics of the data that the 1559 authorization server associates with the token. 1561 6. Specify how the token data is associated with, contained within, 1562 and/or retrieved by means of, the on-the-wire token string. 1564 7. Specify processing rules for token data. 1566 8. Identify any restrictions on grant types to be used with the 1567 token profile. 1569 9. Define any additional or changed error states. 1571 10. Supply any additional security and privacy considerations. 1573 11. Specify any obligations specific to the token profile, in the 1574 fashion of [UMA-obligations]. 1576 12. Specify any conformance considerations. 1578 See Section 3.3.2 for an example. 1580 6.3. Specifying Claim Profiles 1582 In addition to any requirements listed in Section 3.5, it is 1583 RECOMMENDED that claim profiles document the following information: 1585 1. Specify a URI that uniquely identifies the claim profile. 1587 2. Identify the responsible author and provide postal or electronic 1588 contact information. 1590 3. Supply references to previously defined claim profiles that the 1591 claim profile updates or obsoletes. 1593 4. Specify the syntax and semantics of claim data and requests for 1594 claim data. 1596 5. Specify how an authorization server gathers the claims. 1598 6. Define any additional or changed error states. 1600 7. Supply any additional security and privacy considerations. 1602 8. Specify any obligations specific to the claim profile, in the 1603 fashion of [UMA-obligations]. 1605 9. Specify any conformance considerations. 1607 See [UMAclaims] for examples. 1609 7. Security Considerations 1611 This specification relies mainly on OAuth security mechanisms as well 1612 as transport-level encryption for protecting the protection and 1613 authorization API endpoints. Most PATs and AATs are likely to use 1614 OAuth bearer tokens. See [OAuth-threat] for more information. 1616 This specification defines a number of JSON-based data formats. As a 1617 subset of the JavaScript scripting language, JSON data SHOULD be 1618 consumed through a process that does not dynamically execute it as 1619 code, to avoid malicious code execution. One way to achieve this is 1620 to use a JavaScript interpreter rather than the built-in JavaScript 1621 eval() function. 1623 The issue of impersonation is a crucial aspect in UMA, particularly 1624 when entities are wielding bearer tokens that preclude proof-of- 1625 possession (of a secret or a cryptographic key). As such, one way to 1626 mitigate this risk is for the resource owner to require stronger 1627 claims to accompany any access request. For example, consider the 1628 case where Alice sets policies at the authorization server governing 1629 access to her resources by Bob. When Bob first seeks access and must 1630 obtain an RPT (for which the default RPT profile specifies a bearer 1631 token), Alice could set policies demanding that Bob prove his 1632 identity by providing a set of strong claims issued by a trusted 1633 attribute provider in order to get authorization data associated with 1634 that token. 1636 Another issue concerns the use of the [OAuth2] implicit flow. In 1637 this case, Bob will have exposure to the token, and may maliciously 1638 pass the token to an unauthorized party. To mitigate this weakness 1639 and others, we recommend considering the following steps: 1641 o Require that the Requesting Party (as defined in 1642 [UMA-obligations], meaning this party is able to take on legal 1643 obligations) legitimately represent the wielder of the bearer 1644 token. This solution is based on a legal or contractual approach, 1645 and therefore does not reduce the risk from the technical 1646 perspective. 1648 o The authorization server, possibly with input from the resource 1649 owner, can implement tighter time-to-live strategies around the 1650 authorization data in RPTs. This is a classic approach with 1651 bearer tokens that helps to limit a malicious party's ability to 1652 intercept and use the bearer token. In the same vein, the 1653 authorization server could require claims to have a reasonable 1654 degree of freshness (which would require a custom claims profile). 1656 o The strongest strategy is to disallow bearer-type RPTs within the 1657 UMA profile being deployed, by providing or requiring an RPT 1658 profile that requires use of a holder-of-key approach. In this 1659 way, the wielder of the token must engage in a live session for 1660 proof-of-possession. 1662 For information about the additional technical, operational, and 1663 legal elements of trust establishment between UMA entities and 1664 parties, which affects security considerations, see 1665 [UMA-obligations]. 1667 8. Privacy Considerations 1669 The authorization server comes to be in possession of resource set 1670 information (such as names and icons) that may reveal information 1671 about the resource owner, which the authorization server's trust 1672 relationship with the resource server is assumed to accommodate. 1673 However, the client is a less-trusted party -- in fact, entirely 1674 untrustworthy until authorization data is associated with its RPT. 1675 This specification depends on [OAuth-resource-reg], which recommends 1676 obscuring resource set identifiers in order to avoid leaking 1677 personally identifiable information to clients through the scope 1678 mechanism. 1680 For information about the technical, operational, and legal elements 1681 of trust establishment between UMA entities and parties, which 1682 affects privacy considerations, see [UMA-obligations]. 1684 Additional considerations related to Privacy by Design concepts are 1685 discussed in [UMA-PbD]. 1687 9. Conformance 1689 This section outlines conformance requirements for various entities 1690 implementing UMA endpoints. 1692 This specification has dependencies on other specifications, as 1693 referenced under the normative references listed in this 1694 specification. Its dependencies on some specifications, such as 1695 OpenID Connect ([OIDCCore]), are optional depending on whether the 1696 feature in question is used in the implementation. 1698 The authorization server's configuration data provides a machine- 1699 readable method for it to indicate certain of the conformance options 1700 it supports. Several of the configuration data properties allow for 1701 indicating extension features. Where this specification does not 1702 already require optional features to be documented, it is RECOMMENDED 1703 that authorization server developers and deployers document any 1704 profiled or extended features explicitly and use configuration data 1705 to indicate their usage. See Section 1.4 for information about 1706 providing and extending the configuration data. 1708 10. IANA Considerations 1710 This document makes no request of IANA. 1712 11. Acknowledgments 1714 The current editor of this specification is Thomas Hardjono of MIT. 1715 The following people are co-authors: 1717 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 1719 o Domenico Catalano, Oracle Corp. 1721 o Mark Dobrinic, Cozmanova 1723 o George Fletcher, AOL 1725 o Maciej Machulak, Newcastle University 1727 o Eve Maler, XMLgrrl.com 1729 o Lukasz Moren, Newcastle University 1731 o Christian Scholz, COMlounge GmbH (former editor) 1733 o Mike Schwartz, Gluu 1735 o Jacek Szpot, Newcastle University 1737 Additional contributors to this specification include the Kantara UMA 1738 Work Group participants, a list of whom can be found at 1739 [UMAnitarians]. 1741 12. Issues 1743 Issues are captured at the project's GitHub site ([1]). 1745 13. References 1747 13.1. Normative References 1749 [DynClientReg] 1750 Richer, J., "OAuth 2.0 Core Dynamic Client Registration", 1751 August 2013, . 1754 [OAuth-bearer] 1755 "The OAuth 2.0 Authorization Framework: Bearer Token 1756 Usage", October 2012, 1757 . 1759 [OAuth-introspection] 1760 Richer, J., "OAuth Token Introspection", May 2013, 1761 . 1764 [OAuth-resource-reg] 1765 Hardjono, T., "OAuth 2.0 Resource Set Registration", 1766 December 2012, . 1769 [OAuth-threat] 1770 Lodderstedt, T., "OAuth 2.0 Threat Model and Security 1771 Considerations", January 2013, 1772 . 1774 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 1775 October 2012, . 1777 [OIDCCore] 1778 Sakimura, N., "OpenID Connect Core 1.0", December 2013, 1779 . 1781 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1782 Requirement Levels", BCP 14, RFC 2119, March 1997. 1784 [RFC4627] Crockford, D., "The application/json Media Type for 1785 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1787 [UMA-obligations] 1788 Maler, E., "Binding Obligations on UMA Participants", 1789 January 2013, . 1792 [UMAclaims] 1793 Catalano, D., "Claim Profiles for User-Managed Access 1794 (UMA)", February 2014, . 1797 [hostmeta] 1798 Hammer-Lahav, E., "Web Host Metadata", October 2011, 1799 . 1801 13.2. Informative References 1803 [OAuth-SAML] 1804 Campbell, B., "SAML 2.0 Bearer Assertion Profiles for 1805 OAuth 2.0", December 2013, . 1808 [OAuth-linktypes] 1809 Mills, W., "Link Type Registrations for OAuth 2", February 1810 2013, 1811 . 1813 [OAuth-meta] 1814 Sakimura, N., "JSON Metadata for OAuth Responses", 1815 February 2013, 1816 . 1818 [UMA-PbD] Maler, B., "Privacy by Design Implications of UMA", 1819 December 2013, . 1822 [UMA-casestudies] 1823 Maler, E., "UMA Case Studies", March 2013, 1824 . 1827 [UMA-usecases] 1828 Maler, E., "UMA Scenarios and Use Cases", October 2010, 1829 . 1832 [UMAnitarians] 1833 Maler, E., "UMA Participant Roster", April 2013, 1834 . 1837 13.3. URIs 1839 [1] https://github.com/xmlgrrl/UMA-Specifications/issues 1841 [2] http://kantarainitiative.org/confluence/display/uma/ 1842 UMA+1.0+Core+Protocol 1844 Appendix A. Document History 1846 NOTE: To be removed by RFC editor before publication as an RFC. 1848 See [2] for a list of code-breaking and other major changes made to 1849 this specification at various revision points. 1851 Author's Address 1853 Thomas Hardjono (editor) 1854 MIT 1856 Email: hardjono@mit.edu