idnits 2.17.1 draft-hardjono-oauth-umacore-12.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 (February 23, 2015) is 3349 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: August 27, 2015 ForgeRock 6 M. Machulak 7 Cloud Identity 8 D. Catalano 9 Oracle 10 February 23, 2015 12 User-Managed Access (UMA) Profile of OAuth 2.0 13 draft-hardjono-oauth-umacore-12 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 August 27, 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 . . . . . . . 15 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 . . . . . . . . . . . . . . . . . 21 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 the resource 282 server 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 permission A scope of access over a particular resource set at a 299 particular resource server that is being requested by, or 300 granted to, a requesting party. In authorization policy 301 terminology, a permission is an entitlement that includes a 302 "subject" (requesting party), "verbs" (one or more scopes of 303 access), and an "object" (resource set). A permission is one 304 example of authorization data that an authorization server may 305 add to a requesting party token. 307 permission ticket A correlation handle that is conveyed from an 308 authorization server to a resource server, from a resource 309 server to a client, and ultimately from a client back to an 310 authorization server, to enable the authorization server to 311 assess the correct policies to apply to a request for 312 authorization data. 314 token A packaged collection of data meant to be transmitted to 315 another entity. A token could be used for authorized access 316 (an "access token" such as an UMA RPT, PAT, or AAT), or could 317 be used to exchange information about a subject (a "claim 318 token" such as one that is conveyed by a client to an 319 authorization server while seeking authorization data). 321 1.3. Achieving Distributed Access Control 323 The software components that fill the roles of UMA authorization 324 servers, resource servers, and clients respectively are intended to 325 work in an interoperable fashion when each is operated by an 326 independent party (for example, different organizations). For this 327 reason, UMA specifies communications channels that the authorization 328 server MUST implement as HTTP-based APIs that MUST use TLS and OAuth 329 (or OAuth-based authentication protocol) protection, and that the 330 resource server MUST implement as an HTTP-based interface. UMA's use 331 of TLS is governed by Section 1.6 of [OAuth2], which discusses 332 deployment and adoption characteristics of different TLS versions. 334 For those OAuth protection use cases where an identity token is 335 desired in addition to an access token, it is RECOMMENDED that an 336 OAuth-based authentication protocol such as OpenID Connect be used. 338 It is also REQUIRED, in turn, for resource servers and clients on the 339 requesting side of UMA interactions to use these channels, unless a 340 profile is being used that enables API extensibility. The profiles 341 that enable such alternatives are provided in Section 5. 343 1.3.1. Protection API 345 The authorization server MUST present an HTTP-based protection API, 346 protected by TLS and OAuth (or an OAuth-based authentication 347 protocol), for use by resource servers. The authorization server 348 thus has an OAuth token endpoint and authorization endpoint. The 349 authorization server MUST declare all of its protection API endpoints 350 in its configuration data (see Section 1.4). 352 The protection API consists of three endpoints: 354 o Resource set registration endpoint as defined by 355 [OAuth-resource-reg] 357 o Permission registration endpoint as defined by Section 3.2 359 o Token introspection endpoint as defined by [OAuth-introspection] 360 and Section 3.3.1 362 An entity seeking protection API access MUST have the scope 363 "uma_protection". An access token with at least this scope is called 364 a protection API token (PAT) and an entity that can acquire an access 365 token with this scope is by definition a resource server. A single 366 entity can serve in both resource server and client roles if it has 367 access tokens with the appropriate OAuth scopes. If a request to an 368 endpoint fails due to an invalid, missing, or expired PAT, or 369 requires higher privileges at this endpoint than provided by the PAT, 370 the authorization server responds with an OAuth error. 372 The authorization server MUST support the OAuth bearer token profile 373 for PAT issuance, and MAY support other OAuth token profiles. It 374 MUST declare all supported token profiles and grant types for PAT 375 issuance in its configuration data. Any OAuth authorization grant 376 type might be appropriate depending on circumstances; for example, 377 the client credentials grant is useful in the case of an organization 378 acting as a resource owner. [UMA-Impl] discusses grant options 379 further. 381 A PAT binds a resource owner, a resource server the owner uses for 382 resource management, and an authorization server the owner uses for 383 protection of resources at this resource server. It is not specific 384 to any client or requesting party. The issuance of a PAT represents 385 the approval of the resource owner for this resource server to use 386 this authorization server for protecting some or all of the resources 387 belonging to this resource owner. 389 1.3.2. Authorization API 391 The authorization server MUST present an HTTP-based authorization 392 API, protected by TLS and OAuth (or an OAuth-based authentication 393 protocol), for use by clients. The authorization server thus has an 394 OAuth token endpoint and authorization endpoint. The authorization 395 server MUST declare its authorization API endpoint in its 396 configuration data (see Section 1.4). 398 The authorization API consists of one endpoint: 400 o RPT endpoint as defined in Section 3.4.1 402 An entity seeking authorization API access MUST have the scope 403 "uma_authorization". An access token with at least this scope is 404 called an authorization API token (AAT) and an entity that can 405 acquire an access token with this scope is by definition a client. A 406 single entity can serve in both resource server and client roles if 407 it has access tokens with the appropriate OAuth scopes. If a request 408 to an endpoint fails due to an invalid, missing, or expired AAT, or 409 requires higher privileges at this endpoint than provided by the AAT, 410 the authorization server responds with an OAuth error. 412 The authorization server MUST support the OAuth bearer token profile 413 for AAT issuance, and MAY support other OAuth token profiles. It 414 MUST declare all supported token profiles and grant types for AAT 415 issuance in its configuration data. Any OAuth authorization grant 416 type might be appropriate depending on circumstances; for example, 417 the client credentials grant is useful in the case of an organization 418 acting as a requesting party. [UMA-Impl] discusses grant options 419 further. 421 An AAT binds a requesting party, a client being used by that party, 422 and an authorization server that protects resources this client is 423 seeking access to on this requesting party's behalf. It is not 424 specific to any resource server or resource owner. The issuance of 425 an AAT represents the approval of this requesting party for this 426 client to engage with this authorization server to supply claims, ask 427 for authorization, and perform any other tasks needed for obtaining 428 authorization for access to resources at all resource servers that 429 use this authorization server. The authorization server is able to 430 manage future processes of authorization and claims-caching 431 efficiently for this client/requesting party pair across all resource 432 servers they try to access; however, these management processes are 433 outside the scope of this specification. 435 1.3.3. Protected Resource Interface 437 The resource server MAY present to clients whatever HTTP-based APIs 438 or endpoints it wishes. To protect any of its resources available in 439 this fashion using UMA, it MUST require a requesting party token 440 (RPT) with sufficient authorization data for access. 442 This specification defines one RPT profile, call "bearer" (see 443 Section 3.3.2), which the authorization server MUST support. It MAY 444 support additional RPT profiles, and MUST declare all supported RPT 445 profiles in its configuration data (see Section 1.4). 447 An RPT binds a requesting party, the client being used by that party, 448 the resource server at which protected resources of interest reside, 449 and the authorization server that protects those resources. It is 450 not specific to a single resource owner, though its internal 451 components are likely to be bound in practice to individual resource 452 owners, depending on the RPT profile in use. 454 1.3.4. Time-to-Live Considerations 456 The authorization server has the opportunity to manage the validity 457 periods of access tokens that it issues, their corresponding refresh 458 tokens where applicable, the individual authorization data components 459 associated with RPTs where applicable, and even the client 460 credentials that it issues. Different time-to-live strategies may be 461 suitable for different resource sets and scopes of access, and the 462 authorization server has the opportunity to give the resource owner 463 control over lifetimes of tokens and authorization data issued on 464 their behalf through policy. These options are all outside the scope 465 of this specification. 467 1.4. Authorization Server Configuration Data 469 The authorization server MUST provide configuration data in a JSON 470 document that resides in an /uma-configuration directory at its host- 471 meta [hostmeta] location. The configuration data documents 472 conformance options and endpoints supported by the authorization 473 server. 475 The configuration data has the following properties. 477 version 478 REQUIRED. The version of the UMA core protocol to which this 479 authorization server conforms. The value MUST be the string 480 "1.0". 482 issuer 483 REQUIRED. A URI with no query or fragment component that the 484 authorization server asserts as its issuer identifier. This 485 value MUST be identical to the web location of the 486 configuration data minus the host-meta [hostmeta] and /uma- 487 configuration path components 489 pat_profiles_supported 490 REQUIRED. OAuth access token types supported by this 491 authorization server for PAT issuance. The property value is 492 an array of string values, where each string value (which MAY 493 be a URI) is a token type. Non-URI token type strings defined 494 by OAuth token-defining specifications are privileged. For 495 example, the type "bearer" stands for the OAuth bearer token 496 type defined in [OAuth-bearer]. The authorization server is 497 REQUIRED to support "bearer", and to supply this value 498 explicitly. The authorization server MAY declare its support 499 for additional PAT profiles. 501 aat_profiles_supported 502 REQUIRED. OAuth access token types supported by this 503 authorization server for AAT issuance. The property value is 504 an array of string values, where each string value (which MAY 505 be a URI) is a token type. Non-URI token type strings defined 506 by OAuth token-defining specifications are privileged. For 507 example, the type "bearer" stands for the OAuth bearer token 508 type defined in [OAuth-bearer]. The authorization server is 509 REQUIRED to support "bearer", and to supply this value 510 explicitly. The authorization server MAY declare its support 511 for additional AAT profiles. 513 rpt_profiles_supported 514 REQUIRED. Profiles supported by this authorization server for 515 RPT issuance. The property value is an array of string values, 516 where each string value is a URI identifying an RPT profile. 517 The authorization server is REQUIRED to support the "bearer" 518 RPT profile defined in Section 3.3.2, and to supply its 519 identifying URI explicitly. The authorization server MAY 520 declare its support for additional RPT profiles. 522 pat_grant_types_supported 523 REQUIRED. OAuth grant types supported by this authorization 524 server in issuing PATs. The property value is an array of 525 string values, where each string value (which MAY be a URI) is 526 a grant type. Non-URI token type strings defined by OAuth 527 grant type-defining specifications are privileged. For 528 example, the type "authorization_code" stands for the OAuth 529 authorization code grant type defined in [OAuth2]. 531 aat_grant_types_supported 532 REQUIRED. OAuth grant types supported by this authorization 533 server in issuing AATs. The property value is an array of 534 string values, where each string value (which MAY be a URI) is 535 a grant type. Non-URI token type strings defined by OAuth 536 grant type-defining specifications are privileged. For 537 example, the type "authorization_code" stands for the OAuth 538 authorization code grant type defined in [OAuth2]. 540 claim_token_profiles_supported 541 OPTIONAL. Claim token format profiles supported by this 542 authorization server. The property value is an array of string 543 values, where each string value MAY be a URI. 545 uma_profiles_supported 546 OPTIONAL. UMA profiles supported by this authorization server. 547 The property value is an array of string values, where each 548 string value is a URI identifying an UMA profile. Examples of 549 UMA profiles are the API extensibility profiles defined in 550 Section 5. 552 dynamic_client_endpoint 553 OPTIONAL. The endpoint to use for performing dynamic client 554 registration in the case of the use of [DynClientReg], or 555 alternatively the reserved string "openid" in the case of the 556 use of [OIDCDynClientReg]. In the latter case, it is presumed 557 that the resource server or client will discover the dynamic 558 client registration endpoint from the authorization server's 559 published OpenID Provider Configuration Information. The 560 presence of this property indicates authorization server 561 support for dynamic client registration feature; its absence 562 indicates a lack of support. 564 token_endpoint 565 REQUIRED. The endpoint URI at which the resource server or 566 client asks the authorization server for a PAT or AAT. A 567 requested scope of "uma_protection" results in a PAT. A 568 requested scope of "uma_authorization" results in an AAT. 569 Usage of this endpoint is defined by [OAuth2]. 571 authorization_endpoint 572 REQUIRED. The endpoint URI at which the resource server 573 gathers the consent of the end-user resource owner or the 574 client gathers the consent of the end-user requesting party for 575 issuance of a PAT or AAT respectively, if the 576 "authorization_code" grant type is used. Usage of this 577 endpoint is defined by [OAuth2]. 579 requesting_party_claims_endpoint 580 OPTIONAL. The endpoint URI at which the authorization server 581 interacts with the end-user requesting party to gather claims. 582 If this property is absent, the authorization server does not 583 interact with the end-user requesting party for claims 584 gathering. 586 introspection_endpoint 587 REQUIRED. The endpoint URI at which the resource server 588 introspects an RPT presented to it by a client. Usage of this 589 endpoint is defined by [OAuth-introspection] and Section 3.3.1. 590 A valid PAT MUST accompany requests to this protected endpoint. 592 resource_set_registration_endpoint 593 REQUIRED. The endpoint URI at which the resource server 594 registers resource sets to put them under authorization manager 595 protection. Usage of this endpoint is defined by 597 [OAuth-resource-reg] and Section 2. A valid PAT MUST accompany 598 requests to this protected endpoint. 600 permission_registration_endpoint 601 REQUIRED. The endpoint URI at which the resource server 602 registers a requested permission that would suffice for a 603 client's access attempt. Usage of this endpoint is defined by 604 Section 3.2. A valid PAT MUST accompany requests to this 605 protected endpoint. 607 rpt_endpoint 608 REQUIRED. The endpoint URI at which the client asks for 609 authorization data. Usage of this endpoint is defined in 610 Section 3.4. A valid AAT and a permission ticket MUST, and an 611 RPT MAY, accompany requests to this protected endpoint. 613 Example of authorization server configuration data that resides at 614 https://example.com/.well-known/uma-configuration (note the use of 615 https: for endpoints throughout): 617 { 618 "version":"1.0", 619 "issuer":"https://example.com", 620 "pat_profiles_supported":["bearer"], 621 "aat_profiles_supported":["bearer"], 622 "rpt_profiles_supported": 623 ["https://docs.kantarainitiative.org/uma/profiles/uma-token-bearer-1.0"], 624 "pat_grant_types_supported":["authorization_code"], 625 "aat_grant_types_supported":["authorization_code"], 626 "claim_token_profiles_supported":["https://example.com/claims/formats/token1"], 627 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", 628 "token_endpoint":"https://as.example.com/token_uri", 629 "authorization_endpoint":"https://as.example.com/authz_uri", 630 "requesting_party_claims_endpoint":"https://as.example.com/rqp_claims_uri", 631 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri", 632 "introspection_endpoint":"https://as.example.com/rs/status_uri", 633 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri", 634 "rpt_endpoint":"https://as.example.com/client/rpt_uri" 635 } 637 Where this specification does not already require optional features 638 to be documented, it is RECOMMENDED that authorization server 639 deployers document any profiled or extended features explicitly and 640 use configuration data to indicate their usage. 642 2. Protecting a Resource 644 The resource owner, resource server, and authorization server perform 645 the following actions to put resources under protection. This list 646 assumes that the resource server has discovered the authorization 647 server's configuration data and endpoints as needed. 649 1. The authorization server issues client credentials to the 650 resource server. It is OPTIONAL for the client credentials to be 651 provided dynamically through [DynClientReg] or 652 [OIDCDynClientReg]; alternatively, they MAY use a static process. 654 2. The resource server acquires a PAT from the authorization server. 655 It is OPTIONAL for the resource owner to introduce the resource 656 server to the authorization server dynamically (for example, 657 through a "NASCAR"-style user interface where the resource owner 658 selects a chosen authorization server); alternatively, they MAY 659 use a static process that may or may not directly involve the 660 resource owner at introduction time. 662 3. In an ongoing fashion, the resource server registers any resource 663 sets with the authorization server for which it intends to 664 outsource protection, using the resource set registration 665 endpoint of the protection API (see [OAuth-resource-reg]). 667 Note: The resource server is free to offer the option to protect any 668 subset of the resource owner's resources using different 669 authorization servers or other means entirely, or to protect some 670 resources and not others. Additionally, the choice of protection 671 regimes can be made explicitly by the resource owner or implicitly by 672 the resource server. Any such partitioning by the resource server or 673 owner is outside the scope of this specification. 675 Once a resource set has been placed under authorization server 676 protection through the registration of a resource set description for 677 it, and until such a description's deletion by the resource server, 678 the resource server MUST limit access to corresponding resources, 679 requiring sufficient authorization data associated with client- 680 presented RPTs by the authorization server (see Section 3.1.2). 682 3. Getting Authorization and Accessing a Resource 684 An authorization server orchestrates and controls clients' access (on 685 their requesting parties' behalf) to a resource owner's protected 686 resources at a resource server, under conditions dictated by that 687 resource owner. 689 The process of getting authorization and accessing a resource always 690 begins with the client attempting access at a protected resource 691 endpoint at the resource server. How the client came to learn about 692 this endpoint is out of scope for this specification. The resource 693 owner might, for example, have advertised its availability publicly 694 on a blog or other website, listed it in a discovery service, or 695 emailed a link to a particular intended requesting party. 697 The resource server responds to the client's access request with 698 whatever its application-specific resource interface defines as a 699 success response, either immediately if the client has sufficient 700 authorization, or having first performed one or more embedded 701 interactions with the authorization server and client in the case of 702 a failed access attempt. 704 A high-level summary of the interactions is as follows. The 705 recipient of each request message SHOULD respond unless it detects a 706 security concern, such as a suspected denial of service attack that 707 can be mitigated by rate limiting. 709 o The client attempts to access a protected resource. 711 * If the access attempt is unaccompanied by an RPT, the resource 712 server registers a requested permission at the authorization 713 server that would suffice for the access attempt, and then 714 responds with an HTTP 403 (Forbidden) response, a permission 715 ticket, and instructions on where to go to obtain an RPT and 716 authorization data. 718 * If the access attempt is accompanied by an RPT, the resource 719 server checks the RPT's status. 721 + If the RPT is invalid, or if the RPT is valid but has 722 insufficient authorization data, the resource server 723 registers a requested permission at the authorization server 724 that would suffice for the access attempt, and then responds 725 with an HTTP 403 (Forbidden) response, a permission ticket, 726 and instructions on where to go to obtain a valid RPT and 727 authorization data for it. 729 + If the RPT is valid, and if the authorization data 730 associated with the token is sufficient for allowing access, 731 the resource server responds with an HTTP 2xx (Success) 732 response. 734 o If the client received a 403 response and a permission ticket, it 735 asks the authorization server for authorization data that matches 736 the ticket using the RPT endpoint of the authorization API. If 737 the authorization server needs requesting party claims in order to 738 assess this client's authorization, it engages in a claims- 739 gathering flow. 741 * If the client does not already have an AAT at the appropriate 742 authorization server to be able to use its authorization API, 743 it first obtains one. 745 The interactions are described in detail in the following sections. 747 3.1. Client Attempts to Access Protected Resource 749 This interaction assumes that the resource server has previously 750 registered one or more resource sets that correspond to the resource 751 the client is attempting to access. 753 The client attempts to access a protected resource (for example, when 754 an end-user requesting party clicks on a thumbnail representation of 755 the resource to retrieve a larger version). It is expected to 756 discover, or be provisioned or configured with, knowledge of the 757 protected resource and its location out of band. Further, the client 758 is expected to acquire its own knowledge about the application- 759 specific methods made available by the resource server for operating 760 on this protected resource (such as viewing it with a GET method, or 761 transforming it with some complex API call). 763 The access attempt either is or is not accompanied by an RPT. 765 3.1.1. Client Presents No RPT 767 Example of a request carrying no RPT: 769 GET /album/photo.jpg HTTP/1.1 770 Host: photoz.example.com 771 ... 773 If the client does not present an RPT with the request, the resource 774 server uses the protection API to register a requested permission 775 with the authorization server that would suffice for the access 776 attempt (see Section 3.2), and receives a permission ticket back in 777 response. It then responds to the client. It SHOULD respond with 778 the HTTP 403 (Forbidden) status code, providing the authorization 779 server's URI in an "as_uri" property in the header, along with the 780 just-received permission ticket in the body in a JSON-encoded 781 "ticket" property. Responses that use any code other than 403 are 782 undefined by this specification; any common or best practices for 783 returning other status codes will be documented in the [UMA-Impl]. 785 For example: 787 HTTP/1.1 403 Forbidden 788 WWW-Authenticate: UMA realm="example", 789 as_uri="https://as.example.com" 791 { 792 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 793 } 794 ... 796 3.1.2. Client Presents RPT 798 Example of a request carrying an RPT using the UMA "bearer" RPT 799 profile: 801 GET /album/photo.jpg HTTP/1.1 802 Authorization: Bearer vF9dft4qmT 803 Host: photoz.example.com 804 ... 806 If the client presents an RPT with its request, the resource server 807 MUST determine the RPT's status (see Section 3.3) before responding. 809 If the RPT is invalid, or if the RPT is valid but has insufficient 810 authorization data for the type of access sought, the resource server 811 uses the protection API to register a requested permission with the 812 authorization server that would suffice for the access attempt (see 813 Section 3.2), and receives a permission ticket back in response. It 814 then responds to the client with the HTTP 403 (Forbidden) status 815 code, providing the authorization server's URI in an "as_uri" 816 property in the header, along with the just-received permission 817 ticket in the body in a JSON-encoded "ticket" property. 819 Example of the resource server's response after having registered a 820 requested permission and received a ticket: 822 HTTP/1.1 403 Forbidden 823 WWW-Authenticate: UMA realm="example", 824 as_uri="https://as.example.com" 825 error="insufficient_scope" 827 { 828 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 829 } 830 If the RPT's status is associated with authorization data that is 831 sufficient for the access sought by the client, the resource server 832 MUST give access to the desired resource. 834 Example of the resource server's response after having determined 835 that the RPT is valid and associated with sufficient authorization 836 data: 838 HTTP/1.1 200 OK 839 Content-Type: image/jpeg 840 ... 842 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 843 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 844 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 845 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 847 The resource server MUST NOT give access where the token's status is 848 not associated with sufficient authorization data for the attempted 849 scope of access. 851 3.2. Resource Server Registers Requested Permission With Authorization 852 Server 854 The resource server uses the protection API's permission registration 855 endpoint to register a requested permission with the authorization 856 server that would suffice for the client's access attempt. The 857 authorization server returns a permission ticket for the resource 858 server to give to the client in its response. The PAT provided in 859 the API request implicitly identifies the resource owner ("subject") 860 to which the permission applies. 862 Note: The resource server is free to choose the extent of the 863 requested permission that it registers, as long as it minimally 864 suffices for the access attempted by the client. For example, it can 865 choose to register a permission that covers several scopes or a 866 resource set that is greater in extent than the specific resource 867 that the client attempted to access. Likewise, the authorization 868 server is ultimately free to choose to partially fulfill the elements 869 of a permission request based on incomplete satisfaction of policy 870 criteria, or not to fulfill the request. 872 The resource server uses the POST method at the endpoint. The body 873 of the HTTP request message contains a JSON object providing the 874 requested permission, using a format derived from the scope 875 description format specified in [OAuth-resource-reg], as follows. 876 The object has the following properties: 878 resource_set_id REQUIRED. The identifier for a resource set to 879 which this client is seeking access. The identifier MUST 880 correspond to a resource set that was previously registered. 882 scopes REQUIRED. An array referencing one or more identifiers of 883 scopes to which access is needed for this resource set. Each 884 scope identifier MUST correspond to a scope that was registered by 885 this resource server for the referenced resource set. 887 Example of an HTTP request that registers a requested permission at 888 the authorization server's permission registration endpoint, with a 889 PAT in the header: 891 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 892 Content-Type: application/json 893 Host: as.example.com 894 Authorization: Bearer 204c69636b6c69 896 { 897 "resource_set_id": "112210f47de98100", 898 "scopes": [ 899 "http://photoz.example.com/dev/actions/view", 900 "http://photoz.example.com/dev/actions/all" 901 ] 902 } 904 If the registration request is successful, the authorization server 905 responds with an HTTP 201 (Created) status code and includes the 906 "ticket" property in the JSON-formatted body. 908 The permission ticket is a short-lived opaque structure whose form is 909 determined by the authorization server. The ticket value MUST be 910 securely random (for example, not merely part of a predictable 911 sequential series), to avoid denial-of-service attacks. Since the 912 ticket is an opaque structure from the point of view of the client, 913 the authorization server is free to include information regarding 914 expiration time or any other information within the opaque ticket for 915 its own consumption. When the client subsequently uses the 916 authorization API to ask the authorization server for authorization 917 data to be associated with its RPT, it will submit this ticket to the 918 authorization server. 920 For example: 922 HTTP/1.1 201 Created 923 Content-Type: application/json 924 ... 926 { 927 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 928 } 930 If the registration request is authenticated properly but fails due 931 to other reasons, the authorization server responds with an HTTP 400 932 (Bad Request) status code and includes one of the following UMA error 933 codes (see Section 4.2): 935 invalid_resource_set_id The provided resource set identifier was not 936 found at the authorization server. 938 invalid_scope At least one of the scopes included in the request was 939 not registered previously by this resource server. 941 3.3. Resource Server Determines RPT's Status 943 The resource server MUST determine a received RPT's status, including 944 both whether it is active and, if so, its associated authorization 945 data, before giving or refusing access to the client. An RPT is 946 associated with a set of authorization data that governs whether the 947 client is authorized for access. The token's nature and format are 948 dictated by its profile; the profile might allow it to be self- 949 contained, such that the resource server is able to determine its 950 status locally, or might require or allow the resource server to make 951 a run-time introspection request of the authorization server that 952 issued the token. 954 This specification makes one type of RPT REQUIRED for the 955 authorization server to support: the UMA bearer token profile, as 956 defined in Section 3.3.2. Implementers MAY define and use other RPT 957 profiles. 959 3.3.1. Token Introspection 961 Within any RPT profile, when a resource server needs to introspect a 962 token in a non-self-contained way to determine its status, it MAY 963 require, allow, or prohibit use of the OAuth token introspection 964 endpoint (defined by [OAuth-introspection]) that is part of the 965 protection API, and MAY profile its usage. The resource server MUST 966 use the POST method in interacting with the endpoint, not the GET 967 method also defined by [OAuth-introspection]. 969 3.3.2. RPT Profile: Bearer 971 This section defines the UMA bearer token profile. Following is a 972 summary: 974 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 975 uma-token-bearer-1.0 977 o Profile author and contact information: Thomas Hardjono 978 (hardjono@mit.edu) 980 o Updates or obsoletes: None; this profile is new. 982 o Keyword in HTTP Authorization header: "Bearer". 984 o Syntax and semantics of token data: As defined below; an opaque 985 string value, resolving to an extended JSON Web Token (JWT) [JWT] 986 format on introspection at the authorization server. 988 o Token data association: The on-the-wire token is opaque; it is 989 introspected at run time by the resource server through profiled 990 use of the OAuth token introspection endpoint 991 [OAuth-introspection], as defined below. 993 o Token data processing: As defined in this section and throughout 994 Section 3 of this specification. 996 o Grant type restrictions: None. 998 o Error states: As defined below. 1000 o Security and privacy considerations: As defined in this section, 1001 throughout Section 3, and in Section 8. 1003 An example of a client making a request with an RPT using the 1004 "Bearer" scheme appears in Section 3.1.2. 1006 On receiving an RPT with the "Bearer" scheme in an authorization 1007 header from a client making an access attempt, the resource server 1008 introspects the token by using the token introspection endpoint of 1009 the protection API. The PAT used by the resource server to make the 1010 introspection request provides resource-owner context to the 1011 authorization server. 1013 The authorization server responds with a JSON object with the 1014 structure dictated by [OAuth-introspection]. If the "active" 1015 property has a Boolean value of true, then the JSON object MUST NOT 1016 contain a "scope" claim, and MUST contain an extension property with 1017 the name "permissions" that contains an array of zero or more values, 1018 each of which is an object consisting of these properties: 1020 resource_set_id REQUIRED. A string that uniquely identifies the 1021 resource set, access to which has been granted to this client on 1022 behalf of this requesting party. The identifier MUST correspond 1023 to a resource set that was previously registered as protected. 1025 scopes REQUIRED. An array referencing one or more URIs of scopes to 1026 which access was granted for this resource set. Each scope MUST 1027 correspond to a scope that was registered by this resource server 1028 for the referenced resource set. 1030 exp OPTIONAL. Integer timestamp, measured in the number of seconds 1031 since January 1 1970 UTC, indicating when this permission will 1032 expire. If the property is absent, the permission does not 1033 expire. If the token-level "exp" value pre-dates a permission- 1034 level "exp" value, the former overrides the latter. 1036 iat OPTIONAL. Integer timestamp, measured in the number of seconds 1037 since January 1 1970 UTC, indicating when this permission was 1038 originally issued. If the token-level "iat" value post-dates a 1039 permission-level "iat" value, the former overrides the latter. 1041 nbf OPTIONAL. Integer timestamp, measured in the number of seconds 1042 since January 1 1970 UTC, indicating the time before which this 1043 permission is not valid. If the token-level "nbf" value post- 1044 dates a permission-level "nbf" value, the former overrides the 1045 latter. 1047 Example: 1049 HTTP/1.1 200 OK 1050 Content-Type: application/json 1051 Cache-Control: no-store 1053 { 1054 "active": true, 1055 "exp": 1256953732, 1056 "iat": 1256912345, 1057 "permissions": [ 1058 { 1059 "resource_set_id": "112210f47de98100", 1060 "scopes": [ 1061 "http://photoz.example.com/dev/actions/view", 1062 "http://photoz.example.com/dev/actions/all" 1063 ], 1064 "exp" : 1256953732 1065 } 1066 ] 1067 } 1069 3.4. Client Seeks Authorization for Access 1071 In order to access a protected resource successfully, a client needs 1072 to present a valid RPT with sufficient authorization data for access. 1073 To get to this stage requires a number of previously successful 1074 steps: 1076 1. The authorization server issues client credentials to the client. 1077 It is OPTIONAL for the client credentials to be provided 1078 dynamically through [DynClientReg] or [OIDCDynClientReg]; 1079 alternatively, they MAY use a static process. 1081 2. The client acquires an AAT. 1083 3. The client uses the authorization API to acquire an RPT and to 1084 ask for authorization data, providing the permission ticket it 1085 got from the resource server. The authorization server 1086 associates authorization data with the RPT based on the 1087 permission ticket, the resource owner's operative policies, and 1088 the results of any claims-gathering flows. 1090 3.4.1. Client Requests Authorization Data 1092 Once in possession of a permission ticket and an AAT for this 1093 authorization server, the client asks the authorization server to 1094 give it authorization data corresponding to that permission ticket. 1096 It performs a POST on the RPT endpoint, supplying its own AAT in the 1097 header and a JSON object in the body with a "ticket" property 1098 containing the ticket as its value. 1100 If the client had included an RPT in its failed access attempt, It 1101 MAY also provide that RPT in an "rpt" property in its request to the 1102 authorization server. 1104 In circumstances where the client needs to provide requesting party 1105 claims to the authorization server, it MAY also include a 1106 "claim_tokens" property in its request; see Section 3.4.1.2.1 for 1107 more information. 1109 Example of a request message containing an AAT, an RPT, and a 1110 permission ticket: 1112 POST /authz_request HTTP/1.1 1113 Host: as.example.com 1114 Authorization: Bearer jwfLG53^sad$#f 1115 ... 1117 { 1118 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1119 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1120 } 1122 The authorization server uses the ticket to look up the details of 1123 the previously registered requested permission, maps the requested 1124 permission to operative resource owner policies based on the resource 1125 set identifier and scopes associated with it, potentially requests 1126 additional information, and ultimately responds positively or 1127 negatively to the request for authorization data. 1129 The authorization server bases the issuing of authorization data on 1130 resource owner policies. These policies thus amount to an 1131 asynchronous OAuth authorization grant. The authorization server is 1132 also free to enable the resource owner to set policies that require 1133 the owner to interact with the server in near-real time to provide 1134 consent subsequent to an access attempt. All such processes are 1135 outside the scope of this specification. 1137 Once the authorization server adds the requested authorization data, 1138 it returns an HTTP 200 (OK) status code with a response body 1139 containing the RPT with which it associates the requested 1140 authorization data. If the client did not present an RPT in the 1141 request for authorization data, the authorization server creates and 1142 returns a new RPT. If the client did present an RPT in the request, 1143 the authorization server returns the RPT with which it associated the 1144 requested authorization data, which MAY be either the RPT that was in 1145 the request or a new one. Note: It is entirely an implementation 1146 issue whether the returned RPT is the same one that appeared in the 1147 request or a new RPT, and it is also an implementation issue whether 1148 the AS chooses to invalidate or retain the validity of the original 1149 RPT or any authorization data that was previously added to that RPT; 1150 to assist in client interoperability and token caching expectations, 1151 it is RECOMMENDED that authorization servers document their 1152 practices. [UMA-Impl] discusses the implications. 1154 Example: 1156 HTTP/1.1 200 OK 1157 Content-Type: application/json 1159 { 1160 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1161 } 1163 If the authorization server does not add the requested authorization 1164 data, it responds using one of the following UMA error codes and 1165 corresponding HTTP status codes (see Section 4.2): 1167 invalid_ticket The provided ticket was not found at the 1168 authorization server. The authorization server responds with the 1169 HTTP 400 (Bad Request) status code. 1171 expired_ticket The provided ticket has expired. The authorization 1172 server responds with the HTTP 400 (Bad Request) status code. 1174 not_authorized The client is not authorized to have this 1175 authorization data added. The authorization server responds with 1176 the HTTP 403 (Forbidden) status code. 1178 need_info The authorization server needs additional information in 1179 order to determine whether the client is authorized to have this 1180 authorization data. The authorization server responds with the 1181 HTTP 403 (Forbidden) status code. It MAY also respond with an 1182 "error_details" object that contains one or more sub-properties 1183 with hints about the nature of further required information. The 1184 client then has the opportunity to engage in follow-on flows to 1185 continue seeking authorization, in a process sometimes referred as 1186 "trust elevation". This specification defines two nonexclusive 1187 "error_details" sub-properties: "authentication_context", 1188 described in Section 3.4.1.1, and "requesting_party_claims", 1189 described in Section 3.4.1.2. 1191 request_submitted The authorization server requires intervention by 1192 the resource owner to determine whether the client is authorized 1193 to have this authorization data. Further immediate interaction 1194 between the client and authorization server is out of scope of 1195 this specification. 1197 Example when the ticket has expired: 1199 HTTP/1.1 400 Bad Request 1200 Content-Type: application/json 1201 Cache-Control: no-store 1202 ... 1204 { 1205 "error": "expired_ticket" 1206 } 1208 Example of a "need_info" response with a full set of "error_details" 1209 hints: 1211 HTTP/1.1 403 Forbidden 1212 Content-Type: application/json 1213 Cache-Control: no-store 1214 ... 1216 { 1217 "error": "need_info", 1218 "error_details": { 1219 "authentication_context": { 1220 "required_acr": ["https://example.com/acrs/LOA3.14159"] 1221 }, 1222 "requesting_party_claims": { 1223 "required_claims": [ 1224 { 1225 "name": "email23423453ou453", 1226 "friendly_name": "email", 1227 "claim_type": "urn:oid:0.9.2342.19200300.100.1.3", 1228 "claim_token_format": 1229 ["http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken"], 1230 "issuer": ["https://example.com/idp"] 1231 } 1232 ], 1233 "redirect_user": true, 1234 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 1235 } 1236 } 1237 } 1239 3.4.1.1. Authentication Context Flows 1241 The "authentication_context" sub-property provides hints about 1242 additional requirements regarding the requesting party's 1243 authentication that underlies the issuance of the currently valid 1244 AAT. On receiving such hints, the client has the opportunity to 1245 redirect the requesting party to the authorization server to 1246 reauthenticate in a manner anticipated to be more successful for 1247 gaining access. Such an action is sometimes referred to as "step-up" 1248 authentication. The "authentication_context" sub-property contains 1249 the following parameter: 1251 required_acr REQUIRED. An array of strings specifying a set of 1252 acceptable authentication context class reference values. Any one 1253 of the referenced authentication context classes (sets of 1254 authentication methods or procedures considered to be equivalent 1255 in a particular context) would satisfy the requesting party 1256 authentication requirements. Each string MAY be a URI, including 1257 one that has been registered through [RFC6711]. 1259 3.4.1.2. Claims-Gathering Flows 1261 The "requesting_party_claims" sub-property provides hints about 1262 additional requirements regarding information the authorization 1263 server needs about the requesting party. On receiving such hints, 1264 the client has the opportunity to engage in claims-gathering flows of 1265 various types. The "requesting_party_claims" sub-property MAY 1266 contain the following parameters, where at least one of 1267 "required_claims" or "redirect_user" MUST be supplied: 1269 required_claims An array containing objects that describe 1270 characteristics of the required claims, with the following 1271 properties: 1273 name OPTIONAL. A string (which MAY be a URI) representing the 1274 name of the claim; the "key" in a key-value pair. 1276 friendly_name OPTIONAL. A string that provides a more human- 1277 readable form of the attribute's name, which may be useful as a 1278 "display name" for use in user interfaces in cases where the 1279 actual name is complex or opaque, such as an OID or a UUID. 1281 claim_type OPTIONAL. A string, indicating the expected 1282 interpretation of the provided claim value. The string MAY be 1283 a URI. 1285 claim_token_format OPTIONAL. An array of strings specifying a 1286 set of acceptable formats for a token pushed by the client 1287 containing this claim (see Section 3.4.1.2.1). Any one of the 1288 referenced formats would satisfy the authorization server's 1289 requirements. Each string MAY be a URI. 1291 issuer OPTIONAL. An array of strings specifying a set of 1292 acceptable issuing authorities for the claim. Any one of the 1293 referenced authorities would satisfy the authorization server's 1294 requirements. Each string MAY be a URI. 1296 redirect_user A Boolean value indicating whether the requesting 1297 party's presence at the authorization server is required for the 1298 process of claims gathering. For example, the authorization 1299 server may require the requesting party to fill out a CAPTCHA to 1300 help prove humanness. The default is false if this parameter is 1301 not present. See Section 1.4 for how the authorization server 1302 declares the requesting party claims endpoint to which the client 1303 has the opportunity to redirect the requesting party. Note that 1304 the word "user" implies a human requesting party; if the 1305 requesting party is not an end-user, then no client action would 1306 be possible on receiving the hint. 1308 ticket The permission ticket that was in the client's request for 1309 authorization data. If the authorization server provides the 1310 "redirect_user" property, it MUST also provide the "ticket" 1311 property. This helps the client avoid maintaining this state 1312 information after the redirect. 1314 An example of the use of these properties appears in Section 3.4.1. 1316 The authorization server has many options for gathering requesting 1317 party claims. For example, it could interact with an end-user 1318 requesting party directly, or accept claims delivered by a client, or 1319 perform a lookup in some external system. The process is extensible 1320 and can have dependencies on the type of requesting party (for 1321 example, natural person or legal person) or client (for example, 1322 browser, native app, or autonomously running web service). 1324 The client and authorization server have two nonexclusive claims- 1325 gathering interaction patterns: push and redirect. 1327 3.4.1.2.1. Client Pushes Claim Tokens to Authorization Server 1329 If the client is ?claims-aware? and the authorization server can 1330 accept pushed claims (for example, as it might have indicated by 1331 providing "requesting_party_claims" hints described in 1332 Section 3.4.1), the client has the option to _push_ claim tokens to 1333 the RPT endpoint. The claim token can reflect the client's role as a 1334 federated identity provider, a federated relying party, or an 1335 application integrated with a native identity repository. 1337 If the client is aware of the authorization server's requirements for 1338 claims through an out-of-band relationship, the client MAY push claim 1339 tokens in an initial interaction with the RPT endpoint. 1341 The client supplies claim tokens in the body of the authorization 1342 data request message by providing, in addition to the "rpt" and 1343 "ticket" properties, the following property: 1345 claim_tokens REQUIRED. An array of objects with the following 1346 properties: 1348 format REQUIRED. A string specifying the format of the 1349 accompanying claim tokens. The string MAY be a URI. 1351 token REQUIRED. A string containing the claim information in the 1352 indicated format, base64url encoded. If claim token format 1353 features are included that require special interpretation, the 1354 client and authorization server are assumed to have a prior 1355 relationship that establishes how to interpret these features. 1356 For example, if the referenced format equates to SAML 2.0 1357 assertions and the claim token contains audience restrictions, 1358 it is the joint responsibility of the client and authorization 1359 server to determine the proper audience values that enable 1360 successful token consumption. 1362 Example: 1364 POST /rpt_authorization HTTP/1.1 1365 Host: www.example.com 1366 Authorization: Bearer jwfLG53^sad$#f 1367 ... 1368 { 1369 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 1370 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 1371 "claim_tokens": [ 1372 { 1373 "format": 1374 "http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken", 1375 "token": "..." 1376 } 1377 ] 1378 } 1380 This specification provides a framework for extensibility through 1381 claim token format profiling. The authorization server MAY support 1382 any number of claim token profiles, and SHOULD document the claim 1383 token profiles it supports in its configuration data. 1385 3.4.1.2.2. Client Redirects Requesting Party to Authorization Server 1387 If the client is ?claims-unaware? and the authorization server has 1388 declared a requesting party claims endpoint in its configuration 1389 data, or if the authorization server requires direct interaction with 1390 the requesting party as part of its claims-gathering process (for 1391 example, as it might have indicated through the "redirect_user" hint 1392 described in Section 3.4.1), the client has the option to _redirect_ 1393 an end-user requesting party to the requesting party claims endpoint. 1394 In this case, the authorization server might be a relying party in a 1395 federated identity interaction, or it might connect to a directory or 1396 other user repository, or even interact with the user in other ways, 1397 such as presenting a questionnaire in a web form. After this process 1398 completes, the authorization server redirects the end-user requesting 1399 party back to the client. 1401 The client constructs the request URI by adding the following 1402 parameters to the query component of the requesting party claims 1403 endpoint URI using the "application/x-www-form-urlencoded" format: 1405 client_id REQUIRED. The client's identifier issued by the 1406 authorization server. 1408 redirect_uri OPTIONAL. The URI to which the client wishes the 1409 authorization server to direct the requesting party's user agent 1410 after completing its interaction. The URI MUST be absolute, MAY 1411 contain an "application/x-www-form-urlencoded" formatted query 1412 parameter component that MUST be retained when adding addition 1413 parameters, and MUST NOT contain a fragment component. The 1414 authorization server SHOULD require all clients to register their 1415 redirection endpoint prior to utilizing the authorization 1416 endpoint. If the URI is pre-registered, this URI MUST exactly 1417 match one of the pre-registered redirection URIs, with the 1418 matching performed as described in Section 6.2.1 of [RFC3986] 1419 (Simple String Comparison). 1421 ticket REQUIRED. The permission ticket associated with the client's 1422 current request for authorization data for this requesting party. 1423 The authorization server MUST return this parameter back to when 1424 the authorization_state is need_info. 1426 state OPTIONAL. An opaque value used by the client to maintain 1427 state between the request and callback. The authorization server 1428 includes this value when redirecting the user agent back to the 1429 client. The use of this parameter is STRONGLY RECOMMENDED for 1430 preventing cross-site request forgery. 1432 Example of a request issued by a client application (line breaks are 1433 shown only for display convenience): 1435 GET /rqp_claims?client_id=some_client_id&state=abc 1436 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect HTTP/1.1 1437 Host: as.example.com 1439 At the conclusion of its interaction with the requesting party, the 1440 authorization server returns the user agent to the client adding the 1441 following parameters to the query component of the redirection URI 1442 using the "application/x-www-form-urlencoded" format: 1444 authorization_state REQUIRED. Indicates that the authorization 1445 server completed its claims-gathering interaction with the 1446 requesting party with the indicated state: 1448 claims_submitted The client is free to return to the RPT endpoint 1449 to seek authorization data once again. 1451 not_authorized The client is not authorized to have the desired 1452 authorization data added. 1454 need_info The authorization server needs additional information 1455 in order to determine whether the client is authorized to have 1456 this authorization data. This response directs the client to 1457 return to the RPT endpoint, where it might be provided with 1458 error_details hints about additional information needed. 1460 request_submitted The authorization server requires intervention 1461 by the resource owner to determine whether authorization data 1462 can be added. Further immediate interaction between the 1463 client, requesting party, and authorization server is out of 1464 scope of this specification. 1466 ticket OPTIONAL. The same permission ticket value that the client 1467 provided in the request. It MUST be present if and only if the 1468 authorization_state is need_info. 1470 state OPTIONAL. The same state value that the client provided in 1471 the request. It MUST be present if and only if the client 1472 provided it. 1474 The client MUST ignore unrecognized response parameters. If the 1475 request fails due to a missing, invalid, or mismatching redirection 1476 URI, or if the client identifier is missing or invalid, the 1477 authorization server SHOULD inform the resource owner of the error 1478 and MUST NOT automatically redirect the user agent to the invalid 1479 redirection URI. If the request fails for reasons other than a 1480 missing or invalid redirection URI, the authorization server informs 1481 the client by adding an "error" parameter to the query component of 1482 the redirection URI using the "application/x-www-form-urlencoded" 1483 format, containing one of the following ASCII error codes: 1485 invalid_request The request is missing a required parameter, 1486 includes an invalid parameter value (such as an invalid or expired 1487 ticket), includes a parameter more than once, or is otherwise 1488 malformed. 1490 server_error The authorization server encountered an unexpected 1491 condition that prevented it from fulfilling the request. (This 1492 error code is needed because an HTTP 500 (Internal Server Error) 1493 status code cannot be returned to the client via an HTTP 1494 redirect.) 1496 temporarily_unavailable The authorization server is currently unable 1497 to handle the request due to a temporary overloading or 1498 maintenance of the server. (This error code is needed because an 1499 HTTP 503 (Service Unavailable) status code cannot be returned to 1500 the client via an HTTP redirect.) 1502 4. Error Messages 1504 Ultimately the resource server is responsible for either granting the 1505 access the client attempted, or returning an error response to the 1506 client with a reason for the failure. [OAuth2] defines several error 1507 responses for a resource server to return. UMA makes use of these 1508 error responses, but requires the resource server to "outsource" the 1509 determination of some error conditions to the authorization server. 1510 This specification defines additional UMA-specific error responses 1511 that the authorization server may give to the resource server and 1512 client as they interact with it, and that the resource server may 1513 give to the client. 1515 4.1. OAuth Error Responses 1517 When a resource server or client attempts to access one of the 1518 authorization server endpoints or a client attempts to access a 1519 protected resource at the resource server, it has to make an 1520 authenticated request by including an OAuth access token in the HTTP 1521 request as described in [OAuth2] Section 7.2. 1523 If the request failed authentication, the authorization server or the 1524 resource server responds with an OAuth error message as described in 1525 this specification in Section 3. 1527 4.2. UMA Error Responses 1529 When a resource server or client attempts to access one of the 1530 authorization server endpoints or a client attempts to access a 1531 protected resource at the resource server, if the request is 1532 successfully authenticated by OAuth means, but is invalid for another 1533 reason, the authorization server or resource server responds with an 1534 UMA error response by adding the following properties to the entity 1535 body of the HTTP response: 1537 error REQUIRED. A single error code. Values for this property are 1538 defined throughout this specification. 1540 error_description OPTIONAL. Human-readable text providing 1541 additional information. 1543 error_uri OPTIONAL. A URI identifying a human-readable web page 1544 with information about the error. 1546 The following is a common error code that applies to several UMA- 1547 specified request messages: 1549 invalid_request The request is missing a required parameter, 1550 includes an invalid parameter value, includes a parameter more 1551 than once, or is otherwise malformed. The authorization server 1552 MUST respond with the HTTP 400 (Bad Request) status code. 1554 For example: 1556 HTTP/1.1 400 Bad Request 1557 Content-Type: application/json 1558 Cache-Control: no-store 1559 ... 1561 { 1562 "error": "invalid_request", 1563 "error_description": "There is already a resource with this identifier.", 1564 "error_uri": "https://as.example.com/errors/resource_exists" 1565 } 1566 5. Profiles for API Extensibility 1568 In some circumstances, it may be desirable to couple UMA roles 1569 tightly. For example, an authorization server application might also 1570 need to act as a client application in order to retrieve protected 1571 resources so that it can present to resource owners a dashboard-like 1572 user interface that accurately guides the setting of policy; it might 1573 need to access itself-as-authorization server for that purpose. For 1574 another example, the same organization might operate both an 1575 authorization server and a resource server that communicate only with 1576 each other behind a firewall, and it might seek more efficient 1577 communication methods between them. 1579 In other circumstances, it may be desirable to bind UMA flows to 1580 transport mechanisms other than HTTP even if entities remain loosely 1581 coupled. For example, in Internet of Things scenarios, Constrained 1582 Application Protocol (CoAP) may be preferred over HTTP. 1584 This section defines profiles that allow inter-role communications 1585 channels and methods to vary in these circumstances. This 1586 specification still REQUIRES authorization servers to issue PATs, 1587 AATs, and RPTs and associate authorization data with RPTs, and 1588 REQUIRES resource servers to give clients access only when RPTs are 1589 associated with sufficient authorization data. This is because, 1590 although tokens might not always appear on the wire in the normal 1591 fashion, the tokens may represent binding obligations that involve 1592 additional parties unable to take part in these optimization 1593 opportunities (see [UMA-obligations]). 1595 Where alternate communications channels are being used between 1596 independently implemented system entities, it is RECOMMENDED, for 1597 reasons of implementation interoperability, to define concrete 1598 extension profiles that build on these extensibility profiles (see 1599 Section 6.1). 1601 5.1. Protection API Extensibility Profile 1603 This section defines a profile for UMA where the authorization server 1604 and resource server roles either reside in the same system entity or 1605 otherwise have a privileged or specialized communications channel 1606 between them. Following is a summary: 1608 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1609 prot-ext-1.0 1611 o Profile author and contact information: Mark Dobrinic 1612 (mdobrinic@cozmanova.com) 1614 o Updates or obsoletes: None; this profile is new. 1616 o Security considerations: See below. 1618 o Privacy considerations: See below. 1620 o Error states: None additional. 1622 Using this profile, the resource server MAY use means other than the 1623 HTTP-based protection API that is protected by TLS and OAuth (or an 1624 OAuth-based authentication protocol) to communicate with the 1625 authorization server in all respects, including using software 1626 interfaces and methods rather than network interfaces and APIs. The 1627 authorization server MUST still issue PATs, AATs, and RPTs and 1628 associate authorization data with RPTs, and the resource server MUST 1629 still give clients access only when RPTs are associated with 1630 sufficient authorization data. Interactions with entities other than 1631 the authorization server or resource server MUST be preserved exactly 1632 as they would have if either of them were using standardized UMA 1633 APIs, unless other extensibility profiles are also in use. 1635 An authorization server using any of the opportunities afforded by 1636 this profile MUST declare use of this profile by supplying its 1637 identifying URI for one of its "uma_profiles_supported" values in its 1638 configuration data (see Section 1.4). 1640 Same-entity communication or a tight integration of entities has the 1641 opportunity to make deployments more secure by reducing possible 1642 attack vectors. However, if the entities do not use TLS but 1643 communicate across a transport layer, it is RECOMMENDED to use an 1644 alternate means of transport-layer security, for example, using DTLS 1645 in the case of a CoAP-based UMA profile. 1647 Same-entity communication or a tight integration of entities has the 1648 potential to compromise privacy by promoting the freer exchange of 1649 personal information within a deployment ecosystem. It is 1650 RECOMMENDED to account for privacy impacts in each deployment 1651 scenario. 1653 5.2. Authorization API Extensibility Profile 1655 This section defines a profile for UMA where the authorization server 1656 and client roles either reside in the same system entity or otherwise 1657 have a privileged or specialized communications channel between them. 1658 Following is a summary: 1660 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1661 authz-ext-1.0 1663 o Profile author and contact information: Mark Dobrinic 1664 (mdobrinic@cozmanova.com) 1666 o Updates or obsoletes: None; this profile is new. 1668 o Security considerations: See below. 1670 o Privacy considerations: See below. 1672 o Error states: None additional. 1674 Using this profile, the client MAY use means other than the HTTP- 1675 based authorization API that is protected by TLS and OAuth (or an 1676 OAuth-based authentication protocol) to communicate with the 1677 authorization server in all respects, including using software 1678 interfaces and methods rather than network interfaces and APIs. The 1679 authorization server MUST still issue PATs, AATs, and RPTs and 1680 associate authorization data with RPTs, and the resource server MUST 1681 still give clients access only when RPTs are associated with 1682 sufficient authorization data. Interactions with entities other than 1683 the authorization server or client MUST be preserved exactly as they 1684 would have if either of them were using standardized UMA APIs, unless 1685 other extensibility profiles are also in use. 1687 An authorization server using any of the opportunities afforded by 1688 this profile MUST declare use of this profile by supplying its 1689 identifying URI for one of its "uma_profiles_supported" values in its 1690 configuration data (see Section 1.4). 1692 Same-entity communication or a tight integration of entities has the 1693 opportunity to make deployments more secure by reducing possible 1694 attack vectors. However, if the entities do not use TLS but 1695 communicate across a transport layer, it is RECOMMENDED to use an 1696 alternate means of transport-layer security, for example, using DTLS 1697 in the case of a CoAP-based UMA profile. 1699 Same-entity communication or a tight integration of entities has the 1700 potential to compromise privacy by promoting the freer exchange of 1701 personal information within a deployment ecosystem. It is 1702 RECOMMENDED to account for privacy impacts in each deployment 1703 scenario. 1705 5.3. Resource Interface Extensibility Profile 1707 This section defines a profile for UMA where the resource server and 1708 client roles either reside in the same system entity or otherwise 1709 have a privileged or specialized communications channel between them. 1710 Following is a summary: 1712 o Identifying URI: https://docs.kantarainitiative.org/uma/profiles/ 1713 rsrc-ext-1.0 1715 o Profile author and contact information: Mark Dobrinic 1716 (mdobrinic@cozmanova.com) 1718 o Updates or obsoletes: None; this profile is new. 1720 o Security considerations: See below. 1722 o Privacy considerations: See below. 1724 o Error states: None additional. 1726 Using this profile, the resource server MAY use means other than an 1727 HTTP-based resource interface to communicate with the authorization 1728 server in all respects, including using software interfaces and 1729 methods rather than network interfaces and APIs. The resource server 1730 MUST still give clients access only when RPTs are associated with 1731 sufficient authorization data. Interactions with entities other than 1732 the resource server or client MUST be preserved exactly as they would 1733 have if either of them were using standardized UMA APIs, unless other 1734 extensibility profiles are also in use. 1736 An authorization server involved in deployments where resource 1737 servers and clients are known to be using opportunities afforded by 1738 the resource interface extensibility profile MAY declare use of this 1739 profile by supplying its identifying URI for one of its 1740 "uma_profiles_supported" values in its configuration data (see 1741 Section 1.4). 1743 Same-entity communication or a tight integration of entities has the 1744 opportunity to make deployments more secure by reducing possible 1745 attack vectors. However, if the entities do not use TLS but 1746 communicate across a transport layer, it is RECOMMENDED to use an 1747 alternate means of transport-layer security, for example, using DTLS 1748 in the case of a CoAP-based UMA profile. 1750 Same-entity communication or a tight integration of entities has the 1751 potential to compromise privacy by promoting the freer exchange of 1752 personal information within a deployment ecosystem. It is 1753 RECOMMENDED to account for privacy impacts in each deployment 1754 scenario. 1756 6. Specifying Additional Profiles 1758 This specification defines a protocol that has optional features. 1759 For implementation interoperability and to serve particular 1760 deployment scenarios, including sector-specific ones such as 1761 healthcare or e-government, third parties may want to define profiles 1762 of UMA that restrict these options. 1764 Further, this specification creates extensibility points for RPT 1765 profiles and claim token profiles, and third parties may likewise 1766 want to define their own. Different RPT profiles could be used, for 1767 example, to change the dividing line between authorization server and 1768 resource server responsibilities in controlling access. Different 1769 claim token profiles could be used to customize sector-specific or 1770 population-specific (such as individual vs. employee) claim types 1771 that drive the types of policies resource owners could set. 1773 It is not practical for this specification to standardize all desired 1774 profiles. However, to serve overall interoperability goals, this 1775 section provides guidelines for third parties that wish to specify 1776 UMA-related profiles. In all cases, it is RECOMMENDED that profiles 1777 document the following information: 1779 o Specify a URI that uniquely identifies the profile. 1781 o Identify the responsible author and provide postal or electronic 1782 contact information. 1784 o Supply references to any previously defined profiles that the 1785 profile updates or obsoletes. 1787 o Define any additional or changed error states. 1789 o Specify any conformance and interoperability considerations. 1791 o Supply any additional security and privacy considerations. 1793 6.1. Specifying Profiles of UMA 1795 It is RECOMMENDED that profiles of UMA additionally document the 1796 following information: 1798 o Specify the set of interactions between endpoint entities involved 1799 in the profile, calling out any restrictions on ordinary UMA- 1800 conformant operations and any extension properties used in message 1801 formats. 1803 See Section 5 for examples. 1805 6.2. Specifying RPT Profiles 1807 It is RECOMMENDED that RPT profiles additionally document the 1808 following information: 1810 o Specify the keyword to be used in HTTP Authorization headers with 1811 tokens conforming to this profile. 1813 o Specify the syntax and semantics of the data that the 1814 authorization server associates with the token. 1816 o Specify how the token data is associated with, contained within, 1817 and/or retrieved by means of, the on-the-wire token string. 1819 o Specify processing rules for token data. 1821 o Identify any restrictions on grant types to be used with the token 1822 profile. 1824 See Section 3.3.2 for an example. 1826 6.3. Specifying Claim Token Format Profiles 1828 It is RECOMMENDED that claim token format profiles additionally 1829 document the following information: 1831 o Specify any related or additional error_details hints. 1833 o Specify any constraints on the claim token format vs. a standard 1834 definition for it in a specification. 1836 o Specify any mutual interpretation details of claim token formats 1837 by authorization servers and clients. 1839 7. Compatibility Notes 1841 Implementers should heed the following compatibility notes. 1843 o This specification uses a specific draft of a specification that 1844 is not yet final: [OAuth-introspection] (draft 04); the reference 1845 will be updated until this "UMA V1.0 candidate" specification is 1846 finalized. While every effort will be made to prevent breaking 1847 changes to this specification, should they occur, UMA 1848 implementations should continue to use the specifically referenced 1849 draft version in preference to the final versions, unless using a 1850 possible future UMA profile or specification that updates the 1851 relevant references. 1853 o In cases where this specification is not prescriptive regarding 1854 conformance or interoperability, any common or best practices for 1855 implementation will be documented in the [UMA-Impl] over time. 1857 8. Security Considerations 1859 As a profile of OAuth, this specification relies mainly on OAuth 1860 security mechanisms as well as transport-level encryption. Thus, 1861 implementers are strongly advised to read the security considerations 1862 in [OAuth2] (Section 10) and [OAuth-bearer] (Section 5) along with 1863 the security considerations of any other OAuth token-defining 1864 specifications in use, along with the entire [OAuth-threat] 1865 specification, and apply the countermeasures described therein. As 1866 well, since this specification builds on [OAuth-resource-reg], 1867 implementers should also take into account the security 1868 considerations in that specification. 1870 The following sections describe additional security considerations. 1872 8.1. Redirection and Impersonation Threats 1874 This section discusses threats related to UMA's nature as an protocol 1875 enabling autonomous (non-resource-owner) requesting parties to gain 1876 authorized access to sensitive resources, including through the 1877 process of claims-gathering redirection. 1879 Like ordinary OAuth redirection, UMA redirection for the purpose of 1880 gathering claims from an end-user requesting party (described in 1881 Section 3.4.1.2.2) creates the potential for cross-site request 1882 forgery (CSRF) through an open redirect if the authorization server 1883 does not force the client to pre-register its redirection endpoint, 1884 and server-side artifact tampering if the client does not avail 1885 itself of the state parameter. The client SHOULD check that the 1886 ticket value returned by an authorization server after a redirect is 1887 completed has not been maliciously changed, for example by a man in 1888 the browser (MITB), by using the state parameter. (See the 1889 [UMA-Impl] for advice on ways to accomplish this.) Sections 4.4.1.8, 1890 4.4.2.5, and 5.3.5 of [OAuth-threat] are apropos for the UMA claims- 1891 gathering redirection flow as well. 1893 When a client redirects an end-user requesting party to the 1894 requesting party claims endpoint, the client provides no a priori 1895 context to the authorization server about which user is appearing at 1896 the endpoint, other than implicitly through the permission ticket. 1897 Since the authorization server is free to gather any claims it 1898 wishes, the effect is to "late-bind" them to the permission ticket 1899 and the state string provided by the client, with the effect of 1900 enabling the authorization server not to trust client-asserted 1901 claims. This is a desirable result and reflects one reason why the 1902 authorization server might choose to demand use of the redirect flow 1903 over the push flow. However, the client has the opportunity to 1904 switch end-users -- say, enabling malicious end-user Carlos to 1905 impersonate the original end-user Bob who approved the minting of of 1906 the AAT -- after the redirect completes and before it returns to the 1907 RPT endpoint to seek authorization data. 1909 Another issue concerns the exposure of the RPT to an autonomous 1910 requesting party, which could maliciously pass the token to an 1911 unauthorized party. 1913 To mitigate requesting-party switching and RPT exposure threats, 1914 consider the following strategies. 1916 o Require that the Requesting Party (as defined in 1917 [UMA-obligations], meaning this party is able to take on legal 1918 obligations) legitimately represent the wielder of the bearer 1919 token. This solution is based on a legal or contractual approach, 1920 and therefore does not reduce the risk from the technical 1921 perspective. 1923 o The authorization server, possibly with input from the resource 1924 owner, can implement tighter time-to-live strategies around the 1925 authorization data in RPTs. This is a classic approach with 1926 bearer tokens that helps to limit a malicious party's ability to 1927 intercept and use the bearer token. In the same vein, the 1928 authorization server could require claims to have a reasonable 1929 degree of freshness (which would require a custom claims profile). 1931 o The strongest strategy is to disallow bearer-type RPTs within the 1932 UMA profile being deployed, by providing or requiring an RPT 1933 profile that requires use of a holder-of-key approach. In this 1934 way, the wielder of the token must engage in a live session for 1935 proof-of-possession. A less complex version of this strategy is 1936 to "elevate trust" in the requesting party by requiring a stronger 1937 authentication context, forcing step-up authentication by the 1938 requesting party at run time. 1940 8.2. Client Authentication 1942 Along with TLS, UMA requires OAuth, or any OAuth-based authentication 1943 protocol, as the security mechanism for its standardized APIs. The 1944 UMA resource server acts in the role of an OAuth client at the 1945 authorization server's protection API, and the UMA client acts in the 1946 role of an OAuth client at the authorization server's authorization 1947 API. While it is possible to use any profile of OAuth for this 1948 protection, it is RECOMMENDED for the authorization server to use 1949 OpenID Connect, and to use its mechanisms for stronger client 1950 authentication at the token endpoint, in order to strengthen the 1951 authentication of OAuth clients. Section 16 of [OIDCCore] provides 1952 more information on OpenID Connect security considerations. 1954 Clients using the OAuth implicit grant type carry particular 1955 vulnerabilities in OAuth, and OpenID Connect doesn't help because of 1956 the nature of the implicit grant flow. UMA scenarios are vulnerable 1957 as well. For example, an "implicit client" might require the 1958 retrieval of AATs more frequently, for each browser on each platform. 1959 An attacker can initiate a spear phishing attack on the requesting 1960 party with a link to a malicious website, relying on the requesting 1961 party to authenticate to the authorization server through an email- 1962 based identity provider in order to receive the AAT. The site can 1963 impersonate the requesting party using the browser client's client ID 1964 in an OpenID Connect implicit request to the UMA authorization 1965 server. If the requesting party had previously given consent for an 1966 AAT to be issued, this attempt will likely succeed. The subsequently 1967 issued AAT and permission ticket for an attempted resource access 1968 could potentially be used for RPT retrieval and authorization data 1969 issuance. 1971 A number of mitigation strategies are possible. 1973 o The authorization server could penalize or disallow use of the 1974 implicit grant flow. This could be done at a variety of levels: 1976 * Enabling resource owners to define policies controlling the use 1977 of such clients 1979 * Setting system-default policies controlling their use 1981 * Participating in mutual agreements with other parties that 1982 admit only suitably secure client applications to interact with 1983 service operators 1985 o The authorization server could support dynamic client registration 1986 at the client instance level, such that each instance receives a 1987 unique client_id and secret. The client can then use the 1988 authorization code flow and have at least some form of client 1989 authentication. However, this is easier for a mobile app than for 1990 a browser-based HTML app. 1992 8.3. JSON Usage 1994 This specification defines a number of data formats based on [JSON]. 1995 As a subset of the JavaScript scripting language, JSON data SHOULD be 1996 consumed through a process that does not dynamically execute it as 1997 code, to avoid malicious code execution. One way to achieve this is 1998 to use a JavaScript interpreter rather than the built-in JavaScript 1999 eval() function. 2001 8.4. Profiles, Binding Obligations, and Trust Establishment 2003 Parties operating and using UMA software entities have opportunities 2004 to establish agreements about mutual rights, responsibilities, and 2005 common interpretations of UMA constructs for consistent and expected 2006 software behavior. These agreements can be used to improve the 2007 parties' respective security postures, and written profiles are a key 2008 mechanism for conveying and enforcing these agreements. Section 6 2009 discusses profiling. Section 5 discusses profiling for 2010 extensibility. [UMA-obligations] discusses the development of 2011 binding obligations. 2013 9. Privacy Considerations 2015 The authorization server comes to be in possession of resource set 2016 information that may reveal information about the resource owner, 2017 which the authorization server's trust relationship with the resource 2018 server is assumed to accommodate. However, the client is a less- 2019 trusted party -- in fact, entirely untrustworthy until authorization 2020 data is associated with its RPT. The more information about a 2021 resource set that is registered, the more risk of privacy compromise 2022 there is through a less-trusted authorization server. 2024 The primary privacy duty of UMA's design is to the resource owner. 2025 However, privacy considerations affect the requesting party as well. 2026 This can be seen in the issuance of an AAT, which represents the 2027 approval of a requesting party for a client to engage with an 2028 authorization server to perform tasks needed for obtaining 2029 authorization, possibly including pushing claim tokens. 2031 Parties operating and using UMA software entities have opportunities 2032 to establish agreements about mutual rights, responsibilities, and 2033 common interpretations of UMA constructs for consistent and expected 2034 software behavior. These agreements can be used to improve the 2035 parties' respective privacy postures. For information about the 2036 additional technical, operational, and legal elements of trust 2037 establishment, see [UMA-obligations]. Additional considerations 2038 related to Privacy by Design concepts are discussed in [UMA-PbD]. 2040 10. IANA Considerations 2042 This document makes the following requests of IANA. 2044 10.1. JSON Web Token Claims Registration 2046 This specification registers the claim defined in Section 3.3.2. 2048 10.1.1. Registry Contents 2050 o Claim name: permissions 2052 o Claim description: Array of objects, each describing a set of 2053 scoped, time-limitable entitlements to a resource set 2055 o Change controller: Kantara Initiative User-Managed Access Work 2056 Group - wg-uma@kantarainitiative.org 2058 o Specification document: Section 3.3.2 in this document 2060 10.2. Well-Known URI Registration 2062 This specification registers the well-known URI defined in 2063 Section 1.4. 2065 10.2.1. Registry Contents 2067 o URI suffix: uma-configuration 2069 o Change controller: Kantara Initiative User-Managed Access Work 2070 Group - wg-uma@kantarainitiative.org 2072 o Specification document: Section 1.4 in this document 2074 11. Acknowledgments 2076 The following people made significant text contributions to the 2077 specification: 2079 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 2081 o Mark Dobrinic, Cozmanova 2083 o George Fletcher, AOL 2085 o Lukasz Moren, Cloud Identity Ltd 2087 o Christian Scholz, COMlounge GmbH (former editor) 2089 o Mike Schwartz, Gluu 2091 o Jacek Szpot, Newcastle University 2092 Additional contributors to this specification include the Kantara UMA 2093 Work Group participants, a list of whom can be found at 2094 [UMAnitarians]. 2096 12. References 2098 12.1. Normative References 2100 [DynClientReg] 2101 Richer, J., "OAuth 2.0 Core Dynamic Client Registration", 2102 December 2014, 2103 . 2105 [JSON] Bray, T., "The JavaScript Object Notation (JSON) Data 2106 Interchange Format", March 2014, 2107 . 2109 [JWT] Jones, M., "JSON Web Token (JWT)", December 2014, 2110 . 2113 [OAuth-bearer] 2114 "The OAuth 2.0 Authorization Framework: Bearer Token 2115 Usage", October 2012, 2116 . 2118 [OAuth-introspection] 2119 Richer, J., "OAuth Token Introspection", December 2014, 2120 . 2123 [OAuth-resource-reg] 2124 Hardjono, T., "OAuth 2.0 Resource Set Registration", 2125 February 2015, . 2128 [OAuth-threat] 2129 Lodderstedt, T., "OAuth 2.0 Threat Model and Security 2130 Considerations", January 2013, 2131 . 2133 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework", 2134 October 2012, . 2136 [OIDCCore] 2137 Sakimura, N., "OpenID Connect Core 1.0 incorporating 2138 errata set 1", November 2014, 2139 . 2141 [OIDCDynClientReg] 2142 Sakimura, N., "OpenID Connect Dynamic Client Registration 2143 1.0 incorporating errata set 1", November 2014, 2144 . 2147 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2148 Requirement Levels", BCP 14, RFC 2119, March 1997. 2150 [RFC3986] Berners-Lee, T., "Uniform Resource Identifier (URI): 2151 Generic Syntax", January 2005, 2152 . 2154 [RFC6711] Johansson, L., "An IANA Registry for Level of Assurance 2155 (LoA) Profiles", August 2012, 2156 . 2158 [hostmeta] 2159 Hammer-Lahav, E., "Web Host Metadata", October 2011, 2160 . 2162 12.2. Informative References 2164 [UMA-Impl] 2165 Maler, E., "UMA Implementer's Guide", December 2014, 2166 . 2169 [UMA-PbD] Maler, E., "Privacy by Design Implications of UMA", 2170 December 2013, 2171 . 2174 [UMA-casestudies] 2175 Maler, E., "UMA Case Studies", April 2014, 2176 . 2179 [UMA-obligations] 2180 Maler, E., "Binding Obligations on UMA Participants", 2181 January 2013, . 2184 [UMA-usecases] 2185 Maler, E., "UMA Scenarios and Use Cases", October 2010, 2186 . 2189 [UMAnitarians] 2190 Maler, E., "UMA Participant Roster", December 2014, 2191 . 2194 Authors' Addresses 2196 Thomas Hardjono (editor) 2197 MIT 2199 Email: hardjono@mit.edu 2201 Eve Maler 2202 ForgeRock 2204 Email: eve.maler@forgerock.com 2206 Maciej Machulak 2207 Cloud Identity 2209 Email: maciej.machulak@cloudidentity.co.uk 2211 Domenico Catalano 2212 Oracle 2214 Email: domenico.catalano@oracle.com