idnits 2.17.1 draft-hardjono-oauth-umacore-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 7 characters in excess of 72. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. 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 (January 5, 2015) is 3392 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 2164 -- Looks like a reference, but probably isn't: '2' on line 2173 -- Possible downref: Non-RFC (?) normative reference: ref. 'DynClientReg' ** Obsolete normative reference: RFC 7159 (ref. 'JSON') (Obsoleted by RFC 8259) == Outdated reference: A later version (-11) exists of draft-ietf-oauth-introspection-04 -- 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' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDCDynClientReg' ** Downref: Normative reference to an Informational RFC: RFC 6711 -- No information found for draft-uma-trust - is the name correct? Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 8 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 E. Maler 5 Expires: July 9, 2015 ForgeRock 6 M. Machulak 7 Cloud Identity 8 D. Catalano 9 Oracle 10 January 5, 2015 12 User-Managed Access (UMA) Profile of OAuth 2.0 13 draft-hardjono-oauth-umacore-11 15 Abstract 17 User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how 18 resource owners can control protected-resource access by clients 19 operated by arbitrary requesting parties, where the resources reside 20 on any number of resource servers, and where a centralized 21 authorization server governs access based on resource owner policies. 22 This revision of the specification is part of the UMA "candidate 23 V1.0" process. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on July 9, 2015. 42 Copyright Notice 44 Copyright (c) 2015 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 6 61 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 62 1.3. Achieving Distributed Access Control . . . . . . . . . . 8 63 1.3.1. Protection API . . . . . . . . . . . . . . . . . . . 8 64 1.3.2. Authorization API . . . . . . . . . . . . . . . . . . 9 65 1.3.3. Protected Resource Interface . . . . . . . . . . . . 10 66 1.3.4. Time-to-Live Considerations . . . . . . . . . . . . . 11 67 1.4. Authorization Server Configuration Data . . . . . . . . . 11 68 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 14 69 3. Getting Authorization and Accessing a Resource . . . . . . . 15 70 3.1. Client Attempts to Access Protected Resource . . . . . . 17 71 3.1.1. Client Presents No RPT . . . . . . . . . . . . . . . 17 72 3.1.2. Client Presents RPT . . . . . . . . . . . . . . . . . 18 73 3.2. Resource Server Registers Requested Permission With 74 Authorization Server . . . . . . . . . . . . . . . . . . 19 75 3.3. Resource Server Determines RPT's Status . . . . . . . . . 21 76 3.3.1. Token Introspection . . . . . . . . . . . . . . . . . 21 77 3.3.2. RPT Profile: Bearer . . . . . . . . . . . . . . . . . 21 78 3.4. Client Seeks Authorization for Access . . . . . . . . . . 23 79 3.4.1. Client Requests Authorization Data . . . . . . . . . 24 80 3.4.1.1. Authentication Context Flows . . . . . . . . . . 27 81 3.4.1.2. Claims-Gathering Flows . . . . . . . . . . . . . 28 82 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 33 83 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 33 84 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 33 85 5. Profiles for API Extensibility . . . . . . . . . . . . . . . 34 86 5.1. Protection API Extensibility Profile . . . . . . . . . . 35 87 5.2. Authorization API Extensibility Profile . . . . . . . . . 36 88 5.3. Resource Interface Extensibility Profile . . . . . . . . 37 89 6. Specifying Additional Profiles . . . . . . . . . . . . . . . 38 90 6.1. Specifying Profiles of UMA . . . . . . . . . . . . . . . 39 91 6.2. Specifying RPT Profiles . . . . . . . . . . . . . . . . . 39 92 6.3. Specifying Claim Token Format Profiles . . . . . . . . . 39 93 7. Compatibility Notes . . . . . . . . . . . . . . . . . . . . . 40 94 8. Security Considerations . . . . . . . . . . . . . . . . . . . 40 95 8.1. Redirection and Impersonation Threats . . . . . . . . . . 40 96 8.2. Client Authentication . . . . . . . . . . . . . . . . . . 42 97 8.3. JSON Usage . . . . . . . . . . . . . . . . . . . . . . . 42 98 8.4. Profiles, Binding Obligations, and Trust Establishment . 42 99 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 42 100 10. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 43 101 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 102 11.1. JSON Web Token Claims Registration . . . . . . . . . . . 44 103 11.1.1. Registry Contents . . . . . . . . . . . . . . . . . 44 104 11.2. Well-Known URI Registration . . . . . . . . . . . . . . 44 105 11.2.1. Registry Contents . . . . . . . . . . . . . . . . . 44 106 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 107 13. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 108 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 109 14.1. Normative References . . . . . . . . . . . . . . . . . . 45 110 14.2. Informative References . . . . . . . . . . . . . . . . . 46 111 14.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 47 112 Appendix A. Document History . . . . . . . . . . . . . . . . . . 47 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 115 1. Introduction 117 User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2]. UMA 118 defines how resource owners can control protected-resource access by 119 clients operated by arbitrary requesting parties, where the resources 120 reside on any number of resource servers, and where a centralized 121 authorization server governs access based on resource owner policies. 122 Resource owners configure authorization servers with access policies 123 that serve as asynchronous authorization grants. 125 UMA serves numerous use cases where a resource owner uses a dedicated 126 service to manage authorization for access to their resources, 127 potentially even without the run-time presence of the resource owner. 128 A typical example is the following: a web user (an end-user resource 129 owner) can authorize a web or native app (a client) to gain one-time 130 or ongoing access to a protected resource containing his home address 131 stored at a "personal data store" service (a resource server), by 132 telling the resource server to respect access entitlements issued by 133 his chosen cloud-based authorization service (an authorization 134 server). The requesting party operating the client might be the 135 resource owner, where the app is run by an e-commerce company that 136 needs to know where to ship a purchased item, or the requesting party 137 might be resource owner's friend who is using an online address book 138 service to collect contact information, or the requesting party might 139 be a survey company that uses an autonomous web service to compile 140 population demographics. A variety of use cases can be found in 141 [UMA-usecases] and [UMA-casestudies]. 143 Practical control of access among loosely coupled parties requires 144 more than just messaging protocols. This specification defines only 145 the "technical contract" between UMA-conforming entities; a companion 146 specification, [UMA-obligations], additionally discusses expected 147 behaviors of parties operating and using these entities. Parties 148 operating entities that claim to be UMA-conforming should provide 149 documentation of any rights and obligations between and among them, 150 especially as they pertain the concepts and clauses discussed in this 151 companion specification. 153 In enterprise settings, application access management sometimes 154 involves letting back-office applications serve only as policy 155 enforcement points (PEPs), depending entirely on access decisions 156 coming from a central policy decision point (PDP) to govern the 157 access they give to requesters. This separation eases auditing and 158 allows policy administration to scale in several dimensions. UMA 159 makes use of a separation similar to this, letting the resource owner 160 serve as a policy administrator crafting authorization strategies for 161 resources under their control. 163 In order to increase interoperable communication among the 164 authorization server, resource server, and client, UMA defines two 165 purpose-built APIs related to the outsourcing of authorization, 166 themselves protected by OAuth (or an OAuth-based authentication 167 protocol) in embedded fashion. 169 The UMA protocol has three broad phases, as shown in Figure 1. 171 The Three Phases of the UMA Profile of OAuth 173 +--------------+ 174 | resource | 175 +---------manage (A)------------ | owner | 176 | +--------------+ 177 | Phase 1: | 178 | protect a control (C) 179 | resource | 180 v v 181 +------------+ +----------+--------------+ 182 | | |protection| | 183 | resource | | API | authorization| 184 | server |<-protect (B)--| (needs | server | 185 | | | PAT) | | 186 +------------+ +----------+--------------+ 187 | protected | | authorization| 188 | resource | | API | 189 |(needs RPT) | | (needs AAT) | 190 +------------+ +--------------+ 191 ^ | 192 | Phases 2 and 3: authorize (D) 193 | get authorization, | 194 | access a resource v 195 | +--------------+ 196 +---------access (E)-------------| client | 197 +--------------+ 199 requesting party 201 Figure 1 203 The phases work as follows: 205 Protect a resource (Described in Section 2.) The resource owner, 206 who manages online resources at the resource server ("A"), 207 introduces it to the authorization server so that the latter can 208 begin protecting the resources. To accomplish this, the 209 authorization server presents a protection API ("B") to the 210 resource server. This API is protected by OAuth (or an OAuth- 211 based authentication protocol) and requires a protection API token 212 (PAT) for access. Out of band, the resource owner configures the 213 authorization server with policies associated with the resource 214 sets ("C") that the resource registers for protection. 216 Get authorization (Described in Section 3.) The client approaches 217 the resource server seeking access to an UMA-protected resource. 218 In order to access it successfully, the client must first use the 219 authorization server's authorization API ("D") to obtain 220 authorization data and a requesting party token (RPT) on behalf of 221 its requesting party, and the requesting party may need to supply 222 identity claims. The API is protected by OAuth (or an OAuth-based 223 authentication protocol) and requires an authorization API token 224 (AAT) for access. 226 Access a resource (Described in Section 3.) The client successfully 227 presents to the resource server an RPT that has sufficient 228 authorization data associated with it, gaining access to the 229 desired resource ("E"). Phase 3 is effectively the "success path" 230 embedded within phase 2. 232 Implementers have the opportunity to develop profiles (see Section 6) 233 that specify and restrict various UMA protocol, RPT, and identity 234 claim format options, according to deployment and usage conditions. 236 1.1. Notational Conventions 238 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 239 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 240 document are to be interpreted as described in [RFC2119]. 242 Unless otherwise noted, all protocol properties and values are case 243 sensitive. JSON [JSON] data structures defined by this specification 244 MAY contain extension properties that are not defined in this 245 specification. Any entity receiving or retrieving a JSON data 246 structure SHOULD ignore extension properties it is unable to 247 understand. Extension names that are unprotected from collisions are 248 outside the scope of this specification. 250 1.2. Terminology 252 UMA introduces the following new terms and enhancements of OAuth term 253 definitions. 255 resource owner 256 An OAuth resource owner that is the "user" in User-Managed 257 Access. This is typically an end-user (a natural person) but 258 it can also be a corporation or other legal person. 260 policy The configuration parameters of an authorization server that 261 effect resource access management. Authorization policies 262 typically include elements similar to parts of speech; for 263 example, "subjects" describe those seeking access (requesting 264 parties and clients), "verbs" describe operational scopes of 265 access, and "objects" describe targeted resource sets. Policy 266 configuration takes place between the resource owner and the 267 authorization server, and thus is out of band of UMA. 269 requesting party 270 An end-user, or a corporation or other legal person, that uses 271 a client to seek access to a protected resource. The 272 requesting party may or may not be the same party as the 273 resource owner. 275 client 276 An application making protected resource requests with the 277 resource owner's authorization and on the requesting party's 278 behalf. 280 claim 281 A statement of the value or values of one or more identity 282 attributes of a requesting party. A requesting party may need 283 to provide claims to an authorization server in order to gain 284 permission for access to a protected resource. 286 resource set One or more protected resources that the resource 287 server manages as a set, abstractly. In authorization policy 288 terminology, a resource set is the "object" being protected. 289 This term derives from [OAuth-resource-reg]. 291 scope A bounded extent of access that is possible to perform on a 292 resource set. In authorization policy terminology, a scope is 293 one of the potentially many "verbs" that can logically apply to 294 a resource set ("object"). UMA associates scopes with labeled 295 resource sets. 297 authorization data Data associated with an RPT that enables some 298 combination of the authorization server and resource server to 299 determine the correct extent of access to allow to a client. 300 Authorization data is a key part of the definition of an RPT 301 profile. 303 permission A scope of access over a particular resource set at a 304 particular resource server that is being requested by, or 305 granted to, a requesting party. In authorization policy 306 terminology, a permission is an entitlement that includes a 307 "subject" (requesting party), "verbs" (one or more scopes of 308 access), and an "object" (resource set). A permission is one 309 example of authorization data that an authorization server may 310 add to a requesting party token. 312 permission ticket A correlation handle that is conveyed from an 313 authorization server to a resource server, from a resource 314 server to a client, and ultimately from a client back to an 315 authorization server, to enable the authorization server to 316 assess the correct policies to apply to a request for 317 authorization data. 319 token A packaged collection of data meant to be transmitted to 320 another entity. A token could be used for authorized access 321 (an "access token" such as an UMA RPT, PAT, or AAT), or could 322 be used to exchange information about a subject (a "claim 323 token" such as one that is conveyed by a client to an 324 authorization server while seeking authorization data). 326 1.3. Achieving Distributed Access Control 328 The software components that fill the roles of UMA authorization 329 servers, resource servers, and clients respectively are intended to 330 work in an interoperable fashion when each is operated by an 331 independent party (for example, different organizations). For this 332 reason, UMA specifies communications channels that the authorization 333 server MUST implement as HTTP-based APIs that MUST use TLS and OAuth 334 (or OAuth-based authentication protocol) protection, and that the 335 resource server MUST implement as an HTTP-based interface. UMA's use 336 of TLS is governed by Section 1.6 of [OAuth2], which discusses 337 deployment and adoption characteristics of different TLS versions. 339 For those OAuth protection use cases where an identity token is 340 desired in addition to an access token, it is RECOMMENDED that an 341 OAuth-based authentication protocol such as OpenID Connect be used. 343 It is also REQUIRED, in turn, for resource servers and clients on the 344 requesting side of UMA interactions to use these channels, unless a 345 profile is being used that enables API extensibility. The profiles 346 that enable such alternatives are provided in Section 5. 348 1.3.1. Protection API 350 The authorization server MUST present an HTTP-based protection API, 351 protected by TLS and OAuth (or an OAuth-based authentication 352 protocol), for use by resource servers. The authorization server 353 thus has an OAuth token endpoint and authorization endpoint. The 354 authorization server MUST declare all of its protection API endpoints 355 in its configuration data (see Section 1.4). 357 The protection API consists of three endpoints: 359 o Resource set registration endpoint as defined by 360 [OAuth-resource-reg] 362 o Permission registration endpoint as defined by Section 3.2 364 o Token introspection endpoint as defined by [OAuth-introspection] 365 and Section 3.3.1 367 An entity seeking protection API access MUST have the scope 368 "uma_protection". An access token with at least this scope is called 369 a protection API token (PAT) and an entity that can acquire an access 370 token with this scope is by definition a resource server. A single 371 entity can serve in both resource server and client roles if it has 372 access tokens with the appropriate OAuth scopes. If a request to an 373 endpoint fails due to an invalid, missing, or expired PAT, or 374 requires higher privileges at this endpoint than provided by the PAT, 375 the authorization server responds with an OAuth error. 377 The authorization server MUST support the OAuth bearer token profile 378 for PAT issuance, and MAY support other OAuth token profiles. It 379 MUST declare all supported token profiles and grant types for PAT 380 issuance in its configuration data. Any OAuth authorization grant 381 type might be appropriate depending on circumstances; for example, 382 the client credentials grant is useful in the case of an organization 383 acting as a resource owner. [UMA-Impl] discusses grant options 384 further. 386 A PAT binds a resource owner, a resource server the owner uses for 387 resource management, and an authorization server the owner uses for 388 protection of resources at this resource server. It is not specific 389 to any client or requesting party. The issuance of a PAT represents 390 the approval of the resource owner for this resource server to use 391 this authorization server for protecting some or all of the resources 392 belonging to this resource owner. 394 1.3.2. Authorization API 396 The authorization server MUST present an HTTP-based authorization 397 API, protected by TLS and OAuth (or an OAuth-based authentication 398 protocol), for use by clients. The authorization server thus has an 399 OAuth token endpoint and authorization endpoint. The authorization 400 server MUST declare its authorization API endpoint in its 401 configuration data (see Section 1.4). 403 The authorization API consists of one endpoint: 405 o RPT endpoint as defined in Section 3.4.1 407 An entity seeking authorization API access MUST have the scope 408 "uma_authorization". An access token with at least this scope is 409 called an authorization API token (AAT) and an entity that can 410 acquire an access token with this scope is by definition a client. A 411 single entity can serve in both resource server and client roles if 412 it has access tokens with the appropriate OAuth scopes. If a request 413 to an endpoint fails due to an invalid, missing, or expired AAT, or 414 requires higher privileges at this endpoint than provided by the AAT, 415 the authorization server responds with an OAuth error. 417 The authorization server MUST support the OAuth bearer token profile 418 for AAT issuance, and MAY support other OAuth token profiles. It 419 MUST declare all supported token profiles and grant types for AAT 420 issuance in its configuration data. Any OAuth authorization grant 421 type might be appropriate depending on circumstances; for example, 422 the client credentials grant is useful in the case of an organization 423 acting as a requesting party. [UMA-Impl] discusses grant options 424 further. 426 An AAT binds a requesting party, a client being used by that party, 427 and an authorization server that protects resources this client is 428 seeking access to on this requesting party's behalf. It is not 429 specific to any resource server or resource owner. The issuance of 430 an AAT represents the approval of this requesting party for this 431 client to engage with this authorization server to supply claims, ask 432 for authorization, and perform any other tasks needed for obtaining 433 authorization for access to resources at all resource servers that 434 use this authorization server. The authorization server is able to 435 manage future processes of authorization and claims-caching 436 efficiently for this client/requesting party pair across all resource 437 servers they try to access; however, these management processes are 438 outside the scope of this specification. 440 1.3.3. Protected Resource Interface 442 The resource server MAY present to clients whatever HTTP-based APIs 443 or endpoints it wishes. To protect any of its resources available in 444 this fashion using UMA, it MUST require a requesting party token 445 (RPT) with sufficient authorization data for access. 447 This specification defines one RPT profile, call "bearer" (see 448 Section 3.3.2), which the authorization server MUST support. It MAY 449 support additional RPT profiles, and MUST declare all supported RPT 450 profiles in its configuration data (see Section 1.4). 452 An RPT binds a requesting party, the client being used by that party, 453 the resource server at which protected resources of interest reside, 454 and the authorization server that protects those resources. It is 455 not specific to a single resource owner, though its internal 456 components are likely to be bound in practice to individual resource 457 owners, depending on the RPT profile in use. 459 1.3.4. Time-to-Live Considerations 461 The authorization server has the opportunity to manage the validity 462 periods of access tokens that it issues, their corresponding refresh 463 tokens where applicable, the individual authorization data components 464 associated with RPTs where applicable, and even the client 465 credentials that it issues. Different time-to-live strategies may be 466 suitable for different resource sets and scopes of access, and the 467 authorization server has the opportunity to give the resource owner 468 control over lifetimes of tokens and authorization data issued on 469 their behalf through policy. These options are all outside the scope 470 of this specification. 472 1.4. Authorization Server Configuration Data 474 The authorization server MUST provide configuration data in a JSON 475 document that resides in an /uma-configuration directory at its host- 476 meta [hostmeta] location. The configuration data documents 477 conformance options and endpoints supported by the authorization 478 server. 480 The configuration data has the following properties. 482 version 483 REQUIRED. The version of the UMA core protocol to which this 484 authorization server conforms. The value MUST be the string 485 "1.0". 487 issuer 488 REQUIRED. A URI with no query or fragment component that the 489 authorization server asserts as its issuer identifier. This 490 value MUST be identical to the web location of the 491 configuration data minus the host-meta [hostmeta] and /uma- 492 configuration path components 494 pat_profiles_supported 495 REQUIRED. OAuth access token types supported by this 496 authorization server for PAT issuance. The property value is 497 an array of string values, where each string value (which MAY 498 be a URI) is a token type. Non-URI token type strings defined 499 by OAuth token-defining specifications are privileged. For 500 example, the type "bearer" stands for the OAuth bearer token 501 type defined in [OAuth-bearer]. The authorization server is 502 REQUIRED to support "bearer", and to supply this value 503 explicitly. The authorization server MAY declare its support 504 for additional PAT profiles. 506 aat_profiles_supported 507 REQUIRED. OAuth access token types supported by this 508 authorization server for AAT issuance. The property value is 509 an array of string values, where each string value (which MAY 510 be a URI) is a token type. Non-URI token type strings defined 511 by OAuth token-defining specifications are privileged. For 512 example, the type "bearer" stands for the OAuth bearer token 513 type defined in [OAuth-bearer]. The authorization server is 514 REQUIRED to support "bearer", and to supply this value 515 explicitly. The authorization server MAY declare its support 516 for additional AAT profiles. 518 rpt_profiles_supported 519 REQUIRED. Profiles supported by this authorization server for 520 RPT issuance. The property value is an array of string values, 521 where each string value is a URI identifying an RPT profile. 522 The authorization server is REQUIRED to support the "bearer" 523 RPT profile defined in Section 3.3.2, and to supply its 524 identifying URI explicitly. The authorization server MAY 525 declare its support for additional RPT profiles. 527 pat_grant_types_supported 528 REQUIRED. OAuth grant types supported by this authorization 529 server in issuing PATs. The property value is an array of 530 string values, where each string value (which MAY be a URI) is 531 a grant type. Non-URI token type strings defined by OAuth 532 grant type-defining specifications are privileged. For 533 example, the type "authorization_code" stands for the OAuth 534 authorization code grant type defined in [OAuth2]. 536 aat_grant_types_supported 537 REQUIRED. OAuth grant types supported by this authorization 538 server in issuing AATs. The property value is an array of 539 string values, where each string value (which MAY be a URI) is 540 a grant type. Non-URI token type strings defined by OAuth 541 grant type-defining specifications are privileged. For 542 example, the type "authorization_code" stands for the OAuth 543 authorization code grant type defined in [OAuth2]. 545 claim_token_profiles_supported 546 OPTIONAL. Claim token format profiles supported by this 547 authorization server. The property value is an array of string 548 values, where each string value MAY be a URI. 550 uma_profiles_supported 551 OPTIONAL. UMA profiles supported by this authorization server. 552 The property value is an array of string values, where each 553 string value is a URI identifying an UMA profile. Examples of 554 UMA profiles are the API extensibility profiles defined in 555 Section 5. 557 dynamic_client_endpoint 558 OPTIONAL. The endpoint to use for performing dynamic client 559 registration in the case of the use of [DynClientReg], or 560 alternatively the reserved string "openid" in the case of the 561 use of [OIDCDynClientReg]. In the latter case, it is presumed 562 that the resource server or client will discover the dynamic 563 client registration endpoint from the authorization server's 564 published OpenID Provider Configuration Information. The 565 presence of this property indicates authorization server 566 support for dynamic client registration feature; its absence 567 indicates a lack of support. 569 token_endpoint 570 REQUIRED. The endpoint URI at which the resource server or 571 client asks the authorization server for a PAT or AAT. A 572 requested scope of "uma_protection" results in a PAT. A 573 requested scope of "uma_authorization" results in an AAT. 574 Usage of this endpoint is defined by [OAuth2]. 576 authorization_endpoint 577 REQUIRED. The endpoint URI at which the resource server 578 gathers the consent of the end-user resource owner or the 579 client gathers the consent of the end-user requesting party for 580 issuance of a PAT or AAT respectively, if the 581 "authorization_code" grant type is used. Usage of this 582 endpoint is defined by [OAuth2]. 584 requesting_party_claims_endpoint 585 OPTIONAL. The endpoint URI at which the authorization server 586 interacts with the end-user requesting party to gather claims. 587 If this property is absent, the authorization server does not 588 interact with the end-user requesting party for claims 589 gathering. 591 introspection_endpoint 592 REQUIRED. The endpoint URI at which the resource server 593 introspects an RPT presented to it by a client. Usage of this 594 endpoint is defined by [OAuth-introspection] and Section 3.3.1. 595 A valid PAT MUST accompany requests to this protected endpoint. 597 resource_set_registration_endpoint 598 REQUIRED. The endpoint URI at which the resource server 599 registers resource sets to put them under authorization manager 600 protection. Usage of this endpoint is defined by 602 [OAuth-resource-reg] and Section 2. A valid PAT MUST accompany 603 requests to this protected endpoint. 605 permission_registration_endpoint 606 REQUIRED. The endpoint URI at which the resource server 607 registers a requested permission that would suffice for a 608 client's access attempt. Usage of this endpoint is defined by 609 Section 3.2. A valid PAT MUST accompany requests to this 610 protected endpoint. 612 rpt_endpoint 613 REQUIRED. The endpoint URI at which the client asks for 614 authorization data. Usage of this endpoint is defined in 615 Section 3.4. A valid AAT and a permission ticket MUST, and an 616 RPT MAY, accompany requests to this protected endpoint. 618 Example of authorization server configuration data that resides at 619 https://example.com/.well-known/uma-configuration (note the use of 620 https: for endpoints throughout): 622 { 623 "version":"1.0", 624 "issuer":"https://example.com", 625 "pat_profiles_supported":["bearer"], 626 "aat_profiles_supported":["bearer"], 627 "rpt_profiles_supported": 628 ["https://docs.kantarainitiative.org/uma/profiles/uma-token-bearer-1.0"], 629 "pat_grant_types_supported":["authorization_code"], 630 "aat_grant_types_supported":["authorization_code"], 631 "claim_token_profiles_supported":["https://example.com/claims/formats/token1"], 632 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", 633 "token_endpoint":"https://as.example.com/token_uri", 634 "authorization_endpoint":"https://as.example.com/authz_uri", 635 "requesting_party_claims_endpoint":"https://as.example.com/rqp_claims_uri", 636 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri", 637 "introspection_endpoint":"https://as.example.com/rs/status_uri", 638 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri", 639 "rpt_endpoint":"https://as.example.com/client/rpt_uri" 640 } 642 2. Protecting a Resource 644 The resource owner, resource server, and authorization server perform 645 the following actions to put resources under protection. This list 646 assumes that the resource server has discovered the authorization 647 server's configuration data and endpoints as needed. 649 1. The authorization server issues client credentials to the 650 resource server. It is OPTIONAL for the client credentials to be 651 provided dynamically through [DynClientReg] or 652 [OIDCDynClientReg]; alternatively, they MAY use a static process. 654 2. The resource server acquires a PAT from the authorization server. 655 It is OPTIONAL for the resource owner to introduce the resource 656 server to the authorization server dynamically (for example, 657 through a "NASCAR"-style user interface where the resource owner 658 selects a chosen authorization server); alternatively, they MAY 659 use a static process that may or may not directly involve the 660 resource owner at introduction time. 662 3. In an ongoing fashion, the resource server registers any resource 663 sets with the authorization server for which it intends to 664 outsource protection, using the resource set registration 665 endpoint of the protection API (see [OAuth-resource-reg]). 667 Note: The resource server is free to offer the option to protect any 668 subset of the resource owner's resources using different 669 authorization servers or other means entirely, or to protect some 670 resources and not others. Additionally, the choice of protection 671 regimes can be made explicitly by the resource owner or implicitly by 672 the resource server. Any such partitioning by the resource server or 673 owner is outside the scope of this specification. 675 Once a resource set has been placed under authorization server 676 protection through the registration of a resource set description for 677 it, and until such a description's deletion by the resource server, 678 the resource server MUST limit access to corresponding resources, 679 requiring sufficient authorization data associated with client- 680 presented RPTs by the authorization server (see Section 3.1.2). 682 3. Getting Authorization and Accessing a Resource 684 An authorization server orchestrates and controls clients' access (on 685 their requesting parties' behalf) to a resource owner's protected 686 resources at a resource server, under conditions dictated by that 687 resource owner. 689 The process of getting authorization and accessing a resource always 690 begins with the client attempting access at a protected resource 691 endpoint at the resource server. How the client came to learn about 692 this endpoint is out of scope for this specification. The resource 693 owner might, for example, have advertised its availability publicly 694 on a blog or other website, listed it in a discovery service, or 695 emailed a link to a particular intended requesting party. 697 The resource server responds to the client's access request with 698 whatever its application-specific resource interface defines as a 699 success response, either immediately if the client has sufficient 700 authorization, or having first performed one or more embedded 701 interactions with the authorization server and client in the case of 702 a failed access attempt. 704 A high-level summary of the interactions is as follows. The 705 recipient of each request message SHOULD respond unless it detects a 706 security concern, such as a suspected denial of service attack that 707 can be mitigated by rate limiting. 709 o The client attempts to access a protected resource. 711 * If the access attempt is unaccompanied by an RPT, the resource 712 server registers a requested permission at the authorization 713 server that would suffice for the access attempt, and then 714 responds with an HTTP 403 (Forbidden) response, a permission 715 ticket, and instructions on where to go to obtain an RPT and 716 authorization data. 718 * If the access attempt is accompanied by an RPT, the resource 719 server checks the RPT's status. 721 + If the RPT is invalid, or if the RPT is valid but has 722 insufficient authorization data, the resource server 723 registers a requested permission at the authorization server 724 that would suffice for the access attempt, and then responds 725 with an HTTP 403 (Forbidden) response, a permission ticket, 726 and instructions on where to go to obtain a valid RPT and 727 authorization data for it. 729 + If the RPT is valid, and if the authorization data 730 associated with the token is sufficient for allowing access, 731 the resource server responds with an HTTP 2xx (Success) 732 response. 734 o If the client received a 403 response and a permission ticket, it 735 asks the authorization server for authorization data that matches 736 the ticket using the RPT endpoint of the authorization API. If 737 the authorization server needs requesting party claims in order to 738 assess this client's authorization, it engages in a claims- 739 gathering flow. 741 * If the client does not already have an AAT at the appropriate 742 authorization server to be able to use its authorization API, 743 it first obtains one. 745 The interactions are described in detail in the following sections. 747 3.1. Client Attempts to Access Protected Resource 749 This interaction assumes that the resource server has previously 750 registered one or more resource sets that correspond to the resource 751 the client is attempting to access. 753 The client attempts to access a protected resource (for example, when 754 an end-user requesting party clicks on a thumbnail representation of 755 the resource to retrieve a larger version). It is expected to 756 discover, or be provisioned or configured with, knowledge of the 757 protected resource and its location out of band. Further, the client 758 is expected to acquire its own knowledge about the application- 759 specific methods made available by the resource server for operating 760 on this protected resource (such as viewing it with a GET method, or 761 transforming it with some complex API call). 763 The access attempt either is or is not accompanied by an RPT. 765 3.1.1. Client Presents No RPT 767 Example of a request carrying no RPT: 769 GET /album/photo.jpg HTTP/1.1 770 Host: photoz.example.com 771 ... 773 If the client does not present an RPT with the request, the resource 774 server uses the protection API to register a requested permission 775 with the authorization server that would suffice for the access 776 attempt (see Section 3.2), and receives a permission ticket back in 777 response. It then responds to the client. It SHOULD respond with 778 the HTTP 403 (Forbidden) status code, providing the authorization 779 server's URI in an "as_uri" property in the header, along with the 780 just-received permission ticket in the body in a JSON-encoded 781 "ticket" property. Responses that use any code other than 403 are 782 undefined by this specification; any common or best practices for 783 returning other status codes will be documented in the [UMA-Impl]. 785 For example: 787 HTTP/1.1 403 Forbidden 788 WWW-Authenticate: UMA realm="example", 789 as_uri="https://as.example.com" 791 { 792 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 793 } 794 ... 796 3.1.2. Client Presents RPT 798 Example of a request carrying an RPT using the UMA "bearer" RPT 799 profile: 801 GET /album/photo.jpg HTTP/1.1 802 Authorization: Bearer vF9dft4qmT 803 Host: photoz.example.com 804 ... 806 If the client presents an RPT with its request, the resource server 807 MUST determine the RPT's status (see Section 3.3) before responding. 809 If the RPT is invalid, or if the RPT is valid but has insufficient 810 authorization data for the type of access sought, the resource server 811 uses the protection API to register a requested permission with the 812 authorization server that would suffice for the access attempt (see 813 Section 3.2), and receives a permission ticket back in response. It 814 then responds to the client with the HTTP 403 (Forbidden) status 815 code, providing the authorization server's URI in an "as_uri" 816 property in the header, along with the just-received permission 817 ticket in the body in a JSON-encoded "ticket" property. 819 Example of the resource server's response after having registered a 820 requested permission and received a ticket: 822 HTTP/1.1 403 Forbidden 823 WWW-Authenticate: UMA realm="example", 824 as_uri="https://as.example.com" 825 error="insufficient_scope" 827 { 828 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 829 } 830 If the RPT's status is associated with authorization data that is 831 sufficient for the access sought by the client, the resource server 832 MUST give access to the desired resource. 834 Example of the resource server's response after having determined 835 that the RPT is valid and associated with sufficient authorization 836 data: 838 HTTP/1.1 200 OK 839 Content-Type: image/jpeg 840 ... 842 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 843 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 844 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 845 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 847 The resource server MUST NOT give access where the token's status is 848 not associated with sufficient authorization data for the attempted 849 scope of access. 851 3.2. Resource Server Registers Requested Permission With Authorization 852 Server 854 The resource server uses the protection API's permission registration 855 endpoint to register a requested permission with the authorization 856 server that would suffice for the client's access attempt. The 857 authorization server returns a permission ticket for the resource 858 server to give to the client in its response. The PAT provided in 859 the API request implicitly identifies the resource owner ("subject") 860 to which the permission applies. 862 Note: The resource server is free to choose the extent of the 863 requested permission that it registers, as long as it minimally 864 suffices for the access attempted by the client. For example, it can 865 choose to register a permission that covers several scopes or a 866 resource set that is greater in extent than the specific resource 867 that the client attempted to access. 869 The resource server uses the POST method at the endpoint. The body 870 of the HTTP request message contains a JSON object providing the 871 requested permission, using a format derived from the scope 872 description format specified in [OAuth-resource-reg], as follows. 873 The object has the following properties: 875 resource_set_id REQUIRED. The identifier for a resource set to 876 which this client is seeking access. The identifier MUST 877 correspond to a resource set that was previously registered. 879 scopes REQUIRED. An array referencing one or more identifiers of 880 scopes to which access is needed for this resource set. Each 881 scope identifier MUST correspond to a scope that was registered by 882 this resource server for the referenced resource set. 884 Example of an HTTP request that registers a requested permission at 885 the authorization server's permission registration endpoint, with a 886 PAT in the header: 888 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 889 Content-Type: application/json 890 Host: as.example.com 891 Authorization: Bearer 204c69636b6c69 893 { 894 "resource_set_id": "112210f47de98100", 895 "scopes": [ 896 "http://photoz.example.com/dev/actions/view", 897 "http://photoz.example.com/dev/actions/all" 898 ] 899 } 901 If the registration request is successful, the authorization server 902 responds with an HTTP 201 (Created) status code and includes the 903 "ticket" property in the JSON-formatted body. 905 The permission ticket is a short-lived opaque structure whose form is 906 determined by the authorization server. The ticket value MUST be 907 securely random (for example, not merely part of a predictable 908 sequential series), to avoid denial-of-service attacks. Since the 909 ticket is an opaque structure from the point of view of the client, 910 the authorization server is free to include information regarding 911 expiration time or any other information within the opaque ticket for 912 its own consumption. When the client subsequently uses the 913 authorization API to ask the authorization server for authorization 914 data to be associated with its RPT, it will submit this ticket to the 915 authorization server. 917 For example: 919 HTTP/1.1 201 Created 920 Content-Type: application/json 921 ... 923 { 924 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 925 } 926 If the registration request is authenticated properly but fails due 927 to other reasons, the authorization server responds with an HTTP 400 928 (Bad Request) status code and includes one of the following UMA error 929 codes (see Section 4.2): 931 invalid_resource_set_id The provided resource set identifier was not 932 found at the authorization server. 934 invalid_scope At least one of the scopes included in the request was 935 not registered previously by this resource server. 937 3.3. Resource Server Determines RPT's Status 939 The resource server MUST determine a received RPT's status, including 940 both whether it is active and, if so, its associated authorization 941 data, before giving or refusing access to the client. An RPT is 942 associated with a set of authorization data that governs whether the 943 client is authorized for access. The token's nature and format are 944 dictated by its profile; the profile might allow it to be self- 945 contained, such that the resource server is able to determine its 946 status locally, or might require or allow the resource server to make 947 a run-time introspection request of the authorization server that 948 issued the token. 950 This specification makes one type of RPT REQUIRED for the 951 authorization server to support: the UMA bearer token profile, as 952 defined in Section 3.3.2. Implementers MAY define and use other RPT 953 profiles. 955 3.3.1. Token Introspection 957 Within any RPT profile, when a resource server needs to introspect a 958 token in a non-self-contained way to determine its status, it MAY 959 require, allow, or prohibit use of the OAuth token introspection 960 endpoint (defined by [OAuth-introspection]) that is part of the 961 protection API, and MAY profile its usage. The resource server MUST 962 use the POST method in interacting with the endpoint, not the GET 963 method also defined by [OAuth-introspection]. 965 3.3.2. RPT Profile: Bearer 967 This section defines the UMA bearer token profile. Following is a 968 summary: 970 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 971 uma-token-bearer-1.0 973 o Profile author and contact information: Thomas Hardjono 974 (hardjono@mit.edu) 976 o Updates or obsoletes: None; this profile is new. 978 o Keyword in HTTP Authorization header: "Bearer". 980 o Syntax and semantics of token data: As defined below; an extended 981 JSON Web Token (JWT) format. The token data format mainly 982 involves time-bounded permissions. 984 o Token data association: The on-the-wire token is opaque; it is 985 introspected at run time by the resource server through profiled 986 use of the OAuth token introspection endpoint 987 [OAuth-introspection], as defined below. 989 o Token data processing: As defined in this section and throughout 990 Section 3 of this specification. 992 o Grant type restrictions: None. 994 o Error states: As defined below. 996 o Security and privacy considerations: As defined in this section, 997 throughout Section 3, and in Section 8. 999 On receiving an RPT with the "Bearer" scheme in an authorization 1000 header from a client making an access attempt, the resource server 1001 introspects the token by using the token introspection endpoint of 1002 the protection API. The PAT used by the resource server to make the 1003 introspection request provides resource-owner context to the 1004 authorization server. 1006 The authorization server responds with a JSON object with the 1007 structure dictated by [OAuth-introspection]. If the "active" 1008 property has a Boolean value of true, then the JSON object MUST NOT 1009 contain a "scope" claim, and MUST contain an extension property with 1010 the name "permissions" that contains an array of zero or more values, 1011 each of which is an object consisting of these properties: 1013 resource_set_id REQUIRED. A string that uniquely identifies the 1014 resource set, access to which has been granted to this client on 1015 behalf of this requesting party. The identifier MUST correspond 1016 to a resource set that was previously registered as protected. 1018 scopes REQUIRED. An array referencing one or more URIs of scopes to 1019 which access was granted for this resource set. Each scope MUST 1020 correspond to a scope that was registered by this resource server 1021 for the referenced resource set. 1023 exp OPTIONAL. Integer timestamp, measured in the number of seconds 1024 since January 1 1970 UTC, indicating when this permission will 1025 expire. If the property is absent, the permission does not 1026 expire. If the token-level "exp" value pre-dates a permission- 1027 level "exp" value, the former overrides the latter. 1029 iat OPTIONAL. Integer timestamp, measured in the number of seconds 1030 since January 1 1970 UTC, indicating when this permission was 1031 originally issued. If the token-level "iat" value post-dates a 1032 permission-level "iat" value, the former overrides the latter. 1034 nbf OPTIONAL. Integer timestamp, measured in the number of seconds 1035 since January 1 1970 UTC, indicating the time before which this 1036 permission is not valid. If the token-level "nbf" value post- 1037 dates a permission-level "nbf" value, the former overrides the 1038 latter. 1040 Example: 1042 HTTP/1.1 200 OK 1043 Content-Type: application/json 1044 Cache-Control: no-store 1046 { 1047 "active": true, 1048 "exp": 1256953732, 1049 "iat": 1256912345, 1050 "permissions": [ 1051 { 1052 "resource_set_id": "112210f47de98100", 1053 "scopes": [ 1054 "http://photoz.example.com/dev/actions/view", 1055 "http://photoz.example.com/dev/actions/all" 1056 ], 1057 "exp" : 1256953732 1058 } 1059 ] 1060 } 1062 3.4. Client Seeks Authorization for Access 1064 In order to access a protected resource successfully, a client needs 1065 to present a valid RPT with sufficient authorization data for access. 1066 To get to this stage requires a number of previously successful 1067 steps: 1069 1. The authorization server issues client credentials to the client. 1070 It is OPTIONAL for the client credentials to be provided 1071 dynamically through [DynClientReg] or [OIDCDynClientReg]; 1072 alternatively, they MAY use a static process. 1074 2. The client acquires an AAT. 1076 3. The client uses the authorization API to acquire an RPT and to 1077 ask for authorization data, providing the permission ticket it 1078 got from the resource server. The authorization server 1079 associates authorization data with the RPT based on the 1080 permission ticket, the resource owner's operative policies, and 1081 the results of any claims-gathering flows. 1083 3.4.1. Client Requests Authorization Data 1085 Once in possession of a permission ticket and an AAT for this 1086 authorization server, the client asks the authorization server to 1087 give it authorization data corresponding to that permission ticket. 1088 It performs a POST on the RPT endpoint, supplying its own AAT in the 1089 header and a JSON object in the body with a "ticket" property 1090 containing the ticket as its value. 1092 If the client had included an RPT in its failed access attempt, It 1093 MAY also provide that RPT in an "rpt" property in its request to the 1094 authorization server. 1096 In circumstances where the client needs to provide requesting party 1097 claims to the authorization server, it MAY also include a 1098 "claim_tokens" property in its request; see Section 3.4.1.2.1 for 1099 more information. 1101 Example of a request message containing an AAT, an RPT, and a 1102 permission ticket: 1104 POST /authz_request HTTP/1.1 1105 Host: as.example.com 1106 Authorization: Bearer jwfLG53^sad$#f 1107 ... 1109 { 1110 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1111 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1112 } 1114 The authorization server uses the ticket to look up the details of 1115 the previously registered requested permission, maps the requested 1116 permission to operative resource owner policies based on the resource 1117 set identifier and scopes associated with it, potentially requests 1118 additional information, and ultimately responds positively or 1119 negatively to the request for authorization data. 1121 The authorization server bases the issuing of authorization data on 1122 resource owner policies. These policies thus amount to an 1123 asynchronous OAuth authorization grant. The authorization server is 1124 also free to enable the resource owner to set policies that require 1125 the owner to interact with the server in near-real time to provide 1126 consent subsequent to an access attempt. All such processes are 1127 outside the scope of this specification. 1129 Once the authorization server adds the requested authorization data, 1130 it returns an HTTP 200 (OK) status code with a response body 1131 containing the RPT with which it associates the requested 1132 authorization data. If the client did not present an RPT in the 1133 request for authorization data, the authorization server creates and 1134 returns a new RPT. If the client did present an RPT in the request, 1135 the authorization server returns the RPT with which it associated the 1136 requested authorization data, which MAY be either the RPT that was in 1137 the request or a new one. Note: It is entirely an implementation 1138 issue whether the returned RPT is the same one that appeared in the 1139 request or a new RPT, and it is also an implementation issue whether 1140 the AS chooses to invalidate or retain the validity of the original 1141 RPT or any authorization data that was previously added to that RPT; 1142 to assist in client interoperability and token caching expectations, 1143 it is RECOMMENDED that authorization servers document their 1144 practices. [UMA-Impl] discusses the implications. 1146 Example: 1148 HTTP/1.1 200 OK 1149 Content-Type: application/json 1151 { 1152 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1153 } 1155 If the authorization server does not add the requested authorization 1156 data, it responds using one of the following UMA error codes and 1157 corresponding HTTP status codes (see Section 4.2): 1159 invalid_ticket The provided ticket was not found at the 1160 authorization server. The authorization server responds with the 1161 HTTP 400 (Bad Request) status code. 1163 expired_ticket The provided ticket has expired. The authorization 1164 server responds with the HTTP 400 (Bad Request) status code. 1166 not_authorized The client is not authorized to have this 1167 authorization data added. The authorization server responds with 1168 the HTTP 403 (Forbidden) status code. 1170 need_info The authorization server needs additional information in 1171 order to determine whether the client is authorized to have this 1172 authorization data. The authorization server responds with the 1173 HTTP 403 (Forbidden) status code. It MAY also respond with an 1174 "error_details" object that contains one or more sub-properties 1175 with hints about the nature of further required information. The 1176 client then has the opportunity to engage in follow-on flows to 1177 continue seeking authorization, in a process sometimes referred as 1178 "trust elevation". This specification defines two nonexclusive 1179 "error_details" sub-properties: "authentication_context", 1180 described in Section 3.4.1.1, and "requesting_party_claims", 1181 described in Section 3.4.1.2. 1183 request_submitted The authorization server requires intervention by 1184 the resource owner to determine whether the client is authorized 1185 to have this authorization data. Further immediate interaction 1186 between the client and authorization server is out of scope of 1187 this specification. 1189 Example when the ticket has expired: 1191 HTTP/1.1 400 Bad Request 1192 Content-Type: application/json 1193 Cache-Control: no-store 1194 ... 1196 { 1197 "error": "expired_ticket" 1198 } 1199 Example of a "need_info" response with a full set of "error_details" 1200 hints: 1202 HTTP/1.1 403 Forbidden 1203 Content-Type: application/json 1204 Cache-Control: no-store 1205 ... 1207 { 1208 "error": "need_info", 1209 "error_details": { 1210 "authentication_context": { 1211 "required_acr": ["https://example.com/acrs/LOA3.14159"] 1212 }, 1213 "requesting_party_claims": { 1214 "required_claims": [ 1215 { 1216 "name": "email23423453ou453", 1217 "friendly_name": "email", 1218 "claim_type": "urn:oid:0.9.2342.19200300.100.1.3", 1219 "claim_token_format": 1220 ["http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken"], 1221 "issuer": ["https://example.com/idp"] 1222 } 1223 ], 1224 "redirect_user": "yes", 1225 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1226 } 1227 } 1228 } 1230 3.4.1.1. Authentication Context Flows 1232 The "authentication_context" sub-property provides hints about 1233 additional requirements regarding the requesting party's 1234 authentication that underlies the issuance of the currently valid 1235 AAT. On receiving such hints, the client has the opportunity to 1236 redirect the requesting party to the authorization server to 1237 reauthenticate in a manner anticipated to be more successful for 1238 gaining access. Such an action is sometimes referred to as "step-up" 1239 authentication. The "authentication_context" sub-property contains 1240 the following parameter: 1242 required_acr REQUIRED. An array of strings specifying a set of 1243 acceptable authentication context class reference values. Any one 1244 of the referenced authentication context classes (sets of 1245 authentication methods or procedures considered to be equivalent 1246 in a particular context) would satisfy the requesting party 1247 authentication requirements. Each string MAY be a URI, including 1248 one that has been registered through [RFC6711]. 1250 3.4.1.2. Claims-Gathering Flows 1252 The "requesting_party_claims" sub-property provides hints about 1253 additional requirements regarding information the authorization 1254 server needs about the requesting party. On receiving such hints, 1255 the client has the opportunity to engage in claims-gathering flows of 1256 various types. The "requesting_party_claims" sub-property MAY 1257 contain the following parameters, where at least one of 1258 "required_claims" or "redirect_user" MUST be supplied: 1260 required_claims An array containing objects that describe 1261 characteristics of the required claims, with the following 1262 properties: 1264 name OPTIONAL. A string (which MAY be a URI) representing the 1265 name of the claim; the "key" in a key-value pair. 1267 friendly_name OPTIONAL. A string that provides a more human- 1268 readable form of the attribute's name, which may be useful as a 1269 "display name" for use in user interfaces in cases where the 1270 actual name is complex or opaque, such as an OID or a UUID. 1272 claim_type OPTIONAL. A string, indicating the expected 1273 interpretation of the provided claim value. The string MAY be 1274 a URI. 1276 claim_token_format OPTIONAL. An array of strings specifying a 1277 set of acceptable formats for a token pushed by the client 1278 containing this claim (see Section 3.4.1.2.1). Any one of the 1279 referenced formats would satisfy the authorization server's 1280 requirements. Each string MAY be a URI. 1282 issuer OPTIONAL. An array of strings specifying a set of 1283 acceptable issuing authorities for the claim. Any one of the 1284 referenced authorities would satisfy the authorization server's 1285 requirements. Each string MAY be a URI. 1287 redirect_user A Boolean value indicating whether the requesting 1288 party's presence at the authorization server is required for the 1289 process of claims gathering. For example, the authorization 1290 server may require the requesting party to fill out a CAPTCHA to 1291 help prove humanness. The default is false if this parameter is 1292 not present. See Section 1.4 for how the authorization server 1293 declares the requesting party claims endpoint to which the client 1294 has the opportunity to redirect the requesting party. 1296 ticket The permission ticket that was in the client's request for 1297 authorization data. If the authorization server provides the 1298 "redirect_user" property, it MUST also provide the "ticket" 1299 property. This helps the client avoid maintaining this state 1300 information after the redirect. 1302 The authorization server has many options for gathering requesting 1303 party claims. For example, it could interact with an end-user 1304 requesting party directly, or accept claims delivered by a client, or 1305 perform a lookup in some external system. The process is extensible 1306 and can have dependencies on the type of requesting party (for 1307 example, natural person or legal person) or client (for example, 1308 browser, native app, or autonomously running web service). 1310 The client and authorization server have two nonexclusive claims- 1311 gathering interaction patterns: push and redirect. 1313 3.4.1.2.1. Client Pushes Claim Tokens to Authorization Server 1315 If the client is ?claims-aware? and the authorization server can 1316 accept pushed claims (for example, as it might have indicated by 1317 providing "requesting_party_claims" hints described in 1318 Section 3.4.1), the client has the option to _push_ claim tokens to 1319 the RPT endpoint. The claim token can reflect the client's role as a 1320 federated identity provider, a federated relying party, or an 1321 application integrated with a native identity repository. 1323 If the client is aware of the authorization server's requirements for 1324 claims through an out-of-band relationship, the client MAY push claim 1325 tokens in an initial interaction with the RPT endpoint. 1327 The client supplies claim tokens in the body of the authorization 1328 data request message by providing, in addition to the "rpt" and 1329 "ticket" properties, the following property: 1331 claim_tokens REQUIRED. An array of objects with the following 1332 properties: 1334 format REQUIRED. A string specifying the format of the 1335 accompanying claim tokens. The string MAY be a URI. 1337 token REQUIRED. A string containing the claim information in the 1338 indicated format, base64url encoded. If claim token format 1339 features are included that require special interpretation, the 1340 client and authorization server are assumed to have a prior 1341 relationship that establishes how to interpret these features. 1342 For example, if the referenced format equates to SAML 2.0 1343 assertions and the claim token contains audience restrictions, 1344 it is the joint responsibility of the client and authorization 1345 server to determine the proper audience values that enable 1346 successful token consumption. 1348 Example: 1350 POST /rpt_authorization HTTP/1.1 1351 Host: www.example.com 1352 Authorization: Bearer jwfLG53^sad$#f 1353 ... 1354 { 1355 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1356 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 1357 "claim_tokens": [ 1358 { 1359 "format": 1360 "http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken", 1361 "token": "..." 1362 } 1363 ] 1364 } 1366 This specification provides a framework for extensibility through 1367 claim token format profiling. The authorization server MAY support 1368 any number of claim token profiles, and SHOULD document the claim 1369 token profiles it supports in its configuration data. 1371 3.4.1.2.2. Client Redirects Requesting Party to Authorization Server 1373 If the client is ?claims-unaware? and the authorization server has 1374 declared a requesting party claims endpoint in its configuration 1375 data, or if the authorization server requires direct interaction with 1376 the requesting party as part of its claims-gathering process (for 1377 example, as it might have indicated through the "redirect_user" hint 1378 described in Section 3.4.1), the client has the option to _redirect_ 1379 an end-user requesting party to the requesting party claims endpoint. 1380 In this case, the authorization server might be a relying party in a 1381 federated identity interaction, or it might connect to a directory or 1382 other user repository, or even interact with the user in other ways, 1383 such as presenting a questionnaire in a web form. After this process 1384 completes, the authorization server redirects the end-user requesting 1385 party back to the client. 1387 The client constructs the request URI by adding the following 1388 parameters to the query component of the requesting party claims 1389 endpoint URI using the "application/x-www-form-urlencoded" format: 1391 client_id REQUIRED. The client's identifier issued by the 1392 authorization server. 1394 redirect_uri OPTIONAL. The URI to which the client wishes the 1395 authorization server to direct the requesting party's user agent 1396 after completing its interaction. The URI MUST be absolute, MAY 1397 contain an "application/x-www-form-urlencoded" formatted query 1398 parameter component that MUST be retained when adding addition 1399 parameters, and MUST NOT contain a fragment component. The 1400 authorization server SHOULD require all clients to register their 1401 redirection endpoint prior to utilizing the authorization 1402 endpoint. If the the URI is pre-registered, this URI MUST exactly 1403 match one of the pre-registered redirection URIs, with the 1404 matching performed as described in Section 6.2.1 of [RFC3986] 1405 (Simple String Comparison). 1407 ticket REQUIRED. The permission ticket associated with the client's 1408 current request for authorization data for this requesting party. 1409 The authorization server MUST return this parameter back to when 1410 the authorization_state is need_info. 1412 state OPTIONAL. An opaque value used by the client to maintain 1413 state between the request and callback. The authorization server 1414 includes this value when redirecting the user agent back to the 1415 client. The use of this parameter is STRONGLY RECOMMENDED for 1416 preventing cross-site request forgery. 1418 Example of a request issued by a client application (line breaks are 1419 shown only for display convenience): 1421 GET /rqp_claims?client_id=some_client_id&state=abc 1422 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect HTTP/1.1 1423 Host: as.example.com 1425 At the conclusion of its interaction with the requesting party, the 1426 authorization server returns the user agent to the client adding the 1427 following parameters to the query component of the redirection URI 1428 using the "application/x-www-form-urlencoded" format: 1430 authorization_state REQUIRED. Indicates that the authorization 1431 server completed its claims-gathering interaction with the 1432 requesting party with the indicated state: 1434 claims_submitted The client is free to return to the RPT endpoint 1435 to seek authorization data once again. 1437 not_authorized The client is not authorized to have the desired 1438 authorization data added. 1440 need_info The authorization server needs additional information 1441 in order to determine whether the client is authorized to have 1442 this authorization data. This response directs the client to 1443 return to the RPT endpoint, where it might be provided with 1444 error_details hints about additional information needed. 1446 request_submitted The authorization server requires intervention 1447 by the resource owner to determine whether authorization data 1448 can be added. Further immediate interaction between the 1449 client, requesting party, and authorization server is out of 1450 scope of this specification. 1452 ticket OPTIONAL. The same permission ticket value that the client 1453 provided in the request. It MUST be present if and only if the 1454 authorization_state is need_info. 1456 state OPTIONAL. The same state value that the client provided in 1457 the request. It MUST be present if and only if the client 1458 provided it. 1460 The client MUST ignore unrecognized response parameters. If the 1461 request fails due to a missing, invalid, or mismatching redirection 1462 URI, or if the client identifier is missing or invalid, the 1463 authorization server SHOULD inform the resource owner of the error 1464 and MUST NOT automatically redirect the user agent to the invalid 1465 redirection URI. If the request fails for reasons other than a 1466 missing or invalid redirection URI, the authorization server informs 1467 the client by adding an "error" parameter to the query component of 1468 the redirection URI using the "application/x-www-form-urlencoded" 1469 format, containing one of the following ASCII error codes: 1471 invalid_request The request is missing a required parameter, 1472 includes an invalid parameter value (such as an invalid or expired 1473 ticket), includes a parameter more than once, or is otherwise 1474 malformed. 1476 server_error The authorization server encountered an unexpected 1477 condition that prevented it from fulfilling the request. (This 1478 error code is needed because an HTTP 500 (Internal Server Error) 1479 status code cannot be returned to the client via an HTTP 1480 redirect.) 1482 temporarily_unavailable The authorization server is currently unable 1483 to handle the request due to a temporary overloading or 1484 maintenance of the server. (This error code is needed because an 1485 HTTP 503 (Service Unavailable) status code cannot be returned to 1486 the client via an HTTP redirect.) 1488 4. Error Messages 1490 Ultimately the resource server is responsible for either granting the 1491 access the client attempted, or returning an error response to the 1492 client with a reason for the failure. [OAuth2] defines several error 1493 responses for a resource server to return. UMA makes use of these 1494 error responses, but requires the resource server to "outsource" the 1495 determination of some error conditions to the authorization server. 1496 This specification defines additional UMA-specific error responses 1497 that the authorization server may give to the resource server and 1498 client as they interact with it, and that the resource server may 1499 give to the client. 1501 4.1. OAuth Error Responses 1503 When a resource server or client attempts to access one of the 1504 authorization server endpoints or a client attempts to access a 1505 protected resource at the resource server, it has to make an 1506 authenticated request by including an OAuth access token in the HTTP 1507 request as described in [OAuth2] Section 7.2. 1509 If the request failed authentication, the authorization server or the 1510 resource server responds with an OAuth error message as described in 1511 this specification in Section 3. 1513 4.2. UMA Error Responses 1515 When a resource server or client attempts to access one of the 1516 authorization server endpoints or a client attempts to access a 1517 protected resource at the resource server, if the request is 1518 successfully authenticated by OAuth means, but is invalid for another 1519 reason, the authorization server or resource server responds with an 1520 UMA error response by adding the following properties to the entity 1521 body of the HTTP response: 1523 error REQUIRED. A single error code. Values for this property are 1524 defined throughout this specification. 1526 error_description OPTIONAL. Human-readable text providing 1527 additional information. 1529 error_uri OPTIONAL. A URI identifying a human-readable web page 1530 with information about the error. 1532 The following is a common error code that applies to several UMA- 1533 specified request messages: 1535 invalid_request The request is missing a required parameter, 1536 includes an invalid parameter value, includes a parameter more 1537 than once, or is otherwise malformed. The authorization server 1538 MUST respond with the HTTP 400 (Bad Request) status code. 1540 For example: 1542 HTTP/1.1 400 Bad Request 1543 Content-Type: application/json 1544 Cache-Control: no-store 1545 ... 1547 { 1548 "error": "invalid_request", 1549 "error_description": "There is already a resource with this identifier.", 1550 "error_uri": "https://as.example.com/errors/resource_exists" 1551 } 1553 5. Profiles for API Extensibility 1555 In some circumstances, it may be desirable to couple UMA roles 1556 tightly. For example, an authorization server application might also 1557 need to act as a client application in order to retrieve protected 1558 resources so that it can present to resource owners a dashboard-like 1559 user interface that accurately guides the setting of policy; it might 1560 need to access itself-as-authorization server for that purpose. For 1561 another example, the same organization might operate both an 1562 authorization server and a resource server that communicate only with 1563 each other behind a firewall, and it might seek more efficient 1564 communication methods between them. 1566 In other circumstances, it may be desirable to bind UMA flows to 1567 transport mechanisms other than HTTP even if entities remain loosely 1568 coupled. For example, in Internet of Things scenarios, Constrained 1569 Application Protocol (CoAP) may be preferred over HTTP. 1571 This section defines profiles that allow inter-role communications 1572 channels and methods to vary in these circumstances. This 1573 specification still REQUIRES authorization servers to issue PATs, 1574 AATs, and RPTs and associate authorization data with RPTs, and 1575 REQUIRES resource servers to give clients access only when RPTs are 1576 associated with sufficient authorization data. This is because, 1577 although tokens might not always appear on the wire in the normal 1578 fashion, the tokens may represent binding obligations that involve 1579 additional parties unable to take part in these optimization 1580 opportunities (see [UMA-obligations]). 1582 Where alternate communications channels are being used between 1583 independently implemented system entities, it is RECOMMENDED, for 1584 reasons of implementation interoperability, to define concrete 1585 extension profiles that build on these extensibility profiles (see 1586 Section 6.1). 1588 5.1. Protection API Extensibility Profile 1590 This section defines a profile for UMA where the authorization server 1591 and resource server roles either reside in the same system entity or 1592 otherwise have a privileged or specialized communications channel 1593 between them. Following is a summary: 1595 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1596 prot-ext-1.0 1598 o Profile author and contact information: Mark Dobrinic 1599 (mdobrinic@cozmanova.com) 1601 o Updates or obsoletes: None; this profile is new. 1603 o Security considerations: See below. 1605 o Privacy considerations: See below. 1607 o Error states: None additional. 1609 Using this profile, the resource server MAY use means other than the 1610 HTTP-based protection API that is protected by TLS and OAuth (or an 1611 OAuth-based authentication protocol) to communicate with the 1612 authorization server in all respects, including using software 1613 interfaces and methods rather than network interfaces and APIs. The 1614 authorization server MUST still issue PATs, AATs, and RPTs and 1615 associate authorization data with RPTs, and the resource server MUST 1616 still give clients access only when RPTs are associated with 1617 sufficient authorization data. Interactions with entities other than 1618 the authorization server or resource server MUST be preserved exactly 1619 as they would have if either of them were using standardized UMA 1620 APIs, unless other extensibility profiles are also in use. 1622 An authorization server using any of the opportunities afforded by 1623 this profile MUST declare use of this profile by supplying its 1624 identifying URI for one of its "uma_profiles_supported" values in its 1625 configuration data (see Section 1.4). 1627 Same-entity communication or a tight integration of entities has the 1628 opportunity to make deployments more secure by reducing possible 1629 attack vectors. However, if the entities do not use TLS but 1630 communicate across a transport layer, it is RECOMMENDED to use an 1631 alternate means of transport-layer security, for example, using DTLS 1632 in the case of a CoAP-based UMA profile. 1634 Same-entity communication or a tight integration of entities has the 1635 potential to compromise privacy by promoting the freer exchange of 1636 personal information within a deployment ecosystem. It is 1637 RECOMMENDED to account for privacy impacts in each deployment 1638 scenario. 1640 5.2. Authorization API Extensibility Profile 1642 This section defines a profile for UMA where the authorization server 1643 and client roles either reside in the same system entity or otherwise 1644 have a privileged or specialized communications channel between them. 1645 Following is a summary: 1647 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1648 authz-ext-1.0 1650 o Profile author and contact information: Mark Dobrinic 1651 (mdobrinic@cozmanova.com) 1653 o Updates or obsoletes: None; this profile is new. 1655 o Security considerations: See below. 1657 o Privacy considerations: See below. 1659 o Error states: None additional. 1661 Using this profile, the client MAY use means other than the HTTP- 1662 based authorization API that is protected by TLS and OAuth (or an 1663 OAuth-based authentication protocol) to communicate with the 1664 authorization server in all respects, including using software 1665 interfaces and methods rather than network interfaces and APIs. The 1666 authorization server MUST still issue PATs, AATs, and RPTs and 1667 associate authorization data with RPTs, and the resource server MUST 1668 still give clients access only when RPTs are associated with 1669 sufficient authorization data. Interactions with entities other than 1670 the authorization server or client MUST be preserved exactly as they 1671 would have if either of them were using standardized UMA APIs, unless 1672 other extensibility profiles are also in use. 1674 An authorization server using any of the opportunities afforded by 1675 this profile MUST declare use of this profile by supplying its 1676 identifying URI for one of its "uma_profiles_supported" values in its 1677 configuration data (see Section 1.4). 1679 Same-entity communication or a tight integration of entities has the 1680 opportunity to make deployments more secure by reducing possible 1681 attack vectors. However, if the entities do not use TLS but 1682 communicate across a transport layer, it is RECOMMENDED to use an 1683 alternate means of transport-layer security, for example, using DTLS 1684 in the case of a CoAP-based UMA profile. 1686 Same-entity communication or a tight integration of entities has the 1687 potential to compromise privacy by promoting the freer exchange of 1688 personal information within a deployment ecosystem. It is 1689 RECOMMENDED to account for privacy impacts in each deployment 1690 scenario. 1692 5.3. Resource Interface Extensibility Profile 1694 This section defines a profile for UMA where the resource server and 1695 client roles either reside in the same system entity or otherwise 1696 have a privileged or specialized communications channel between them. 1697 Following is a summary: 1699 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1700 rsrc-ext-1.0 1702 o Profile author and contact information: Mark Dobrinic 1703 (mdobrinic@cozmanova.com) 1705 o Updates or obsoletes: None; this profile is new. 1707 o Security considerations: See below. 1709 o Privacy considerations: See below. 1711 o Error states: None additional. 1713 Using this profile, the resource server MAY use means other than an 1714 HTTP-based resource interface to communicate with the authorization 1715 server in all respects, including using software interfaces and 1716 methods rather than network interfaces and APIs. The resource server 1717 MUST still give clients access only when RPTs are associated with 1718 sufficient authorization data. Interactions with entities other than 1719 the resource server or client MUST be preserved exactly as they would 1720 have if either of them were using standardized UMA APIs, unless other 1721 extensibility profiles are also in use. 1723 An authorization server involved in deployments where resource 1724 servers and clients are known to be using opportunities afforded by 1725 the resource interface extensibility profile MAY declare use of this 1726 profile by supplying its identifying URI for one of its 1727 "uma_profiles_supported" values in its configuration data (see 1728 Section 1.4). 1730 Same-entity communication or a tight integration of entities has the 1731 opportunity to make deployments more secure by reducing possible 1732 attack vectors. However, if the entities do not use TLS but 1733 communicate across a transport layer, it is RECOMMENDED to use an 1734 alternate means of transport-layer security, for example, using DTLS 1735 in the case of a CoAP-based UMA profile. 1737 Same-entity communication or a tight integration of entities has the 1738 potential to compromise privacy by promoting the freer exchange of 1739 personal information within a deployment ecosystem. It is 1740 RECOMMENDED to account for privacy impacts in each deployment 1741 scenario. 1743 6. Specifying Additional Profiles 1745 This specification defines a protocol that has optional features. 1746 For implementation interoperability and to serve particular 1747 deployment scenarios, including sector-specific ones such as 1748 healthcare or e-government, third parties may want to define profiles 1749 of UMA that restrict these options. 1751 Further, this specification creates extensibility points for RPT 1752 profiles and claim token profiles, and third parties may likewise 1753 want to define their own. Different RPT profiles could be used, for 1754 example, to change the dividing line between authorization server and 1755 resource server responsibilities in controlling access. Different 1756 claim token profiles could be used to customize sector-specific or 1757 population-specific (such as individual vs. employee) claim types 1758 that drive the types of policies resource owners could set. 1760 It is not practical for this specification to standardize all desired 1761 profiles. However, to serve overall interoperability goals, this 1762 section provides guidelines for third parties that wish to specify 1763 UMA-related profiles. In all cases, it is RECOMMENDED that profiles 1764 document the following information: 1766 o Specify a URI that uniquely identifies the profile. 1768 o Identify the responsible author and provide postal or electronic 1769 contact information. 1771 o Supply references to any previously defined profiles that the 1772 profile updates or obsoletes. 1774 o Define any additional or changed error states. 1776 o Specify any conformance and interoperability considerations. 1778 o Supply any additional security and privacy considerations. 1780 6.1. Specifying Profiles of UMA 1782 It is RECOMMENDED that profiles of UMA additionally document the 1783 following information: 1785 o Specify the set of interactions between endpoint entities involved 1786 in the profile, calling out any restrictions on ordinary UMA- 1787 conformant operations and any extension properties used in message 1788 formats. 1790 See Section 5 for examples. 1792 6.2. Specifying RPT Profiles 1794 It is RECOMMENDED that RPT profiles additionally document the 1795 following information: 1797 o Specify the keyword to be used in HTTP Authorization headers with 1798 tokens conforming to this profile. 1800 o Specify the syntax and semantics of the data that the 1801 authorization server associates with the token. 1803 o Specify how the token data is associated with, contained within, 1804 and/or retrieved by means of, the on-the-wire token string. 1806 o Specify processing rules for token data. 1808 o Identify any restrictions on grant types to be used with the token 1809 profile. 1811 See Section 3.3.2 for an example. 1813 6.3. Specifying Claim Token Format Profiles 1815 It is RECOMMENDED that claim token format profiles additionally 1816 document the following information: 1818 o Specify any related or additional error_details hints. 1820 o Specify any constraints on the claim token format vs. a standard 1821 definition for it in a specification. 1823 o Specify any mutual interpretation details of claim token formats 1824 by authorization servers and clients. 1826 7. Compatibility Notes 1828 Implementers should heed the following compatibility notes. 1830 o This specification uses a specific draft of a specification that 1831 is not yet final: [OAuth-introspection] (draft 04); the reference 1832 will be updated until this "UMA V1.0 candidate" specification is 1833 finalized. While every effort will be made to prevent breaking 1834 changes to this specification, should they occur, UMA 1835 implementations should continue to use the specifically referenced 1836 draft version in preference to the final versions, unless using a 1837 possible future UMA profile or specification that updates the 1838 relevant references. 1840 o In cases where this specification is not prescriptive regarding 1841 conformance or interoperability, any common or best practices for 1842 implementation will be documented in the [UMA-Impl] over time. 1844 8. Security Considerations 1846 As a profile of OAuth, this specification relies mainly on OAuth 1847 security mechanisms as well as transport-level encryption. Thus, 1848 implementers are strongly advised to read the security considerations 1849 in [OAuth2] (Section 10) and [OAuth-bearer] (Section 5) along with 1850 the security considerations of any other OAuth token-defining 1851 specifications in use, along with the entire [OAuth-threat] 1852 specification, and apply the countermeasures described therein. 1854 The following sections describe additional security considerations. 1856 8.1. Redirection and Impersonation Threats 1858 This section discusses threats related to UMA's nature as an protocol 1859 enabling autonomous (non-resource-owner) requesting parties to gain 1860 authorized access to sensitive resources, including through the 1861 process of claims-gathering redirection. 1863 Like ordinary OAuth redirection, UMA redirection for the purpose of 1864 gathering claims from an end-user requesting party (described in 1865 Section 3.4.1.2.2) creates the potential for cross-site request 1866 forgery (CSRF) through an open redirect if the authorization server 1867 does not force the client to pre-register its redirection endpoint, 1868 and server-side artifact tampering if the client does not avail 1869 itself of the state parameter. The client SHOULD check that the 1870 ticket value returned by an authorization server after a redirect is 1871 completed has not been maliciously changed, for example by a man in 1872 the browser (MITB), by using the state parameter. (See the 1873 [UMA-Impl] for advice on ways to accomplish this.) Sections 4.4.1.8, 1874 4.4.2.5, and 5.3.5 of [OAuth-threat] are apropos for the UMA claims- 1875 gathering redirection flow as well. 1877 When a client redirects an end-user requesting party to the 1878 requesting party claims endpoint, the client provides no a priori 1879 context to the authorization server about which user is appearing at 1880 the endpoint, other than implicitly through the permission ticket. 1881 Since the authorization server is free to gather any claims it 1882 wishes, the effect is to "late-bind" them to the permission ticket 1883 and the state string provided by the client, with the effect of 1884 enabling the authorization server not to trust client-asserted 1885 claims. This is a desirable result and reflects one reason why the 1886 authorization server might choose to demand use of the redirect flow 1887 over the push flow. However, the client has the opportunity to 1888 switch end-users -- say, enabling malicious end-user Carlos to 1889 impersonate the original end-user Bob who approved the minting of of 1890 the AAT -- after the redirect completes and before it returns to the 1891 RPT endpoint to seek authorization data. 1893 Another issue concerns the exposure of the RPT to an autonomous 1894 requesting party, which could maliciously pass the token to an 1895 unauthorized party. 1897 To mitigate requesting-party switching and RPT exposure threats, 1898 consider the following mitigation strategies. 1900 o Require that the Requesting Party (as defined in 1901 [UMA-obligations], meaning this party is able to take on legal 1902 obligations) legitimately represent the wielder of the bearer 1903 token. This solution is based on a legal or contractual approach, 1904 and therefore does not reduce the risk from the technical 1905 perspective. 1907 o The authorization server, possibly with input from the resource 1908 owner, can implement tighter time-to-live strategies around the 1909 authorization data in RPTs. This is a classic approach with 1910 bearer tokens that helps to limit a malicious party's ability to 1911 intercept and use the bearer token. In the same vein, the 1912 authorization server could require claims to have a reasonable 1913 degree of freshness (which would require a custom claims profile). 1915 o The strongest strategy is to disallow bearer-type RPTs within the 1916 UMA profile being deployed, by providing or requiring an RPT 1917 profile that requires use of a holder-of-key approach. In this 1918 way, the wielder of the token must engage in a live session for 1919 proof-of-possession. 1921 8.2. Client Authentication 1923 Along with TLS, UMA requires OAuth, or any OAuth-based authentication 1924 protocol, as the security mechanism for its standardized APIs. The 1925 UMA resource server acts in the role of an OAuth client at the 1926 authorization server's protection API, and the UMA client acts in the 1927 role of an OAuth client at the authorization server's authorization 1928 API. While it is possible to use any profile of OAuth for this 1929 protection, it is RECOMMENDED for the authorization server to use 1930 OpenID Connect, and to use its mechanisms for stronger client 1931 authentication at the token endpoint, in order to strengthen the 1932 authentication of OAuth clients. Section 16 of [OIDCCore] provides 1933 more information on OpenID Connect security considerations. 1935 8.3. JSON Usage 1937 This specification defines a number of data formats based on [JSON]. 1938 As a subset of the JavaScript scripting language, JSON data SHOULD be 1939 consumed through a process that does not dynamically execute it as 1940 code, to avoid malicious code execution. One way to achieve this is 1941 to use a JavaScript interpreter rather than the built-in JavaScript 1942 eval() function. 1944 8.4. Profiles, Binding Obligations, and Trust Establishment 1946 Parties operating and using UMA software entities have opportunities 1947 to establish agreements about mutual rights, responsibilities, and 1948 common interpretations of UMA constructs for consistent and expected 1949 software behavior. These agreements can be used to improve the 1950 parties' respective security postures, and written profiles are a key 1951 mechanism for conveying and enforcing these agreements. Section 6 1952 discusses profiling. Section 5 discusses profiling for 1953 extensibility. [UMA-obligations] discusses the development of 1954 binding obligations. 1956 9. Privacy Considerations 1958 The authorization server comes to be in possession of resource set 1959 information that may reveal information about the resource owner, 1960 which the authorization server's trust relationship with the resource 1961 server is assumed to accommodate. However, the client is a less- 1962 trusted party -- in fact, entirely untrustworthy until authorization 1963 data is associated with its RPT. This specification depends on 1964 [OAuth-resource-reg], which recommends obscuring resource set 1965 identifiers in order to avoid leaking personally identifiable 1966 information to clients through the scope mechanism. The more 1967 information about a resource set that is registered, the more risk of 1968 privacy compromise there is through a less-trusted authorization 1969 server. 1971 The primary privacy duty of UMA's design is to the resource owner. 1972 However, privacy considerations affect the requesting party as well. 1973 This can be seen in the issuance of an AAT, which represents the 1974 approval of a requesting party for a client to engage with an 1975 authorization server to perform tasks needed for obtaining 1976 authorization, possibly including pushing claim tokens. 1978 Parties operating and using UMA software entities have opportunities 1979 to establish agreements about mutual rights, responsibilities, and 1980 common interpretations of UMA constructs for consistent and expected 1981 software behavior. These agreements can be used to improve the 1982 parties' respective privacy postures. For information about the 1983 additional technical, operational, and legal elements of trust 1984 establishment, see [UMA-obligations]. Additional considerations 1985 related to Privacy by Design concepts are discussed in [UMA-PbD]. 1987 10. Conformance 1989 This section outlines conformance requirements for various entities 1990 implementing UMA endpoints. 1992 This specification has dependencies on other specifications, as 1993 referenced under the normative references listed in this 1994 specification. Its dependencies on some specifications, such as 1995 OpenID Connect ([OIDCCore]), are optional depending on whether the 1996 feature in question is used in the implementation. 1998 The authorization server's configuration data provides a machine- 1999 readable method for it to indicate certain of the conformance options 2000 it supports. Several of the configuration data properties allow for 2001 indicating extension features. Where this specification does not 2002 already require optional features to be documented, it is RECOMMENDED 2003 that authorization server developers and deployers document any 2004 profiled or extended features explicitly and use configuration data 2005 to indicate their usage. See Section 1.4 for information about 2006 providing and extending the configuration data. 2008 11. IANA Considerations 2010 This document makes the following requests of IANA. 2012 11.1. JSON Web Token Claims Registration 2014 This specification registers the claim defined in Section 3.3.2. 2016 11.1.1. Registry Contents 2018 o Claim name: permissions 2020 o Claim description: Array of objects, each describing a set of 2021 scoped, time-limitable entitlements to a resource set 2023 o Change controller: Kantara Initiative User-Managed Access Work 2024 Group - wg-uma@kantarainitiative.org 2026 o Specification document: Section 3.3.2 in this document 2028 11.2. Well-Known URI Registration 2030 This specification registers the well-known URI defined in 2031 Section 1.4. 2033 11.2.1. Registry Contents 2035 o URI suffix: uma-configuration 2037 o Change controller: Kantara Initiative User-Managed Access Work 2038 Group - wg-uma@kantarainitiative.org 2040 o Specification document: Section 1.4 in this document 2042 12. Acknowledgments 2044 The following people made significant text contributions to the 2045 specification: 2047 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 2049 o Mark Dobrinic, Cozmanova 2051 o George Fletcher, AOL 2053 o Lukasz Moren, Cloud Identity Ltd 2055 o Christian Scholz, COMlounge GmbH (former editor) 2057 o Mike Schwartz, Gluu 2059 o Jacek Szpot, Newcastle University 2060 Additional contributors to this specification include the Kantara UMA 2061 Work Group participants, a list of whom can be found at 2062 [UMAnitarians]. 2064 13. Issues 2066 Issues are captured at the project's GitHub site ([1]). 2068 14. References 2070 14.1. Normative References 2072 [DynClientReg] 2073 Richer, J., "OAuth 2.0 Core Dynamic Client Registration", 2074 December 2014, 2075 . 2077 [JSON] Bray, T., "The JavaScript Object Notation (JSON) Data 2078 Interchange Format", March 2014, 2079 . 2081 [OAuth-bearer] 2082 "The OAuth 2.0 Authorization Framework: Bearer Token 2083 Usage", October 2012, 2084 . 2086 [OAuth-introspection] 2087 Richer, J., "OAuth Token Introspection", December 2014, 2088 . 2091 [OAuth-resource-reg] 2092 Hardjono, T., "OAuth 2.0 Resource Set Registration", July 2093 2014, . 2096 [OAuth-threat] 2097 Lodderstedt, T., "OAuth 2.0 Threat Model and Security 2098 Considerations", January 2013, 2099 . 2101 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 2102 October 2012, . 2104 [OIDCCore] 2105 Sakimura, N., "OpenID Connect Core 1.0 incorporating 2106 errata set 1", November 2014, 2107 . 2109 [OIDCDynClientReg] 2110 Sakimura, N., "OpenID Connect Dynamic Client Registration 2111 1.0 incorporating errata set 1", November 2014, 2112 . 2115 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2116 Requirement Levels", BCP 14, RFC 2119, March 1997. 2118 [RFC3986] Berners-Lee, T., "Uniform Resource Identifier (URI): 2119 Generic Syntax", January 2005, 2120 . 2122 [RFC6711] Johansson, L., "An IANA Registry for Level of Assurance 2123 (LoA) Profiles", August 2012, 2124 . 2126 [hostmeta] 2127 Hammer-Lahav, E., "Web Host Metadata", October 2011, 2128 . 2130 14.2. Informative References 2132 [UMA-Impl] 2133 Maler, E., "UMA Implementer's Guide", December 2014, 2134 . 2137 [UMA-PbD] Maler, E., "Privacy by Design Implications of UMA", 2138 December 2013, 2139 . 2142 [UMA-casestudies] 2143 Maler, E., "UMA Case Studies", April 2014, 2144 . 2147 [UMA-obligations] 2148 Maler, E., "Binding Obligations on UMA Participants", 2149 January 2013, . 2152 [UMA-usecases] 2153 Maler, E., "UMA Scenarios and Use Cases", October 2010, 2154 . 2157 [UMAnitarians] 2158 Maler, E., "UMA Participant Roster", December 2014, 2159 . 2162 14.3. URIs 2164 [1] https://github.com/xmlgrrl/UMA-Specifications/issues 2166 [2] http://kantarainitiative.org/confluence/display/uma/ 2167 UMA+1.0+Core+Protocol 2169 Appendix A. Document History 2171 NOTE: To be removed by RFC editor before publication as an RFC. 2173 See [2] for a list of code-breaking and other major changes made to 2174 this specification at various revision points. 2176 Authors' Addresses 2178 Thomas Hardjono (editor) 2179 MIT 2181 Email: hardjono@mit.edu 2183 Eve Maler 2184 ForgeRock 2186 Email: eve.maler@forgerock.com 2188 Maciej Machulak 2189 Cloud Identity 2191 Email: maciej.machulak@cloudidentity.co.uk 2193 Domenico Catalano 2194 Oracle 2196 Email: domenico.catalano@oracle.com