idnits 2.17.1 draft-lodderstedt-oauth-rar-02.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 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 20, 2019) is 1677 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) == Outdated reference: A later version (-34) exists of draft-ietf-oauth-jwsreq-19 == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-13 == Outdated reference: A later version (-01) exists of draft-lodderstedt-oauth-par-00 Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Web Authorization Protocol T. Lodderstedt 3 Internet-Draft yes.com 4 Intended status: Standards Track J. Richer 5 Expires: March 23, 2020 Bespoke Engineering 6 B. Campbell 7 Ping Identity 8 September 20, 2019 10 OAuth 2.0 Rich Authorization Requests 11 draft-lodderstedt-oauth-rar-02 13 Abstract 15 This document specifies a new parameter "authorization_details" that 16 is used to carry fine grained authorization data in the OAuth 17 authorization request. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on March 23, 2020. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 55 2. Request parameter "authorization_details" . . . . . . . . . . 3 56 2.1. Authorization data elements types . . . . . . . . . . . . 5 57 2.2. Using "authorization_details" . . . . . . . . . . . . . . 7 58 2.3. Authorization Request Processing . . . . . . . . . . . . 9 59 2.4. Token Response . . . . . . . . . . . . . . . . . . . . . 10 60 2.5. Relationship to "resource" parameter . . . . . . . . . . 11 61 3. Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . 12 62 4. Implementation Considerations . . . . . . . . . . . . . . . . 12 63 5. Security Considerations . . . . . . . . . . . . . . . . . . . 13 64 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13 65 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 66 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 67 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 68 9.1. Normative References . . . . . . . . . . . . . . . . . . 14 69 9.2. Informative References . . . . . . . . . . . . . . . . . 14 70 Appendix A. Document History . . . . . . . . . . . . . . . . . . 15 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 73 1. Introduction 75 The OAuth 2.0 authorization framework [RFC6749] defines the parameter 76 "scope" that allows OAuth clients to specify the requested scope, 77 i.e., the permission, of an access token. This mechanism is 78 sufficient to implement static scenarios and coarse-grained 79 authorization requests, such as "give me read access to the resource 80 owner's profile" but it is not sufficient to specify fine-grained 81 authorization requirements, such as "please let me make a payment 82 with the amount of 45 Euros" or "please give me read access to folder 83 A and write access to file X". 85 This draft introduces a new parameter "authorization_details" that 86 allows clients to specify their fine-grained authorization 87 requirements using the expressiveness of JSON data structures. 89 For example, a request for payment authorization can be represented 90 using a JSON object like this: 92 [ 93 { 94 "type": "payment_initiation", 95 "instructedAmount":{ 96 "currency":"EUR", 97 "amount":"123.50" 98 }, 99 "debtorAccount":{ 100 "iban":"DE40100100103307118608" 101 }, 102 "creditorName":"Merchant123", 103 "creditorAccount":{ 104 "iban":"DE02100100109307118603" 105 }, 106 "remittanceInformationUnstructured":"Ref Number Merchant" 107 } 108 ] 110 In addition to facilitating custom authorization requests, this draft 111 also introduces a set of common data type fields for use across 112 different APIs. 114 For a comprehensive discussion of the challenges arising from new use 115 cases in the open banking and electronic signing spaces see 116 [transaction-authorization]. 118 1.1. Conventions and Terminology 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 122 "OPTIONAL" in this document are to be interpreted as described in BCP 123 14 [RFC2119] [RFC8174] when, and only when, they appear in all 124 capitals, as shown here. 126 This specification uses the terms "access token", "refresh token", 127 "authorization server", "resource server", "authorization endpoint", 128 "authorization request", "authorization response", "token endpoint", 129 "grant type", "access token request", "access token response", and 130 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 132 2. Request parameter "authorization_details" 134 The request parameter "authorization_details" contains a JSON array 135 of JSON objects. Each JSON object contains the data to specify the 136 authorization requirements for a certain type of resource. The type 137 of resource or access requirement is determined by the "type" field. 139 This example shows the specification of authorization details for a 140 payment initiation transaction: 142 [ 143 { 144 "type": "payment_initiation", 145 "actions": ["initiate", "status", "cancel"], 146 "locations":[ 147 "https://example.com/payments" 148 ], 149 "instructedAmount":{ 150 "currency":"EUR", 151 "amount":"123.50" 152 }, 153 "debtorAccount":{ 154 "iban":"DE40100100103307118608" 155 }, 156 "creditorName":"Merchant123", 157 "creditorAccount":{ 158 "iban":"DE02100100109307118603" 159 }, 160 "remittanceInformationUnstructured":"Ref Number Merchant" 161 } 162 ] 164 This example shows a combined request asking for access to account 165 information and permission to initiate a payment: 167 [ 168 { 169 "type": "account_information", 170 "actions": 171 ["list_accounts", "read_balances", "read_transactions"], 172 "identifier": "abc-123565", 173 "locations": [ 174 "https://example.com/accounts" 175 ] 176 }, 177 { 178 "type": "payment_initiation", 179 "actions": ["initiate", "status", "cancel"], 180 "locations":[ 181 "https://example.com/payments" 182 ], 183 "instructedAmount":{ 184 "currency":"EUR", 185 "amount":"123.50" 186 }, 187 "debtorAccount":{ 188 "iban":"DE40100100103307118608" 189 }, 190 "creditorName":"Merchant123", 191 "creditorAccount":{ 192 "iban":"DE02100100109307118603" 193 }, 194 "remittanceInformationUnstructured":"Ref Number Merchant" 195 } 196 ] 198 The JSON objects with "type" fields of "account_information" and 199 "payment_initiation" represent the different authorization data to be 200 used by the AS to ask for consent and MUST subsequently also be made 201 available to the respective resource servers. The array MAY contain 202 several elements of the same "type". 204 2.1. Authorization data elements types 206 This draft defines a set of common data elements that are designed to 207 be usable across different types of APIs. These data elements MAY be 208 combined in different ways depending on the needs of the API. Unless 209 otherwise noted, all data elements are OPTIONAL. 211 type: 212 The type of resource request as a string. This field MAY define 213 which other elements are allowed in the request. This element is 214 REQUIRED. 216 locations: 217 An array of strings representing the location of the resource or 218 resource server. This is typically composed of URIs. 220 actions: 221 An array of strings representing the kinds of actions to be taken 222 at the resource. The values of the strings are determined by the 223 API being protected. 225 data: 226 An array of strings representing the kinds of data being requested 227 from the resource. 229 identifier: 230 A string identifier indicating a specific resource available at 231 the API. 233 An API MAY define its own extensions, subject to the "type" of the 234 request. It is assumed that the full structure of each of the 235 authorization data elements is tailored to the needs of a certain 236 application, API, or resource type. The example structures shown 237 above are based on certain kinds of APIs that can be found in the 238 Open Banking space. 240 Note: Applications MUST ensure that their authorization data types do 241 not collide. This is either achieved by using a namespace under the 242 control of the entity defining the type name or by registering the 243 type with the new "OAuth Authorization Data Type Registry" (see 244 Section 8). 246 The following example shows how an implementation could utilize the 247 namespace "https://scheme.example.org/" to ensure collision resistant 248 element names. 250 { 251 "type":"https://scheme.example.org/files", 252 "locations":[ 253 "https://example.com/files" 254 ], 255 "permissions":[ 256 { 257 "path":"/myfiles/A", 258 "access":[ 259 "read" 260 ] 261 }, 262 { 263 "path":"/myfiles/A/X", 264 "access":[ 265 "read", 266 "write" 267 ] 268 } 269 ] 270 } 272 2.2. Using "authorization_details" 274 The request parameter can be used anywhere where the "scope" 275 parameter is used, examples include: 277 o Authorization requests as specified in [RFC6749], 279 o Access token requests as specified in [RFC6749], 281 o Request objects as specified in [I-D.ietf-oauth-jwsreq], 283 o Device Authorization Request as specified in [RFC8628]. 285 Parameter encoding is determined by the respective context. 287 In the context of an authorization request according to [RFC6749], 288 the parameter is encoded using the "application/x-www-form- 289 urlencoded" format as shown in the following example (JSON string 290 trimmed for brevity): 292 GET /authorize?response_type=code&client_id=s6BhdRkqt3 293 &state=af0ifjsldkj 294 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 295 &code_challenge_method=S256 296 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U 297 &authorization_details=%5B%7B%22type%22%3A%22https%3A%2F%2F 298 www.someorg.com%2Fpayment_initiation%22%2C%22actions%22%3A%5 299 B%22initiate%22%2C%22status%22%2C%22cancel%22%5D%2C%22locat 300 ions%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpayments%22%5D% 301 2C%22instructedAmount%22%3A%7B%22currency%22%3A%22EUR%22%2C 302 %22amount%22%3A%22123.50%22%7D%2C%22debtorAccount%22%3A%7B% 303 22iban%22%3A%22DE40100100103307118608%22%7D%2C%22creditorNa 304 me%22%3A%22Merchant123%22%2C%22creditorAccount%22%3A%7B%22i 305 ban%22%3A%22DE02100100109307118603%22%7D%2C%22remittanceInf 306 ormationUnstructured%22%3A%22Ref%20Number%20Merchant%22%7D% 307 5D%0A%20%20%20 HTTP/1.1 308 Host: server.example.com 310 In the context of a request object as specified in 311 [I-D.ietf-oauth-jwsreq], "authorization_details" is added as another 312 top level JSON element. 314 { 315 "iss":"s6BhdRkqt3", 316 "aud":"https://server.example.com", 317 "response_type":"code", 318 "client_id":"s6BhdRkqt3", 319 "redirect_uri":"https://client.example.com/cb", 320 "state":"af0ifjsldkj", 321 "code_challenge_method":"S256", 322 "code_challenge":"K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U", 323 "authorization_details":[ 324 { 325 "type": "https://www.someorg.com/payment_initiation", 326 "actions": ["initiate", "status", "cancel"], 327 "locations":[ 328 "https://example.com/payments" 329 ], 330 "instructedAmount":{ 331 "currency":"EUR", 332 "amount":"123.50" 333 }, 334 "debtorAccount":{ 335 "iban":"DE40100100103307118608" 336 }, 337 "creditorName":"Merchant123", 338 "creditorAccount":{ 339 "iban":"DE02100100109307118603" 340 }, 341 "remittanceInformationUnstructured":"Ref Number Merchant" 342 } 343 ] 344 } 346 Note: Authorization request URIs containing authorization details in 347 a request parameter or a request object can become very long. 348 Implementers SHOULD therefore consider using the "request_uri" 349 parameter as defined in [I-D.ietf-oauth-jwsreq], potentially in 350 combination with the pushed request object mechanism as defined in 351 [I-D.lodderstedt-oauth-par] to pass authorization details in a 352 reliable and secure manner. 354 2.3. Authorization Request Processing 356 Based on the data provided in the "authorization_details" parameter 357 the AS will ask the user for consent to the requested access 358 permissions. 360 Note: The AS is supposed to merge the authorization requirements 361 given in the "scope" parameter and the "authorization_details" 362 parameter if both are present in the authorization request. 364 The AS MUST refuse to process any unknown authorization data type. 365 If the "authorization_details" contains any unknown authorization 366 data type, the AS MUST abort processing and respond with an error 367 "invalid_scope" to the client. 369 If the resource owner grants the client the requested access, the AS 370 will issue tokens to the client that are associated with the 371 respective "authorization_details". 373 The AS MUST make the "authorization_details" available to the 374 respective resource servers. The AS MAY add the 375 "authorization_details" element to access tokens in JWT format and to 376 Token Introspection responses. 378 The AS MUST take into consideration the privacy implications when 379 sharing authorization details with the resource servers. The AS 380 SHOULD share this data with the resource servers on a "need to know" 381 basis. 383 2.4. Token Response 385 In addition to the token response parameters as defined in [RFC6749], 386 the authorization server MUST also return the authorization details 387 as granted by the resource owner and assigned to the respective 388 access token. 390 This is shown in the following example: 392 HTTP/1.1 200 OK 393 Content-Type: application/json 394 Cache-Control: no-cache, no-store 396 { 397 "access_token":"2YotnFZFEjr1zCsicMWpAA", 398 "token_type":"example", 399 "expires_in":3600, 400 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 401 "authorization_details":[ 402 { 403 "type": "https://www.someorg.com/payment_initiation", 404 "actions": ["initiate", "status", "cancel"], 405 "locations":[ 406 "https://example.com/payments" 407 ], 408 "instructedAmount":{ 409 "currency":"EUR", 410 "amount":"123.50" 411 }, 412 "debtorAccount":{ 413 "iban":"DE40100100103307118608" 414 }, 415 "creditorName":"Merchant123", 416 "creditorAccount":{ 417 "iban":"DE02100100109307118603" 418 }, 419 "remittanceInformationUnstructured":"Ref Number Merchant" 420 } 421 ] 422 } 424 2.5. Relationship to "resource" parameter 426 [I-D.ietf-oauth-resource-indicators] defines the request parameter 427 "resource" indicating to the AS the resource(s) where the client 428 intends to use the access tokens issued based on a certain grant. 430 This mechanism is a way to audience-restrict access tokens and to 431 allow the AS to create resource specific access tokens. 433 This draft can be used in conjunction with 434 [I-D.ietf-oauth-resource-indicators] in the same way as the "scope" 435 parameter. The AS is supposed to narrow down the authorization 436 details and respective permissions to the needs of the particular 437 resource when minting an access token. 439 This depends, however, on the AS to know what authorization details 440 are relevant for what RS. The parameter introduced in this 441 specification can also be combined with the concept of resource 442 indicators to make this relationship explicit. This enables the AS 443 to narrow down the privileges of an access token to specific 444 permissions for individual operations on specific resources (see 445 [I-D.ietf-oauth-security-topics], section-3.3). 447 The "locations" and the "identifier" elements together allow the AS 448 to determine the resource a client wants to access as shown in 449 following example: 451 [ 452 { 453 "type": "https://scheme.example.org/storage": 454 "locations":["https://storage.example.com"], 455 "identifier":"/shared/group1", 456 "actions":[ 457 "read" 458 ] 459 } 460 } 462 The AS MUST respect those values when deciding whether a certain 463 element is placed into a (structured) access token or token 464 introspection response. 466 3. Metadata 468 The AS advertises support for "authorization_details" using the 469 metadata parameter "authorization_details_supported" of type boolean. 471 The authorization data types supported can be determined using the 472 metadata parameter "authorization_data_types_supported", which is an 473 JSON array. 475 Clients announce the authorization data types they use in the new 476 dynamic client registration parameter "authorization_data_types". 478 The registration of new authorization data types with the AS is out 479 of scope of this draft. 481 4. Implementation Considerations 483 The scheme and processing will vary significantly among different 484 authorization data types. Any implementation of this draft is 485 therefore supposed to allow the customization of the user consent and 486 the handling of access token data. 488 One option would be to have a mechanism allowing the registration of 489 extension modules, each of them responsible for rendering the 490 respective user consent and any transformation needed to provide the 491 data needed to the resource server by way of structured access tokens 492 or token introspection responses. 494 5. Security Considerations 496 Authorization details are sent through the user agent in case of an 497 OAuth authorization request, which makes them vulnerable to 498 modifications by the user. In order to ensure their integrity, the 499 client SHOULD send authorization details in a signed request object 500 as defined in [I-D.ietf-oauth-jwsreq] or use the "request_uri" 501 authorization request parameter as defined in [I-D.ietf-oauth-jwsreq] 502 to pass the URI of the request object to the authorization server. 504 6. Privacy Considerations 506 Implementers MUST design and use authorization details in a privacy 507 preserving manner. 509 Any sensitive personal data included in authorization details MUST be 510 prevented from leaking, e.g., through referrer headers. 511 Implementation options include encrypted request objects as defined 512 in [I-D.ietf-oauth-jwsreq] or transmission of authorization details 513 via end-to-end encrypted connections between client and authorization 514 server by utilizing the "request_uri" authorization request parameter 515 as defined in [I-D.ietf-oauth-jwsreq]. 517 Even if the request data are encrypted, an attacker could use the 518 authorization server to learn the user data by injecting the 519 encrypted request data into an authorization request on a device 520 under his control and use the authorization server's user consent 521 screens to show the (decrypted) user data in the clear. 522 Implementations MUST consider this attacker vector and implement 523 appropriate counter measures, e.g. by only showing portions of the 524 data or, if possible, determing whether the assumed user context is 525 still the same (after user authentication). 527 7. Acknowledgements 529 We would would like to thank Daniel Fett, Sebastian Ebling, Dave 530 Tonge, Mike Jones, Nat Sakimura, and Rob Otto for their valuable 531 feedback during the preparation of this draft. 533 We would also like to thank Daniel Fett, Dave Tonge and Aaron Parecki 534 for their valuable feedback to this draft. 536 8. IANA Considerations 538 TBD 540 o "authorization_details" as JWT claim 542 o "authorization_details_supported" and 543 "authorization_data_types_supported" as metadata parameters 545 o "authorization_data_types" as dynamic client registration 546 parameter 548 o establish authorization data type registry 550 9. References 552 9.1. Normative References 554 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 555 Requirement Levels", BCP 14, RFC 2119, 556 DOI 10.17487/RFC2119, March 1997, 557 . 559 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 560 RFC 6749, DOI 10.17487/RFC6749, October 2012, 561 . 563 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 564 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 565 May 2017, . 567 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 568 "OAuth 2.0 Device Authorization Grant", RFC 8628, 569 DOI 10.17487/RFC8628, August 2019, 570 . 572 9.2. Informative References 574 [I-D.ietf-oauth-jwsreq] 575 Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization 576 Framework: JWT Secured Authorization Request (JAR)", 577 draft-ietf-oauth-jwsreq-19 (work in progress), June 2019. 579 [I-D.ietf-oauth-resource-indicators] 580 Campbell, B., Bradley, J., and H. Tschofenig, "Resource 581 Indicators for OAuth 2.0", draft-ietf-oauth-resource- 582 indicators-08 (work in progress), September 2019. 584 [I-D.ietf-oauth-security-topics] 585 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 586 "OAuth 2.0 Security Best Current Practice", draft-ietf- 587 oauth-security-topics-13 (work in progress), July 2019. 589 [I-D.lodderstedt-oauth-par] 590 Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 591 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 592 draft-lodderstedt-oauth-par-00 (work in progress), 593 September 2019. 595 [transaction-authorization] 596 Lodderstedt, T., "Transaction Authorization or why we need 597 to re-think OAuth scopes", Apr 2019, . 601 Appendix A. Document History 603 [[ To be removed from the final specification ]] 605 -02 607 o Added Security Considerations 609 o Added Privacy Considerations 611 o Added notes on URI size and authorization details 613 o Added requirement to return the effective authorization details 614 granted by the resource owner in the token response 616 o changed "authorization_details" structure from object to array 618 o added Justin Richer & Brian Campbell as Co-Authors 620 -00 / -01 622 o first draft 624 Authors' Addresses 626 Torsten Lodderstedt 627 yes.com 629 Email: torsten@lodderstedt.net 630 Justin Richer 631 Bespoke Engineering 633 Email: ietf@justin.richer.org 635 Brian Campbell 636 Ping Identity 638 Email: bcampbell@pingidentity.com