idnits 2.17.1 draft-maler-oauth-umagrant-00.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 8 instances of too long lines in the document, the longest one being 32 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 217 has weird spacing: '... server own...' -- The document date (February 13, 2019) is 1898 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-10) exists of draft-ietf-oauth-discovery-08 ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Maler, Ed. 3 Internet-Draft ForgeRock 4 Intended status: Informational M. Machulak 5 Expires: August 17, 2019 HSBC 6 J. Richer 7 Bespoke Engineering 8 T. Hardjono 9 MIT 10 February 13, 2019 12 User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization 13 draft-maler-oauth-umagrant-00 15 Abstract 17 This specification defines a means for a client, representing a 18 requesting party, to use a permission ticket to request an OAuth 2.0 19 access token to gain access to a protected resource asynchronously 20 from the time a resource owner authorizes access. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on August 17, 2019. 39 Copyright Notice 41 Copyright (c) 2019 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 58 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 1.3. Abstract Flow . . . . . . . . . . . . . . . . . . . . . . 5 60 1.3.1. Authorization Process . . . . . . . . . . . . . . . . 7 61 2. Authorization Server Metadata . . . . . . . . . . . . . . . . 8 62 3. Flow Details . . . . . . . . . . . . . . . . . . . . . . . . 9 63 3.1. Client Requests Resource Without Providing an Access 64 Token . . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 3.2. Resource Server Responds to Client's Tokenless Access 66 Attempt . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 3.2.1. Resource Server Response to Client on Permission 68 Request Success . . . . . . . . . . . . . . . . . . . 10 69 3.2.2. Resource Server Response to Client on Permission 70 Request Failure . . . . . . . . . . . . . . . . . . . 10 71 3.3. Client Seeks RPT on Requesting Party's Behalf . . . . . . 11 72 3.3.1. Client Request to Authorization Server for RPT . . . 11 73 3.3.2. Client Redirect of Requesting Party to Authorization 74 Server for Interactive Claims-Gathering . . . . . . . 13 75 3.3.3. Authorization Server Redirect of Requesting Party 76 Back to Client After Interactive Claims-Gathering . . 15 77 3.3.4. Authorization Assessment and Results Determination . 16 78 3.3.5. Authorization Server Response to Client on 79 Authorization Success . . . . . . . . . . . . . . . . 18 80 3.3.6. Authorization Server Response to Client on 81 Authorization Failure . . . . . . . . . . . . . . . . 20 82 3.4. Client Requests Resource and Provides an RPT . . . . . . 23 83 3.5. Resource Server Responds to Client's RPT-Accompanied 84 Resource Request . . . . . . . . . . . . . . . . . . . . 23 85 3.6. Authorization Server Refreshes RPT . . . . . . . . . . . 24 86 3.7. Client Requests Token Revocation . . . . . . . . . . . . 24 87 4. Profiles and Extensions . . . . . . . . . . . . . . . . . . . 24 88 5. Security Considerations . . . . . . . . . . . . . . . . . . . 25 89 5.1. Cross-Site Request Forgery . . . . . . . . . . . . . . . 25 90 5.2. RPT and PCT Exposure . . . . . . . . . . . . . . . . . . 26 91 5.3. Strengthening RPT Protection Using Proof of Possession . 27 92 5.4. Credentials-Guessing . . . . . . . . . . . . . . . . . . 28 93 5.5. Permission Ticket Management . . . . . . . . . . . . . . 28 94 5.6. Naive Implementations of Default-Deny Authorization . . . 28 95 5.7. Requirements for Pre-Established Trust Regarding Claim 96 Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 29 98 5.8. Profiles and Trust Establishment . . . . . . . . . . . . 29 99 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 30 100 6.1. Policy Condition Setting, Time-to-Live Management, and 101 Removal of Authorization Grants . . . . . . . . . . . . . 30 102 6.2. Requesting Party Information at the Authorization Server 30 103 6.3. Resource Owner Information at the Resource Server . . . . 31 104 6.4. Profiles and Trust Establishment . . . . . . . . . . . . 31 105 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 106 7.1. Well-Known URI Registration . . . . . . . . . . . . . . . 31 107 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 31 108 7.2. OAuth 2.0 Authorization Server Metadata Registry . . . . 32 109 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 32 110 7.3. OAuth 2.0 Dynamic Client Registration Metadata Registry . 32 111 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 32 112 7.4. OAuth 2.0 Extension Grant Parameters Registration . . . . 33 113 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 33 114 7.5. OAuth 2.0 Extensions Error Registration . . . . . . . . . 34 115 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 34 116 7.6. OAuth Token Type Hints Registration . . . . . . . . . . . 35 117 7.6.1. Registry Contents . . . . . . . . . . . . . . . . . . 35 118 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 35 119 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 120 9.1. Normative References . . . . . . . . . . . . . . . . . . 36 121 9.2. Informative References . . . . . . . . . . . . . . . . . 37 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 124 1. Introduction 126 This specification defines an extension OAuth 2.0 [RFC6749] grant. 127 The grant enhances OAuth capabilities in the following ways: 129 o The resource owner authorizes protected resource access to clients 130 used by entities that are in a _requesting party_ role. This 131 enables party-to-party authorization, rather than authorization of 132 application access alone. 134 o The authorization server and resource server interact with the 135 client and requesting party in a way that is _asynchronous_ with 136 respect to resource owner interactions. This lets a resource 137 owner configure an authorization server with authorization grant 138 rules (policy conditions) at will, rather than authorizing access 139 token issuance synchronously just after authenticating. 141 For example, bank customer (resource owner) Alice with a bank account 142 service (resource server) can use a sharing management service 143 (authorization server) hosted by the bank to manage access to her 144 various protected resources by spouse Bob, accounting professional 145 Charline, and and financial information aggregation company Decide 146 Account, all using different client applications. Each of her bank 147 accounts is a protected resource, and two different scopes of access 148 she can control on them are viewing account data and accessing 149 payment functions. 151 An OPTIONAL second specification, [UMAFedAuthz], defines a means for 152 an UMA-enabled authorization server and resource server to be loosely 153 coupled, or federated, in a resource owner context. This 154 specification, together with [UMAFedAuthz], constitutes UMA 2.0. 156 1.1. Notational Conventions 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 160 "OPTIONAL" in this document are to be interpreted as described in 161 [RFC2119]. 163 Unless otherwise noted, all parameter names and values are case 164 sensitive. JSON [RFC7159] data structures defined in this 165 specification MAY contain extension parameters that are not defined 166 in this specification. Any entity receiving or retrieving a JSON 167 data structure SHOULD ignore extension parameters it is unable to 168 understand. Extension names that are unprotected from collisions are 169 outside the scope of this specification. 171 1.2. Roles 173 The UMA grant enhances the OAuth definitions of entities in order to 174 accommodate the requesting party role. 176 resource owner 177 An entity capable of granting access to a protected resource, the 178 "user" in User-Managed Access. The resource owner MAY be an end- 179 user (natural person) or MAY be a non-human entity treated as a 180 person for limited legal purposes (legal person), such as a 181 corporation. 183 requesting party 184 A natural or legal person that uses a client to seek access to a 185 protected resource. The requesting party may or may not be the 186 same party as the resource owner. 188 client 189 An application that is capable of making requests for protected 190 resources with the resource owner's authorization and on the 191 requesting party's behalf. 193 resource server 194 A server that hosts resources on a resource owner's behalf and is 195 capable of accepting and responding to requests for protected 196 resources. 198 authorization server 199 A server that protects, on a resource owner's behalf, resources 200 hosted at a resource server. 202 1.3. Abstract Flow 204 The UMA grant enhances the abstract protocol flow of OAuth. 206 Figure 1 shows an example flow illustrating a variety of messaging 207 paths and artifacts. The resource owner entity and its 208 communications with the authorization server are included for 209 completeness, although policy condition setting is outside the scope 210 of this specification and communications among the other four 211 entities are asynchrjonous with respect to resource owner actions. 212 Further, although both claims pushing and interactive claims 213 gathering are shown, both might not typically be used in one 214 scenario. 216 requesting authorization resource resource 217 party client server server owner 218 | | | | | 219 | | |Set policy| | 220 | | |conditions (anytime)| 221 | | |<- - - - - - - - - -| 222 | |Resource request (no access token) | | 223 | |------------------------------------->| | 224 | |401 response with initial permission | | 225 | |ticket, authz server location | | 226 | |<-------------------------------------| | 227 | |Access token (RPT) request | | | 228 | |with permission ticket, | | | 229 | |claim token (push claims) | | | 230 | |-------------------------->| | | 231 | | +----|Authz | | 232 | | +--->|assessment| | 233 | |403 response with new | | | 234 | |permission ticket, | | | 235 | |need_info error, | | | 236 | |redirect_user hint | | | 237 | |<--------------------------| | | 238 |Redirect | | | | 239 |user with | | | | 240 |permission | | | | 241 |ticket | | | | 242 |<-----------| | | | 243 |Follow redirect to authz server | | | 244 |--------------------------------------->| | | 245 |Interactive claims gathering | | | 246 |<- - - - - - - - - - - - - - - - - - - >| | | 247 |Redirect back with new permission | | | 248 |ticket | | | 249 |<---------------------------------------| | | 250 |Follow | | | | 251 |redirect | | | | 252 |to client | | | | 253 |----------->| | | | 254 | |RPT request with permission| | | 255 | |ticket | | | 256 | |-------------------------->| | | 257 | | +----|Authz | | 258 | | +--->|assessment| | 259 | |Response with RPT and PCT | | | 260 | |<--------------------------| | | 261 | |Resource request with RPT | | | 262 | |------------------------------------->| | 263 | |Protected resource | | | 264 | |<-------------------------------------| | 266 Figure 1: Example Flow 268 Following are key concepts relevant to this specification, as 269 illustrated in the figure: 271 requesting party token (RPT) An OAuth access token associated with 272 the UMA grant. An RPT is unique to a requesting party, client, 273 authorization server, resource server, and resource owner. 275 permission Authorized access to a particular resource with some 276 number of scopes bound to that resource. A permission ticket 277 represents some number of requested permissions. An RPT 278 represents some number of granted permissions. Permissions are 279 part of the authorization server's process and are opaque to the 280 client. 282 permission ticket A correlation handle representing requested 283 permissions that is created and maintained by the authorization 284 server, initially passed to the client by the resource server, and 285 presented by the client at the token endpoint and during 286 requesting party redirects. 288 authorization process The process through which the authorization 289 server determines whether it should issue an RPT to the client on 290 the requesting party's behalf, based on a variety of inputs. A 291 key component of the process is authorization assessment. (See 292 Section 1.3.1.) 294 claim A statement of the value or values of one or more attributes 295 of an entity. The authorization server typically needs to collect 296 and assess one or more claims of the requesting party or client 297 against policy conditions as part of protecting a resource. The 298 two methods available for UMA claims collection are claims pushing 299 and interactive claims gathering. Note: Claims collection might 300 involve authentication for unique user identification, but 301 depending on policy conditions might additionally or instead 302 involve the collection of non-uniquely identifying attributes, 303 authorization for some action (for example, see Section 3.3.3), or 304 other statements of agreement. 306 claim token A package of claims provided directly by the client to 307 the authorization server through claims pushing. 309 persisted claims token (PCT) A correlation handle issued by an 310 authorization server that represents a set of claims collected 311 during one authorization process, available for a client to use in 312 attempting to optimize a future authorization process. 314 Note: How the client acquired knowledge of the resource server's 315 interface and the specific endpoint of the desired protected resource 316 is outside the scope of this specification. For example, the 317 resource server might have a programmatic API or it might serve up 318 simple web pages, and the resource owner might have advertised the 319 endpoint publicly on a blog or other website, listed it in a 320 discovery service, or emailed a link to a particular intended 321 requesting party. 323 1.3.1. Authorization Process 325 The authorization process involves the following activities: 327 o Claims collection. Claims pushing by a client is defined in 328 Section 3.3.1, and interactive claims gathering with an end-user 329 requesting party is defined in Section 3.3.2. 331 o Authorization assessment (as defined in Section 3.3.4). 332 Authorization assessment involves the authorization server 333 assembling and evaluating policy conditions, scopes, claims, and 334 any other relevant information sourced outside of UMA claims 335 collection flows, in order to mitigate access authorization risk. 337 o Authorization results determination (as defined in Section 3.3.4). 338 The authorization server either returns a success code (as defined 339 in Section 3.3.5), an RPT, and an optional PCT, or an error code 340 (as defined in Section 3.3.6). If the error code is "need_info" 341 or "request_submitted", the authorization server provides a 342 permission ticket, giving the client an opportunity to continue 343 within the same authorization process (including engaging in 344 further claims collection). 346 Different choices of claims collection methods, other inputs to 347 authorization assessment, and error codes might be best suited for 348 different deployment ecosystems. For example, where no pre- 349 established relationship is expected between the resource owner's 350 authorization server and the requesting party, initial requesting 351 party redirection might be a useful pattern, at which point the 352 authorization server might either authenticate the requesting party 353 locally or serve as a relying party for a remote identity provider. 354 Where a common authorization server functions as an identity provider 355 for all resource owners and requesting parties, having the client 356 push claim tokens sourced from that central server itself with a pre- 357 negotiated format and contents might be a useful pattern. 359 2. Authorization Server Metadata 361 The authorization server supplies metadata in a discovery document to 362 declare its endpoints. The client uses this discovery document to 363 discover these endpoints for use in the flows defined in Section 3. 365 The authorization server MUST make a discovery document available. 366 The structure of the discovery document MUST conform to that defined 367 in [OAuthMeta]. The discovery document MUST be available at an 368 endpoint formed by concatenating the string "/.well-known/ 369 uma2-configuration" to the "issuer" metadata value defined in 370 [OAuthMeta], using the well-known URI syntax and semantics defined in 371 [RFC5785]. In addition to the metadata defined in [OAuthMeta], this 372 specification defines the following metadata for inclusion in the 373 discovery document: 375 claims_interaction_endpoint 376 OPTIONAL. A static endpoint URI at which the authorization 377 server declares that it interacts with end-user requesting 378 parties to gather claims. If the authorization server also 379 provides a claims interaction endpoint URI as part of its 380 "redirect_user" hint in a "need_info" response to a client on 381 authorization failure (see Section 3.3.6), that value overrides 382 this metadata value. Providing the static endpoint URI is 383 useful for enabling interactive claims gathering prior to any 384 pushed-claims flows taking place, for example, for gathering 385 authorization for subsequent claim pushing (see Section 3.3.2). 387 uma_profiles_supported 388 OPTIONAL. UMA profiles and extensions supported by this 389 authorization server. The value is an array of string values, 390 where each string value is a URI identifying an UMA profile or 391 extension. As discussed in Section 4, an authorization server 392 supporting a profile or extension related to UMA SHOULD supply 393 the specification's identifying URI (if any) here. 395 If the authorization server supports dynamic client registration, it 396 MUST allow client applications to register "claims_redirect_uri" 397 metadata, as defined in Section 3.3.2, using the following metadata 398 field: 400 claims_redirect_uris 401 OPTIONAL. Array of one or more claims redirection URIs. 403 3. Flow Details 405 3.1. Client Requests Resource Without Providing an Access Token 407 The client requests a protected resource without providing any access 408 token. 410 Note: This process does not assume that any relevant policy 411 conditions have already been defined at the authorization server. 413 For an example of how the resource server can put resources under the 414 protection of an authorization server, see [UMAFedAuthz]. 416 Example of a client request at a protected resource without providing 417 an access token: 419 GET /users/alice/album/photo.jpg HTTP/1.1 Host: 420 photoz.example.com ... 422 3.2. Resource Server Responds to Client's Tokenless Access Attempt 424 The resource server responds to the client's tokenless resource 425 request. 427 The resource server MUST obtain a permission ticket from the 428 authorization server to provide in its response, but the means of 429 doing so is outside the scope of this specification. For an example 430 of how the resource server can obtain the permission ticket, see 431 [UMAFedAuthz]. 433 The process of choosing what permissions to request from the 434 authorization server may require interpretation and mapping of the 435 client's resource request. The resource server SHOULD request a set 436 of permissions with scopes that is reasonable for the client's 437 resource request. 439 Note: In order for the resource server to know which authorization 440 server to approach for the permission ticket and on which resource 441 owner's behalf, it needs to derive the necessary information using 442 cues provided by the structure of the API where the resource request 443 was made, rather than by an access token. Commonly, this information 444 can be passed through the URI, headers, or body of the client's 445 request. Alternatively, the entire interface could be dedicated to 446 the use of a single resource owner and protected by a single 447 authorization server. 449 See Section 5.5 for permission ticket security considerations. 451 3.2.1. Resource Server Response to Client on Permission Request Success 453 If the resource server is able to provide a permission ticket from 454 the authorization server, it responds to the client by providing a 455 "WWW-Authenticate" header with the authentication scheme "UMA", with 456 the "issuer" URI from the authorization server's discovery document 457 in an "as_uri" parameter and the permission ticket in a "ticket" 458 parameter. 460 For example: 462 HTTP/1.1 401 Unauthorized WWW-Authenticate: UMA 463 realm="example", as_uri="https://as.example.com", 464 ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de" ... 466 3.2.2. Resource Server Response to Client on Permission Request Failure 468 If the resource server is unable to provide a permission ticket from 469 the authorization server, then it includes a header of the following 470 form in its response to the client: "Warning: 199 - "UMA 471 Authorization Server Unreachable"". 473 For example: 475 HTTP/1.1 403 Forbidden Warning: 199 - "UMA Authorization 476 Server Unreachable" ... 478 Without an authorization server location and permission ticket, the 479 client is unable to continue. 481 3.3. Client Seeks RPT on Requesting Party's Behalf 483 The client seeks issuance of an RPT. 485 This process assumes that: 487 o The client has obtained a permission ticket and an authorization 488 server location from the resource server. 490 o The client has retrieved the authorization server's discovery 491 document as needed. 493 o The client has obtained a client identifier or a full set of 494 client credentials as appropriate, either statically or 495 dynamically (for example, through [RFC7591] or 496 [OIDCDynClientReg]). This grant works with clients of both 497 confidential and public types. 499 Initiation of this process has two options. One option is for the 500 client to request an RPT from the token endpoint immediately, as 501 defined in Section 3.3.1. Claim pushing is available at this 502 endpoint. The other option, if the authorization server's discovery 503 document statically provided a claims interaction endpoint, is for 504 the client to redirect the requesting party immediately to that 505 endpoint for interactive claims gathering, as defined in 506 Section 3.3.2. 508 3.3.1. Client Request to Authorization Server for RPT 510 The client makes a request to the token endpoint by sending the 511 following parameters: 513 grant_type REQUIRED. MUST be the value 514 "urn:ietf:params:oauth:grant-type:uma-ticket". 516 ticket REQUIRED. The most recent permission ticket received by the 517 client as part of this authorization process. 519 claim_token OPTIONAL. If this parameter is used, it MUST appear 520 together with the "claim_token_format" parameter. A string 521 containing directly pushed claim information in the indicated 522 format. It MUST be base64url encoded unless specified otherwise 523 by the claim token format. The client MAY provide this 524 information on both first and subsequent requests to this 525 endpoint. The client and authorization server together might need 526 to establish proper audience restrictions for the claim token 527 prior to claims pushing. See Section 5.7 and Section 6.2 for 528 security and privacy considerations regarding pushing of claims. 530 claim_token_format OPTIONAL. If this parameter is used, it MUST 531 appear together with the "claim_token" parameter. A string 532 specifying the format of the claim token in which the client is 533 directly pushing claims to the authorization server. The string 534 MAY be a URI. Examples of potential types of claim token formats 535 are [OIDCCore] ID Tokens and SAML assertions. 537 pct OPTIONAL. If the authorization server previously returned a PCT 538 along with an RPT, the client MAY include the PCT in order to 539 optimize the process of seeking a new RPT. Given that some claims 540 represented by a PCT are likely to contain identity information 541 about a requesting party, a client supplying a PCT in its RPT 542 request MUST make a best effort to ensure that the requesting 543 party using the client now is the same as the requesting party 544 that was associated with the PCT when it was issued. See 545 Section 5.7 and Section 6.2 for additional security and privacy 546 considerations regarding persistence of claims. The client MAY 547 use the PCT for the same requesting party when seeking an RPT for 548 a resource different from the one sought when the PCT was issued, 549 or a protected resource at a different resource server entirely. 550 See Section 5.2 for additional PCT security considerations. See 551 Section 3.3.5 for the form of the authorization server's response 552 with a PCT. 554 rpt OPTIONAL. Supplying an existing RPT (which MAY be expired) 555 gives the authorization server the option of upgrading that RPT 556 instead of issuing a new one (see Section 3.3.5.1 for more about 557 this option). 559 scope OPTIONAL. A string of space-separated values representing 560 requested scopes. For the authorization server to consider any 561 requested scope in its assessment, the client MUST have been pre- 562 registered for the same scope with the authorization server. The 563 client should consult the resource server's API documentation for 564 details about which scopes it can expect the resource server's 565 initial returned permission ticket to represent as part of the 566 authorization assessment (see Section 3.3.4). 568 Example of a request message with no optional parameters (line breaks 569 are shown only for display convenience): 571 POST /token HTTP/1.1 Host: as.example.com Authorization: 572 Basic jwfLG53^sad$#f ... 573 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Auma-ticket 574 &ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de 576 Example of a request message that includes an existing RPT for 577 upgrading, a scope being sought that was previously registered with 578 the authorization server, and a PCT and a claim token for 579 consideration in the authorization process: 581 POST /token HTTP/1.1 Host: as.example.com Authorization: 582 Basic jwfLG53^sad$#f ... 583 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Auma-ticket 584 &ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de 585 &claim_token=eyj0... 586 &claim_token_format=http%3A%2F%2Fopenid.net%2Fspecs%2Fopenid-connect-core-1_0.html%23IDToken 587 &pct=c2F2ZWRjb25zZW50 588 &rpt=sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv 589 &scope=read 591 This specification provides a means to define profiles of claim token 592 formats for use with UMA (see Section 4). The authorization server 593 SHOULD document the profiles it supports in its discovery document. 595 3.3.2. Client Redirect of Requesting Party to Authorization Server for 596 Interactive Claims-Gathering 598 The client redirects an end-user requesting party to the 599 authorization server's claims interaction endpoint for one or more 600 interactive claims-gathering processes as the authorization server 601 requires. These can include direct interactions, such as account 602 registration and authentication local to the authorization server as 603 an identity provider, filling out a questionnaire, or asking the user 604 to authorize subsequent collection of claims by interaction or 605 pushing, and persistent storage of such claims (for example, as 606 associated with a PCT). Interactions could also involve further 607 redirection, for example, for federated (such as social) 608 authentication at a remote identity provider, and other federated 609 claims gathering. See Section 5.7 and Section 6.2 for security and 610 privacy considerations regarding pushing and persistence of claims. 612 The client might have initiated redirection immediately on receiving 613 an initial permission ticket from the resource server, or, for 614 example, in response to receiving a "redirect_user" hint in a 615 "need_info" error (see Section 3.3.6). 617 In order for the client to redirect the requesting party immediately 618 on receiving the initial permission ticket from the resource server, 619 this process assumes that the authorization server has statically 620 declared its claims interaction endpoint in its discovery document. 622 The client constructs the request URI by adding the following 623 parameters to the query component of the claims interaction endpoint 624 URI using the "application/x-www-form-urlencoded" format: 626 client_id REQUIRED. The client's identifier issued by the 627 authorization server. 629 ticket REQUIRED. The most recent permission ticket received by the 630 client as part of this authorization process. 632 claims_redirect_uri REQUIRED if the client has pre-registered 633 multiple claims redirection URIs or has pre-registered no claims 634 redirection URI; OPTIONAL only if the client has pre-registered a 635 single claims redirection URI. The URI to which the client wishes 636 the authorization server to direct the requesting party's user 637 agent after completing its interaction. The URI MUST be absolute, 638 MAY contain an "application/x-www-form-urlencoded"-formatted query 639 parameter component that MUST be retained when adding additional 640 parameters, and MUST NOT contain a fragment component. The client 641 SHOULD pre-register its "claims_redirect_uri" with the 642 authorization server, and the authorization server SHOULD require 643 all clients, and MUST require public clients, to pre-register 644 their claims redirection endpoints (see Section 2). Claims 645 redirection URIs are different from the redirection URIs defined 646 in [RFC6749] in that they are intended for the exclusive use of 647 requesting parties and not resource owners. Therefore, 648 authorization servers MUST NOT redirect requesting parties to pre- 649 registered redirection URIs defined in [RFC6749] unless such URIs 650 are also pre-registered specifically as claims redirection URIs. 651 If the URI is pre-registered, this URI MUST exactly match one of 652 the pre-registered claims redirection URIs, with the matching 653 performed as described in Section 6.2.1 of [RFC3986] (Simple 654 String Comparison). 656 state RECOMMENDED. An opaque value used by the client to maintain 657 state between the request and callback. The authorization server 658 includes this value when redirecting the user agent back to the 659 client. The use of this parameter is for preventing cross-site 660 request forgery (see Section 5.1 for further security 661 information). 663 Example of a request issued by a client application (line breaks are 664 shown only for display convenience): 666 GET /rqp_claims?client_id=some_client_id 667 &ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de 668 &claims_redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect_claims 669 &state=abc HTTP/1.1 Host: as.example.com 671 3.3.3. Authorization Server Redirect of Requesting Party Back to Client 672 After Interactive Claims-Gathering 674 At the conclusion of a successful interaction with the requesting 675 party, the authorization server returns the requesting party to the 676 client, adding the following parameters to the query component of the 677 claims redirection URI using the "application/x-www-form-urlencoded" 678 format: 680 ticket REQUIRED. A permission ticket that allows the client to make 681 further requests to the authorization server during this 682 authorization process. The value MUST NOT be the same as the one 683 the client used to make its request. 685 state OPTIONAL. The same state value that the client provided in 686 the request. It MUST be present if and only if the client 687 provided it (see Section 5.1 for further security information). 689 Note: Interactive claims-gathering processes are outside the scope of 690 this specification. The purpose of the interaction is for the 691 authorization server to gather information for its own authorization 692 assessment purposes. This redirection does not involve sending any 693 of the information back to the client. 695 The authorization server MAY use interactive claims-gathering to 696 request authorization from the requesting party for persisting claims 697 across authorization processes. Such persisted claims will be 698 represented by a PCT issued to the client in a subsequent step. 700 The client MUST ignore unrecognized response parameters. If the 701 request fails due to a missing, invalid, or mismatching claims 702 redirection URI, or if the client identifier is missing or invalid, 703 the authorization server SHOULD inform the requesting party of the 704 error and MUST NOT automatically redirect the user agent to the 705 invalid redirection URI. 707 If the request fails for reasons other than a missing or invalid 708 claims redirection URI, the authorization server informs the client 709 by adding an "error" parameter to the query component of the claims 710 redirection URI as defined in Section 4.1.2.1 of [RFC6749]. 712 Example of a response issued by an authorization server (line breaks 713 are shown only for display convenience): 715 HTTP/1.1 302 Found Location: 716 https://client.example.com/redirect_claims? 717 ticket=cHJpdmFjeSBpcyBjb250ZXh0LCBjb250cm9s&state=abc 719 3.3.4. Authorization Assessment and Results Determination 721 When the authorization server has received a request for an RPT from 722 a client as defined in Section 3.3.1, it assesses whether the client 723 is authorized to receive the requested RPT and determines the 724 results. 726 The authorization server MUST apply the following conceptual 727 authorization assessment calculation in determining authorization 728 results. Note: As this calculation is internal to authorization 729 server operations, its particulars are outside the scope of this 730 specification. 732 1. Assemble a set called _RegisteredScopes_ containing the scopes 733 for which the client is pre-registered (either dynamically or 734 through some static process) at the authorization server. 735 Assemble a set called _RequestedScopes_ containing the scopes the 736 client most recently requested at the token endpoint. The 737 permission ticket that was presented by the client at the token 738 endpoint represents some number of resources, each with some 739 number of scopes; for each of those resources, assemble a set 740 called _TicketScopes(resource)_ containing the scopes associated 741 with that resource. 743 2. For each resource in the permission ticket, determine a final set 744 of requested scopes as follows: 745 _RequestedScopes(resource)={TicketScopes(resource) ∪ 746 {RegisteredScopes ∩ RequestedScopes}}_. Treat each scope in 747 _{RegisteredScopes ∩ RequestedScopes}_ as matching any 748 available scope associated with a resource found in the 749 permission ticket. 751 3. For each _RequestedScopes(resource)_ set, determine all operative 752 policy conditions, and claims and other relevant information 753 serving as input to them, and evaluate its authorization status. 755 4. For each scope in _RequestedScopes(resource)_ that passes the 756 evaluation, add it to a set called 757 _CandidateGrantedScopes(resource)_. 759 Note: Claims and other information gathered during one authorization 760 process may become out of date in terms of their relevance for future 761 authorization processes. The authorization server is responsible for 762 managing such relevance wherever information associated with a PCT, 763 or other persistently stored information, is used as input to 764 authorization, including policy conditions themselves. 766 Note: Since the authorization server's policy expression and 767 evaluation capabilities are outside the scope of this specification, 768 any one implementation might take a simple or arbitrarily complex 769 form, with varying abilities to combine or perform calculations over 770 claims and their values. For example, logical operations such as 771 accepting "either claim value A or claim value B" as correct are 772 possible to implement. 774 In the authorization results phase, the authorization server examines 775 each _CandidateGrantedScopes(resource)_ set to determine whether to 776 issue an RPT and what permissions should be associated with it. If 777 all _RequestedScopes(resource)_ sets can be granted, then the 778 authorization server subsequently responds with a success code and 779 issues an RPT containing _CandidateGrantedScopes_ for each resource. 781 Otherwise, the authorization server subsequently issues either an RPT 782 containing _CandidateGrantedScopes_ for each resource, or one of the 783 error codes, as appropriate. The reason for the two options is that 784 granting only partial scopes might not be useful for the client's and 785 requesting party's purposes in seeking authorization for access. The 786 choice of error depends on policy conditions and the authorization 787 server's implementation choices. The conditions for the "need_info", 788 "request_denied", and "request_submitted" error codes are dependent 789 on authorization assessment and thus these codes might be more likely 790 than the others to be issued subsequent to such a calculation. 792 The following example illustrates authorization assessment and 793 partial results. 795 o The resource server has three of the resource owner's resources of 796 interest to the client and requesting party, "photo1" and "photo2" 797 with scopes "view", "resize", "print", and "download", and "album" 798 with scopes "view", "edit", and "download". It considers "photo1" 799 and "photo2" to be logically "inside" "album". 801 o Though the exact contents of RPTs, permissions, and permission 802 requests are opaque to the client, the resource server has 803 documented its API, available scopes, and permission requesting 804 practices. For example, if the client requests an album resource, 805 it expects that the resource server will request a permission for 806 the album with a scope that approximates the attempted client 807 operation, but will also request permissions for all the photos 808 "inside" the album, with "view" scope only. 810 o The client has a pre-registered scope of "download" with the 811 authorization server. This enables the client later to request 812 this scope dynamically on behalf of its requesting party from the 813 token endpoint. The authorization server assembles the set 814 _RegisteredScopes_ with contents of scope "download". 816 o The client requests the album resource in an attempt to edit it, 817 so the resource server obtains a permission ticket with three 818 permissions in it: for "album" with a scope of "edit", and for 819 "photo1" and "photo2", each with a scope of "view". The 820 authorization server assembles the following sets: 821 _TicketScopes_("album") containing "edit", 822 _TicketScopes_("photo1") containing "view", and 823 _TicketScopes_("photo2") containing "view". 825 o While asking for an RPT at the token endpoint, the client requests 826 "download" scope on the requesting party's behalf. The 827 authorization server determines the contents of the following 828 sets: _RequestedScopes_("album") containing "edit" and "download", 829 _RequestedScopes_("photo1") containing "view" and "download", and 830 _RequestedScopes_("photo2") containing "view" and "download". 832 o The resource owner has set policy conditions that allow access by 833 this particular requesting party only to "photo1" and only for 834 "view" scope. 836 o Based on the authorization server's authorization assessment 837 calculation, it determines the contents of the following sets: 838 _CandidateGrantedScopes_("album") containing no scopes, 839 _CandidateGrantedScopes_("photo1") containing "view", and 840 _CandidateGrantedScopes_("photo2") containing no scopes. This 841 adds up to less than in the corresponding _RequestedScopes_ sets. 842 The authorization server therefore has a choice whether to issue 843 an RPT (in this case, containing a permission for "photo1" with 844 "view" scope) or an error (say, "request_denied", or 845 "request_submitted" if has a way to notify the resource owner 846 about the album editing resource request and seek an added policy 847 covering it). 849 See Section 5.6 for a discussion of authorization implementation 850 threats. 852 3.3.5. Authorization Server Response to Client on Authorization Success 854 If the authorization server's assessment process results in issuance 855 of permissions, it issues the RPT with which it has associated the 856 permissions by using the successful response form defined in 857 Section 5.1 of [RFC6749]. 859 The authorization server MAY return a refresh token. See Section 3.6 860 for more information about refreshing an RPT. 862 The authorization server MAY add the following parameters to its 863 response: 865 pct OPTIONAL. A correlation handle representing claims and other 866 information collected during this authorization process, which the 867 client is able to present later in order to optimize future 868 authorization processes on behalf of a requesting party. The PCT 869 MUST be unguessable by an attacker. The PCT MUST NOT disclose 870 claims from the requesting party directly to possessors of the 871 PCT. Instead, such claims SHOULD be associated by reference to 872 the PCT or expressed in an encrypted format that can be decrypted 873 only by the authorization server that issued the PCT. See 874 Section 3.3.2 for more information about the end-user requesting 875 party interaction option. See Section 5.2 for additional PCT 876 security considerations. 878 upgraded OPTIONAL. Boolean value. If the client submits an RPT in 879 the request and the authorization server includes the permissions 880 of the RPT from the request as part of the newly issued RPT, then 881 it MUST set this value to "true". If it sets the value to "false" 882 or the value is absent, the client MUST act as if the newly issued 883 RPT does not include the permissions associated with the RPT from 884 the request. (See Section 3.3.5.1.) 886 The authorization server MAY include any of the parameters defined in 887 Section 5.1 of [RFC6749] on its response, except that it SHOULD NOT 888 include the "scope" parameter. This is because for an RPT's 889 permissions, each scope is associated with a specific resource, even 890 though this association is opaque to the client. Note: The outcome 891 of authorization assessment may result in expiration periods for 892 RPTs, permissions, and refresh tokens that can affect the client's 893 later requests for refreshing the RPT. 895 Example: 897 HTTP/1.1 200 OK Content-Type: application/json ... { 898 "access_token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 899 "token_type":"Bearer" } 901 Example with a PCT in the response: 903 HTTP/1.1 200 OK Content-Type: application/json ... { 904 "access_token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 905 "token_type":"Bearer", "pct":"c2F2ZWRjb25zZW50" } 907 3.3.5.1. Authorization Server Upgrades RPT 909 The authorization server MAY implement RPT upgrading. The 910 authorization server SHOULD document its practices regarding RPT 911 upgrades and to act consistently with respect to RPT upgrades so as 912 to enable clients to manage received RPTs efficiently. 914 If the authorization server has implemented RPT upgrading, the client 915 has submitted an RPT in its request, and the result is success, the 916 authorization server adds the permissions from the client's previous 917 RPT to the RPT it is about to issue, setting the value of "upgraded" 918 in its response containing the upgraded RPT to "true". 920 If the authorization server is upgrading an RPT, and the RPT string 921 is new rather than repeating the RPT provided by the client in the 922 request, then the authorization server SHOULD revoke the existing 923 RPT, if possible, and the client MUST discard its previous RPT. If 924 the authorization server does not upgrade the RPT but issues a new 925 RPT, the client MAY retain the existing RPT. 927 Example with "upgraded" in the response: 929 HTTP/1.1 200 OK Content-Type: application/json ... { 930 "access_token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 931 "token_type":"Bearer", "upgraded":true } 933 3.3.6. Authorization Server Response to Client on Authorization Failure 935 If the client's request to the token endpoint results in failure, the 936 authorization server responds with an error, as defined in 937 Section 5.2 of [RFC6749] and as follows. 939 invalid_grant If the provided permission ticket was not found at the 940 authorization server, or the provided permission ticket has 941 expired, or any other original reasons to use this error code are 942 found as defined in [RFC6749], the authorization server responds 943 with the HTTP 400 (Bad Request) status code. 945 invalid_scope At least one of the scopes included in the request 946 does not match an available scope for any of the resources 947 associated with requested permissions for the permission ticket 948 provided by the client. The authorization server MAY also return 949 this error when at least one of the scopes included in the request 950 does not match a scope for which the client is pre-registered with 951 the authorization server. The authorization server responds with 952 the HTTP 400 (Bad Request) status code. 954 need_info The authorization server needs additional information in 955 order for a request to succeed, for example, a provided claim 956 token was invalid or expired, or had an incorrect format, or 957 additional claims are needed to complete the authorization 958 assessment. The authorization server responds with the HTTP 403 959 (Forbidden) status code. It MUST include a "ticket" parameter, 960 and it MUST also include either the "required_claims" parameter or 961 the "redirect_user" parameter, or both, as hints about the 962 information it needs. 964 ticket REQUIRED. A permission ticket that allows the client to 965 make a further request to the authorization server's token 966 endpoint as part of this same authorization process, 967 potentially immediately. The value MUST NOT be the same as the 968 one the client used to make its request. 970 required_claims An array of objects that describe the required 971 claims, with the following subparameters: 973 claim_token_format OPTIONAL. An array of strings specifying a 974 set of acceptable formats for a claim token pushed by the 975 client containing this claim, as defined in Section 3.3.1. 976 Any one of the referenced formats would satisfy the 977 authorization server's requirements. Each string MAY be a 978 URI. 980 claim_type OPTIONAL. A string, indicating the expected 981 interpretation of the provided claim value. The string MAY 982 be a URI. 984 friendly_name OPTIONAL. A string that provides a human- 985 readable form of the claim's name. This can be useful as a 986 "display name" for use in user interfaces in cases where the 987 actual name is complex or opaque, such as an OID or a UUID. 989 issuer OPTIONAL. An array of strings specifying a set of 990 acceptable issuing authorities for the claim. Any one of 991 the referenced authorities would satisfy the authorization 992 server's requirements. Each string MAY be a URI. 994 name OPTIONAL. A string (which MAY be a URI) representing the 995 name of the claim; the "key" in a key-value pair. 997 redirect_user The claims interaction endpoint URI to which to 998 redirect the end-user requesting party at the authorization 999 server to continue the process of interactive claims gathering, 1000 as defined in Section 3.3.2. For example, the authorization 1001 server could require the requesting party to log in to an 1002 account, or fill out a CAPTCHA to help prove humanness, or 1003 perform any number of other interactive tasks. If the 1004 requesting party is not an end-user, then no client action is 1005 possible on receiving the hint. If a static claims interaction 1006 endpoint was also provided in the authorization server's 1007 discovery document, then this value overrides the static value. 1008 Providing a value in this response might be appropriate, for 1009 example, if the URI needs to be customized per requesting party 1010 with a query parameter. 1012 request_denied The client is not authorized to have these 1013 permissions. The authorization server responds with the HTTP 403 1014 (Forbidden) status code. 1016 request_submitted The authorization server requires intervention by 1017 the resource owner to determine whether the client is authorized 1018 to have these permissions. The authorization server responds with 1019 the HTTP 403 (Forbidden) status code. It MUST include a "ticket" 1020 parameter and MAY include an "interval" parameter. 1022 ticket REQUIRED. A permission ticket that allows the client to 1023 make one or more later polling requests to the token endpoint 1024 as part of this same authorization process, when the resource 1025 owner might have completed some approval (or denial) action. 1026 The value MUST NOT be the same as the one the client used to 1027 make its request. 1029 interval OPTIONAL. The minimum amount of time in seconds that 1030 the client SHOULD wait between polling requests to the token 1031 endpoint. See Section 5.5 for security considerations in 1032 scenarios involving polling and consequences for permission 1033 ticket lifetimes. 1035 Example when the permission ticket was not found or has expired: 1037 HTTP/1.1 400 Bad Request Content-Type: application/json 1038 Cache-Control: no-store ... { "error":"invalid_grant" } 1040 Example of a "need_info" response with hints about required claims: 1042 HTTP/1.1 403 Forbidden Content-Type: application/json 1043 Cache-Control: no-store ... { "error":"need_info", 1044 "ticket":"ZXJyb3JfZGV0YWlscw==", "required_claims":[ { 1045 "claim_token_format":[ 1046 "http://openid.net/specs/openid-connect-core-1_0.html#IDToken" ], 1047 "claim_type":"urn:oid:0.9.2342.19200300.100.1.3", 1048 "friendly_name":"email", "issuer":[ "https://example.com/idp" ], 1049 "name":"email23423453ou453" } ] } 1051 Example of a "need_info" response with a hint to redirect the 1052 requesting party to a claims interaction endpoint: 1054 HTTP/1.1 403 Forbidden Content-Type: application/json 1055 Cache-Control: no-store ... { "error":"need_info", 1056 "ticket":"ZXJyb3JfZGV0YWlscw==", 1057 "redirect_user":"https://as.example.com/rqp_claims?id=2346576421" 1058 } 1060 Example when the client was not authorized to have the permissions: 1062 HTTP/1.1 403 Forbidden Content-Type: application/json 1063 Cache-Control: no-store ... { "error":"request_denied" } 1065 Example when the authorization server requires resource owner 1066 intervention, including the optional "interval" parameter: 1068 HTTP/1.1 403 Forbidden Content-Type: application/json 1069 Cache-Control: no-store ... { "error":"request_submitted", 1070 "ticket?:?ZXJyb3JfZGV0YWlscw==", "interval": 5 } 1072 3.4. Client Requests Resource and Provides an RPT 1074 The client requests the resource, now in possession of an RPT. The 1075 client uses [RFC6750] for a bearer token, and any other suitable 1076 presentation mechanism for an RPT of another access token type. 1078 Example of a client request for the resource carrying an RPT: 1080 GET /users/alice/album/photo.jpg HTTP/1.1 Authorization: 1081 Bearer sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv Host: photoz.example.com 1082 ... 1084 3.5. Resource Server Responds to Client's RPT-Accompanied Resource 1085 Request 1087 The resource server responds to the client's RPT-accompanied resource 1088 request. 1090 If the resource request fails, the resource server responds as if the 1091 request were unaccompanied by an access token, as defined in 1092 Section 3.2. 1094 The resource server MUST NOT give access in the case of an invalid 1095 RPT or an RPT associated with insufficient authorization. 1097 For an example of how the resource server can introspect the RPT and 1098 its permissions at the authorization server prior to responding to 1099 the client's request, see [UMAFedAuthz]. 1101 3.6. Authorization Server Refreshes RPT 1103 As noted in Section 3.3.5, when issuing an RPT, the authorization 1104 server MAY also issue a refresh token. 1106 Having previously received a refresh token from the authorization 1107 server, the client MAY use the refresh token grant as defined in 1108 [RFC6749] to attempt to refresh an expired RPT. If the client 1109 includes the "scope" parameter in its request, the authorization 1110 server MAY limit the scopes in the permissions associated with any 1111 resulting refreshed RPT to the scopes requested by the client. 1113 The authorization server MUST NOT perform an authorization assessment 1114 calculation on receiving the client's request to refresh an RPT. 1116 3.7. Client Requests Token Revocation 1118 If the authorization server presents a token revocation endpoint as 1119 defined in [RFC7009], the client MAY use the endpoint to request 1120 revocation of an RPT (access token), refresh token, or PCT previously 1121 issued to it on behalf of a requesting party. This specification 1122 defines the following token type hint value: 1124 pct Helps the authorization server optimize lookup of a PCT for 1125 revocation. 1127 4. Profiles and Extensions 1129 An UMA profile restricts UMA's available options. An UMA extension 1130 defines how to use UMA's extensibility points. The two can be 1131 combined. Some reasons for creating profiles and extensions include: 1133 o A profile restricting options in order to tighten security 1135 o A profile/extension restricting options and adding messaging 1136 parameters for use with a specific industry API 1138 o A profile that documents a specific URI, format, and 1139 interpretation for pushed claim tokens (see Section 3.3.1) 1141 o An extension that defines additional metadata for the 1142 authorization server discovery document to define machine-readable 1143 usage details 1145 The following actions are RECOMMENDED regarding the creation and use 1146 of profiles and extensions: 1148 o The creator of a profile or extension related to UMA SHOULD assign 1149 it a uniquely identifying URI. 1151 o The authorization server supporting a profile or extension related 1152 to UMA with such a URI SHOULD supply the identifying URI in its 1153 "uma_profiles_supported" metadata (see Section 2). 1155 5. Security Considerations 1157 This specification relies mainly on OAuth 2.0 security mechanisms as 1158 well as transport-level security. Thus, implementers are strongly 1159 advised to read [BCP195] and the security considerations in [RFC6749] 1160 (Section 10) and [RFC6750] (Section 5) along with the security 1161 considerations of any other OAuth token-defining specifications in 1162 use, along with the entire [RFC6819] specification, and apply the 1163 countermeasures described therein. As well, implementers should take 1164 into account the security considerations in all other normatively 1165 referenced specifications. 1167 The following sections describe additional security considerations. 1169 5.1. Cross-Site Request Forgery 1171 Redirection used for gathering claims interactively from an end-user 1172 requesting party (described in Section 3.3.2) creates the potential 1173 for cross-site request forgery (CSRF). This may be the result of an 1174 open redirect if the authorization server does not force the client 1175 to pre-register its claims redirection endpoint, and server-side 1176 artifact tampering if the client does not avail itself of the "state" 1177 parameter. 1179 A CSRF attack against the authorization server's claims interaction 1180 endpoint can result in an attacker obtaining authorization for access 1181 through a malicious client without involving or alerting the end-user 1182 requesting party. The authorization server MUST implement CSRF 1183 protection for its claims interaction endpoint and ensure that a 1184 malicious client cannot obtain authorization without the awareness 1185 and involvement of the requesting party. 1187 If the client uses the interactive claims gathering feature, it MUST 1188 implement CSRF protection for its claims redirection URI. It SHOULD 1189 use the "state" parameter when redirecting the requesting party to 1190 the claims interaction endpoint. The value of the "state" parameter 1191 MUST be unguessable by an attacker. Once the authorization server 1192 redirects the requesting party back, with the required binding value 1193 contained in the "state" parameter, the client MUST check that the 1194 value of the "state" parameter received is equal to the value sent in 1195 the initial redirection request. Depending on the type of 1196 application, a client has several methods for storing and later 1197 verifying the value of the "state" parameter in between the initial 1198 redirect and the eventual resulting request to the claims redirection 1199 URI, including storage in a server-side session-bound variable, 1200 cryptographic derivation from a browser cookie, or secure 1201 application-level storage. The client MUST treat requests containing 1202 an invalid or unknown "state" parameter value as an error. 1204 The "state" parameter SHOULD NOT include sensitive client or 1205 requesting party information in plain text, as it is transmitted 1206 through third-party components (the requesting party's user agent) 1207 and could be stored insecurely. 1209 5.2. RPT and PCT Exposure 1211 When a client redirects an end-user requesting party to the claims 1212 interaction endpoint, the client provides no a priori context to the 1213 authorization server about which user is appearing at the endpoint, 1214 other than implicitly through the permission ticket. Thus, a 1215 malicious client has the opportunity to switch end-users -- say, 1216 enabling malicious end-user Carlos to impersonate legitimate end-user 1217 Bob, who might be represented by a PCT already in that client's 1218 possession and might even have authorized the issuance of that PCT -- 1219 after the redirect completes and before it returns to the token 1220 endpoint to seek permissions. 1222 To mitigate this threat, the authorization server, with the support 1223 of the resource owner, should consider the following strategies in 1224 combination. 1226 o Require that the requesting party legitimately represent the 1227 wielder of the RPT on a legal or contractual level. This solution 1228 alone does not reduce the risk from a technical perspective. 1230 o Gather claims interactively from an end-user requesting party that 1231 demonstrate that some sufficiently strong level of authentication 1232 was performed. 1234 o Require claims to have a high degree of freshness in order for 1235 them to satify policy conditions. 1237 o Tighten time-to-live strategies around RPTs and their associated 1238 permissions (see Section 6.1). 1240 The client MUST only share the RPT (access token) with the resource 1241 server and authorization server, as explained in Section 10.3 of 1242 [RFC6749], and thus MUST keep it confidential from the requesting 1243 party. Because a malicious requesting party (the user of the client 1244 in the UMA grant) may have incentives to steal an RPT that the 1245 resource owner (the user of the client in other OAuth grants) does 1246 not, this security consideration takes on especial importance. 1248 The PCT is similar to a refresh token in that it allows non- 1249 interactive issuance of access tokens. The authorization server and 1250 client MUST keep the PCT confidential in transit and storage, and 1251 MUST NOT share the PCT with any entity other than each other. The 1252 authorization server MUST maintain the binding between the PCT and 1253 the client to which it was issued. 1255 Given that the PCT represents a set of requesting party claims, a 1256 client supplying a PCT in its RPT request MUST make a best effort to 1257 ensure that the requesting party using the client now is the same as 1258 the requesting party that was associated with the PCT when it was 1259 issued. Different clients will have different capabilities in this 1260 respect; for example, some applications are single-user and perform 1261 no local authentication, associating all PCTs with the "current 1262 user", while others might have more sophisticated authentication and 1263 user mapping capabilities. 1265 If the authorization server has reason to believe that a PCT is 1266 compromised, for example, if the PCT has been supplied by a client 1267 that has "impossible geography" parameters, the authorization server 1268 should consider not using the claims based on that PCT in its 1269 authorization assessment. 1271 5.3. Strengthening RPT Protection Using Proof of Possession 1273 After the client's resource request with an RPT, assuming the client 1274 sent an RPT of the bearer style such as defined in [RFC6750], the 1275 resource server will have received from the client the entire secret 1276 portion of the token. This specification assumes only bearer-type 1277 tokens because they are the only type standardized as of this 1278 specification's publication. However, to strengthen protection for 1279 RPTs using a proof-of-possession approach, the resource server could 1280 receive an RPT that consists of only a cryptographically signed token 1281 identifier, and then to validate the signature, it could, for 1282 example, submit the token identifier to the token introspection 1283 endpoint to obtain the necessary key information. The details of 1284 this usage are outside the scope of this specification. 1286 5.4. Credentials-Guessing 1288 Permission tickets and PCTs are additional credentials that the 1289 authorization server MUST prevent attackers from guessing, as defined 1290 in Section 10.10 of [RFC6749]. 1292 5.5. Permission Ticket Management 1294 Within the constraints of making permission ticket values 1295 unguessable, the authorization server MAY format the permission 1296 ticket however it chooses, for example, either as a random string 1297 that references data held on the server or by including data within 1298 the ticket itself. 1300 Permission tickets MUST be single-use. This prevents susceptibility 1301 to a session fixation attack. 1303 The authorization server MUST invalidate a permission ticket when the 1304 client presents the permission ticket to either the token endpoint or 1305 the claims interaction endpoint, or when the permission ticket 1306 expires, whichever occurs first. 1308 The client SHOULD check that the value of the "ticket" parameter it 1309 receives back from the authorization server in each response and each 1310 redirect of the requesting party back to it differs from the one it 1311 sent to the server in the initial request or redirect. 1313 If the authorization server has reason to believe that a permission 1314 ticket is compromised, for example, because it has seen the 1315 permission ticket before and it believes the first appearance was 1316 from a legitimate client and the second appearance is from an 1317 attacker, it should consider invalidating any access tokens based on 1318 this evidence. 1320 Given that scenarios involving the "request_submitted" error code are 1321 likely to involve polling intervals, the permission ticket needs to 1322 last long enough to give the client a chance to attempt a polling 1323 request, which then needs to figure into other permission ticket 1324 security considerations. 1326 5.6. Naive Implementations of Default-Deny Authorization 1328 While a reasonable approach for most scenarios is to implement the 1329 classic stance of default-deny ("everything that is not expressly 1330 allowed is forbidden"), corner cases can inadvertently result in 1331 default-permit behavior. For example, it is insufficient to create 1332 default "empty" policy conditions stating "no claims are needed", and 1333 then accept an empty set of supplied claims as sufficient for access 1334 during authorization assessment. 1336 5.7. Requirements for Pre-Established Trust Regarding Claim Tokens 1338 When a client makes an RPT request, it has the opportunity to push a 1339 claim token to attempt to satisfy policy conditions (see 1340 Section 3.3.1). 1342 Claim tokens of any format typically contain audience restrictions, 1343 and an authorization server would not typically be in the primary 1344 audience for a claim token held or generated by a client. It is 1345 RECOMMENDED to document how the client, authorization server, 1346 requesting party, and any additional ecosystem entities and parties 1347 will establish a trust relationship and communicate any required 1348 keying material in a claim token profile, as described in Section 4. 1349 Authorization servers are RECOMMENDED not to accept claim tokens 1350 pushed by untrusted clients and not to ignore audience restrictions 1351 found in claim tokens pushed by clients. 1353 A malicious client could push a claim token to the authorization 1354 server (revealing the claims therein; see Section 6.2) to seek 1355 resource access on its own behalf prior to any opportunity for an 1356 end-user requesting party to authorize claims collection. It is 1357 RECOMMENDED either for trust relationships established by the 1358 ecosystem parties to include prior requesting party authorization as 1359 required, or for end-user requesting party authorization to be 1360 gathered interactively prior to claims pushing, as described in 1361 Section 3.3.2. 1363 Some deployments could have exceptional circumstances allowing the 1364 authorization server to validate claim tokens. For example, if the 1365 authorization server itself is also the identity provider for the 1366 requesting party, then it would be able to validate any ID token that 1367 the client pushes as a claim token and also validate the client to 1368 which it was issued. 1370 5.8. Profiles and Trust Establishment 1372 Parties that are operating and using UMA software entities may need 1373 to establish agreements about the parties' rights and 1374 responsibilities on a legal or contractual level, along with common 1375 interpretations of UMA constructs for consistent and expected 1376 software behavior. These agreements can be used to improve the 1377 parties' respective security postures. Written profiles are a key 1378 mechanism for conveying and enforcing these agreements. Section 4 1379 discusses profiling. See [UMA-legal] to learn about frameworks and 1380 tools to assist in the legal and contractual elements of deploying 1381 UMA-enabled services. 1383 6. Privacy Considerations 1385 UMA has the following privacy considerations. 1387 6.1. Policy Condition Setting, Time-to-Live Management, and Removal of 1388 Authorization Grants 1390 The setting of policy conditions, the resource owner-authorization 1391 server interface, and the resource owner-resource server interface 1392 are outside the scope of this specification. (For an example of how 1393 a secure and authorized resource owner context can be established 1394 between the resource server and authorization server, see 1395 [UMAFedAuthz].) 1397 A variety of flows and user interfaces for policy condition setting 1398 involving user agents for both of these servers are possible, each 1399 with different privacy consequences for end-user resource owners. As 1400 well, various authorization, security, and time-to-live strategies 1401 could be applied on a per-resource owner basis or a per-authorization 1402 server basis, as the entities see fit. Validity periods of RPTs, 1403 refresh tokens, permissions, caching periods for responses, and even 1404 OAuth client credentials are all subject to management. Different 1405 time-to-live strategies might be suitable for different resources and 1406 scopes. 1408 In order to account for modifications of policy conditions that 1409 result in the withdrawal of authorization grants (for example, fewer 1410 scopes, fewer resources, or resources available for a shorter time) 1411 in as timely a fashion as possible, the authorization server should 1412 align its strategies for management of these factors with resource 1413 owner needs and actions rather than those of clients and requesting 1414 parties. For example, the authorization server may want to 1415 invalidate a client's RPT and refresh token as soon as a resource 1416 owner changes policy conditions in such a way as to deny the client 1417 and its requesting party future access to a full set of previously 1418 held permissions. 1420 6.2. Requesting Party Information at the Authorization Server 1422 Claims are likely to contain personal, personally identifiable, and 1423 sensitive information, particularly in the case of requesting parties 1424 who are end-users. 1426 If the authorization server supports persisting claims for any length 1427 of time (for example, to support issuance of PCTs), then it SHOULD 1428 provide a secure and privacy-protected means of storing claim data. 1429 It is also RECOMMENDED for the authorization server to use an 1430 interactive claims-gathering flow to ask an end-user requesting party 1431 for authorization to collect any claims subsequently and to persist 1432 their claims (for example, before issuing a PCT), if no prior 1433 requesting party authorization has been established among the 1434 ecosystem parties (see Section 5.7). 1436 6.3. Resource Owner Information at the Resource Server 1438 Since the client's initial request for a protected resource is made 1439 in an unauthorized and unauthenticated context, such requests are by 1440 definition open to all users. The response to that request includes 1441 the authorization server's location to enable the client to request 1442 an access token and present claims. If it is known out of band that 1443 authorization server is owned and controlled by a single user, or 1444 visiting the authorization server contains other identifying 1445 information, then an unauthenticated and unauthorized client would be 1446 able to tell which resource owner is associated with a given 1447 resource. Other information about the resource owner, such as 1448 organizational affiliation or group membership, may be gained from 1449 this transaction as well. 1451 6.4. Profiles and Trust Establishment 1453 Parties that are operating and using UMA software entities may need 1454 to establish agreements about mutual rights, responsibilities, and 1455 common interpretations of UMA constructs for consistent and expected 1456 software behavior. These agreements can be used to improve the 1457 parties' respective privacy postures. See Section 5.8 for more 1458 information. Additional considerations related to Privacy by Design 1459 concepts are discussed in [UMA-PbD]. 1461 7. IANA Considerations 1463 This document makes the following requests of IANA. 1465 7.1. Well-Known URI Registration 1467 This specification registers the well-known URI defined in Section 2, 1468 as required by Section 5.1 of [RFC5785]. 1470 7.1.1. Registry Contents 1472 o URI suffix: "uma2-configuration" 1474 o Change controller: Kantara Initiative User-Managed Access Work 1475 Group - staff@kantarainitiative.org 1477 o Specification document: Section 2 in this document 1479 7.2. OAuth 2.0 Authorization Server Metadata Registry 1481 This specification registers OAuth 2.0 authorization server metadata 1482 defined in Section 2, as required by Section 7.1 of [OAuthMeta]. 1484 7.2.1. Registry Contents 1486 o Metadata name: "claims_interaction_endpoint" 1488 o Metadata description: endpoint metadata 1490 o Change controller: Kantara Initiative User-Managed Access Work 1491 Group - staff@kantarainitiative.org 1493 o Specification document: Section 2 in this document 1495 o Metadata name: "uma_profiles_supported" 1497 o Metadata description: profile/extension feature metadata 1499 o Change controller: Kantara Initiative User-Managed Access Work 1500 Group - staff@kantarainitiative.org 1502 o Specification document: Section 2 in this document 1504 7.3. OAuth 2.0 Dynamic Client Registration Metadata Registry 1506 This specification registers OAuth 2.0 dynamic client registration 1507 metadata defined in Section 2, as required by Section 4.1 of 1508 [RFC7591]. 1510 7.3.1. Registry Contents 1512 o Metadata name: "claims_redirect_uris" 1514 o Metadata description: claims redirection endpoints 1516 o Change controller: Kantara Initiative User-Managed Access Work 1517 Group - staff@kantarainitiative.org 1519 o Specification document: Section 2 in this document 1521 7.4. OAuth 2.0 Extension Grant Parameters Registration 1523 This specification registers the parameters defined in Section 3.3.1, 1524 as required by Section 11.2 of [RFC6749]. 1526 7.4.1. Registry Contents 1528 o Parameter name: "claim_token" 1530 o Parameter usage location: client request, token endpoint 1532 o Change controller: Kantara Initiative User-Managed Access Work 1533 Group - staff@kantarainitiative.org 1535 o Specification document: Section 3.3.1 in this document 1537 o Parameter name: "pct" 1539 o Parameter usage location: client request, token endpoint 1541 o Change controller: Kantara Initiative User-Managed Access Work 1542 Group - staff@kantarainitiative.org 1544 o Specification document: Section 3.3.1 in this document 1546 o Parameter name: "pct" 1548 o Parameter usage location: authorization server response, token 1549 endpoint 1551 o Change controller: Kantara Initiative User-Managed Access Work 1552 Group - staff@kantarainitiative.org 1554 o Specification document: Section 3.3.5 in this document 1556 o Parameter name: "rpt" 1558 o Parameter usage location: client request, token endpoint 1560 o Change controller: Kantara Initiative User-Managed Access Work 1561 Group - staff@kantarainitiative.org 1563 o Specification document: Section 3.3.1 in this document 1565 o Parameter name: "ticket" 1567 o Parameter usage location: client request, token endpoint 1568 o Change controller: Kantara Initiative User-Managed Access Work 1569 Group - staff@kantarainitiative.org 1571 o Specification document: Section 3.3.1 in this document 1573 o Parameter name: "upgraded" 1575 o Parameter usage location: authorization server response, token 1576 endpoint 1578 o Change controller: Kantara Initiative User-Managed Access Work 1579 Group - staff@kantarainitiative.org 1581 o Specification document: Section 3.3.5 in this document 1583 7.5. OAuth 2.0 Extensions Error Registration 1585 This specification registers the errors defined in Section 3.3.6, as 1586 required by Section 11.4 of [RFC6749]. 1588 7.5.1. Registry Contents 1590 o Error name: "need_info" (and its subsidiary parameters) 1592 o Change controller: Kantara Initiative User-Managed Access Work 1593 Group - staff@kantarainitiative.org 1595 o Specification document: Section 3.3.6 in this document 1597 o Error usage location: authorization server response, token 1598 endpoint 1600 o Error name: "request_denied" 1602 o Change controller: Kantara Initiative User-Managed Access Work 1603 Group - staff@kantarainitiative.org 1605 o Specification document: Section 3.3.6 in this document 1607 o Error usage location: authorization server response, token 1608 endpoint 1610 o Error name: "request_submitted" (and its subsidiary parameters) 1612 o Change controller: Kantara Initiative User-Managed Access Work 1613 Group - staff@kantarainitiative.org 1615 o Specification document: Section 3.3.6 in this document 1616 o Error usage location: authorization server response, token 1617 endpoint 1619 7.6. OAuth Token Type Hints Registration 1621 This specification registers the errors defined in Section 3.7, as 1622 required by Section 4.1.2 of [RFC7009]. 1624 7.6.1. Registry Contents 1626 o Hint value: "pct" 1628 o Change controller: Kantara Initiative User-Managed Access Work 1629 Group - staff@kantarainitiative.org 1631 o Specification document: Section 3.7 in this document 1633 8. Acknowledgments 1635 The following people made significant text contributions to the 1636 specification: 1638 o Paul C. Bryan, ForgeRock US, Inc. (former editor) 1640 o Domenico Catalano, Oracle (former author) 1642 o Mark Dobrinic, Cozmanova 1644 o George Fletcher, AOL 1646 o Thomas Hardjono, MIT (former editor) 1648 o Andrew Hindle, Hindle Consulting Limited 1650 o Lukasz Moren, Cloud Identity Ltd 1652 o James Phillpotts, ForgeRock 1654 o Christian Scholz, COMlounge GmbH (former editor) 1656 o Mike Schwartz, Gluu 1658 o Cigdem Sengul, Nominet UK 1660 o Jacek Szpot, Newcastle University 1661 Additional contributors to this specification include the Kantara UMA 1662 Work Group participants, a list of whom can be found at 1663 [UMAnitarians]. 1665 9. References 1667 9.1. Normative References 1669 [BCP195] Sheffer, Y., "Recommendations for Secure Use of Transport 1670 Layer Security (TLS) and Datagram Transport Layer Security 1671 (DTLS)", May 2015, . 1673 [OAuthMeta] 1674 Jones, M., "OAuth 2.0 Authorization Server Metadata", 1675 November 2017, . 1678 [OIDCCore] 1679 Sakimura, N., "OpenID Connect Core 1.0 incorporating 1680 errata set 1", November 2014, 1681 . 1683 [OIDCDynClientReg] 1684 Sakimura, N., "OpenID Connect Dynamic Client Registration 1685 1.0 incorporating errata set 1", November 2014, 1686 . 1689 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1690 Requirement Levels", BCP 14, RFC 2119, 1691 DOI 10.17487/RFC2119, March 1997, 1692 . 1694 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1695 Resource Identifier (URI): Generic Syntax", STD 66, 1696 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1697 . 1699 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1700 Uniform Resource Identifiers (URIs)", RFC 5785, 1701 DOI 10.17487/RFC5785, April 2010, 1702 . 1704 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1705 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1706 . 1708 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1709 Framework: Bearer Token Usage", RFC 6750, 1710 DOI 10.17487/RFC6750, October 2012, 1711 . 1713 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 1714 Threat Model and Security Considerations", RFC 6819, 1715 DOI 10.17487/RFC6819, January 2013, 1716 . 1718 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1719 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1720 August 2013, . 1722 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1723 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1724 2014, . 1726 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1727 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1728 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1729 . 1731 [UMAFedAuthz] 1732 Maler, E., "Federated Authorization for User-Managed 1733 Access (UMA) 2.0", January 2019, 1734 . 1737 9.2. Informative References 1739 [UMA-legal] 1740 Maler, E., "UMA Legal", 2017, 1741 . 1744 [UMA-PbD] Maler, E., "Privacy by Design Implications of UMA", 2018, 1745 . 1748 [UMAnitarians] 1749 Maler, E., "UMA Participant Roster", 2017, 1750 . 1753 Authors' Addresses 1755 Eve Maler (editor) 1756 ForgeRock 1758 Email: eve.maler@forgerock.com 1760 Maciej Machulak 1761 HSBC 1763 Email: maciej.p.machulak@hsbc.com 1765 Justin Richer 1766 Bespoke Engineering 1768 Email: justin@bspk.io 1770 Thomas Hardjono 1771 MIT 1773 Email: hardjono@mit.edu