idnits 2.17.1 draft-hardjono-oauth-umacore-13.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 (April 4, 2015) is 3303 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '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 (==), 6 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: October 6, 2015 ForgeRock 6 M. Machulak 7 Cloud Identity 8 D. Catalano 9 Oracle 10 April 4, 2015 12 User-Managed Access (UMA) Profile of OAuth 2.0 13 draft-hardjono-oauth-umacore-13 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. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on October 6, 2015. 40 Copyright Notice 42 Copyright (c) 2015 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 6 59 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 60 1.3. Achieving Distributed Access Control . . . . . . . . . . 8 61 1.3.1. Protection API . . . . . . . . . . . . . . . . . . . 8 62 1.3.2. Authorization API . . . . . . . . . . . . . . . . . . 9 63 1.3.3. Protected Resource Interface . . . . . . . . . . . . 10 64 1.3.4. Time-to-Live Considerations . . . . . . . . . . . . . 11 65 1.4. Authorization Server Configuration Data . . . . . . . . . 11 66 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 15 67 3. Getting Authorization and Accessing a Resource . . . . . . . 16 68 3.1. Client Attempts to Access Protected Resource . . . . . . 17 69 3.1.1. Client Presents No RPT . . . . . . . . . . . . . . . 17 70 3.1.2. Client Presents RPT . . . . . . . . . . . . . . . . . 18 71 3.2. Resource Server Registers Requested Permission With 72 Authorization Server . . . . . . . . . . . . . . . . . . 19 73 3.3. Resource Server Determines RPT's Status . . . . . . . . . 21 74 3.3.1. Token Introspection . . . . . . . . . . . . . . . . . 22 75 3.3.2. RPT Profile: Bearer . . . . . . . . . . . . . . . . . 22 76 3.4. Client Seeks Authorization for Access . . . . . . . . . . 24 77 3.4.1. Client Requests Authorization Data . . . . . . . . . 24 78 3.4.1.1. Authentication Context Flows . . . . . . . . . . 28 79 3.4.1.2. Claims-Gathering Flows . . . . . . . . . . . . . 28 80 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 33 81 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 33 82 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 34 83 5. Profiles for API Extensibility . . . . . . . . . . . . . . . 35 84 5.1. Protection API Extensibility Profile . . . . . . . . . . 35 85 5.2. Authorization API Extensibility Profile . . . . . . . . . 36 86 5.3. Resource Interface Extensibility Profile . . . . . . . . 37 87 6. Specifying Additional Profiles . . . . . . . . . . . . . . . 39 88 6.1. Specifying Profiles of UMA . . . . . . . . . . . . . . . 39 89 6.2. Specifying RPT Profiles . . . . . . . . . . . . . . . . . 40 90 6.3. Specifying Claim Token Format Profiles . . . . . . . . . 40 91 7. Compatibility Notes . . . . . . . . . . . . . . . . . . . . . 40 92 8. Security Considerations . . . . . . . . . . . . . . . . . . . 41 93 8.1. Redirection and Impersonation Threats . . . . . . . . . . 41 94 8.2. Client Authentication . . . . . . . . . . . . . . . . . . 42 95 8.3. JSON Usage . . . . . . . . . . . . . . . . . . . . . . . 43 96 8.4. Profiles, Binding Obligations, and Trust Establishment . 44 98 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 44 99 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 100 10.1. JSON Web Token Claims Registration . . . . . . . . . . . 45 101 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . 45 102 10.2. Well-Known URI Registration . . . . . . . . . . . . . . 45 103 10.2.1. Registry Contents . . . . . . . . . . . . . . . . . 45 104 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 105 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 106 12.1. Normative References . . . . . . . . . . . . . . . . . . 46 107 12.2. Informative References . . . . . . . . . . . . . . . . . 47 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 110 1. Introduction 112 User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2]. UMA 113 defines how resource owners can control protected-resource access by 114 clients operated by arbitrary requesting parties, where the resources 115 reside on any number of resource servers, and where a centralized 116 authorization server governs access based on resource owner policies. 117 Resource owners configure authorization servers with access policies 118 that serve as asynchronous authorization grants. 120 UMA serves numerous use cases where a resource owner uses a dedicated 121 service to manage authorization for access to their resources, 122 potentially even without the run-time presence of the resource owner. 123 A typical example is the following: a web user (an end-user resource 124 owner) can authorize a web or native app (a client) to gain one-time 125 or ongoing access to a protected resource containing his home address 126 stored at a "personal data store" service (a resource server), by 127 telling the resource server to respect access entitlements issued by 128 his chosen cloud-based authorization service (an authorization 129 server). The requesting party operating the client might be the 130 resource owner, where the app is run by an e-commerce company that 131 needs to know where to ship a purchased item, or the requesting party 132 might be resource owner's friend who is using an online address book 133 service to collect contact information, or the requesting party might 134 be a survey company that uses an autonomous web service to compile 135 population demographics. A variety of use cases can be found in 136 [UMA-usecases] and [UMA-casestudies]. 138 Practical control of access among loosely coupled parties requires 139 more than just messaging protocols. This specification defines only 140 the "technical contract" between UMA-conforming entities; a companion 141 specification, [UMA-obligations], additionally discusses expected 142 behaviors of parties operating and using these entities. Parties 143 operating entities that claim to be UMA-conforming should provide 144 documentation of any rights and obligations between and among them, 145 especially as they pertain the concepts and clauses discussed in this 146 companion specification. 148 In enterprise settings, application access management sometimes 149 involves letting back-office applications serve only as policy 150 enforcement points (PEPs), depending entirely on access decisions 151 coming from a central policy decision point (PDP) to govern the 152 access they give to requesters. This separation eases auditing and 153 allows policy administration to scale in several dimensions. UMA 154 makes use of a separation similar to this, letting the resource owner 155 serve as a policy administrator crafting authorization strategies for 156 resources under their control. 158 In order to increase interoperable communication among the 159 authorization server, resource server, and client, UMA defines two 160 purpose-built APIs related to the outsourcing of authorization, 161 themselves protected by OAuth (or an OAuth-based authentication 162 protocol) in embedded fashion. 164 The UMA protocol has three broad phases, as shown in Figure 1. 166 The Three Phases of the UMA Profile of OAuth 168 +--------------+ 169 | resource | 170 +---------manage (A)------------ | owner | 171 | +--------------+ 172 | Phase 1: | 173 | protect a control (C) 174 | resource | 175 v v 176 +------------+ +----------+--------------+ 177 | | |protection| | 178 | resource | | API | authorization| 179 | server |<-protect (B)--| (needs | server | 180 | | | PAT) | | 181 +------------+ +----------+--------------+ 182 | protected | | authorization| 183 | resource | | API | 184 |(needs RPT) | | (needs AAT) | 185 +------------+ +--------------+ 186 ^ | 187 | Phases 2 and 3: authorize (D) 188 | get authorization, | 189 | access a resource v 190 | +--------------+ 191 +---------access (E)-------------| client | 192 +--------------+ 194 requesting party 196 Figure 1 198 The phases work as follows: 200 Protect a resource (Described in Section 2.) The resource owner, 201 who manages online resources at the resource server ("A"), 202 introduces it to the authorization server so that the latter can 203 begin protecting the resources. To accomplish this, the 204 authorization server presents a protection API ("B") to the 205 resource server. This API is protected by OAuth (or an OAuth- 206 based authentication protocol) and requires a protection API token 207 (PAT) for access. Out of band, the resource owner configures the 208 authorization server with policies associated with the resource 209 sets ("C") that the resource registers for protection. 211 Get authorization (Described in Section 3.) The client approaches 212 the resource server seeking access to an UMA-protected resource. 213 In order to access it successfully, the client must first use the 214 authorization server's authorization API ("D") to obtain 215 authorization data and a requesting party token (RPT) on behalf of 216 its requesting party, and the requesting party may need to supply 217 identity claims. The API is protected by OAuth (or an OAuth-based 218 authentication protocol) and requires an authorization API token 219 (AAT) for access. 221 Access a resource (Described in Section 3.) The client successfully 222 presents to the resource server an RPT that has sufficient 223 authorization data associated with it, gaining access to the 224 desired resource ("E"). Phase 3 is effectively the "success path" 225 embedded within phase 2. 227 Implementers have the opportunity to develop profiles (see Section 6) 228 that specify and restrict various UMA protocol, RPT, and identity 229 claim format options, according to deployment and usage conditions. 231 1.1. Notational Conventions 233 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 234 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 235 document are to be interpreted as described in [RFC2119]. 237 Unless otherwise noted, all protocol properties and values are case 238 sensitive. JSON [JSON] data structures defined by this specification 239 MAY contain extension properties that are not defined in this 240 specification. Any entity receiving or retrieving a JSON data 241 structure SHOULD ignore extension properties it is unable to 242 understand. Extension names that are unprotected from collisions are 243 outside the scope of this specification. 245 1.2. Terminology 247 UMA introduces the following new terms and enhancements of OAuth term 248 definitions. 250 resource owner 251 An OAuth resource owner that is the "user" in User-Managed 252 Access. This is typically an end-user (a natural person) but 253 it can also be a corporation or other legal person. 255 policy The configuration parameters of an authorization server that 256 effect resource access management. Authorization policies 257 typically include elements similar to parts of speech; for 258 example, "subjects" describe those seeking access (requesting 259 parties and clients), "verbs" describe operational scopes of 260 access, and "objects" describe targeted resource sets. Policy 261 configuration takes place between the resource owner and the 262 authorization server, and thus is out of band of UMA. 264 requesting party 265 An end-user, or a corporation or other legal person, that uses 266 a client to seek access to a protected resource. The 267 requesting party may or may not be the same party as the 268 resource owner. 270 client 271 An application making protected resource requests with the 272 resource owner's authorization and on the requesting party's 273 behalf. 275 claim 276 A statement of the value or values of one or more identity 277 attributes of a requesting party. A requesting party may need 278 to provide claims to an authorization server in order to gain 279 permission for access to a protected resource. 281 resource set One or more protected resources that a resource server 282 manages as a set, abstractly. In authorization policy 283 terminology, a resource set is the "object" being protected. 284 This term derives from [OAuth-resource-reg]. 286 scope A bounded extent of access that is possible to perform on a 287 resource set. In authorization policy terminology, a scope is 288 one of the potentially many "verbs" that can logically apply to 289 a resource set ("object"). UMA associates scopes with labeled 290 resource sets. 292 authorization data Data associated with an RPT that enables some 293 combination of the authorization server and resource server to 294 determine the correct extent of access to allow to a client. 295 Authorization data is a key part of the definition of an RPT 296 profile. 298 authorization server 299 A server that issues authorization data and RPTs to a client 300 and protects resources managed at a resource server. 302 permission A scope of access over a particular resource set at a 303 particular resource server that is being requested by, or 304 granted to, a requesting party. In authorization policy 305 terminology, a permission is an entitlement that includes a 306 "subject" (requesting party), "verbs" (one or more scopes of 307 access), and an "object" (resource set). A permission is one 308 example of authorization data that an authorization server may 309 add to a requesting party token. 311 permission ticket A correlation handle that is conveyed from an 312 authorization server to a resource server, from a resource 313 server to a client, and ultimately from a client back to an 314 authorization server, to enable the authorization server to 315 assess the correct policies to apply to a request for 316 authorization data. 318 token A packaged collection of data meant to be transmitted to 319 another entity. A token could be used for authorized access 320 (an "access token" such as an UMA RPT, PAT, or AAT), or could 321 be used to exchange information about a subject (a "claim 322 token" such as one that is conveyed by a client to an 323 authorization server while seeking authorization data). 325 1.3. Achieving Distributed Access Control 327 The software components that fill the roles of UMA authorization 328 servers, resource servers, and clients respectively are intended to 329 work in an interoperable fashion when each is operated by an 330 independent party (for example, different organizations). For this 331 reason, UMA specifies communications channels that the authorization 332 server MUST implement as HTTP-based APIs that MUST use TLS and OAuth 333 (or OAuth-based authentication protocol) protection, and that the 334 resource server MUST implement as an HTTP-based interface. UMA's use 335 of TLS is governed by Section 1.6 of [OAuth2], which discusses 336 deployment and adoption characteristics of different TLS versions. 338 For those OAuth protection use cases where an identity token is 339 desired in addition to an access token, it is RECOMMENDED that an 340 OAuth-based authentication protocol such as OpenID Connect be used. 342 It is also REQUIRED, in turn, for resource servers and clients on the 343 requesting side of UMA interactions to use these channels, unless a 344 profile is being used that enables API extensibility. The profiles 345 that enable such alternatives are provided in Section 5. 347 1.3.1. Protection API 349 The authorization server MUST present an HTTP-based protection API, 350 protected by TLS and OAuth (or an OAuth-based authentication 351 protocol), for use by resource servers. The authorization server 352 thus has an OAuth token endpoint and authorization endpoint. The 353 authorization server MUST declare all of its protection API endpoints 354 in its configuration data (see Section 1.4). 356 The protection API consists of three endpoints: 358 o Resource set registration endpoint as defined by 359 [OAuth-resource-reg] 361 o Permission registration endpoint as defined by Section 3.2 363 o Token introspection endpoint as defined by [OAuth-introspection] 364 and Section 3.3.1 366 An entity seeking protection API access MUST have the scope 367 "uma_protection". An access token with at least this scope is called 368 a protection API token (PAT) and an entity that can acquire an access 369 token with this scope is by definition a resource server. A single 370 entity can serve in both resource server and client roles if it has 371 access tokens with the appropriate OAuth scopes. If a request to an 372 endpoint fails due to an invalid, missing, or expired PAT, or 373 requires higher privileges at this endpoint than provided by the PAT, 374 the authorization server responds with an OAuth error. 376 The authorization server MUST support the OAuth bearer token profile 377 for PAT issuance, and MAY support other OAuth token profiles. It 378 MUST declare all supported token profiles and grant types for PAT 379 issuance in its configuration data. Any OAuth authorization grant 380 type might be appropriate depending on circumstances; for example, 381 the client credentials grant is useful in the case of an organization 382 acting as a resource owner. [UMA-Impl] discusses grant options 383 further. 385 A PAT binds a resource owner, a resource server the owner uses for 386 resource management, and an authorization server the owner uses for 387 protection of resources at this resource server. It is not specific 388 to any client or requesting party. The issuance of a PAT represents 389 the approval of the resource owner for this resource server to use 390 this authorization server for protecting some or all of the resources 391 belonging to this resource owner. 393 1.3.2. Authorization API 395 The authorization server MUST present an HTTP-based authorization 396 API, protected by TLS and OAuth (or an OAuth-based authentication 397 protocol), for use by clients. The authorization server thus has an 398 OAuth token endpoint and authorization endpoint. The authorization 399 server MUST declare its authorization API endpoint in its 400 configuration data (see Section 1.4). 402 The authorization API consists of one endpoint: 404 o RPT endpoint as defined in Section 3.4.1 406 An entity seeking authorization API access MUST have the scope 407 "uma_authorization". An access token with at least this scope is 408 called an authorization API token (AAT) and an entity that can 409 acquire an access token with this scope is by definition a client. A 410 single entity can serve in both resource server and client roles if 411 it has access tokens with the appropriate OAuth scopes. If a request 412 to an endpoint fails due to an invalid, missing, or expired AAT, or 413 requires higher privileges at this endpoint than provided by the AAT, 414 the authorization server responds with an OAuth error. 416 The authorization server MUST support the OAuth bearer token profile 417 for AAT issuance, and MAY support other OAuth token profiles. It 418 MUST declare all supported token profiles and grant types for AAT 419 issuance in its configuration data. Any OAuth authorization grant 420 type might be appropriate depending on circumstances; for example, 421 the client credentials grant is useful in the case of an organization 422 acting as a requesting party. [UMA-Impl] discusses grant options 423 further. 425 An AAT binds a requesting party, a client being used by that party, 426 and an authorization server that protects resources this client is 427 seeking access to on this requesting party's behalf. It is not 428 specific to any resource server or resource owner. The issuance of 429 an AAT represents the approval of this requesting party for this 430 client to engage with this authorization server to supply claims, ask 431 for authorization, and perform any other tasks needed for obtaining 432 authorization for access to resources at all resource servers that 433 use this authorization server. The authorization server is able to 434 manage future processes of authorization and claims-caching 435 efficiently for this client/requesting party pair across all resource 436 servers they try to access; however, these management processes are 437 outside the scope of this specification. 439 1.3.3. Protected Resource Interface 441 The resource server MAY present to clients whatever HTTP-based APIs 442 or endpoints it wishes. To protect any of its resources available in 443 this fashion using UMA, it MUST require a requesting party token 444 (RPT) with sufficient authorization data for access. 446 This specification defines one RPT profile, call "bearer" (see 447 Section 3.3.2), which the authorization server MUST support. It MAY 448 support additional RPT profiles, and MUST declare all supported RPT 449 profiles in its configuration data (see Section 1.4). 451 An RPT binds a requesting party, the client being used by that party, 452 the resource server at which protected resources of interest reside, 453 and the authorization server that protects those resources. It is 454 not specific to a single resource owner, though its internal 455 components are likely to be bound in practice to individual resource 456 owners, depending on the RPT profile in use. 458 1.3.4. Time-to-Live Considerations 460 The authorization server has the opportunity to manage the validity 461 periods of access tokens that it issues, their corresponding refresh 462 tokens where applicable, the individual authorization data components 463 associated with RPTs where applicable, and even the client 464 credentials that it issues. Different time-to-live strategies may be 465 suitable for different resource sets and scopes of access, and the 466 authorization server has the opportunity to give the resource owner 467 control over lifetimes of tokens and authorization data issued on 468 their behalf through policy. These options are all outside the scope 469 of this specification. 471 1.4. Authorization Server Configuration Data 473 The authorization server MUST provide configuration data in a JSON 474 document that resides in an /uma-configuration directory at its host- 475 meta [hostmeta] location. The configuration data documents 476 conformance options and endpoints supported by the authorization 477 server. 479 The configuration data has the following properties. 481 version 482 REQUIRED. The version of the UMA core protocol to which this 483 authorization server conforms. The value MUST be the string 484 "1.0". 486 issuer 487 REQUIRED. A URI with no query or fragment component that the 488 authorization server asserts as its issuer identifier. This 489 value MUST be identical to the web location of the 490 configuration data minus the host-meta [hostmeta] and /uma- 491 configuration path components 493 pat_profiles_supported 494 REQUIRED. OAuth access token types supported by this 495 authorization server for PAT issuance. The property value is 496 an array of string values, where each string value (which MAY 497 be a URI) is a token type. Non-URI token type strings defined 498 by OAuth token-defining specifications are privileged. For 499 example, the type "bearer" stands for the OAuth bearer token 500 type defined in [OAuth-bearer]. The authorization server is 501 REQUIRED to support "bearer", and to supply this value 502 explicitly. The authorization server MAY declare its support 503 for additional PAT profiles. 505 aat_profiles_supported 506 REQUIRED. OAuth access token types supported by this 507 authorization server for AAT issuance. The property value is 508 an array of string values, where each string value (which MAY 509 be a URI) is a token type. Non-URI token type strings defined 510 by OAuth token-defining specifications are privileged. For 511 example, the type "bearer" stands for the OAuth bearer token 512 type defined in [OAuth-bearer]. The authorization server is 513 REQUIRED to support "bearer", and to supply this value 514 explicitly. The authorization server MAY declare its support 515 for additional AAT profiles. 517 rpt_profiles_supported 518 REQUIRED. Profiles supported by this authorization server for 519 RPT issuance. The property value is an array of string values, 520 where each string value is a URI identifying an RPT profile. 521 The authorization server is REQUIRED to support the "bearer" 522 RPT profile defined in Section 3.3.2, and to supply its 523 identifying URI explicitly. The authorization server MAY 524 declare its support for additional RPT profiles. 526 pat_grant_types_supported 527 REQUIRED. OAuth grant types supported by this authorization 528 server in issuing PATs. The property value is an array of 529 string values, where each string value (which MAY be a URI) is 530 a grant type. Non-URI token type strings defined by OAuth 531 grant type-defining specifications are privileged. For 532 example, the type "authorization_code" stands for the OAuth 533 authorization code grant type defined in [OAuth2]. 535 aat_grant_types_supported 536 REQUIRED. OAuth grant types supported by this authorization 537 server in issuing AATs. The property value is an array of 538 string values, where each string value (which MAY be a URI) is 539 a grant type. Non-URI token type strings defined by OAuth 540 grant type-defining specifications are privileged. For 541 example, the type "authorization_code" stands for the OAuth 542 authorization code grant type defined in [OAuth2]. 544 claim_token_profiles_supported 545 OPTIONAL. Claim token format profiles supported by this 546 authorization server. The property value is an array of string 547 values, where each string value MAY be a URI. 549 uma_profiles_supported 550 OPTIONAL. UMA profiles supported by this authorization server. 551 The property value is an array of string values, where each 552 string value is a URI identifying an UMA profile. Examples of 553 UMA profiles are the API extensibility profiles defined in 554 Section 5. 556 dynamic_client_endpoint 557 OPTIONAL. The endpoint to use for performing dynamic client 558 registration in the case of the use of [DynClientReg], or 559 alternatively the reserved string "openid" in the case of the 560 use of [OIDCDynClientReg]. In the latter case, it is presumed 561 that the resource server or client will discover the dynamic 562 client registration endpoint from the authorization server's 563 published OpenID Provider Configuration Information. The 564 presence of this property indicates authorization server 565 support for dynamic client registration feature; its absence 566 indicates a lack of support. 568 token_endpoint 569 REQUIRED. The endpoint URI at which the resource server or 570 client asks the authorization server for a PAT or AAT. A 571 requested scope of "uma_protection" results in a PAT. A 572 requested scope of "uma_authorization" results in an AAT. 573 Usage of this endpoint is defined by [OAuth2]. 575 authorization_endpoint 576 REQUIRED. The endpoint URI at which the resource server 577 gathers the consent of the end-user resource owner or the 578 client gathers the consent of the end-user requesting party for 579 issuance of a PAT or AAT respectively, if the 580 "authorization_code" grant type is used. Usage of this 581 endpoint is defined by [OAuth2]. 583 requesting_party_claims_endpoint 584 OPTIONAL. The endpoint URI at which the authorization server 585 interacts with the end-user requesting party to gather claims. 586 If this property is absent, the authorization server does not 587 interact with the end-user requesting party for claims 588 gathering. 590 introspection_endpoint 591 REQUIRED. The endpoint URI at which the resource server 592 introspects an RPT presented to it by a client. Usage of this 593 endpoint is defined by [OAuth-introspection] and Section 3.3.1. 594 A valid PAT MUST accompany requests to this protected endpoint. 596 resource_set_registration_endpoint 597 REQUIRED. The endpoint URI at which the resource server 598 registers resource sets to put them under authorization manager 599 protection. Usage of this endpoint is defined by 600 [OAuth-resource-reg] and Section 2. A valid PAT MUST accompany 601 requests to this protected endpoint. 603 permission_registration_endpoint 604 REQUIRED. The endpoint URI at which the resource server 605 registers a requested permission that would suffice for a 606 client's access attempt. Usage of this endpoint is defined by 607 Section 3.2. A valid PAT MUST accompany requests to this 608 protected endpoint. 610 rpt_endpoint 611 REQUIRED. The endpoint URI at which the client asks for 612 authorization data. Usage of this endpoint is defined in 613 Section 3.4. A valid AAT and a permission ticket MUST, and an 614 RPT MAY, accompany requests to this protected endpoint. 616 Example of authorization server configuration data that resides at 617 https://example.com/.well-known/uma-configuration (note the use of 618 https: for endpoints throughout): 620 { 621 "version":"1.0", 622 "issuer":"https://example.com", 623 "pat_profiles_supported":["bearer"], 624 "aat_profiles_supported":["bearer"], 625 "rpt_profiles_supported": 626 ["https://docs.kantarainitiative.org/uma/profiles/uma-token-bearer-1.0"], 627 "pat_grant_types_supported":["authorization_code"], 628 "aat_grant_types_supported":["authorization_code"], 629 "claim_token_profiles_supported":["https://example.com/claims/formats/token1"], 630 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", 631 "token_endpoint":"https://as.example.com/token_uri", 632 "authorization_endpoint":"https://as.example.com/authz_uri", 633 "requesting_party_claims_endpoint":"https://as.example.com/rqp_claims_uri", 634 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri", 635 "introspection_endpoint":"https://as.example.com/rs/status_uri", 636 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri", 637 "rpt_endpoint":"https://as.example.com/client/rpt_uri" 638 } 639 Where this specification does not already require optional features 640 to be documented, it is RECOMMENDED that authorization server 641 deployers document any profiled or extended features explicitly and 642 use configuration data to indicate their usage. 644 2. Protecting a Resource 646 The resource owner, resource server, and authorization server perform 647 the following actions to put resources under protection. This list 648 assumes that the resource server has discovered the authorization 649 server's configuration data and endpoints as needed. 651 1. The authorization server issues client credentials to the 652 resource server. It is OPTIONAL for the client credentials to be 653 provided dynamically through [DynClientReg] or 654 [OIDCDynClientReg]; alternatively, they MAY use a static process. 656 2. The resource server acquires a PAT from the authorization server. 657 It is OPTIONAL for the resource owner to introduce the resource 658 server to the authorization server dynamically (for example, 659 through a "NASCAR"-style user interface where the resource owner 660 selects a chosen authorization server); alternatively, they MAY 661 use a static process that may or may not directly involve the 662 resource owner at introduction time. 664 3. In an ongoing fashion, the resource server registers any resource 665 sets with the authorization server for which it intends to 666 outsource protection, using the resource set registration 667 endpoint of the protection API (see [OAuth-resource-reg]). 669 Note: The resource server is free to offer the option to protect any 670 subset of the resource owner's resources using different 671 authorization servers or other means entirely, or to protect some 672 resources and not others. Additionally, the choice of protection 673 regimes can be made explicitly by the resource owner or implicitly by 674 the resource server. Any such partitioning by the resource server or 675 owner is outside the scope of this specification. 677 Once a resource set has been placed under authorization server 678 protection through the registration of a resource set description for 679 it, and until such a description's deletion by the resource server, 680 the resource server MUST limit access to corresponding resources, 681 requiring sufficient authorization data associated with client- 682 presented RPTs by the authorization server (see Section 3.1.2). 684 3. Getting Authorization and Accessing a Resource 686 An authorization server orchestrates and controls clients' access (on 687 their requesting parties' behalf) to a resource owner's protected 688 resources at a resource server, under conditions dictated by that 689 resource owner. 691 The process of getting authorization and accessing a resource always 692 begins with the client attempting access at a protected resource 693 endpoint at the resource server. How the client came to learn about 694 this endpoint is out of scope for this specification. The resource 695 owner might, for example, have advertised its availability publicly 696 on a blog or other website, listed it in a discovery service, or 697 emailed a link to a particular intended requesting party. 699 The resource server responds to the client's access request with 700 whatever its application-specific resource interface defines as a 701 success response, either immediately if the client has sufficient 702 authorization, or having first performed one or more embedded 703 interactions with the authorization server and client in the case of 704 a failed access attempt. 706 A high-level summary of the interactions is as follows. The 707 recipient of each request message SHOULD respond unless it detects a 708 security concern, such as a suspected denial of service attack that 709 can be mitigated by rate limiting. 711 o The client attempts to access a protected resource. 713 * If the access attempt is unaccompanied by an RPT, the resource 714 server registers a requested permission at the authorization 715 server that would suffice for the access attempt, and then 716 responds with an HTTP 403 (Forbidden) response, a permission 717 ticket, and instructions on where to go to obtain an RPT and 718 authorization data. 720 * If the access attempt is accompanied by an RPT, the resource 721 server checks the RPT's status. 723 + If the RPT is invalid, or if the RPT is valid but has 724 insufficient authorization data, the resource server 725 registers a requested permission at the authorization server 726 that would suffice for the access attempt, and then responds 727 with an HTTP 403 (Forbidden) response, a permission ticket, 728 and instructions on where to go to obtain a valid RPT and 729 authorization data for it. 731 + If the RPT is valid, and if the authorization data 732 associated with the token is sufficient for allowing access, 733 the resource server responds with an HTTP 2xx (Success) 734 response. 736 o If the client received a 403 response and a permission ticket, it 737 asks the authorization server for authorization data that matches 738 the ticket using the RPT endpoint of the authorization API. If 739 the authorization server needs requesting party claims in order to 740 assess this client's authorization, it engages in a claims- 741 gathering flow. 743 * If the client does not already have an AAT at the appropriate 744 authorization server to be able to use its authorization API, 745 it first obtains one. 747 The interactions are described in detail in the following sections. 749 3.1. Client Attempts to Access Protected Resource 751 This interaction assumes that the resource server has previously 752 registered one or more resource sets that correspond to the resource 753 the client is attempting to access. 755 The client attempts to access a protected resource (for example, when 756 an end-user requesting party clicks on a thumbnail representation of 757 the resource to retrieve a larger version). It is expected to 758 discover, or be provisioned or configured with, knowledge of the 759 protected resource and its location out of band. Further, the client 760 is expected to acquire its own knowledge about the application- 761 specific methods made available by the resource server for operating 762 on this protected resource (such as viewing it with a GET method, or 763 transforming it with some complex API call). 765 The access attempt either is or is not accompanied by an RPT. 767 3.1.1. Client Presents No RPT 769 Example of a request carrying no RPT: 771 GET /album/photo.jpg HTTP/1.1 772 Host: photoz.example.com 773 ... 775 If the client does not present an RPT with the request, the resource 776 server uses the protection API to register a requested permission 777 with the authorization server that would suffice for the access 778 attempt (see Section 3.2), and receives a permission ticket back in 779 response. It then responds to the client. It SHOULD respond with 780 the HTTP 403 (Forbidden) status code, providing the authorization 781 server's URI in an "as_uri" property in the header, along with the 782 just-received permission ticket in the body in a JSON-encoded 783 "ticket" property. Responses that use any code other than 403 are 784 undefined by this specification; any common or best practices for 785 returning other status codes will be documented in the [UMA-Impl]. 787 For example: 789 HTTP/1.1 403 Forbidden 790 WWW-Authenticate: UMA realm="example", 791 as_uri="https://as.example.com" 793 { 794 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 795 } 796 ... 798 3.1.2. Client Presents RPT 800 Example of a request carrying an RPT using the UMA "bearer" RPT 801 profile: 803 GET /album/photo.jpg HTTP/1.1 804 Authorization: Bearer vF9dft4qmT 805 Host: photoz.example.com 806 ... 808 If the client presents an RPT with its request, the resource server 809 MUST determine the RPT's status (see Section 3.3) before responding. 811 If the RPT is invalid, or if the RPT is valid but has insufficient 812 authorization data for the type of access sought, the resource server 813 uses the protection API to register a requested permission with the 814 authorization server that would suffice for the access attempt (see 815 Section 3.2), and receives a permission ticket back in response. It 816 then responds to the client with the HTTP 403 (Forbidden) status 817 code, providing the authorization server's URI in an "as_uri" 818 property in the header, along with the just-received permission 819 ticket in the body in a JSON-encoded "ticket" property. 821 Example of the resource server's response after having registered a 822 requested permission and received a ticket: 824 HTTP/1.1 403 Forbidden 825 WWW-Authenticate: UMA realm="example", 826 as_uri="https://as.example.com" 827 error="insufficient_scope" 829 { 830 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 831 } 833 If the RPT's status is associated with authorization data that is 834 sufficient for the access sought by the client, the resource server 835 MUST give access to the desired resource. 837 Example of the resource server's response after having determined 838 that the RPT is valid and associated with sufficient authorization 839 data: 841 HTTP/1.1 200 OK 842 Content-Type: image/jpeg 843 ... 845 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 846 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 847 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 848 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 850 The resource server MUST NOT give access where the token's status is 851 not associated with sufficient authorization data for the attempted 852 scope of access. 854 3.2. Resource Server Registers Requested Permission With Authorization 855 Server 857 The resource server uses the protection API's permission registration 858 endpoint to register a requested permission with the authorization 859 server that would suffice for the client's access attempt. The 860 authorization server returns a permission ticket for the resource 861 server to give to the client in its response. The PAT provided in 862 the API request implicitly identifies the resource owner ("subject") 863 to which the permission applies. 865 Note: The resource server is free to choose the extent of the 866 requested permission that it registers, as long as it minimally 867 suffices for the access attempted by the client. For example, it can 868 choose to register a permission that covers several scopes or a 869 resource set that is greater in extent than the specific resource 870 that the client attempted to access. Likewise, the authorization 871 server is ultimately free to choose to partially fulfill the elements 872 of a permission request based on incomplete satisfaction of policy 873 criteria, or not to fulfill the request. 875 The resource server uses the POST method at the endpoint. The body 876 of the HTTP request message contains a JSON object providing the 877 requested permission, using a format derived from the scope 878 description format specified in [OAuth-resource-reg], as follows. 879 The object has the following properties: 881 resource_set_id REQUIRED. The identifier for a resource set to 882 which this client is seeking access. The identifier MUST 883 correspond to a resource set that was previously registered. 885 scopes REQUIRED. An array referencing one or more identifiers of 886 scopes to which access is needed for this resource set. Each 887 scope identifier MUST correspond to a scope that was registered by 888 this resource server for the referenced resource set. 890 Example of an HTTP request that registers a requested permission at 891 the authorization server's permission registration endpoint, with a 892 PAT in the header: 894 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 895 Content-Type: application/json 896 Host: as.example.com 897 Authorization: Bearer 204c69636b6c69 899 { 900 "resource_set_id": "112210f47de98100", 901 "scopes": [ 902 "http://photoz.example.com/dev/actions/view", 903 "http://photoz.example.com/dev/actions/all" 904 ] 905 } 907 If the registration request is successful, the authorization server 908 responds with an HTTP 201 (Created) status code and includes the 909 "ticket" property in the JSON-formatted body. 911 The permission ticket is a short-lived opaque structure whose form is 912 determined by the authorization server. The ticket value MUST be 913 securely random (for example, not merely part of a predictable 914 sequential series), to avoid denial-of-service attacks. Since the 915 ticket is an opaque structure from the point of view of the client, 916 the authorization server is free to include information regarding 917 expiration time or any other information within the opaque ticket for 918 its own consumption. When the client subsequently uses the 919 authorization API to ask the authorization server for authorization 920 data to be associated with its RPT, it will submit this ticket to the 921 authorization server. 923 For example: 925 HTTP/1.1 201 Created 926 Content-Type: application/json 927 ... 929 { 930 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 931 } 933 If the registration request is authenticated properly but fails due 934 to other reasons, the authorization server responds with an HTTP 400 935 (Bad Request) status code and includes one of the following UMA error 936 codes (see Section 4.2): 938 invalid_resource_set_id The provided resource set identifier was not 939 found at the authorization server. 941 invalid_scope At least one of the scopes included in the request was 942 not registered previously by this resource server. 944 3.3. Resource Server Determines RPT's Status 946 The resource server MUST determine a received RPT's status, including 947 both whether it is active and, if so, its associated authorization 948 data, before giving or refusing access to the client. An RPT is 949 associated with a set of authorization data that governs whether the 950 client is authorized for access. The token's nature and format are 951 dictated by its profile; the profile might allow it to be self- 952 contained, such that the resource server is able to determine its 953 status locally, or might require or allow the resource server to make 954 a run-time introspection request of the authorization server that 955 issued the token. 957 This specification makes one type of RPT REQUIRED for the 958 authorization server to support: the UMA bearer token profile, as 959 defined in Section 3.3.2. Implementers MAY define and use other RPT 960 profiles. 962 3.3.1. Token Introspection 964 Within any RPT profile, when a resource server needs to introspect a 965 token in a non-self-contained way to determine its status, it MAY 966 require, allow, or prohibit use of the OAuth token introspection 967 endpoint (defined by [OAuth-introspection]) that is part of the 968 protection API, and MAY profile its usage. The resource server MUST 969 use the POST method in interacting with the endpoint, not the GET 970 method also defined by [OAuth-introspection]. 972 3.3.2. RPT Profile: Bearer 974 This section defines the UMA bearer token profile. Following is a 975 summary: 977 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 978 uma-token-bearer-1.0 980 o Profile author and contact information: Thomas Hardjono 981 (hardjono@mit.edu) 983 o Updates or obsoletes: None; this profile is new. 985 o Keyword in HTTP Authorization header: "Bearer". 987 o Syntax and semantics of token data: As defined below; an opaque 988 string value, resolving to an extended JSON Web Token (JWT) [JWT] 989 format on introspection at the authorization server. 991 o Token data association: The on-the-wire token is opaque; it is 992 introspected at run time by the resource server through profiled 993 use of the OAuth token introspection endpoint 994 [OAuth-introspection], as defined below. 996 o Token data processing: As defined in this section and throughout 997 Section 3 of this specification. 999 o Grant type restrictions: None. 1001 o Error states: As defined below. 1003 o Security and privacy considerations: As defined in this section, 1004 throughout Section 3, and in Section 8. 1006 An example of a client making a request with an RPT using the 1007 "Bearer" scheme appears in Section 3.1.2. 1009 On receiving an RPT with the "Bearer" scheme in an authorization 1010 header from a client making an access attempt, the resource server 1011 introspects the token by using the token introspection endpoint of 1012 the protection API. The PAT used by the resource server to make the 1013 introspection request provides resource-owner context to the 1014 authorization server. 1016 The authorization server responds with a JSON object with the 1017 structure dictated by [OAuth-introspection]. If the "active" 1018 property has a Boolean value of true, then the JSON object MUST NOT 1019 contain a "scope" claim, and MUST contain an extension property with 1020 the name "permissions" that contains an array of zero or more values, 1021 each of which is an object consisting of these properties: 1023 resource_set_id REQUIRED. A string that uniquely identifies the 1024 resource set, access to which has been granted to this client on 1025 behalf of this requesting party. The identifier MUST correspond 1026 to a resource set that was previously registered as protected. 1028 scopes REQUIRED. An array referencing one or more URIs of scopes to 1029 which access was granted for this resource set. Each scope MUST 1030 correspond to a scope that was registered by this resource server 1031 for the referenced resource set. 1033 exp OPTIONAL. Integer timestamp, measured in the number of seconds 1034 since January 1 1970 UTC, indicating when this permission will 1035 expire. If the property is absent, the permission does not 1036 expire. If the token-level "exp" value pre-dates a permission- 1037 level "exp" value, the former overrides the latter. 1039 iat OPTIONAL. Integer timestamp, measured in the number of seconds 1040 since January 1 1970 UTC, indicating when this permission was 1041 originally issued. If the token-level "iat" value post-dates a 1042 permission-level "iat" value, the former overrides the latter. 1044 nbf OPTIONAL. Integer timestamp, measured in the number of seconds 1045 since January 1 1970 UTC, indicating the time before which this 1046 permission is not valid. If the token-level "nbf" value post- 1047 dates a permission-level "nbf" value, the former overrides the 1048 latter. 1050 Example: 1052 HTTP/1.1 200 OK 1053 Content-Type: application/json 1054 Cache-Control: no-store 1056 { 1057 "active": true, 1058 "exp": 1256953732, 1059 "iat": 1256912345, 1060 "permissions": [ 1061 { 1062 "resource_set_id": "112210f47de98100", 1063 "scopes": [ 1064 "http://photoz.example.com/dev/actions/view", 1065 "http://photoz.example.com/dev/actions/all" 1066 ], 1067 "exp" : 1256953732 1068 } 1069 ] 1070 } 1072 3.4. Client Seeks Authorization for Access 1074 In order to access a protected resource successfully, a client needs 1075 to present a valid RPT with sufficient authorization data for access. 1076 To get to this stage requires a number of previously successful 1077 steps: 1079 1. The authorization server issues client credentials to the client. 1080 It is OPTIONAL for the client credentials to be provided 1081 dynamically through [DynClientReg] or [OIDCDynClientReg]; 1082 alternatively, they MAY use a static process. 1084 2. The client acquires an AAT. 1086 3. The client uses the authorization API to acquire an RPT and to 1087 ask for authorization data, providing the permission ticket it 1088 got from the resource server. The authorization server 1089 associates authorization data with the RPT based on the 1090 permission ticket, the resource owner's operative policies, and 1091 the results of any claims-gathering flows. 1093 3.4.1. Client Requests Authorization Data 1095 Once in possession of a permission ticket and an AAT for this 1096 authorization server, the client asks the authorization server to 1097 give it authorization data corresponding to that permission ticket. 1099 It performs a POST on the RPT endpoint, supplying its own AAT in the 1100 header and a JSON object in the body with a "ticket" property 1101 containing the ticket as its value. 1103 If the client had included an RPT in its failed access attempt, It 1104 MAY also provide that RPT in an "rpt" property in its request to the 1105 authorization server. 1107 In circumstances where the client needs to provide requesting party 1108 claims to the authorization server, it MAY also include a 1109 "claim_tokens" property in its request; see Section 3.4.1.2.1 for 1110 more information. 1112 Example of a request message containing an AAT, an RPT, and a 1113 permission ticket: 1115 POST /authz_request HTTP/1.1 1116 Host: as.example.com 1117 Authorization: Bearer jwfLG53^sad$#f 1118 ... 1120 { 1121 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1122 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1123 } 1125 The authorization server uses the ticket to look up the details of 1126 the previously registered requested permission, maps the requested 1127 permission to operative resource owner policies based on the resource 1128 set identifier and scopes associated with it, potentially requests 1129 additional information, and ultimately responds positively or 1130 negatively to the request for authorization data. 1132 The authorization server bases the issuing of authorization data on 1133 resource owner policies. These policies thus amount to an 1134 asynchronous OAuth authorization grant. The authorization server is 1135 also free to enable the resource owner to set policies that require 1136 the owner to interact with the server in near-real time to provide 1137 consent subsequent to an access attempt. All such processes are 1138 outside the scope of this specification. 1140 Once the authorization server adds the requested authorization data, 1141 it returns an HTTP 200 (OK) status code with a response body 1142 containing the RPT with which it associates the requested 1143 authorization data. If the client did not present an RPT in the 1144 request for authorization data, the authorization server creates and 1145 returns a new RPT. If the client did present an RPT in the request, 1146 the authorization server returns the RPT with which it associated the 1147 requested authorization data, which MAY be either the RPT that was in 1148 the request or a new one. Note: It is entirely an implementation 1149 issue whether the returned RPT is the same one that appeared in the 1150 request or a new RPT, and it is also an implementation issue whether 1151 the AS chooses to invalidate or retain the validity of the original 1152 RPT or any authorization data that was previously added to that RPT; 1153 to assist in client interoperability and token caching expectations, 1154 it is RECOMMENDED that authorization servers document their 1155 practices. [UMA-Impl] discusses the implications. 1157 Example: 1159 HTTP/1.1 200 OK 1160 Content-Type: application/json 1162 { 1163 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1164 } 1166 If the authorization server does not add the requested authorization 1167 data, it responds using one of the following UMA error codes and 1168 corresponding HTTP status codes (see Section 4.2): 1170 invalid_ticket The provided ticket was not found at the 1171 authorization server. The authorization server responds with the 1172 HTTP 400 (Bad Request) status code. 1174 expired_ticket The provided ticket has expired. The authorization 1175 server responds with the HTTP 400 (Bad Request) status code. 1177 not_authorized The client is not authorized to have this 1178 authorization data added. The authorization server responds with 1179 the HTTP 403 (Forbidden) status code. 1181 need_info The authorization server needs additional information in 1182 order to determine whether the client is authorized to have this 1183 authorization data. The authorization server responds with the 1184 HTTP 403 (Forbidden) status code. It MAY also respond with an 1185 "error_details" object that contains one or more sub-properties 1186 with hints about the nature of further required information. The 1187 client then has the opportunity to engage in follow-on flows to 1188 continue seeking authorization, in a process sometimes referred as 1189 "trust elevation". This specification defines two nonexclusive 1190 "error_details" sub-properties: "authentication_context", 1191 described in Section 3.4.1.1, and "requesting_party_claims", 1192 described in Section 3.4.1.2. 1194 request_submitted The authorization server requires intervention by 1195 the resource owner to determine whether the client is authorized 1196 to have this authorization data. Further immediate interaction 1197 between the client and authorization server is out of scope of 1198 this specification. 1200 Example when the ticket has expired: 1202 HTTP/1.1 400 Bad Request 1203 Content-Type: application/json 1204 Cache-Control: no-store 1205 ... 1207 { 1208 "error": "expired_ticket" 1209 } 1211 Example of a "need_info" response with a full set of "error_details" 1212 hints: 1214 HTTP/1.1 403 Forbidden 1215 Content-Type: application/json 1216 Cache-Control: no-store 1217 ... 1219 { 1220 "error": "need_info", 1221 "error_details": { 1222 "authentication_context": { 1223 "required_acr": ["https://example.com/acrs/LOA3.14159"] 1224 }, 1225 "requesting_party_claims": { 1226 "required_claims": [ 1227 { 1228 "name": "email23423453ou453", 1229 "friendly_name": "email", 1230 "claim_type": "urn:oid:0.9.2342.19200300.100.1.3", 1231 "claim_token_format": 1232 ["http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken"], 1233 "issuer": ["https://example.com/idp"] 1234 } 1235 ], 1236 "redirect_user": true, 1237 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1238 } 1239 } 1240 } 1242 3.4.1.1. Authentication Context Flows 1244 The "authentication_context" sub-property provides hints about 1245 additional requirements regarding the requesting party's 1246 authentication that underlies the issuance of the currently valid 1247 AAT. On receiving such hints, the client has the opportunity to 1248 redirect the requesting party to the authorization server to 1249 reauthenticate in a manner anticipated to be more successful for 1250 gaining access. Such an action is sometimes referred to as "step-up" 1251 authentication. The "authentication_context" sub-property contains 1252 the following parameter: 1254 required_acr REQUIRED. An array of strings specifying a set of 1255 acceptable authentication context class reference values. Any one 1256 of the referenced authentication context classes (sets of 1257 authentication methods or procedures considered to be equivalent 1258 in a particular context) would satisfy the requesting party 1259 authentication requirements. Each string MAY be a URI, including 1260 one that has been registered through [RFC6711]. 1262 3.4.1.2. Claims-Gathering Flows 1264 The "requesting_party_claims" sub-property provides hints about 1265 additional requirements regarding information the authorization 1266 server needs about the requesting party. On receiving such hints, 1267 the client has the opportunity to engage in claims-gathering flows of 1268 various types. The "requesting_party_claims" sub-property MAY 1269 contain the following parameters, where at least one of 1270 "required_claims" or "redirect_user" MUST be supplied: 1272 required_claims An array containing objects that describe 1273 characteristics of the required claims, with the following 1274 properties: 1276 name OPTIONAL. A string (which MAY be a URI) representing the 1277 name of the claim; the "key" in a key-value pair. 1279 friendly_name OPTIONAL. A string that provides a more human- 1280 readable form of the attribute's name, which may be useful as a 1281 "display name" for use in user interfaces in cases where the 1282 actual name is complex or opaque, such as an OID or a UUID. 1284 claim_type OPTIONAL. A string, indicating the expected 1285 interpretation of the provided claim value. The string MAY be 1286 a URI. 1288 claim_token_format OPTIONAL. An array of strings specifying a 1289 set of acceptable formats for a token pushed by the client 1290 containing this claim (see Section 3.4.1.2.1). Any one of the 1291 referenced formats would satisfy the authorization server's 1292 requirements. Each string MAY be a URI. 1294 issuer OPTIONAL. An array of strings specifying a set of 1295 acceptable issuing authorities for the claim. Any one of the 1296 referenced authorities would satisfy the authorization server's 1297 requirements. Each string MAY be a URI. 1299 redirect_user A Boolean value indicating whether the requesting 1300 party's presence at the authorization server is required for the 1301 process of claims gathering. For example, the authorization 1302 server may require the requesting party to fill out a CAPTCHA to 1303 help prove humanness. The default is false if this parameter is 1304 not present. See Section 1.4 for how the authorization server 1305 declares the requesting party claims endpoint to which the client 1306 has the opportunity to redirect the requesting party. Note that 1307 the word "user" implies a human requesting party; if the 1308 requesting party is not an end-user, then no client action would 1309 be possible on receiving the hint. 1311 ticket The permission ticket that was in the client's request for 1312 authorization data. If the authorization server provides the 1313 "redirect_user" property, it MUST also provide the "ticket" 1314 property. This helps the client avoid maintaining this state 1315 information after the redirect. 1317 An example of the use of these properties appears in Section 3.4.1. 1319 The authorization server has many options for gathering requesting 1320 party claims. For example, it could interact with an end-user 1321 requesting party directly, or accept claims delivered by a client, or 1322 perform a lookup in some external system. The process is extensible 1323 and can have dependencies on the type of requesting party (for 1324 example, natural person or legal person) or client (for example, 1325 browser, native app, or autonomously running web service). 1327 The client and authorization server have two nonexclusive claims- 1328 gathering interaction patterns: push and redirect. 1330 3.4.1.2.1. Client Pushes Claim Tokens to Authorization Server 1332 If the client is ?claims-aware? and the authorization server can 1333 accept pushed claims (for example, as it might have indicated by 1334 providing "requesting_party_claims" hints described in 1335 Section 3.4.1), the client has the option to _push_ claim tokens to 1336 the RPT endpoint. The claim token can reflect the client's role as a 1337 federated identity provider, a federated relying party, or an 1338 application integrated with a native identity repository. 1340 If the client is aware of the authorization server's requirements for 1341 claims through an out-of-band relationship, the client MAY push claim 1342 tokens in an initial interaction with the RPT endpoint. 1344 The client supplies claim tokens in the body of the authorization 1345 data request message by providing, in addition to the "rpt" and 1346 "ticket" properties, the following property: 1348 claim_tokens REQUIRED. An array of objects with the following 1349 properties: 1351 format REQUIRED. A string specifying the format of the 1352 accompanying claim tokens. The string MAY be a URI. 1354 token REQUIRED. A string containing the claim information in the 1355 indicated format, base64url encoded. If claim token format 1356 features are included that require special interpretation, the 1357 client and authorization server are assumed to have a prior 1358 relationship that establishes how to interpret these features. 1359 For example, if the referenced format equates to SAML 2.0 1360 assertions and the claim token contains audience restrictions, 1361 it is the joint responsibility of the client and authorization 1362 server to determine the proper audience values that enable 1363 successful token consumption. 1365 Example: 1367 POST /rpt_authorization HTTP/1.1 1368 Host: www.example.com 1369 Authorization: Bearer jwfLG53^sad$#f 1370 ... 1371 { 1372 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1373 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 1374 "claim_tokens": [ 1375 { 1376 "format": 1377 "http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken", 1378 "token": "..." 1379 } 1380 ] 1381 } 1383 This specification provides a framework for extensibility through 1384 claim token format profiling. The authorization server MAY support 1385 any number of claim token profiles, and SHOULD document the claim 1386 token profiles it supports in its configuration data. 1388 3.4.1.2.2. Client Redirects Requesting Party to Authorization Server 1390 If the client is ?claims-unaware? and the authorization server has 1391 declared a requesting party claims endpoint in its configuration 1392 data, or if the authorization server requires direct interaction with 1393 the requesting party as part of its claims-gathering process (for 1394 example, as it might have indicated through the "redirect_user" hint 1395 described in Section 3.4.1), the client has the option to _redirect_ 1396 an end-user requesting party to the requesting party claims endpoint. 1397 In this case, the authorization server might be a relying party in a 1398 federated identity interaction, or it might connect to a directory or 1399 other user repository, or even interact with the user in other ways, 1400 such as presenting a questionnaire in a web form. After this process 1401 completes, the authorization server redirects the end-user requesting 1402 party back to the client. 1404 The client constructs the request URI by adding the following 1405 parameters to the query component of the requesting party claims 1406 endpoint URI using the "application/x-www-form-urlencoded" format: 1408 client_id REQUIRED. The client's identifier issued by the 1409 authorization server. 1411 redirect_uri OPTIONAL. The URI to which the client wishes the 1412 authorization server to direct the requesting party's user agent 1413 after completing its interaction. The URI MUST be absolute, MAY 1414 contain an "application/x-www-form-urlencoded" formatted query 1415 parameter component that MUST be retained when adding addition 1416 parameters, and MUST NOT contain a fragment component. The 1417 authorization server SHOULD require all clients to register their 1418 redirection endpoint prior to utilizing the authorization 1419 endpoint. If the URI is pre-registered, this URI MUST exactly 1420 match one of the pre-registered redirection URIs, with the 1421 matching performed as described in Section 6.2.1 of [RFC3986] 1422 (Simple String Comparison). 1424 ticket REQUIRED. The permission ticket associated with the client's 1425 current request for authorization data for this requesting party. 1426 The authorization server MUST return this parameter back to when 1427 the authorization_state is need_info. 1429 state OPTIONAL. An opaque value used by the client to maintain 1430 state between the request and callback. The authorization server 1431 includes this value when redirecting the user agent back to the 1432 client. The use of this parameter is STRONGLY RECOMMENDED for 1433 preventing cross-site request forgery. 1435 Example of a request issued by a client application (line breaks are 1436 shown only for display convenience): 1438 GET /rqp_claims?client_id=some_client_id&state=abc 1439 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect HTTP/1.1 1440 Host: as.example.com 1442 At the conclusion of its interaction with the requesting party, the 1443 authorization server returns the user agent to the client adding the 1444 following parameters to the query component of the redirection URI 1445 using the "application/x-www-form-urlencoded" format: 1447 authorization_state REQUIRED. Indicates that the authorization 1448 server completed its claims-gathering interaction with the 1449 requesting party with the indicated state: 1451 claims_submitted The client is free to return to the RPT endpoint 1452 to seek authorization data once again. 1454 not_authorized The client is not authorized to have the desired 1455 authorization data added. 1457 need_info The authorization server needs additional information 1458 in order to determine whether the client is authorized to have 1459 this authorization data. This response directs the client to 1460 return to the RPT endpoint, where it might be provided with 1461 error_details hints about additional information needed. 1463 request_submitted The authorization server requires intervention 1464 by the resource owner to determine whether authorization data 1465 can be added. Further immediate interaction between the 1466 client, requesting party, and authorization server is out of 1467 scope of this specification. 1469 ticket OPTIONAL. The same permission ticket value that the client 1470 provided in the request. It MUST be present if and only if the 1471 authorization_state is need_info. 1473 state OPTIONAL. The same state value that the client provided in 1474 the request. It MUST be present if and only if the client 1475 provided it. 1477 The client MUST ignore unrecognized response parameters. If the 1478 request fails due to a missing, invalid, or mismatching redirection 1479 URI, or if the client identifier is missing or invalid, the 1480 authorization server SHOULD inform the resource owner of the error 1481 and MUST NOT automatically redirect the user agent to the invalid 1482 redirection URI. If the request fails for reasons other than a 1483 missing or invalid redirection URI, the authorization server informs 1484 the client by adding an "error" parameter to the query component of 1485 the redirection URI using the "application/x-www-form-urlencoded" 1486 format, containing one of the following ASCII error codes: 1488 invalid_request The request is missing a required parameter, 1489 includes an invalid parameter value (such as an invalid or expired 1490 ticket), includes a parameter more than once, or is otherwise 1491 malformed. 1493 server_error The authorization server encountered an unexpected 1494 condition that prevented it from fulfilling the request. (This 1495 error code is needed because an HTTP 500 (Internal Server Error) 1496 status code cannot be returned to the client via an HTTP 1497 redirect.) 1499 temporarily_unavailable The authorization server is currently unable 1500 to handle the request due to a temporary overloading or 1501 maintenance of the server. (This error code is needed because an 1502 HTTP 503 (Service Unavailable) status code cannot be returned to 1503 the client via an HTTP redirect.) 1505 4. Error Messages 1507 Ultimately the resource server is responsible for either granting the 1508 access the client attempted, or returning an error response to the 1509 client with a reason for the failure. [OAuth2] defines several error 1510 responses for a resource server to return. UMA makes use of these 1511 error responses, but requires the resource server to "outsource" the 1512 determination of some error conditions to the authorization server. 1513 This specification defines additional UMA-specific error responses 1514 that the authorization server may give to the resource server and 1515 client as they interact with it, and that the resource server may 1516 give to the client. 1518 4.1. OAuth Error Responses 1520 When a resource server or client attempts to access one of the 1521 authorization server endpoints or a client attempts to access a 1522 protected resource at the resource server, it has to make an 1523 authenticated request by including an OAuth access token in the HTTP 1524 request as described in [OAuth2] Section 7.2. 1526 If the request failed authentication, the authorization server or the 1527 resource server responds with an OAuth error message as described in 1528 this specification in Section 3. 1530 4.2. UMA Error Responses 1532 When a resource server or client attempts to access one of the 1533 authorization server endpoints or a client attempts to access a 1534 protected resource at the resource server, if the request is 1535 successfully authenticated by OAuth means, but is invalid for another 1536 reason, the authorization server or resource server responds with an 1537 UMA error response by adding the following properties to the entity 1538 body of the HTTP response: 1540 error REQUIRED. A single error code. Values for this property are 1541 defined throughout this specification. 1543 error_description OPTIONAL. Human-readable text providing 1544 additional information. 1546 error_uri OPTIONAL. A URI identifying a human-readable web page 1547 with information about the error. 1549 The following is a common error code that applies to several UMA- 1550 specified request messages: 1552 invalid_request The request is missing a required parameter, 1553 includes an invalid parameter value, includes a parameter more 1554 than once, or is otherwise malformed. The authorization server 1555 MUST respond with the HTTP 400 (Bad Request) status code. 1557 For example: 1559 HTTP/1.1 400 Bad Request 1560 Content-Type: application/json 1561 Cache-Control: no-store 1562 ... 1564 { 1565 "error": "invalid_request", 1566 "error_description": "There is already a resource with this identifier.", 1567 "error_uri": "https://as.example.com/errors/resource_exists" 1568 } 1569 5. Profiles for API Extensibility 1571 In some circumstances, it may be desirable to couple UMA roles 1572 tightly. For example, an authorization server application might also 1573 need to act as a client application in order to retrieve protected 1574 resources so that it can present to resource owners a dashboard-like 1575 user interface that accurately guides the setting of policy; it might 1576 need to access itself-as-authorization server for that purpose. For 1577 another example, the same organization might operate both an 1578 authorization server and a resource server that communicate only with 1579 each other behind a firewall, and it might seek more efficient 1580 communication methods between them. 1582 In other circumstances, it may be desirable to bind UMA flows to 1583 transport mechanisms other than HTTP even if entities remain loosely 1584 coupled. For example, in Internet of Things scenarios, Constrained 1585 Application Protocol (CoAP) may be preferred over HTTP. 1587 This section defines profiles that allow inter-role communications 1588 channels and methods to vary in these circumstances. This 1589 specification still REQUIRES authorization servers to issue PATs, 1590 AATs, and RPTs and associate authorization data with RPTs, and 1591 REQUIRES resource servers to give clients access only when RPTs are 1592 associated with sufficient authorization data. This is because, 1593 although tokens might not always appear on the wire in the normal 1594 fashion, the tokens may represent binding obligations that involve 1595 additional parties unable to take part in these optimization 1596 opportunities (see [UMA-obligations]). 1598 Where alternate communications channels are being used between 1599 independently implemented system entities, it is RECOMMENDED, for 1600 reasons of implementation interoperability, to define concrete 1601 extension profiles that build on these extensibility profiles (see 1602 Section 6.1). 1604 5.1. Protection API Extensibility Profile 1606 This section defines a profile for UMA where the authorization server 1607 and resource server roles either reside in the same system entity or 1608 otherwise have a privileged or specialized communications channel 1609 between them. Following is a summary: 1611 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1612 prot-ext-1.0 1614 o Profile author and contact information: Mark Dobrinic 1615 (mdobrinic@cozmanova.com) 1617 o Updates or obsoletes: None; this profile is new. 1619 o Security considerations: See below. 1621 o Privacy considerations: See below. 1623 o Error states: None additional. 1625 Using this profile, the resource server MAY use means other than the 1626 HTTP-based protection API that is protected by TLS and OAuth (or an 1627 OAuth-based authentication protocol) to communicate with the 1628 authorization server in all respects, including using software 1629 interfaces and methods rather than network interfaces and APIs. The 1630 authorization server MUST still issue PATs, AATs, and RPTs and 1631 associate authorization data with RPTs, and the resource server MUST 1632 still give clients access only when RPTs are associated with 1633 sufficient authorization data. Interactions with entities other than 1634 the authorization server or resource server MUST be preserved exactly 1635 as they would have if either of them were using standardized UMA 1636 APIs, unless other extensibility profiles are also in use. 1638 An authorization server using any of the opportunities afforded by 1639 this profile MUST declare use of this profile by supplying its 1640 identifying URI for one of its "uma_profiles_supported" values in its 1641 configuration data (see Section 1.4). 1643 Same-entity communication or a tight integration of entities has the 1644 opportunity to make deployments more secure by reducing possible 1645 attack vectors. However, if the entities do not use TLS but 1646 communicate across a transport layer, it is RECOMMENDED to use an 1647 alternate means of transport-layer security, for example, using DTLS 1648 in the case of a CoAP-based UMA profile. 1650 Same-entity communication or a tight integration of entities has the 1651 potential to compromise privacy by promoting the freer exchange of 1652 personal information within a deployment ecosystem. It is 1653 RECOMMENDED to account for privacy impacts in each deployment 1654 scenario. 1656 5.2. Authorization API Extensibility Profile 1658 This section defines a profile for UMA where the authorization server 1659 and client roles either reside in the same system entity or otherwise 1660 have a privileged or specialized communications channel between them. 1661 Following is a summary: 1663 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1664 authz-ext-1.0 1666 o Profile author and contact information: Mark Dobrinic 1667 (mdobrinic@cozmanova.com) 1669 o Updates or obsoletes: None; this profile is new. 1671 o Security considerations: See below. 1673 o Privacy considerations: See below. 1675 o Error states: None additional. 1677 Using this profile, the client MAY use means other than the HTTP- 1678 based authorization API that is protected by TLS and OAuth (or an 1679 OAuth-based authentication protocol) to communicate with the 1680 authorization server in all respects, including using software 1681 interfaces and methods rather than network interfaces and APIs. The 1682 authorization server MUST still issue PATs, AATs, and RPTs and 1683 associate authorization data with RPTs, and the resource server MUST 1684 still give clients access only when RPTs are associated with 1685 sufficient authorization data. Interactions with entities other than 1686 the authorization server or client MUST be preserved exactly as they 1687 would have if either of them were using standardized UMA APIs, unless 1688 other extensibility profiles are also in use. 1690 An authorization server using any of the opportunities afforded by 1691 this profile MUST declare use of this profile by supplying its 1692 identifying URI for one of its "uma_profiles_supported" values in its 1693 configuration data (see Section 1.4). 1695 Same-entity communication or a tight integration of entities has the 1696 opportunity to make deployments more secure by reducing possible 1697 attack vectors. However, if the entities do not use TLS but 1698 communicate across a transport layer, it is RECOMMENDED to use an 1699 alternate means of transport-layer security, for example, using DTLS 1700 in the case of a CoAP-based UMA profile. 1702 Same-entity communication or a tight integration of entities has the 1703 potential to compromise privacy by promoting the freer exchange of 1704 personal information within a deployment ecosystem. It is 1705 RECOMMENDED to account for privacy impacts in each deployment 1706 scenario. 1708 5.3. Resource Interface Extensibility Profile 1710 This section defines a profile for UMA where the resource server and 1711 client roles either reside in the same system entity or otherwise 1712 have a privileged or specialized communications channel between them. 1713 Following is a summary: 1715 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1716 rsrc-ext-1.0 1718 o Profile author and contact information: Mark Dobrinic 1719 (mdobrinic@cozmanova.com) 1721 o Updates or obsoletes: None; this profile is new. 1723 o Security considerations: See below. 1725 o Privacy considerations: See below. 1727 o Error states: None additional. 1729 Using this profile, the resource server MAY use means other than an 1730 HTTP-based resource interface to communicate with the authorization 1731 server in all respects, including using software interfaces and 1732 methods rather than network interfaces and APIs. The resource server 1733 MUST still give clients access only when RPTs are associated with 1734 sufficient authorization data. Interactions with entities other than 1735 the resource server or client MUST be preserved exactly as they would 1736 have if either of them were using standardized UMA APIs, unless other 1737 extensibility profiles are also in use. 1739 An authorization server involved in deployments where resource 1740 servers and clients are known to be using opportunities afforded by 1741 the resource interface extensibility profile MAY declare use of this 1742 profile by supplying its identifying URI for one of its 1743 "uma_profiles_supported" values in its configuration data (see 1744 Section 1.4). 1746 Same-entity communication or a tight integration of entities has the 1747 opportunity to make deployments more secure by reducing possible 1748 attack vectors. However, if the entities do not use TLS but 1749 communicate across a transport layer, it is RECOMMENDED to use an 1750 alternate means of transport-layer security, for example, using DTLS 1751 in the case of a CoAP-based UMA profile. 1753 Same-entity communication or a tight integration of entities has the 1754 potential to compromise privacy by promoting the freer exchange of 1755 personal information within a deployment ecosystem. It is 1756 RECOMMENDED to account for privacy impacts in each deployment 1757 scenario. 1759 6. Specifying Additional Profiles 1761 This specification defines a protocol that has optional features. 1762 For implementation interoperability and to serve particular 1763 deployment scenarios, including sector-specific ones such as 1764 healthcare or e-government, third parties may want to define profiles 1765 of UMA that restrict these options. 1767 Further, this specification creates extensibility points for RPT 1768 profiles and claim token profiles, and third parties may likewise 1769 want to define their own. Different RPT profiles could be used, for 1770 example, to change the dividing line between authorization server and 1771 resource server responsibilities in controlling access. Different 1772 claim token profiles could be used to customize sector-specific or 1773 population-specific (such as individual vs. employee) claim types 1774 that drive the types of policies resource owners could set. 1776 It is not practical for this specification to standardize all desired 1777 profiles. However, to serve overall interoperability goals, this 1778 section provides guidelines for third parties that wish to specify 1779 UMA-related profiles. In all cases, it is RECOMMENDED that profiles 1780 document the following information: 1782 o Specify a URI that uniquely identifies the profile. 1784 o Identify the responsible author and provide postal or electronic 1785 contact information. 1787 o Supply references to any previously defined profiles that the 1788 profile updates or obsoletes. 1790 o Define any additional or changed error states. 1792 o Specify any conformance and interoperability considerations. 1794 o Supply any additional security and privacy considerations. 1796 6.1. Specifying Profiles of UMA 1798 It is RECOMMENDED that profiles of UMA additionally document the 1799 following information: 1801 o Specify the set of interactions between endpoint entities involved 1802 in the profile, calling out any restrictions on ordinary UMA- 1803 conformant operations and any extension properties used in message 1804 formats. 1806 See Section 5 for examples. 1808 6.2. Specifying RPT Profiles 1810 It is RECOMMENDED that RPT profiles additionally document the 1811 following information: 1813 o Specify the keyword to be used in HTTP Authorization headers with 1814 tokens conforming to this profile. 1816 o Specify the syntax and semantics of the data that the 1817 authorization server associates with the token. 1819 o Specify how the token data is associated with, contained within, 1820 and/or retrieved by means of, the on-the-wire token string. 1822 o Specify processing rules for token data. 1824 o Identify any restrictions on grant types to be used with the token 1825 profile. 1827 See Section 3.3.2 for an example. 1829 6.3. Specifying Claim Token Format Profiles 1831 It is RECOMMENDED that claim token format profiles additionally 1832 document the following information: 1834 o Specify any related or additional error_details hints. 1836 o Specify any constraints on the claim token format vs. a standard 1837 definition for it in a specification. 1839 o Specify any mutual interpretation details of claim token formats 1840 by authorization servers and clients. 1842 7. Compatibility Notes 1844 Implementers should heed the following compatibility notes. 1846 o This specification uses a specific draft of a specification that 1847 is not yet final: [OAuth-introspection] (draft 04); the reference 1848 will be updated until this "UMA V1.0 candidate" specification is 1849 finalized. While every effort will be made to prevent breaking 1850 changes to this specification, should they occur, UMA 1851 implementations should continue to use the specifically referenced 1852 draft version in preference to the final versions, unless using a 1853 possible future UMA profile or specification that updates the 1854 relevant references. 1856 o In cases where this specification is not prescriptive regarding 1857 conformance or interoperability, any common or best practices for 1858 implementation will be documented in the [UMA-Impl] over time. 1860 8. Security Considerations 1862 As a profile of OAuth, this specification relies mainly on OAuth 1863 security mechanisms as well as transport-level encryption. Thus, 1864 implementers are strongly advised to read the security considerations 1865 in [OAuth2] (Section 10) and [OAuth-bearer] (Section 5) along with 1866 the security considerations of any other OAuth token-defining 1867 specifications in use, along with the entire [OAuth-threat] 1868 specification, and apply the countermeasures described therein. As 1869 well, since this specification builds on [OAuth-resource-reg], 1870 implementers should also take into account the security 1871 considerations in that specification. 1873 The following sections describe additional security considerations. 1875 8.1. Redirection and Impersonation Threats 1877 This section discusses threats related to UMA's nature as an protocol 1878 enabling autonomous (non-resource-owner) requesting parties to gain 1879 authorized access to sensitive resources, including through the 1880 process of claims-gathering redirection. 1882 Like ordinary OAuth redirection, UMA redirection for the purpose of 1883 gathering claims from an end-user requesting party (described in 1884 Section 3.4.1.2.2) creates the potential for cross-site request 1885 forgery (CSRF) through an open redirect if the authorization server 1886 does not force the client to pre-register its redirection endpoint, 1887 and server-side artifact tampering if the client does not avail 1888 itself of the state parameter. The client SHOULD check that the 1889 ticket value returned by an authorization server after a redirect is 1890 completed has not been maliciously changed, for example by a man in 1891 the browser (MITB), by using the state parameter. (See the 1892 [UMA-Impl] for advice on ways to accomplish this.) Sections 4.4.1.8, 1893 4.4.2.5, and 5.3.5 of [OAuth-threat] are apropos for the UMA claims- 1894 gathering redirection flow as well. 1896 When a client redirects an end-user requesting party to the 1897 requesting party claims endpoint, the client provides no a priori 1898 context to the authorization server about which user is appearing at 1899 the endpoint, other than implicitly through the permission ticket. 1900 Since the authorization server is free to gather any claims it 1901 wishes, the effect is to "late-bind" them to the permission ticket 1902 and the state string provided by the client, with the effect of 1903 enabling the authorization server not to trust client-asserted 1904 claims. This is a desirable result and reflects one reason why the 1905 authorization server might choose to demand use of the redirect flow 1906 over the push flow. However, the client has the opportunity to 1907 switch end-users -- say, enabling malicious end-user Carlos to 1908 impersonate the original end-user Bob who approved the minting of of 1909 the AAT -- after the redirect completes and before it returns to the 1910 RPT endpoint to seek authorization data. 1912 Another issue concerns the exposure of the RPT to an autonomous 1913 requesting party, which could maliciously pass the token to an 1914 unauthorized party. 1916 To mitigate requesting-party switching and RPT exposure threats, 1917 consider the following strategies. 1919 o Require that the Requesting Party (as defined in 1920 [UMA-obligations], meaning this party is able to take on legal 1921 obligations) legitimately represent the wielder of the bearer 1922 token. This solution is based on a legal or contractual approach, 1923 and therefore does not reduce the risk from the technical 1924 perspective. 1926 o The authorization server, possibly with input from the resource 1927 owner, can implement tighter time-to-live strategies around the 1928 authorization data in RPTs. This is a classic approach with 1929 bearer tokens that helps to limit a malicious party's ability to 1930 intercept and use the bearer token. In the same vein, the 1931 authorization server could require claims to have a reasonable 1932 degree of freshness (which would require a custom claims profile). 1934 o The strongest strategy is to disallow bearer-type RPTs within the 1935 UMA profile being deployed, by providing or requiring an RPT 1936 profile that requires use of a holder-of-key approach. In this 1937 way, the wielder of the token must engage in a live session for 1938 proof-of-possession. A less complex version of this strategy is 1939 to "elevate trust" in the requesting party by requiring a stronger 1940 authentication context, forcing step-up authentication by the 1941 requesting party at run time. 1943 8.2. Client Authentication 1945 Along with TLS, UMA requires OAuth, or any OAuth-based authentication 1946 protocol, as the security mechanism for its standardized APIs. The 1947 UMA resource server acts in the role of an OAuth client at the 1948 authorization server's protection API, and the UMA client acts in the 1949 role of an OAuth client at the authorization server's authorization 1950 API. While it is possible to use any profile of OAuth for this 1951 protection, it is RECOMMENDED for the authorization server to use 1952 OpenID Connect, and to use its mechanisms for stronger client 1953 authentication at the token endpoint, in order to strengthen the 1954 authentication of OAuth clients. Section 16 of [OIDCCore] provides 1955 more information on OpenID Connect security considerations. 1957 Clients using the OAuth implicit grant type carry particular 1958 vulnerabilities in OAuth, and OpenID Connect doesn't help because of 1959 the nature of the implicit grant flow. UMA scenarios are vulnerable 1960 as well. For example, an "implicit client" might require the 1961 retrieval of AATs more frequently, for each browser on each platform. 1962 An attacker can initiate a spear phishing attack on the requesting 1963 party with a link to a malicious website, relying on the requesting 1964 party to authenticate to the authorization server through an email- 1965 based identity provider in order to receive the AAT. The site can 1966 impersonate the requesting party using the browser client's client ID 1967 in an OpenID Connect implicit request to the UMA authorization 1968 server. If the requesting party had previously given consent for an 1969 AAT to be issued, this attempt will likely succeed. The subsequently 1970 issued AAT and permission ticket for an attempted resource access 1971 could potentially be used for RPT retrieval and authorization data 1972 issuance. 1974 A number of mitigation strategies are possible. 1976 o The authorization server could penalize or disallow use of the 1977 implicit grant flow. This could be done at a variety of levels: 1979 * Enabling resource owners to define policies controlling the use 1980 of such clients 1982 * Setting system-default policies controlling their use 1984 * Participating in mutual agreements with other parties that 1985 admit only suitably secure client applications to interact with 1986 service operators 1988 o The authorization server could support dynamic client registration 1989 at the client instance level, such that each instance receives a 1990 unique client_id and secret. The client can then use the 1991 authorization code flow and have at least some form of client 1992 authentication. However, this is easier for a mobile app than for 1993 a browser-based HTML app. 1995 8.3. JSON Usage 1997 This specification defines a number of data formats based on [JSON]. 1998 As a subset of the JavaScript scripting language, JSON data SHOULD be 1999 consumed through a process that does not dynamically execute it as 2000 code, to avoid malicious code execution. One way to achieve this is 2001 to use a JavaScript interpreter rather than the built-in JavaScript 2002 eval() function. 2004 8.4. Profiles, Binding Obligations, and Trust Establishment 2006 Parties operating and using UMA software entities have opportunities 2007 to establish agreements about mutual rights, responsibilities, and 2008 common interpretations of UMA constructs for consistent and expected 2009 software behavior. These agreements can be used to improve the 2010 parties' respective security postures, and written profiles are a key 2011 mechanism for conveying and enforcing these agreements. Section 6 2012 discusses profiling. Section 5 discusses profiling for 2013 extensibility. [UMA-obligations] discusses the development of 2014 binding obligations. 2016 9. Privacy Considerations 2018 The authorization server comes to be in possession of resource set 2019 information that may reveal information about the resource owner, 2020 which the authorization server's trust relationship with the resource 2021 server is assumed to accommodate. However, the client is a less- 2022 trusted party -- in fact, entirely untrustworthy until authorization 2023 data is associated with its RPT. The more information about a 2024 resource set that is registered, the more risk of privacy compromise 2025 there is through a less-trusted authorization server. 2027 The primary privacy duty of UMA's design is to the resource owner. 2028 However, privacy considerations affect the requesting party as well. 2029 This can be seen in the issuance of an AAT, which represents the 2030 approval of a requesting party for a client to engage with an 2031 authorization server to perform tasks needed for obtaining 2032 authorization, possibly including pushing claim tokens. 2034 Parties operating and using UMA software entities have opportunities 2035 to establish agreements about mutual rights, responsibilities, and 2036 common interpretations of UMA constructs for consistent and expected 2037 software behavior. These agreements can be used to improve the 2038 parties' respective privacy postures. For information about the 2039 additional technical, operational, and legal elements of trust 2040 establishment, see [UMA-obligations]. Additional considerations 2041 related to Privacy by Design concepts are discussed in [UMA-PbD]. 2043 10. IANA Considerations 2045 This document makes the following requests of IANA. 2047 10.1. JSON Web Token Claims Registration 2049 This specification registers the claim defined in Section 3.3.2. 2051 10.1.1. Registry Contents 2053 o Claim name: permissions 2055 o Claim description: Array of objects, each describing a set of 2056 scoped, time-limitable entitlements to a resource set 2058 o Change controller: Kantara Initiative User-Managed Access Work 2059 Group - wg-uma@kantarainitiative.org 2061 o Specification document: Section 3.3.2 in this document 2063 10.2. Well-Known URI Registration 2065 This specification registers the well-known URI defined in 2066 Section 1.4. 2068 10.2.1. Registry Contents 2070 o URI suffix: uma-configuration 2072 o Change controller: Kantara Initiative User-Managed Access Work 2073 Group - wg-uma@kantarainitiative.org 2075 o Specification document: Section 1.4 in this document 2077 11. Acknowledgments 2079 The following people made significant text contributions to the 2080 specification: 2082 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 2084 o Mark Dobrinic, Cozmanova 2086 o George Fletcher, AOL 2088 o Lukasz Moren, Cloud Identity Ltd 2090 o Christian Scholz, COMlounge GmbH (former editor) 2092 o Mike Schwartz, Gluu 2094 o Jacek Szpot, Newcastle University 2095 Additional contributors to this specification include the Kantara UMA 2096 Work Group participants, a list of whom can be found at 2097 [UMAnitarians]. 2099 12. References 2101 12.1. Normative References 2103 [DynClientReg] 2104 Richer, J., "OAuth 2.0 Core Dynamic Client Registration", 2105 December 2014, 2106 . 2108 [JSON] Bray, T., "The JavaScript Object Notation (JSON) Data 2109 Interchange Format", March 2014, 2110 . 2112 [JWT] Jones, M., "JSON Web Token (JWT)", December 2014, 2113 . 2116 [OAuth-bearer] 2117 "The OAuth 2.0 Authorization Framework: Bearer Token 2118 Usage", October 2012, 2119 . 2121 [OAuth-introspection] 2122 Richer, J., "OAuth Token Introspection", December 2014, 2123 . 2126 [OAuth-resource-reg] 2127 Hardjono, T., "OAuth 2.0 Resource Set Registration", 2128 February 2015, . 2131 [OAuth-threat] 2132 Lodderstedt, T., "OAuth 2.0 Threat Model and Security 2133 Considerations", January 2013, 2134 . 2136 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 2137 October 2012, . 2139 [OIDCCore] 2140 Sakimura, N., "OpenID Connect Core 1.0 incorporating 2141 errata set 1", November 2014, 2142 . 2144 [OIDCDynClientReg] 2145 Sakimura, N., "OpenID Connect Dynamic Client Registration 2146 1.0 incorporating errata set 1", November 2014, 2147 . 2150 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2151 Requirement Levels", BCP 14, RFC 2119, March 1997. 2153 [RFC3986] Berners-Lee, T., "Uniform Resource Identifier (URI): 2154 Generic Syntax", January 2005, 2155 . 2157 [RFC6711] Johansson, L., "An IANA Registry for Level of Assurance 2158 (LoA) Profiles", August 2012, 2159 . 2161 [hostmeta] 2162 Hammer-Lahav, E., "Web Host Metadata", October 2011, 2163 . 2165 12.2. Informative References 2167 [UMA-Impl] 2168 Maler, E., "UMA Implementer's Guide", December 2014, 2169 . 2172 [UMA-PbD] Maler, E., "Privacy by Design Implications of UMA", 2173 December 2013, 2174 . 2177 [UMA-casestudies] 2178 Maler, E., "UMA Case Studies", April 2014, 2179 . 2182 [UMA-obligations] 2183 Maler, E., "Binding Obligations on UMA Participants", 2184 January 2013, . 2187 [UMA-usecases] 2188 Maler, E., "UMA Scenarios and Use Cases", October 2010, 2189 . 2192 [UMAnitarians] 2193 Maler, E., "UMA Participant Roster", December 2014, 2194 . 2197 Authors' Addresses 2199 Thomas Hardjono (editor) 2200 MIT 2202 Email: hardjono@mit.edu 2204 Eve Maler 2205 ForgeRock 2207 Email: eve.maler@forgerock.com 2209 Maciej Machulak 2210 Cloud Identity 2212 Email: maciej.machulak@cloudidentity.co.uk 2214 Domenico Catalano 2215 Oracle 2217 Email: domenico.catalano@oracle.com