idnits 2.17.1 draft-hardjono-oauth-umacore-10.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. 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 (July 20, 2014) is 3561 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 1842 -- Looks like a reference, but probably isn't: '2' on line 1851 -- Possible downref: Non-RFC (?) normative reference: ref. 'DynClientReg' -- 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) -- No information found for draft-uma-trust - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'UMA-obligations' -- No information found for draft-uma-claim-profiles - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'UMAclaims' Summary: 3 errors (**), 0 flaws (~~), 2 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 July 20, 2014 5 Expires: January 21, 2015 7 User-Managed Access (UMA) Profile of OAuth 2.0 8 draft-hardjono-oauth-umacore-10 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. 17 This revision of the specification is part of UMA V0.9. 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 January 21, 2015. 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) V0.9 is a profile of OAuth 2.0 [OAuth2]. 103 UMA defines how resource owners can control protected-resource access 104 by clients operated by arbitrary requesting parties, where the 105 resources reside on any number of resource servers, and where a 106 centralized authorization server governs access based on resource 107 owner policy. Resource owners configure authorization servers with 108 access policies that serve as implicit authorization grants. Thus, 109 the UMA profile of OAuth can be considered to encompass an 110 authorization grant flow. 112 UMA serves numerous use cases where a resource owner outsources 113 authorization for access to their resources, potentially even without 114 the run-time presence of the resource owner. A typical example is 115 the following: a web user (an end-user resource owner) can authorize 116 a web app (client) to gain one-time or ongoing access to a protected 117 resource containing his home address stored at a "personal data 118 store" service (resource server), by telling the resource server to 119 respect access entitlements issued by his chosen cloud-based 120 authorization service (authorization server). The requesting party 121 operating the client might be the resource owner himself, using a web 122 or native app run by an e-commerce company that needs to know where 123 to ship a purchased item, or it might be his friend who is using an 124 online address book service to collect contact information, or it 125 might be a survey company that uses an autonomous web service to 126 compile population demographics. A variety of scenarios and use 127 cases can be found in [UMA-usecases] and [UMA-casestudies]. 129 Practical control of access among loosely coupled parties requires 130 more than just messaging protocols. This specification defines only 131 the technical "contract" between UMA-conforming entities; its 132 companion Binding Obligations specification [UMA-obligations] defines 133 the expected behaviors of parties operating and using these entities. 134 Parties operating entities that claim to be UMA-conforming MUST 135 provide documentation affirmatively stating their acceptance of the 136 binding obligations contractual framework defined in the Binding 137 Obligations specification. 139 In enterprise settings, application access management sometimes 140 involves letting back-office applications serve only as policy 141 enforcement points (PEPs), depending entirely on access decisions 142 coming from a central policy decision point (PDP) to govern the 143 access they give to requesters. This separation eases auditing and 144 allows policy administration to scale in several dimensions. UMA 145 makes use of a separation similar to this, letting the resource owner 146 serve as a policy administrator crafting authorization strategies for 147 resources under their control. 149 In order to increase interoperable communication among the 150 authorization server, resource server, and client, UMA defines 151 several purpose-built APIs related to the outsourcing of 152 authorization, themselves protected by OAuth in embedded fashion. 154 The UMA protocol has three broad phases, as shown in Figure 1. 156 The Three Phases of the UMA Profile of OAuth 158 +--------------+ 159 | resource | 160 +---------manage (A)------------ | owner | 161 | +--------------+ 162 | Phase 1: | 163 | protect a control (B) 164 | resource | 165 v v 166 +------------+ +----------+--------------+ 167 | | |protection| | 168 | resource | | API | authorization| 169 | server |<-protect (C)--| (needs | server | 170 | | | PAT) | | 171 +------------+ +----------+--------------+ 172 | protected | | authorization| 173 | resource | | API | 174 |(needs RPT) | | (needs AAT) | 175 +------------+ +--------------+ 176 ^ | 177 | Phases 2 and 3: authorize (D) 178 | get authorization, | 179 | access a resource v 180 | +--------------+ 181 +---------access (E)-------------| client | 182 +--------------+ 184 requesting party 186 Figure 1 188 The phases work as follows: 190 Protect a resource (Described in Section 2.) The resource owner, 191 who manages online resources at the resource server ("A"), 192 introduces it to the authorization server so that the latter can 193 begin controlling the resources' protection. To accomplish this 194 protection, the authorization server presents a protection API 195 ("C") to the resource server. This API is OAuth-protected and 196 requires a protection API token (PAT) for access. Out of band, 197 the resource owner configures the authorization server with 198 policies associated with the registered resource sets ("B"). 200 Get authorization (Described in Section 3.) The client approaches 201 the resource server seeking access to an UMA-protected resource. 202 In order to access it successfully, the client must first use the 203 authorization server's authorization API ("D") to obtain a 204 requesting party token (RPT) on behalf of its requesting party, 205 and the requesting party must supply to the authorization server 206 any identity claims needed in order for the server to associate 207 sufficient authorization data with that RPT. The API is OAuth- 208 protected and requires an authorization API token (AAT) for 209 access. 211 Access a resource (Described along with Phase 2 in Section 3.) The 212 client successfully presents an RPT that has sufficient 213 authorization data associated with it to the resource server, 214 gaining access to the desired resource ("E"). In this sense, this 215 phase is the "happy path" within phase 2. The nature of the 216 authorization data varies according to the RPT profile in use. 218 Implementers have the oportunity to develop profiles (see Section 6) 219 that specify and restrict various UMA protocol, RPT, and identity 220 claim options, according to deployment and usage conditions. 222 1.1. Notational Conventions 224 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 225 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 226 document are to be interpreted as described in [RFC2119]. 228 Unless otherwise noted, all the protocol properties and values are 229 case sensitive. 231 1.2. Terminology 233 UMA introduces the following new terms and enhancements of OAuth term 234 definitions. 236 resource owner 237 An OAuth resource that is the "user" in User-Managed Access. 238 This is typically an end-user (a natural person) but it can 239 also be a corporation or other legal person. 241 requesting party 242 An end-user, or a corporation or other legal person, that uses 243 a client to seek access to a protected resource. The 244 requesting party may or may not be the same party as the 245 resource owner. 247 client 248 An application making protected resource requests with the 249 resource owner's authorization and on the requesting party's 250 behalf. 252 claim 253 A statement of the value or values of one or more identity 254 attributes of a requesting party. A requesting party may need 255 to provide claims to an authorization server in order to 256 satisfy policy and gain permission for access to a protected 257 resource. 259 resource set A set of one or more protected resources. In 260 authorization policy terminology, a resource set is the 261 "object" being protected. 263 scope A bounded extent of access that is possible to perform on a 264 resource set. In authorization policy terminology, a scope is 265 one of the potentially many "verbs" that can logically apply to 266 a resource set ("object"). UMA associates scopes with labeled 267 resource sets. 269 authorization data Data associated with a requesting party token 270 that enables some combination of the authorization server and 271 resource server to determine the correct extent of access to 272 allow to a client. Authorization data is a key part of the 273 definition of an RPT profile. 275 permission A scope of access over a particular resource set at a 276 particular resource server that is being requested by, or 277 granted to, a requesting party. In authorization policy 278 terminology, a permission is an entitlement that includes a 279 "subject" (requesting party), "verbs" (one or more scopes of 280 access), and an "object" (resource set). A permission is one 281 example of authorization data that an authorization server may 282 issue. 284 permission ticket A correlation handle that is conveyed from an 285 authorization server to a resource server, from a resource 286 server to a client, and ultimately from a client to an 287 authorization server, to enable the authorization server to 288 assess the correct resource owner policies to apply to a 289 request for an authorization grant. 291 1.3. Achieving Distributed Protection Through APIs and Tokens 293 The software components that fill the roles of UMA authorization 294 servers, resource servers, and clients respectively are intended to 295 work in an interoperable fashion when each is operated by an entirely 296 separate party (for example, different organizations). For this 297 reason, UMA specifies communications channels that the authorization 298 server MUST implement as HTTP-based APIs that MUST use TLS and OAuth 299 protection, and that the resource server MUST implement as an HTTP- 300 based interface. UMA's use of TLS transport-layer security is 301 governed by Section 1.6 of [OAuth2], which discusses deployment and 302 adoption characteristics of different TLS versions. Three different 303 types of access tokens are issued and used for a variety of purposes 304 as part of these inter-role interactions. 306 It is also REQUIRED, in turn, for resource servers and clients on the 307 requesting side of UMA interactions to use these channels, unless a 308 profile is being used that enables API extensibility. Profiles that 309 enable such alternatives are described in Section 5. 311 1.3.1. Protection API 313 The authorization server MUST present a TLS- and OAuth-protected, 314 HTTP-based protection API for use by resource servers. The 315 authorization server thus has an OAuth token endpoint and user 316 authorization endpoint, and has the option to issue an OAuth refresh 317 token along with any access tokens issued for these APIs. The 318 authorization server MUST declare all of its protection API endpoints 319 in its configuration data (see Section 1.4). 321 The protection API consists of three endpoints: 323 o OAuth resource set registration endpoint as defined by 324 [OAuth-resource-reg] 326 o Endpoint for registering client-requested permissions 328 o OAuth token introspection endpoint as defined by 329 [OAuth-introspection] and Section 3.3.1 331 An entity seeking protection API access MUST have the scope 332 "http://docs.kantarainitiative.org/uma/scopes/prot.json". (This URI 333 resolves to a JSON-encoded scope description, as defined in 334 [OAuth-resource-reg]. The description is non-normative for UMA 335 purposes.) An access token with at least this scope is called a 336 protection API token (PAT) and an entity with this scope is 337 definitionally a resource server. A single entity can serve in both 338 resource server and client roles if it has the appropriate OAuth 339 scopes. If a request to an endpoint fails due to an invalid, 340 missing, or expired PAT, or requires higher privileges at this 341 endpoint than provided by the PAT, the authorization server responds 342 with an OAuth error. 344 The authorization server MUST support the OAuth bearer token profile 345 for PAT issuance, and MAY support other OAuth token profiles (for 346 example, the SAML bearer token grant type [OAuth-SAML]). It MUST 347 declare all supported token profiles and grant types for PAT issuance 348 in its configuration data. 350 A PAT binds a resource owner, a resource server the owner uses for 351 resource management, and an authorization server the owner uses for 352 protection of resources at this resource server. It is not specific 353 to any client or requesting party. The issuance of a PAT represents 354 the approval of the resource owner for this resource server to trust 355 this authorization server for protecting its resources belonging to 356 this resource owner. 358 1.3.2. Authorization API 360 The authorization server MUST present a TLS- and OAuth-protected, 361 HTTP-based authorization API for use by clients. The authorization 362 server thus has an OAuth token endpoint and user authorization 363 endpoint, and has the option to issue an OAuth refresh token along 364 with any access tokens issued for these APIs. The authorization 365 server MUST declare all of its authorization API endpoints in its 366 configuration data (see Section 1.4). 368 The authorization API consists of two endpoints: 370 o Endpoint for RPT issuance 372 o Endpoint for requesting authorization 374 An entity seeking authorization API access MUST have the scope 375 "http://docs.kantarainitiative.org/uma/scopes/authz.json". (This URI 376 resolves to a JSON-encoded scope description, as defined in 377 [OAuth-resource-reg]. The description is non-normative for UMA 378 purposes.) An access token with at least this scope is called an 379 authorization API token (AAT) and an entity with this scope is 380 definitionally a client. A single entity can serve in both resource 381 server and client roles if it has the appropriate OAuth scopes. If a 382 request to an endpoint fails due to an invalid, missing, or expired 383 AAT, or requires higher privileges at this endpoint than provided by 384 the AAT, the authorization server responds with an OAuth error. 386 The authorization server MUST support the OAuth bearer token profile 387 for AAT issuance, and MAY support other OAuth token profiles (for 388 example, the SAML bearer token grant type [OAuth-SAML]). It MUST 389 declare all supported token profiles and grant types for AAT issuance 390 in its configuration data. 392 An AAT binds a requesting party, a client being used by that party, 393 and an authorization server that protects resources this client is 394 seeking access to on this requesting party's behalf. It is not 395 specific to any resource server or resource owner. The issuance of 396 an AAT represents the approval of this requesting party for this 397 client to engage with this authorization server to supply claims, ask 398 for authorization, and perform any other tasks needed for obtaining 399 authorization for access to resources at all resource servers that 400 use this authorization server. The authorization server is able to 401 manage future processes of authorization and claims-caching 402 efficiently for this client/requesting party pair across all resource 403 servers they try to access; however, these management processes are 404 outside the scope of this specification. 406 1.3.3. Protected Resource Interface 408 The resource server MAY present to clients whatever HTTP-based APIs 409 or endpoints it wishes. To protect any of its resources available in 410 this fashion using UMA, it MUST require a requesting party token 411 (RPT) with sufficient authorization data for access. 413 This specification defines one RPT profile, call "bearer" (see 414 Section 3.3.2), which the authorization server MUST support. It MAY 415 support additional RPT profiles, and MUST declare all supported RPT 416 profiles in its configuration data (see Section 1.4). 418 An RPT binds a requesting party, the client being used by that party, 419 the resource server at which protected resources of interest reside, 420 and the authorization server that protects those resources. It is 421 not specific to a single resource owner, though its internal 422 components are likely to be bound to individual resource owners, 423 depending on the RPT profile in use. 425 1.3.4. Time-to-Live Considerations 427 The authorization server has the opportunity to manage the validity 428 periods of access tokens that it issues, their corresponding refresh 429 tokens where applicable, the individual data components associated 430 with RPTs where applicable, and even the client credentials that it 431 issues. Different time-to-live strategies may be suitable for 432 different resources and scopes of access, and the authorization 433 server has the opportunity to give the resource owner control over 434 lifetimes of tokens and authorization data issued on their behalf 435 through policy. These options are all outside the scope of this 436 specification. 438 1.4. Authorization Server Configuration Data 440 The authorization server MUST provide configuration data in a JSON 441 [RFC4627] document that resides in an /uma-configuration directory at 442 its hostmeta [hostmeta] location. The configuration data documents 443 conformance options and endpoints supported by the authorization 444 server. (At the appropriate time, this section will instead profile 445 whatever self-describing metadata specification OAuth adopts, for 446 example, [OAuth-linktypes] or [OAuth-meta].) 448 The configuration data has the following properties. 450 version 451 REQUIRED. The version of the UMA core protocol to which this 452 authorization server conforms. The value MUST be the string 453 "1.0". 455 issuer 456 REQUIRED. A URI indicating the party operating the 457 authorization server. 459 pat_profiles_supported 460 REQUIRED. OAuth access token profiles supported by this 461 authorization server for PAT issuance. The property value is 462 an array of string values, where each string value is either a 463 reserved keyword defined in this specification or a URI 464 identifying an access token profile defined elsewhere. The 465 reserved keyword "bearer" as a value for this property stands 466 for the OAuth bearer token profile [OAuth-bearer]. The 467 authorization server is REQUIRED to support this profile, and 468 to supply this string value explicitly. The authorization 469 server MAY declare its support for additional access token 470 profiles for PATs. 472 aat_profiles_supported 473 REQUIRED. OAuth access token profiles supported by this 474 authorization server for AAT issuance. The property value is 475 an array of string values, where each string value is either a 476 reserved keyword defined in this specification or a URI 477 identifying an access token profile defined elsewhere. The 478 reserved keyword "bearer" as a value for this property stands 479 for the OAuth bearer token profile [OAuth-bearer]. The 480 authorization server is REQUIRED to support this profile, and 481 to supply this string value explicitly. The authorization 482 server MAY declare its support for additional access token 483 profiles for AATs. 485 rpt_profiles_supported 486 REQUIRED. UMA RPT profiles supported by this authorization 487 server for RPT issuance. The property value is an array of 488 string values, where each string value is either a reserved 489 keyword defined in this specification or a URI identifying an 490 RPT profile defined elsewhere. The reserved keyword "bearer" 491 as a value for this property stands for the UMA bearer RPT 492 profile defined in Section 3.3.2. The authorization server is 493 REQUIRED to support this profile, and to supply this string 494 value explicitly. The authorization server MAY declare its 495 support for additional RPT profiles. 497 pat_grant_types_supported 498 REQUIRED. OAuth grant types supported by this authorization 499 server in issuing PATs. The property value is an array of 500 string values. Each string value MUST be one of the grant_type 501 values defined in [OAuth2], or alternatively a URI identifying 502 a grant type defined elsewhere. 504 aat_grant_types_supported 505 REQUIRED. OAuth grant types supported by this authorization 506 server in issuing AATs. The property value is an array of 507 string values. Each string value MUST be one of the grant_type 508 values defined in [OAuth2], or alternatively a URI identifying 509 a grant type defined elsewhere. 511 claim_profiles_supported 512 OPTIONAL. Claim formats and associated sub-protocols for 513 gathering claims from requesting parties, as supported by this 514 authorization server. The property value is an array of string 515 values, which each string value is either a reserved keyword 516 defined in this specification or a URI identifying a claim 517 profile defined elsewhere. 519 uma_profiles_supported 520 OPTIONAL. UMA profiles supported by this authorization server. 521 The property value is an array of string values, which each 522 string value is either a reserved keyword defined in this 523 specification or a URI identifying an UMA profile defined 524 elsewhere. The reserved keywords "prot-ext", "authz-ext", and 525 "rsrc-ext" as values for this property stand for the 526 extensibility profiles defined, respectively, in Section 5. 528 dynamic_client_endpoint 529 OPTIONAL. The endpoint to use for performing dynamic client 530 registration. Usage of this endpoint is defined by 531 [DynClientReg]. The presence of this property indicates 532 authorization server support for the dynamic client 533 registration feature and its absence indicates a lack of 534 support. 536 token_endpoint 537 REQUIRED. The endpoint URI at which the resource server or 538 client asks the authorization server for a PAT or AAT, 539 respectively. A requested scope of 540 "http://docs.kantarainitiative.org/uma/scopes/prot.json" 541 results in a PAT. A requested scope of 542 "http://docs.kantarainitiative.org/uma/scopes/authz.json" 543 results in an AAT. Usage of this endpoint is defined by 544 [OAuth2]. 546 user_endpoint 547 REQUIRED. The endpoint URI at which the resource server 548 gathers the consent of the end-user resource owner or the 549 client gathers the consent of the end-user requesting party, if 550 the "authorization_code" grant type is used. Usage of this 551 endpoint is defined by [OAuth2]. 553 introspection_endpoint 554 REQUIRED. The endpoint URI at which the resource server 555 introspects an RPT presented to it by a client. Usage of this 556 endpoint is defined by [OAuth-introspection] and Section 3.3.1. 557 A valid PAT MUST accompany requests to this protected endpoint. 559 resource_set_registration_endpoint 560 REQUIRED. The endpoint URI at which the resource server 561 registers resource sets to put them under authorization manager 562 protection. Usage of this endpoint is defined by 563 [OAuth-resource-reg] and Section 2. A valid PAT MUST accompany 564 requests to this protected endpoint. 566 permission_registration_endpoint 567 REQUIRED. The endpoint URI at which the resource server 568 registers a client-requested permission with the authorization 569 server. Usage of this endpoint is defined by Section 3.2. A 570 valid PAT MUST accompany requests to this protected endpoint. 572 rpt_endpoint 573 REQUIRED. The endpoint URI at which the client asks the 574 authorization server for an RPT. Usage of this endpoint is 575 defined by Section 3.4.1. A valid AAT MUST accompany requests 576 to this protected endpoint. 578 authorization_request_endpoint 579 REQUIRED. The endpoint URI at which the client asks to have 580 authorization data associated with its RPT. Usage of this 581 endpoint is defined in Section 3.4.2. A valid AAT MUST 582 accompany requests to this protected endpoint. 584 Example of authorization server configuration data that resides at 585 https://example.com/.well-known/uma-configuration (note the use of 586 https: for endpoints throughout): 588 { 589 "version":"1.0", 590 "issuer":"https://example.com", 591 "pat_profiles_supported":["bearer"], 592 "aat_profiles_supported":["bearer"], 593 "rpt_profiles_supported":["bearer"], 594 "pat_grant_types_supported":["authorization_code"], 595 "aat_grant_types_supported":["authorization_code"], 596 "claim_profiles_supported":["openid"], 597 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", 598 "token_endpoint":"https://as.example.com/token_uri", 599 "user_endpoint":"https://as.example.com/user_uri", 600 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri", 601 "introspection_endpoint":"https://as.example.com/rs/status_uri", 602 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri", 603 "rpt_endpoint":"https://as.example.com/client/rpt_uri", 604 "authorization_request_endpoint":"https://as.example.com/client/perm_uri" 605 } 607 Authorization server configuration data MAY contain extension 608 properties that are not defined in this specification. Extension 609 names that are unprotected from collisions are outside the scope of 610 this specification. 612 2. Protecting a Resource 614 The resource owner, resource server, and authorization server perform 615 the following actions to put resources under protection. This list 616 assumes that the resource server has discovered the authorization 617 server's configuration data and endpoints as needed. 619 1. The authorization server issues client credentials to the 620 resource server. It is OPTIONAL for the client credentials to be 621 provided dynamically through [DynClientReg]; alternatively, they 622 MAY use a static process. 624 2. The resource server acquires a PAT from the authorization server. 625 It is OPTIONAL for the resource owner to introduce the resource 626 server to the authorization server dynamically (for example, 627 through a "NASCAR"-style user interface where the resource owner 628 selects a chosen authorization server); alternatively, they MAY 629 use a static process that may or may not directly involve the 630 resource owner at introduction time. 632 3. In an ongoing fashion, the resource server registers any resource 633 sets with the authorization server for which it intends to 634 outsource protection, using the resource set registration 635 endpoint of the protection API (see [OAuth-resource-reg]). 637 Note: The resource server is free to offer the option to protect any 638 subset of the resource owner's resources using different 639 authorization servers or other means entirely, or to protect some 640 resources and not others. Additionally, the choice of protection 641 regimes can be made explicitly by the resource owner or implicitly by 642 the resource server. Any such partitioning by the resource server or 643 owner is outside the scope of this specification. 645 Once a resource set has been placed under authorization server 646 protection through the registration of a resource set description for 647 it, and until such a description's deletion by the resource server, 648 the resource server MUST limit access to corresponding resources, 649 requiring sufficient authorization data associated with client- 650 presented RPTs by the authorization server (see Section 3.1.2). 652 3. Getting Authorization and Accessing a Resource 654 An authorization server orchestrates and controls clients' access (on 655 their requesting parties' behalf) to a resource owner's protected 656 resources at a resource server, under conditions dictated by that 657 resource owner. 659 The process of getting authorization and accessing a resource always 660 begins with the client attempting access at a protected resource 661 endpoint at the resource server. How the client came to learn about 662 this endpoint is out of scope for this specification. The resource 663 owner might, for example, have advertised its availability publicly 664 on a blog or other website, listed it in a discovery service, or 665 emailed a link to a particular intended requesting party. 667 The resource server responds to the client's access request with 668 whatever its application-specific resource interface defines as a 669 success response, either immediately or having first performed one or 670 more embedded interactions with the authorization server. Depending 671 on the nature of the resource server's response to an failed access 672 attempt, the client and its requesting party engage in embedded 673 interactions with the authorization server before re-attempting 674 access. 676 The interactions are as follows. Each interaction MAY be the last, 677 if the client chooses not to continue pursuing the access attempt or 678 the resource server chooses not to continue facilitating it. 680 o The client attempts to access a protected resource. 682 * If the access attempt is unaccompanied by an RPT, the resource 683 server responds immediately with an HTTP 401 (Unauthorized) 684 response and instructions on where to go to obtain one. 686 * If the access attempt was accompanied by an RPT, the resource 687 server checks the RPT's status. 689 + If the RPT is invalid, the resource server responds with an 690 HTTP 401 (Unauthorized) response and instructions on where 691 to go to obtain a token. 693 + If the RPT is valid but has insufficient authorization data, 694 the resource server registers a suitable requested 695 permission on the client's behalf at the authorization 696 server, and then responds to the client with an HTTP 403 697 (Forbidden) response and instructions on where to go to ask 698 for authorization. 700 + If the RPT is valid, and if the authorization data 701 associated with the token is sufficient for allowing access, 702 the resource server responds with an HTTP 2xx (Success) 703 response and a representation of the resource. 705 o If the client (possessing no RPT or an invalid RPT) received a 401 706 response and an authorization server's location, after looking up 707 its configuration data and endpoints as necessary, it requests an 708 RPT from the RPT endpoint of the authorization API. 710 o If the client (posessing a valid RPT) received a 403 response and 711 a permission ticket, it asks the authorization server for 712 authorization data that matches the ticket using the authorization 713 request endpoint of the authorization API. If the authorization 714 server needs requesting party claims in order to assess this 715 client's authorization, it engages in a claims-gathering flow. 717 * If the client does not already have an AAT at the appropriate 718 authorization server to be able to use its authorization API, 719 it first obtains one. 721 The interactions are described in detail in the following sections. 723 3.1. Client Attempts to Access Protected Resource 725 This interaction assumes that the resource server has previously 726 registered one or more resource sets that correspond to the resource 727 to which access is being attempted. 729 The client attempts to access a protected resource (for example, when 730 an end-user requesting party clicks on a thumbnail representation of 731 the resource to retrieve a larger version). It is expected to 732 discover, or be provisioned or configured with, knowledge of the 733 protected resource and its location out of band. Further, the client 734 is expected to acquire its own knowledge about the application- 735 specific methods made available by the resource server for operating 736 on this protected resource (such as viewing it with a GET method, or 737 transforming it with some complex API call). 739 The access attempt either is or is not accompanied by an RPT. 741 3.1.1. Client Presents No RPT 743 Example of a request carrying no RPT: 745 GET /album/photo.jpg HTTP/1.1 746 Host: photoz.example.com 747 ... 749 If the client does not present an RPT with the request, the resource 750 server returns an HTTP 401 (Unauthorized) status code and providing 751 the authorization server's URI in an "as_uri" property to facilitate 752 authorization server configuration data discovery, including 753 discovery of the endpoint where the client can request an RPT 754 (Section 3.4.1). 756 For example: 758 HTTP/1.1 401 Unauthorized 759 WWW-Authenticate: UMA realm="example", 760 host_id="photoz.example.com", 761 as_uri="https://as.example.com" 762 ... 764 3.1.2. Client Presents RPT 765 Example of a request carrying an RPT using the UMA bearer RPT 766 profile: 768 GET /album/photo.jpg HTTP/1.1 769 Authorization: Bearer vF9dft4qmT 770 Host: photoz.example.com 771 ... 773 If the client presents an RPT with its request, the resource server 774 MUST determine the RPT's status (see Section 3.3) before responding. 776 If the RPT is invalid, the resource server applies UMA protection by 777 returning an HTTP 401 (Unauthorized) status code and providing the 778 authorization server's URI in an "as_uri" property in the header, 779 similarly to the case where no RPT was presented. 781 If the RPT is valid but has insufficient authorization data for the 782 type of access sought, the resource server uses the protection API to 783 register a requested permission with the authorization server that 784 would suffice for that scope of access (see Section 3.2). It then 785 responds with the HTTP 403 (Forbidden) status code and providing the 786 authorization server's URI in an "as_uri" property in the header and 787 the permission ticket it just received from the AM in the body in a 788 JSON-encoded "ticket" property. 790 Example of the resource server's response after having registered a 791 requested permission and received a ticket: 793 HTTP/1.1 403 Forbidden 794 WWW-Authenticate: UMA realm="example", 795 host_id="photoz.example.com", 796 as_uri="https://as.example.com" 797 error="insufficient_scope" 799 { 800 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 801 } 803 If the RPT's status is associated with authorization data that is 804 sufficient for the access sought by the client, the resource server 805 MUST give access to the desired resource. 807 Example of the resource server's response after having determined 808 that the RPT is valid and associated with sufficient authorization 809 data: 811 HTTP/1.1 200 OK 812 Content-Type: image/jpeg 813 ... 815 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 816 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 817 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 818 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 820 The resource server MUST NOT give access where the token's status is 821 not associated with sufficient authorization data for the attempted 822 scope of access. 824 3.2. Resource Server Registers Requested Permission With Authorization 825 Server 827 In response to receiving an access request accompanied by an RPT that 828 has insufficient authorization data, the resource server uses the 829 protection API's permission registration endpoint to register a 830 permission with the authorization server that would be sufficient for 831 the type of access sought. The authorization server returns a 832 permission ticket for the resource server to give to the client in 833 its response. The PAT provided in the API request implicitly 834 identifies the resource owner ("subject") to which the permission 835 applies. 837 The resource server uses the POST method at the endpoint. The body 838 of the HTTP request message contains a JSON object providing the 839 requested permission, using a format derived from the scope 840 description format specified in [OAuth-resource-reg], as follows. 841 The object has the following properties: 843 resource_set_id REQUIRED. The identifier for a resource set to 844 which this client is seeking access. The identifier MUST 845 correspond to a resource set that was previously registered. 847 scopes REQUIRED. An array referencing one or more identifiers of 848 scopes to which access is needed for this resource set. Each 849 scope identifier MUST correspond to a scope that was registered by 850 this resource server for the referenced resource set. 852 Example of an HTTP request that registers a requested permission at 853 the authorization server's permission registration endpoint: 855 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 856 Content-Type: application/json 857 Host: as.example.com 859 { 860 "resource_set_id": "112210f47de98100", 861 "scopes": [ 862 "http://photoz.example.com/dev/actions/view", 863 "http://photoz.example.com/dev/actions/all" 864 ] 865 } 867 If the registration request is successful, the authorization server 868 responds with an HTTP 201 (Created) status code and includes the 869 Location header in its response as well as the "ticket" property in 870 the JSON-formatted body. 872 The permission ticket is a short-lived opaque structure whose form is 873 determined by the authorization server. The ticket value MUST be 874 securely random (for example, not merely part of a predictable 875 sequential series), to avoid denial-of-service attacks. Since the 876 ticket is an opaque structure from the point of view of the client, 877 the authorization server is free to include information regarding 878 expiration time within the opaque ticket for its own consumption. 879 When the client subsequently uses the authorization API to ask the 880 authorization server for authorization data to be associated with its 881 RPT, it will submit this ticket to the authorization server. 883 For example: 885 HTTP/1.1 201 Created 886 Content-Type: application/json 887 Location: https://as.example.com/permreg/host/photoz.example.com/5454345rdsaa4543 888 ... 890 { 891 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 892 } 894 If the registration request is authenticated properly but fails due 895 to other reasons, the authorization server responds with an HTTP 400 896 (Bad Request) status code and includes one of the following UMA error 897 codes (see Section 4.2): 899 invalid_resource_set_id The provided resource set identifier was not 900 found at the authorization server. 902 invalid_scope At least one of the scopes included in the request was 903 not registered previously by this resource server. 905 3.3. Resource Server Determines RPT's Status 907 The resource server MUST determine a received RPT's status, including 908 both its validity and, if valid, its associated authorization data, 909 before giving or refusing access to the client. An RPT is associated 910 with a set of authorization data that governs whether the client is 911 authorized for access. The token's nature and format are dictated by 912 its profile; the profile might allow it to be self-contained, such 913 that the resource server is able to determine its status locally, or 914 might require or allow the resource server to make a run-time 915 introspection request of the authorization server that issued the 916 token. 918 This specification makes one type of RPT REQUIRED for the 919 authorization server to support: the UMA bearer token profile, as 920 defined in Section 3.3.2. Implementers MAY define and use other RPT 921 profiles. 923 3.3.1. Token Introspection 925 Within any RPT profile, when a resource server needs to introspect a 926 token in a non-self-contained way to determine its status, it MAY 927 require, allow, or prohibit use of the OAuth token introspection 928 endpoint (defined by [OAuth-introspection]) that is part of the 929 protection API, and MAY profile its usage. The resource server MUST 930 use the POST method in interacting with the endpoint, not the GET 931 method also defined by [OAuth-introspection]. 933 3.3.2. RPT Profile: Bearer 935 This section defines the UMA bearer token profile. Following is a 936 summary: 938 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 939 uma-token-bearer-1.0 941 o Profile author and contact information: Thomas Hardjono 942 (hardjono@mit.edu) 944 o Updates or obsoletes: None; this profile is new. 946 o Keyword in HTTP Authorization header: "Bearer". 948 o Syntax and semantics of token data: As defined below. The token 949 data format mainly involves time-bounded permissions. 951 o Token data association: The data associated to the on-the-wire 952 token by reference and retrieved at run time by the resource 953 server through profiled use of the OAuth token introspection 954 endpoint [OAuth-introspection], as defined below. 956 o Token data processing: As defined in this section and throughout 957 Section 3 of this specification. 959 o Grant type restrictions: None. 961 o Error states: As defined below. 963 o Security and privacy considerations: As defined in this section 964 and throughout Section 3 of this specification. 966 o Binding obligations: Because this RPT profile is mandatory for 967 authorization servers to implement, binding obligations related to 968 the use of this token profile are documented in [UMA-obligations]. 970 On receiving an RPT of the "Bearer" type in an authorization header 971 from a client making an access attempt, the resource server 972 introspects the token by using the token introspection endpoint of 973 the protection API. The PAT used by the resource server to make the 974 introspection request provides resource-owner context to the 975 authorization server. 977 The authorization server responds with a JSON object with the 978 structure dictated by [OAuth-introspection]. If the valid property 979 has a "true" value, then the JSON object MUST also contain an 980 extension property with the name "permissions" that contains an array 981 of zero or more values, each of which is an object consisting of 982 these properties: 984 resource_set_id REQUIRED. A string that uniquely identifies the 985 resource set, access to which has been granted to this client on 986 behalf of this requesting party. The identifier MUST correspond 987 to a resource set that was previously registered as protected. 989 scopes REQUIRED. An array referencing one or more URIs of scopes to 990 which access was granted for this resource set. Each scope MUST 991 correspond to a scope that was registered by this resource server 992 for the referenced resource set. 994 expires_at REQUIRED. Integer timestamp, measured in the number of 995 seconds since January 1 1970 UTC, indicating when this permission 996 will expire. 998 issued_at OPTIONAL. Integer timestamp, measured in the number of 999 seconds since January 1 1970 UTC, indicating when this permission 1000 was originally issued. 1002 Example: 1004 HTTP/1.1 200 OK 1005 Content-Type: application/json 1006 Cache-Control: no-store 1008 { 1009 "valid": true, 1010 "expires_at": "1256953732", 1011 "issued_at": "1256912345", 1012 "permissions": [ 1013 { 1014 "resource_set_id": "112210f47de98100", 1015 "scopes": [ 1016 "http://photoz.example.com/dev/actions/view", 1017 "http://photoz.example.com/dev/actions/all" 1018 ], 1019 "expires_at" : "1256923456" 1020 } 1021 ] 1022 } 1024 3.4. Client Seeks Authorization for Access 1026 In order to access a protected resource successfully, a client needs 1027 to present a valid RPT with sufficient authorization data for access. 1028 To get to this stage requires a number of previously successful 1029 steps: 1031 1. The authorization server issues client credentials to the client. 1032 It is OPTIONAL for the client credentials to be provided 1033 dynamically through [DynClientReg]; alternatively, they MAY use a 1034 static process. 1036 2. The client acquires an AAT. 1038 3. The client uses the authorization API to acquire an RPT. See 1039 Section 3.4.1 for more detail. 1041 4. The client uses the authorization API to ask for authorization, 1042 providing the permission ticket it got from the resource server. 1043 The authorization server associates authorization data with the 1044 client's RPT based on the permission ticket, the resource owner's 1045 operative policies, and the results of any claims-gathering 1046 flows. See Section 3.4.2 for more detail. 1048 3.4.1. Client Obtains RPT 1050 The client might need an RPT if it has never before requested an RPT 1051 for this combination of requesting party, resource server, and 1052 authorization server, or if it has lost control of a previously 1053 issued RPT and needs a refreshed one. It obtains an RPT by using the 1054 authorization API, performing a POST on the RPT endpoint and 1055 supplying its AAT in the header. No body is expected; if a body is 1056 present, the authorization server MAY ignore it. 1058 Example of a request message containing an AAT: 1060 POST /rpt HTTP/1.1 1061 Host: as.example.com 1062 Authorization: Bearer jwfLG53^sad$#f 1063 ... 1065 The authorization server responds with an HTTP 201 (Created) status 1066 code and provides a new RPT. 1068 For example: 1070 HTTP/1.1 201 Created 1071 Content-Type: application/json 1073 { 1074 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1075 } 1077 If the AAT provided in the header is the same as one provided for a 1078 previously issued still-valid RPT by this authorization server, the 1079 authorization server invalidates the old RPT and issues a new one. 1081 On first issuance, the RPT is associated with no authorization data 1082 and thus does not convey any authorizations for access. 1084 3.4.2. Client Asks for Authorization Data 1086 Once in possession of an AAT for this authorization server, an RPT 1087 that applies to this requesting party for this resource server and 1088 this authorization server, and a permission ticket, the client uses 1089 the authorization API to ask the authorization server to give it 1090 suitable authorization data for the sought-for access. It performs a 1091 POST on the authorization request endpoint, supplying its own AAT in 1092 the header and its RPT and the permission ticket in a JSON object 1093 with properties "rpt" and "ticket", respectively. 1095 Example of a request message containing an AAT, an RPT, and a 1096 permission ticket: 1098 POST /authz_request HTTP/1.1 1099 Host: as.example.com 1100 Authorization: Bearer jwfLG53^sad$#f 1101 ... 1103 { 1104 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1105 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1106 } 1108 The authorization server uses the ticket to look up the details of 1109 the previously registered requested permission, maps the requested 1110 permission to operative resource owner policies based on the resource 1111 set identifier and scopes in it, undergoes any claims-gathering flows 1112 required (see Section 3.5), and ultimately responds to the request. 1113 The resource owner's policies at the authorization server amount to 1114 an implicit authorization grant in governing the issuance of 1115 authorization data. (The authorization server is also free to enable 1116 the resource owner to set policies that require the owner to provide 1117 a run-time authorization grant in the form of a consent interaction, 1118 mediated by the authorization server. This setting of policies and 1119 gathering of consent is outside the scope of this specification.) 1121 The authorization server MUST base the addition of authorization data 1122 to RPTs on user policies. The nature of these policies is outside 1123 the scope of UMA, but generally speaking, they can be thought of as 1124 either independent of requesting-party features (for example, 1125 dictating access based on time of day or client identity) or 1126 dependent on requesting-party features (for example, dictating access 1127 based on whether they are over 18 or present a certain identifier). 1128 Such requesting-party features can potentially be collected in a 1129 claims-gathering flow. 1131 Once the authorization server associates authorization data with the 1132 RPT, it responds with an HTTP 201 (Created) status code. If the 1133 authorization server chooses to invalidate the original RPT in 1134 response to the request and to issue a new one to be associated with 1135 the resulting authorization data, it MUST provide that refreshed RPT 1136 in the body. 1138 Example when the authorization data has been added and the RPT has 1139 been refreshed: 1141 HTTP/1.1 201 Created 1142 Content-Type: application/json 1144 { 1145 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1146 } 1148 If the authorization server does not add the requested authorization 1149 data, it responds using the appropriate HTTP status code and UMA 1150 error code (see Section 4.2): 1152 invalid_ticket The provided ticket was not found at the 1153 authorization server. The authorization server responds with the 1154 HTTP 400 (Bad Request) status code. 1156 expired_ticket The provided ticket has expired. The authorization 1157 server responds with the HTTP 400 (Bad Request) status code. 1159 not_authorized_permission The client is definitively not authorized 1160 for this authorization according to user policy. The 1161 authorization server responds with the HTTP 403 (Forbidden) status 1162 code. 1164 need_claims The authorization server is unable to determine whether 1165 the client is authorized for this permission without gathering 1166 requesting party claims. The authorization server responds with 1167 the HTTP 403 (Forbidden) status code. The client is therefore not 1168 authorized, but has the opportunity to engage in a requesting 1169 party claims-gathering flow (see Section 3.5) to continue seeking 1170 authorization. 1172 Example when the ticket has expired: 1174 HTTP/1.1 400 Bad Request 1175 Content-Type: application/json 1176 Cache-Control: no-store 1177 ... 1179 { 1180 "error": "expired_ticket" 1181 } 1183 3.5. Claims-Gathering Flows 1185 The authorization server has a variety of options for coming into 1186 possession of claims in order to satisfy the resource owner's policy; 1187 this specification does not dictate a single answer. For example, 1188 the authorization server could interact with the requesting party to 1189 gather claims, or could accept claims delivered by a client, or could 1190 perform a lookup in some external system. The process for requesting 1191 and providing claims is extensible and can have a variety of 1192 dependencies on the type of requesting party (for example, natural 1193 person or legal person) and the type of client (for example, browser, 1194 native app, or autonomously running web service). 1196 This specification provides a required framework for extensibility 1197 through profiling. The authorization server MAY support any number 1198 of claim profiles, and SHOULD document the claim profiles it supports 1199 in its configuration data. For the business-level and legal 1200 implications of different claim profiles, see [UMA-obligations]. 1201 Optional claim profiles are defined in [UMAclaims]. 1203 A client is operated by an end-user in one of two typical situations: 1205 o The requesting party is a natural person (for example, a friend or 1206 family member of the resource owner); the requesting party may 1207 even be the resource owner herself. 1209 o The requesting party is a legal person such as a corporation, and 1210 the end-user operating the client is acting as an agent of that 1211 legal person (for example, a customer support specialist 1212 representing a credit card company). 1214 Where a claim profile dictates end-user interaction, a further 1215 variety of options is possible. The end-user could be required to 1216 register for and/or log in to an account or personal profile, or fill 1217 in a questionnaire, or complete a purchase. Several of these 1218 operations could even be required, where the order is treated as 1219 significant for evaluating resource owner policies. 1221 4. Error Messages 1223 Ultimately the resource server is responsible for either granting the 1224 access the client attempted, or returning an error response to the 1225 client with a reason for the failure. [OAuth2] defines several error 1226 responses for a resource server to return. UMA makes use of these 1227 error responses, but requires the resource server to "outsource" the 1228 determination of some error conditions to the authorization server. 1229 This specification defines additional UMA-specific error responses 1230 that the authorization server may give to the resource server and 1231 client as they interact with it, and that the resource server may 1232 give to the client. 1234 4.1. OAuth Error Responses 1236 When a resource server or client attempts to access one of the 1237 authorization server endpoints or a client attempts to access a 1238 protected resource at the resource server, it has to make an 1239 authenticated request by including an OAuth access token in the HTTP 1240 request as described in [OAuth2] Section 7.2. 1242 If the request failed authentication, the authorization server or the 1243 resource server responds with an OAuth error message as described 1244 throughout Section 2 and Section 3. 1246 4.2. UMA Error Responses 1248 When a resource server or client attempts to access one of the 1249 authorization server endpoints or a client attempts to access a 1250 protected resource at the resource server, if the request is 1251 successfully authenticated by OAuth means, but is invalid for another 1252 reason, the authorization server or resource server responds with an 1253 UMA error response by adding the following properties to the entity 1254 body of the HTTP response: 1256 error REQUIRED. A single error code. Values for this property are 1257 defined throughout this specification. 1259 error_description OPTIONAL. Human-readable text providing 1260 additional information. 1262 error_uri OPTIONAL. A URI identifying a human-readable web page 1263 with information about the error. 1265 The following is a common error code that applies to several UMA- 1266 specified request messages: 1268 invalid_request The request is missing a required parameter, 1269 includes an invalid parameter value, includes a parameter more 1270 than once, or is otherwise malformed. The authorization server 1271 MUST respond with the HTTP 400 (Bad Request) status code. 1273 For example: 1275 HTTP/1.1 400 Bad Request 1276 Content-Type: application/json 1277 Cache-Control: no-store 1278 ... 1280 { 1281 "error": "invalid_request", 1282 "error_description": "There is already a resource with this identifier.", 1283 "error_uri": "http://as.example.com/errors/resource_exists" 1284 } 1286 5. Profiles for API Extensibility 1288 In some circumstances, it is desirable to couple UMA roles tightly. 1289 For example, an authorization server application might also need to 1290 act as a client application in order to retrieve protected resources 1291 so that it can present to resource owners a dashboard-like user 1292 interface that accurately guides the setting of policy; it might need 1293 to access itself-as-authorization server for that purpose. For 1294 another example, the same organization might operate both an 1295 authorization server and a resource server that communicate only with 1296 each other behind a firewall, and it might seek more efficient 1297 communication methods between them. 1299 This section defines profiles that allow inter-role communications 1300 channels and methods to vary in these specific circumstances. This 1301 specification still REQUIRES authorization servers to issue PATs, 1302 AATs, and RPTs and associate authorization data with RPTs, and 1303 REQUIRES resource servers to give clients access only when RPTs are 1304 associated with sufficient authorization data. This is because, 1305 although tokens might not always appear on the wire in the normal 1306 fashion in these cases, they represent binding obligations that might 1307 involve additional parties unable to take part in these optimization 1308 opportunities (see [UMA-obligations]). 1310 In circumstances where alternate communications channels are being 1311 used between independently implemented system entities, it is 1312 RECOMMENDED, for reasons of implementation interoperability, to 1313 define concrete extension profiles that build on these extensibility 1314 profiles (see Section 6.1). 1316 An authorization server using any of the opportunities afforded by 1317 the protection and/or authorization API extensibility profile MUST 1318 declare use of each profile by supplying the relevant 1319 "uma_profiles_supported" values in its configuration data (see 1320 Section 1.4). 1322 5.1. Protection API Extensibility Profile 1324 This section defines a profile for UMA where the authorization server 1325 and resource server roles either reside in the same system entity or 1326 otherwise have a privileged communications channel between them. 1327 Following is a summary: 1329 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 1330 prot-ext-1.0 1332 o Profile author and contact information: Mark Dobrinic 1333 (mdobrinic@cozmanova.com) 1335 o Updates or obsoletes: None; this profile is new. 1337 o Security considerations: If the entities do not use TLS but 1338 communicate across a transport layer as opposed to using internal 1339 same-entity communication, it is STRONGLY RECOMMENDED to use an 1340 alternate means of transport-layer security. 1342 o Privacy considerations: If the relationship between the roles is 1343 established in a manner that does not involve the resource owner 1344 at all, they each may maliciously leverage this relationship to 1345 observe the resource owner's personally identifiable information 1346 held in each system. 1348 o Error states: See below. 1350 o Binding obligations: Any applicable binding obligations are 1351 documented in [UMA-obligations]. 1353 Using this profile, the resource server MAY use means other than the 1354 TLS- and OAuth-protected HTTP-based protection API to communicate 1355 with the authorization server. This involves the following 1356 opportunities: 1358 o A PAT MAY be issued without requiring an OAuth flow to establish 1359 one. 1361 o Resource sets MAY be registered (or configured) without requiring 1362 explicit use of the resource set registration endpoint or 1363 presentation of a PAT in any registration request. 1365 o Registration of requested permissions MAY be accomplished without 1366 requiring explicit use of the permission registration endpoint or 1367 presentation of a PAT in any registration request. 1369 o RPT introspection MAY be accomplished without requiring explicit 1370 use of the token introspection endpoint or presentation of a PAT 1371 in any introspection request. 1373 o Error states MAY arise and be reported in a different fashion from 1374 any HTTP-, OAuth-, and UMA-defined errors related to the 1375 protection API. 1377 An authorization server using any of the opportunities afforded by 1378 this profile MUST declare use of this profile by supplying the "prot- 1379 ext-1.0" value for one of its "uma_profiles_supported" values in its 1380 configuration data (see Section 1.4). 1382 5.2. Authorization API Extensibility Profile 1384 This section defines a profile for UMA where the authorization server 1385 and client roles either reside in the same system entity or otherwise 1386 have a privileged communications channel between them. Following is 1387 a summary: 1389 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 1390 authz-ext-1.0 1392 o Profile author and contact information: Mark Dobrinic 1393 (mdobrinic@cozmanova.com) 1395 o Updates or obsoletes: None; this profile is new. 1397 o Security considerations: If the entities do not use TLS but 1398 communicate across a transport layer as opposed to using internal 1399 same-entity communication, it is STRONGLY RECOMMENDED to use an 1400 alternate means of transport-layer security. 1402 o Privacy considerations: If the relationship between the roles is 1403 established in a manner that does not involve the requesting party 1404 at all, they each may maliciously leverage this relationship to 1405 observe the requesting party's personally identifiable information 1406 held in each system. 1408 o Error states: See below. 1410 o Binding obligations: Any applicable binding obligations are 1411 documented in [UMA-obligations]. 1413 Using this profile, the resource server MAY use means other than the 1414 TLS- and OAuth-protected HTTP-based authorization API to communicate 1415 with the authorization server. This involves the following 1416 opportunities: 1418 o An AAT MAY be issued without requiring an OAuth flow to establish 1419 one. 1421 o An RPT MAY be issued without requiring explicit use of the RPT 1422 endpoint or presentation of an AAT in any RPT request. 1424 o Authorization data MAY be associated with the RPT without 1425 requiring explicit use of the authorization request endpoint or 1426 presentation of an AAT, RPT, or ticket in any request. 1428 o The client MAY use alternate means of initating a claims-gathering 1429 flow with the authorization server. (Any further profiling of 1430 this profile might involve a claim profile as well; see 1431 Section 6.3.) 1433 o Error states MAY arise and be reported in a different fashion from 1434 any HTTP-, OAuth-, and UMA-defined errors related to the 1435 authorization API. 1437 An authorization server using any of the opportunities afforded by 1438 this profile MUST declare use of this profile by supplying the 1439 "authz-ext-1.0" value for one of its "uma_profiles_supported" values 1440 in its configuration data (see Section 1.4). 1442 5.3. Resource Interface Extensibility Profile 1444 This section defines a profile for UMA where the resource server and 1445 client roles either reside in the same system entity or otherwise 1446 have a privileged communications channel between them. Following is 1447 a summary: 1449 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/ 1450 rsrc-ext-1.0 1452 o Profile author and contact information: Mark Dobrinic 1453 (mdobrinic@cozmanova.com) 1455 o Updates or obsoletes: None; this profile is new. 1457 o Security considerations: If the entities do not use TLS but 1458 communicate across a transport layer as opposed to using internal 1459 same-entity communication, it is STRONGLY RECOMMENDED to use an 1460 alternate means of transport-layer security. 1462 o Privacy considerations: If the relationship between the roles is 1463 established in a manner that does not involve the authorization 1464 server at all, they each may maliciously leverage this 1465 relationship to observe the resource owner's or requesting party's 1466 personally identifiable information held in each system. 1468 o Error states: See below. 1470 o Binding obligations: Any applicable binding obligations are 1471 documented in [UMA-obligations]. 1473 Using this profile, the resource server MAY use means other than an 1474 HTTP-based resource interface to communicate with the authorization 1475 server. This involves the following opportunities: 1477 o Resource access attempts MAY be accomplished without requiring 1478 explicit use of the HTTP-based endpoint or presentation of an RPT. 1480 o Error states MAY arise and be reported in a different fashion from 1481 any HTTP-, OAuth-, and UMA-defined errors related to the protected 1482 resource's interface. 1484 An authorization server involved in deployments where resource 1485 servers and clients are known to be using opportunities afforded by 1486 the resource interface extensibility profile MAY declare use of this 1487 profile by supplying the "rsrc-ext-1.0" value for one of its 1488 "uma_profiles_supported" values in its configuration data (see 1489 Section 1.4). 1491 6. Specifying Additional Profiles 1493 This specification defines a protocol that has optional features. 1494 For implementation interoperability and to serve particular 1495 deployment scenarios, including sector-specific ones such as 1496 healthcare or e-government, third parties may want to define profiles 1497 of UMA that restrict these options. 1499 Further, this specification creates extensibility points for RPT 1500 profiles and claim profiles, and third parties may likewise want to 1501 define their own. Different RPT profiles could be used, for example, 1502 to change the dividing line between authorization server and resource 1503 server responsibilities in controlling access. Different claim 1504 profiles could be used to customize sector-specific or population- 1505 specific (such as individual vs. employee) claim types that drive the 1506 types of policies resource owners could set. 1508 It is not practical for this specification to standardize all desired 1509 profiles. However, to serve overall interoperability goals, the 1510 following sections provide guidelines for third parties that wish to 1511 specify UMA-related profiles. 1513 6.1. Specifying Profiles of UMA 1515 It is RECOMMENDED that profiles of UMA document the following 1516 information: 1518 1. Specify a URI that uniquely identifies the profile. 1520 2. Identify the responsible author and provide postal or electronic 1521 contact information. 1523 3. Supply references to previously defined profiles that the profile 1524 updates or obsoletes. 1526 4. Specify the set of interactions between endpoint entites involved 1527 in the profile, calling out any restrictions on ordinary UMA- 1528 conformant operations and any extension properties used in 1529 message formats. 1531 5. Identify the legally responsible parties involved in each 1532 interaction and any new obligations imposed, in the fashion of 1533 [UMA-obligations]. 1535 6. Define any additional or changed error states. 1537 7. Supply any additional security and privacy considerations, 1538 including analysis of threats and description of countermeasures. 1540 8. Specify any conformance considerations. 1542 See Section 5 for examples. 1544 6.2. Specifying RPT Profiles 1546 It is RECOMMENDED that RPT profiles document the following 1547 information: 1549 1. Specify a URI that uniquely identifies the token profile. 1551 2. Identify the responsible author and provide postal or electronic 1552 contact information. 1554 3. Supply references to previously defined token profiles that the 1555 token profile updates or obsoletes. 1557 4. Specify the keyword to be used in HTTP Authorization headers 1558 with tokens conforming to this profile. 1560 5. Specify the syntax and semantics of the data that the 1561 authorization server associates with the token. 1563 6. Specify how the token data is associated with, contained within, 1564 and/or retrieved by means of, the on-the-wire token string. 1566 7. Specify processing rules for token data. 1568 8. Identify any restrictions on grant types to be used with the 1569 token profile. 1571 9. Define any additional or changed error states. 1573 10. Supply any additional security and privacy considerations. 1575 11. Specify any obligations specific to the token profile, in the 1576 fashion of [UMA-obligations]. 1578 12. Specify any conformance considerations. 1580 See Section 3.3.2 for an example. 1582 6.3. Specifying Claim Profiles 1584 In addition to any requirements listed in Section 3.5, it is 1585 RECOMMENDED that claim profiles document the following information: 1587 1. Specify a URI that uniquely identifies the claim profile. 1589 2. Identify the responsible author and provide postal or electronic 1590 contact information. 1592 3. Supply references to previously defined claim profiles that the 1593 claim profile updates or obsoletes. 1595 4. Specify the syntax and semantics of claim data and requests for 1596 claim data. 1598 5. Specify how an authorization server gathers the claims. 1600 6. Define any additional or changed error states. 1602 7. Supply any additional security and privacy considerations. 1604 8. Specify any obligations specific to the claim profile, in the 1605 fashion of [UMA-obligations]. 1607 9. Specify any conformance considerations. 1609 See [UMAclaims] for examples. 1611 7. Security Considerations 1613 This specification relies mainly on OAuth security mechanisms as well 1614 as transport-level encryption for protecting the protection and 1615 authorization API endpoints. Most PATs and AATs are likely to use 1616 OAuth bearer tokens. See [OAuth-threat] for more information. 1618 This specification defines a number of JSON-based data formats. As a 1619 subset of the JavaScript scripting language, JSON data SHOULD be 1620 consumed through a process that does not dynamically execute it as 1621 code, to avoid malicious code execution. One way to achieve this is 1622 to use a JavaScript interpreter rather than the built-in JavaScript 1623 eval() function. 1625 The issue of impersonation is a crucial aspect in UMA, particularly 1626 when entities are wielding bearer tokens that preclude proof-of- 1627 possession (of a secret or a cryptographic key). As such, one way to 1628 mitigate this risk is for the resource owner to require stronger 1629 claims to accompany any access request. For example, consider the 1630 case where Alice sets policies at the authorization server governing 1631 access to her resources by Bob. When Bob first seeks access and must 1632 obtain an RPT (for which the default RPT profile specifies a bearer 1633 token), Alice could set policies demanding that Bob prove his 1634 identity by providing a set of strong claims issued by a trusted 1635 attribute provider in order to get authorization data associated with 1636 that token. 1638 Another issue concerns the use of the [OAuth2] implicit flow. In 1639 this case, Bob will have exposure to the token, and may maliciously 1640 pass the token to an unauthorized party. To mitigate this weakness 1641 and others, we recommend considering the following steps: 1643 o Require that the Requesting Party (as defined in 1644 [UMA-obligations], meaning this party is able to take on legal 1645 obligations) legitimately represent the wielder of the bearer 1646 token. This solution is based on a legal or contractual approach, 1647 and therefore does not reduce the risk from the technical 1648 perspective. 1650 o The authorization server, possibly with input from the resource 1651 owner, can implement tighter time-to-live strategies around the 1652 authorization data in RPTs. This is a classic approach with 1653 bearer tokens that helps to limit a malicious party's ability to 1654 intercept and use the bearer token. In the same vein, the 1655 authorization server could require claims to have a reasonable 1656 degree of freshness (which would require a custom claims profile). 1658 o The strongest strategy is to disallow bearer-type RPTs within the 1659 UMA profile being deployed, by providing or requiring an RPT 1660 profile that requires use of a holder-of-key approach. In this 1661 way, the wielder of the token must engage in a live session for 1662 proof-of-possession. 1664 For information about the additional technical, operational, and 1665 legal elements of trust establishment between UMA entities and 1666 parties, which affects security considerations, see 1667 [UMA-obligations]. 1669 8. Privacy Considerations 1671 The authorization server comes to be in possession of resource set 1672 information (such as names and icons) that may reveal information 1673 about the resource owner, which the authorization server's trust 1674 relationship with the resource server is assumed to accommodate. 1675 However, the client is a less-trusted party -- in fact, entirely 1676 untrustworthy until authorization data is associated with its RPT. 1677 This specification depends on [OAuth-resource-reg], which recommends 1678 obscuring resource set identifiers in order to avoid leaking 1679 personally identifiable information to clients through the scope 1680 mechanism. 1682 For information about the technical, operational, and legal elements 1683 of trust establishment between UMA entities and parties, which 1684 affects privacy considerations, see [UMA-obligations]. 1686 Additional considerations related to Privacy by Design concepts are 1687 discussed in [UMA-PbD]. 1689 9. Conformance 1691 This section outlines conformance requirements for various entities 1692 implementing UMA endpoints. 1694 This specification has dependencies on other specifications, as 1695 referenced under the normative references listed in this 1696 specification. Its dependencies on some specifications, such as 1697 OpenID Connect ([OIDCCore]), are optional depending on whether the 1698 feature in question is used in the implementation. 1700 The authorization server's configuration data provides a machine- 1701 readable method for it to indicate certain of the conformance options 1702 it supports. Several of the configuration data properties allow for 1703 indicating extension features. Where this specification does not 1704 already require optional features to be documented, it is RECOMMENDED 1705 that authorization server developers and deployers document any 1706 profiled or extended features explicitly and use configuration data 1707 to indicate their usage. See Section 1.4 for information about 1708 providing and extending the configuration data. 1710 10. IANA Considerations 1712 This document makes no request of IANA. 1714 11. Acknowledgments 1716 The current editor of this specification is Thomas Hardjono of MIT. 1717 The following people are co-authors: 1719 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 1721 o Domenico Catalano, Oracle Corp. 1723 o Mark Dobrinic, Cozmanova 1725 o George Fletcher, AOL 1727 o Maciej Machulak, Cloud Identity Ltd 1729 o Eve Maler, ForgeRock 1731 o Lukasz Moren, Cloud Identity Ltd 1733 o Christian Scholz, COMlounge GmbH (former editor) 1735 o Mike Schwartz, Gluu 1737 o Jacek Szpot, Newcastle University 1739 Additional contributors to this specification include the Kantara UMA 1740 Work Group participants, a list of whom can be found at 1741 [UMAnitarians]. 1743 12. Issues 1745 Issues are captured at the project's GitHub site ([1]). 1747 13. References 1749 13.1. Normative References 1751 [DynClientReg] 1752 Richer, J., "OAuth 2.0 Core Dynamic Client Registration", 1753 July 2014, 1754 . 1756 [OAuth-bearer] 1757 "The OAuth 2.0 Authorization Framework: Bearer Token 1758 Usage", October 2012, 1759 . 1761 [OAuth-introspection] 1762 Richer, J., "OAuth Token Introspection", July 2014, 1763 . 1766 [OAuth-resource-reg] 1767 Hardjono, T., "OAuth 2.0 Resource Set Registration", July 1768 2014, . 1771 [OAuth-threat] 1772 Lodderstedt, T., "OAuth 2.0 Threat Model and Security 1773 Considerations", January 2013, 1774 . 1776 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 1777 October 2012, . 1779 [OIDCCore] 1780 Sakimura, N., "OpenID Connect Core 1.0", February 2014, 1781 . 1783 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1784 Requirement Levels", BCP 14, RFC 2119, March 1997. 1786 [RFC4627] Crockford, D., "The application/json Media Type for 1787 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1789 [UMA-obligations] 1790 Maler, E., "Binding Obligations on UMA Participants", 1791 January 2013, . 1794 [UMAclaims] 1795 Catalano, D., "Claim Profiles for User-Managed Access 1796 (UMA)", July 2014, . 1799 [hostmeta] 1800 Hammer-Lahav, E., "Web Host Metadata", October 2011, 1801 . 1803 13.2. Informative References 1805 [OAuth-SAML] 1806 Campbell, B., "SAML 2.0 Bearer Assertion Profiles for 1807 OAuth 2.0", April 2014, . 1810 [OAuth-linktypes] 1811 Mills, W., "Link Type Registrations for OAuth 2", February 1812 2013, 1813 . 1815 [OAuth-meta] 1816 Sakimura, N., "JSON Metadata for OAuth Responses", 1817 November 2013, 1818 . 1820 [UMA-PbD] Maler, B., "Privacy by Design Implications of UMA", 1821 December 2013, 1822 . 1825 [UMA-casestudies] 1826 Maler, E., "UMA Case Studies", April 2014, 1827 . 1830 [UMA-usecases] 1831 Maler, E., "UMA Scenarios and Use Cases", October 2010, 1832 . 1835 [UMAnitarians] 1836 Maler, E., "UMA Participant Roster", July 2014, 1837 . 1840 13.3. URIs 1842 [1] https://github.com/xmlgrrl/UMA-Specifications/issues 1844 [2] http://kantarainitiative.org/confluence/display/uma/ 1845 UMA+1.0+Core+Protocol 1847 Appendix A. Document History 1849 NOTE: To be removed by RFC editor before publication as an RFC. 1851 See [2] for a list of code-breaking and other major changes made to 1852 this specification at various revision points. 1854 Author's Address 1856 Thomas Hardjono (editor) 1857 MIT 1859 Email: hardjono@mit.edu