idnits 2.17.1 draft-lodderstedt-oauth-rar-01.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 2, 2019) is 1697 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 609 == Outdated reference: A later version (-34) exists of draft-ietf-oauth-jwsreq-19 == Outdated reference: A later version (-08) exists of draft-ietf-oauth-resource-indicators-05 == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-13 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). 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 September 2, 2019 5 Expires: March 5, 2020 7 OAuth 2.0 Rich Authorization Requests 8 draft-lodderstedt-oauth-rar-01 10 Abstract 12 This document specifies a new parameter "authorization_details" that 13 is used to carry fine grained authorization data into the OAuth 14 authorization request. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on March 5, 2020. 33 Copyright Notice 35 Copyright (c) 2019 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 52 2. Request parameter "authorization_details" . . . . . . . . . . 3 53 2.1. Authorization data elements types . . . . . . . . . . . . 5 54 2.2. Multiple instances of the same authorization data type . 6 55 2.3. Using "authorization_details" . . . . . . . . . . . . . . 8 56 2.4. Authorization Request Processing . . . . . . . . . . . . 9 57 2.5. Token Response . . . . . . . . . . . . . . . . . . . . . 10 58 2.6. Relationship to "resource" parameter . . . . . . . . . . 11 59 3. Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . 12 60 4. Further Examples . . . . . . . . . . . . . . . . . . . . . . 13 61 5. Implementation Considerations . . . . . . . . . . . . . . . . 13 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 63 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13 64 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 65 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 66 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 67 10.1. Normative References . . . . . . . . . . . . . . . . . . 14 68 10.2. Informative References . . . . . . . . . . . . . . . . . 15 69 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 15 70 Appendix A. Document History . . . . . . . . . . . . . . . . . . 15 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 73 1. Introduction 75 [RFC6749] defines the parameter "scope" that allows OAuth clients to 76 specify the expected scope, i.e. the permission, of an access token. 77 This mechanism is sufficient to implement static scenarios and course 78 grain authorization requests, such as "give me read access to the 79 resource owner's profile" but it's not sufficient to specify fine 80 grained authorization requirements, such as "please let me make a 81 payment with the amount of 45 Euros" or "please give me read access 82 to folder A and write access to file X". 84 This draft introduces a new parameter "authorization_details" that 85 allows clients to specify their fine grained authorization 86 requirements using the expressiveness of JSON data structures. 88 For example, a request for payment authorization can use a JSON 89 object like this: 91 { 92 "instructedAmount":{ 93 "currency":"EUR", 94 "amount":"123.50" 95 }, 96 "debtorAccount":{ 97 "iban":"DE40100100103307118608" 98 }, 99 "creditorName":"Merchant123", 100 "creditorAccount":{ 101 "iban":"DE02100100109307118603" 102 }, 103 "remittanceInformationUnstructured":"Ref Number Merchant" 104 } 106 For a comprehensive discussion of the challenges arising from new use 107 cases in the open banking and eletronic signing spaces see 108 [transaction-authorization]. 110 1.1. Conventions and Terminology 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in BCP 115 14 [RFC2119] [RFC8174] when, and only when, they appear in all 116 capitals, as shown here. 118 This specification uses the terms "access token", "refresh token", 119 "authorization server", "resource server", "authorization endpoint", 120 "authorization request", "authorization response", "token endpoint", 121 "grant type", "access token request", "access token response", and 122 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 124 2. Request parameter "authorization_details" 126 The request parameter "authorization_details" contains a JSON object. 127 This JSON object is composed of one or more JSON objects on the 128 second level, each of them containing the data to specify the 129 authorization requirements for a certain type of resource. The type 130 of resource or access requirement is determined by the name of the 131 JSON object. 133 This example shows the specification of authorization details for a 134 payment initiation transaction: 136 { 137 "payment":{ 138 "instructedAmount":{ 139 "currency":"EUR", 140 "amount":"123.50" 141 }, 142 "debtorAccount":{ 143 "iban":"DE40100100103307118608" 144 }, 145 "creditorName":"Merchant123", 146 "creditorAccount":{ 147 "iban":"DE02100100109307118603" 148 }, 149 "remittanceInformationUnstructured":"Ref Number Merchant" 150 } 151 } 153 This example shows a combined request asking for access to account 154 information and allowance to initiate a payment: 156 { 157 "accounts":{ 158 "access":{ 159 "accounts":[ 161 ], 162 "balances":[ 164 ], 165 "transactions":[ 167 ] 168 } 169 }, 170 "payment":{ 171 "instructedAmount":{ 172 "currency":"EUR", 173 "amount":"123.50" 174 }, 175 "debtorAccount":{ 176 "iban":"DE40100100103307118608" 177 }, 178 "creditorName":"Merchant123", 179 "creditorAccount":{ 180 "iban":"DE02100100109307118603" 181 }, 182 "remittanceInformationUnstructured":"Ref Number Merchant" 183 } 184 } 186 The named JSON objects "account" and "payment" represent the 187 different authorization data to be used by the AS to ask for consent 188 and MUST subsequently also be made available to the respective RSs. 190 2.1. Authorization data elements types 192 It is assumed that the structure of each of the authorization data 193 elements is tailored to the needs of a certain application, API, or 194 resource type. For example, the example structures shown above are 195 based on certain kinds of APIs that can be found in the Open Banking 196 space. 198 This draft therefore only defines the "authorization_details" element 199 (the container) and a minimal set of requirements regarding the 200 structure of the contained authorization data elements. 202 Note: different applications MUST ensure that their authorization 203 data types do not collide. This is either achieved by using a 204 namespace under the control of the entity defining the type name or 205 by registering the type with the new "OAuth Authorization Data Type 206 Registry" (see Section 9). 208 The following example shows how an implementation could utilize the 209 namespace "https://scheme.examples.org/" to ensure collision 210 resistent element names. 212 { 213 "https://scheme.examples.org/files":{ 214 "permissions":[ 215 { 216 "path":"/myfiles/A", 217 "access":[ 218 "read" 219 ] 220 } 221 ] 222 } 223 } 225 2.2. Multiple instances of the same authorization data type 227 It's possible that the client asks for different kinds of access to 228 different resources of the same type. There are two ways to cope 229 with such a situation. 231 For some applications, e.g. file access, it might be reasonable to 232 build a way to allocated authorization data to certain resources into 233 the application specific JSON structure. 235 Here is an example: 237 { 238 "https://scheme.examples.org/files":{ 239 "permissions":[ 240 { 241 "path":"/myfiles/A", 242 "access":[ 243 "read" 244 ] 245 }, 246 { 247 "path":"/myfiles/A/X", 248 "access":[ 249 "read", 250 "write" 251 ] 252 } 253 ] 254 } 255 } 257 Alternatively, a client MAY specify multiple instances of the same 258 authorization data element type and distinguish those elements by 259 adding a suffix "$"+"". The following shows 260 authorization details for requesting access to different folder on 261 different IMAP servers (assuming the resource owner has access to 262 both of them): 264 { 265 "https://scheme.examples.org/imap":{ 266 "server":"imap.example.com", 267 "mailbox":"/users/", 268 "access":[ 269 "read", 270 "write" 271 ] 272 }, 273 "https://scheme.examples.org/imap$2":{ 274 "server":"imap.example.org", 275 "mailbox":"/users/shared/folder3", 276 "access":[ 277 "read" 278 ] 279 } 280 } 282 2.3. Using "authorization_details" 284 The request parameter can be used anywhere where the "scope" 285 parameter is used, examples include: 287 o Authorization requests as specified in [RFC6749], 289 o Request objects as specified in [I-D.ietf-oauth-jwsreq], 291 o Device Authorization Request as specified in [RFC8628] 293 Parameter encoding is determined by the respective context. 295 In the context of an authorization request according to [RFC6749], 296 the parameter is encoded using the "application/x-www-form- 297 urlencoded" format as shown in the following example (JSON string 298 trimmed for brevity): 300 GET /authorize?response_type=code&client_id=s6BhdRkqt3 301 &state=af0ifjsldkj 302 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 303 &code_challenge_method=S256, 304 &code_challenge=5c305578f8f19b2dcdb6c3c955c0a...97e43917cd, 305 &authorization_details=%7B%22payment%22%3A%7B%22instructedAmount 306 %22%3A%7B%22currency%22%3A%22EUR%22%2C%22amount%22%3A%22123.50%2 307 2%7D%2C%22debtorAccount%22%3A%7B%22iban%22%3A%22DE40100100103307 308 118608%22%7D%2C%22creditorName%22%3A%22Merchant123%22%2C%22credi 309 torAccount%22%3A%7B%22iban%22%3A%22DE02100100109307118603%22%7D% 310 2C%22remittanceInformationUnstructured%22%3A%22Ref%20Number%20Me 311 rchant%22%7D%7D HTTP/1.1 312 Host: server.example.com 314 In the context of a request object, "autorization_details" is added 315 as another top level JSON element. 317 { 318 "iss":"s6BhdRkqt3", 319 "aud":"https://server.example.com", 320 "response_type":"code", 321 "client_id":"s6BhdRkqt3", 322 "redirect_uri":"https://client.example.com/cb", 323 "state":"af0ifjsldkj", 324 "code_challenge_method":"S256", 325 "code_challenge":"5c305578f8f19b2dcdb6c3c955c0a...97e43917cd", 326 "authorization_details":{ 327 "payment":{ 328 "instructedAmount":{ 329 "currency":"EUR", 330 "amount":"123.50" 331 }, 332 "debtorAccount":{ 333 "iban":"DE40100100103307118608" 334 }, 335 "creditorName":"Merchant123", 336 "creditorAccount":{ 337 "iban":"DE02100100109307118603" 338 }, 339 "remittanceInformationUnstructured":"Ref Number Merchant" 340 } 341 } 342 } 344 Note: Authorization request URIs containing authorization details in 345 a request parameter or a request object can become very long. 346 Implementers SHOULD therefore consider to use the "request_uri" 347 parameter as defined in [I-D.ietf-oauth-jwsreq], potentially in 348 combination with the pushed request object mechanism as defined in 349 [PRO] to pass authorization details in a reliable and secure manner. 351 2.4. Authorization Request Processing 353 Based on the data provided in the "authorization_details" parameter 354 the AS will ask the user for consent to the requested access 355 permissions. 357 Note: the AS is supposed to merge the authorization requirements 358 given in the "scope" parameter and the "authorization_details" 359 parameter if both are present in the authorization request. 361 The AS MUST refuse to process any unknown authorization data type. 362 If the "authorization_details" contains any unknown authorization 363 data type, the AS MUST abort processing and respond with an error 364 "invalid_scope" to the client. 366 If the resource owner grants the client the requested access, the AS 367 will issue tokens to the client that are associated with the 368 respective "authorization_details". 370 The AS MUST make the "authorization_details" available to the 371 respective resource servers. The AS MAY add the 372 "authorization_details" element to access tokens in JWT format and to 373 Token Introspection responses. 375 The AS MUST take into consideration the privacy implications when 376 sharing authorization details with the resource servers. The AS 377 SHOULD share this data with the resource servers on a "need to know" 378 basis. 380 2.5. Token Response 382 In addition to the token response parameters as defined in [RFC6749], 383 the authorization server MUST also return the authorization details 384 as granted by the resource owner and assigned to the respective 385 access token. 387 This is shown in the following example: 389 HTTP/1.1 200 OK 390 Content-Type: application/json;charset=UTF-8 391 Cache-Control: no-store 392 Pragma: no-cache 394 { 395 "access_token":"2YotnFZFEjr1zCsicMWpAA", 396 "token_type":"example", 397 "expires_in":3600, 398 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 399 "authorization_details":{ 400 "payment":{ 401 "instructedAmount":{ 402 "currency":"EUR", 403 "amount":"123.50" 404 }, 405 "debtorAccount":{ 406 "iban":"DE40100100103307118608" 407 }, 408 "creditorName":"Merchant123", 409 "creditorAccount":{ 410 "iban":"DE02100100109307118603" 411 }, 412 "remittanceInformationUnstructured": 413 "Ref Number Merchant" 414 } 415 } 416 } 418 2.6. Relationship to "resource" parameter 420 [I-D.ietf-oauth-resource-indicators] defines the request parameter 421 "resource" indicating to the AS the resource(s) where the client 422 intends to use the access tokens issued based on a certain grant. 424 This mechanism is a way to audience restrict access tokens and to 425 allow the AS to create resource specific access tokens. 427 This draft can be used in conjunction with 428 [I-D.ietf-oauth-resource-indicators] in the same way as the "scope" 429 parameter. The AS is supposed to narrow down the authorization 430 details and respective permissions to the needs of the particular 431 resource when minting an access token. 433 While this depends on the AS to know what authorization details are 434 relevant for what RS, this draft can also be combined with the 435 concept of resource indicators to make this relationsship explicit 436 and to narrow the privileges of an access token down to certain 437 permissions given on a certain resource down to the individual 438 operation (see [I-D.ietf-oauth-security-topics], section-3.3). 440 As an example, it is possible to specify that the client will get 441 "read" access to "file X" stored at the resource 442 "https://store.example.com" [1]. To achieve this, the example given 443 above for access to an IMAP server is slightly modfied to use the 444 "resource" element as part of the top level claims within the 445 authorization data element. 447 { 448 "https://scheme.examples.org/imap":{ 449 "resource":"imap.example.com", 450 "mailbox":"/users/", 451 "access":[ 452 "read", 453 "write" 454 ] 455 }, 456 "https://scheme.examples.org/imap$2":{ 457 "resource":"imap.example.org", 458 "mailbox":"/users/shared/folder3", 459 "access":[ 460 "read" 461 ] 462 } 463 } 465 The AS MUST respect the value of the "resource" element when deciding 466 whether a certain element is placed into a (structured) access token 467 or token introspection response. 469 3. Metadata 471 TBD 473 The AS advertises support for "authorization_details" using the 474 metadata parameter "authorization_details_supported" of type boolean. 476 The authorization data types supported can be determined using the 477 metadata parameter "authorization_data_types_supported", which is an 478 JSON array. 480 Clients annonce the authorization data types the use in the new 481 dynamic client registration parameter "authorization_data_types". 483 The registration of new authorization data types with the AS is out 484 of scope of this draft. 486 4. Further Examples 488 TBD 490 o self contained (account information, claims, signing) 492 o external reference (payment) 494 o multiple payments 496 o access to e-mail 498 o access to files/directories 500 5. Implementation Considerations 502 The scheme and processing will significantly vary among different 503 authorization data types. Any implementation of this draft is 504 therefore supposed to allow the customization of the user consent and 505 the handling of access token data. 507 One option would be to have a mechanism allowing the registration of 508 extension modules, each of them responsible for rendering the 509 respective user consent and any transformation needed to provide the 510 data needed to the resource server by way of structured access tokens 511 or token introspection responses. 513 6. Security Considerations 515 Authorization details are sent through the user agent in case of an 516 OAuth authorization request, which makes them vulnerable to 517 modifications by the user. In order to ensure their integrity, the 518 client SHOULD send authorization details in a signed request object 519 as defined in [I-D.ietf-oauth-jwsreq] or use the "request_uri" 520 authorization request parameter as defined in [I-D.ietf-oauth-jwsreq] 521 to pass the URI of the request object to the authorization server. 523 7. Privacy Considerations 525 Implementers MUST design and use authorization details in a privacy 526 preserving manner. Any sensitive personal data included in 527 authorization details MUST be prevented from leakage, e.g. through 528 referrer headers. Implementation options include encrypted request 529 objects as defined in [I-D.ietf-oauth-jwsreq] or transmission of 530 authorization details via end-to-end encrypted connections between 531 client ans authorization server by utilizing the "request_uri" 532 authorization request parameter as defined in 533 [I-D.ietf-oauth-jwsreq]. 535 8. Acknowledgements 537 I would would like to thank Brian Campbell, Daniel Fett, Sebastian 538 Ebling, Dave Tonge, Mike Jones, Nat Sakimura, Rob Otto, and Justin 539 Richer for their valuable feedback during the preparation of this 540 draft. 542 I would like to thank Dave Tonge and Aaron Parecki for their valuable 543 feedback. 545 9. IANA Considerations 547 o "authorization_details" as JWT claim 549 o "authorization_details_supported" and 550 "authorization_data_types_supported" as metadata parameters 552 o "authorization_data_types" as dynamic client registration 553 parameter 555 o establish authorization data type registry 557 10. References 559 10.1. Normative References 561 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 562 Requirement Levels", BCP 14, RFC 2119, 563 DOI 10.17487/RFC2119, March 1997, 564 . 566 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 567 RFC 6749, DOI 10.17487/RFC6749, October 2012, 568 . 570 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 571 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 572 May 2017, . 574 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 575 "OAuth 2.0 Device Authorization Grant", RFC 8628, 576 DOI 10.17487/RFC8628, August 2019, 577 . 579 10.2. Informative References 581 [I-D.ietf-oauth-jwsreq] 582 Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization 583 Framework: JWT Secured Authorization Request (JAR)", 584 draft-ietf-oauth-jwsreq-19 (work in progress), June 2019. 586 [I-D.ietf-oauth-resource-indicators] 587 Campbell, B., Bradley, J., and H. Tschofenig, "Resource 588 Indicators for OAuth 2.0", draft-ietf-oauth-resource- 589 indicators-05 (work in progress), July 2019. 591 [I-D.ietf-oauth-security-topics] 592 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 593 "OAuth 2.0 Security Best Current Practice", draft-ietf- 594 oauth-security-topics-13 (work in progress), July 2019. 596 [PRO] Lodderstedt, T. and B. Campbell, "Financial-grade API: 597 Pushed Request Object", 08 2019, 598 . 601 [transaction-authorization] 602 Lodderstedt, T., "Transaction Authorization or why we need 603 to re-think OAuth scopes", Apr 2019, . 607 10.3. URIs 609 [1] https://store.example.com" 611 Appendix A. Document History 613 [[ To be removed from the final specification ]] 615 -01 617 o Added Security Considerations 619 o Added Privacy Considerations 621 o Added notes on URI size and authorization details 623 o Added requirement to return the effective authorization details 624 granted by the resource owner in the token response 626 -00 627 o first draft 629 Author's Address 631 Torsten Lodderstedt 632 yes.com 634 Email: torsten@lodderstedt.net