idnits 2.17.1 draft-ietf-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 : ---------------------------------------------------------------------------- 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 (21 August 2020) is 1337 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 (-25) exists of draft-ietf-oauth-security-topics-15 == Outdated reference: A later version (-34) exists of draft-ietf-oauth-jwsreq-26 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-jwt-introspection-response-09 Summary: 0 errors (**), 0 flaws (~~), 4 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: 22 February 2021 Bespoke Engineering 6 B. Campbell 7 Ping Identity 8 21 August 2020 10 OAuth 2.0 Rich Authorization Requests 11 draft-ietf-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 22 February 2021. 36 Copyright Notice 38 Copyright (c) 2020 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 (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 4 54 2. Request parameter "authorization_details" . . . . . . . . . . 4 55 2.1. Authorization data elements types . . . . . . . . . . . . 5 56 2.2. Authorization Data Types . . . . . . . . . . . . . . . . 8 57 2.3. Relationship to "scope" parameter . . . . . . . . . . . . 9 58 2.3.1. Scope value "openid" and "claims" parameter . . . . . 9 59 2.4. Relationship to "resource" parameter . . . . . . . . . . 9 60 3. Using "authorization_details" . . . . . . . . . . . . . . . . 12 61 3.1. Authorization Request . . . . . . . . . . . . . . . . . . 12 62 3.2. Authorization Request Processing . . . . . . . . . . . . 14 63 3.3. Token Request . . . . . . . . . . . . . . . . . . . . . . 15 64 3.4. Token Response . . . . . . . . . . . . . . . . . . . . . 15 65 3.4.1. Token Content . . . . . . . . . . . . . . . . . . . . 16 66 3.5. Token Introspection Request . . . . . . . . . . . . . . . 18 67 3.6. Token Introspection Response . . . . . . . . . . . . . . 18 68 4. Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . 19 69 5. Implementation Considerations . . . . . . . . . . . . . . . . 20 70 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 71 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 20 72 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 73 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 74 10. Normative References . . . . . . . . . . . . . . . . . . . . 21 75 11. Informative References . . . . . . . . . . . . . . . . . . . 22 76 Appendix A. Additional Examples . . . . . . . . . . . . . . . . 23 77 A.1. OpenID Connect . . . . . . . . . . . . . . . . . . . . . 24 78 A.2. Remote Electronic Signing . . . . . . . . . . . . . . . . 25 79 A.3. Access to Tax Data . . . . . . . . . . . . . . . . . . . 26 80 A.4. eHealth . . . . . . . . . . . . . . . . . . . . . . . . . 27 81 Appendix B. Document History . . . . . . . . . . . . . . . . . . 30 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 84 1. Introduction 86 The OAuth 2.0 authorization framework [RFC6749] defines the parameter 87 "scope" that allows OAuth clients to specify the requested scope, 88 i.e., the permission, of an access token. This mechanism is 89 sufficient to implement static scenarios and coarse-grained 90 authorization requests, such as "give me read access to the resource 91 owner's profile" but it is not sufficient to specify fine-grained 92 authorization requirements, such as "please let me make a payment 93 with the amount of 45 Euros" or "please give me read access to folder 94 A and write access to file X". 96 This draft introduces a new parameter "authorization_details" that 97 allows clients to specify their fine-grained authorization 98 requirements using the expressiveness of JSON data structures. 100 For example, a request for payment authorization can be represented 101 using a JSON object like this: 103 { 104 "type": "payment_initiation", 105 "locations": [ 106 "https://example.com/payments" 107 ], 108 "instructedAmount": { 109 "currency": "EUR", 110 "amount": "123.50" 111 }, 112 "creditorName": "Merchant123", 113 "creditorAccount": { 114 "iban": "DE02100100109307118603" 115 }, 116 "remittanceInformationUnstructured": "Ref Number Merchant" 117 } 119 This object contains detailed information about the intended payment, 120 such as amount, currency, and creditor, that are required to inform 121 the user and obtain her consent. The AS and the respective RS 122 (providing the payment initiation API) will together enforce this 123 consent. 125 For a comprehensive discussion of the challenges arising from new use 126 cases in the open banking and electronic signing spaces see 127 [transaction-authorization]. 129 In addition to facilitating custom authorization requests, this draft 130 also introduces a set of common data type fields for use across 131 different APIs. 133 Most notably, the field "locations" allows a client to specify where 134 it intends to use a certain authorization, i.e., it is now possible 135 to unambiguously assign permissions to resource servers. In 136 situations with multiple resource servers, this prevents unintended 137 client authorizations (e.g. a "read" scope value potentially 138 applicable for an email as well as a cloud service). In combination 139 with the "resource" token request parameter as specified in 140 [I-D.ietf-oauth-resource-indicators] it enables the AS to mint RS- 141 specific structured access tokens that only contain the permissions 142 applicable to the respective RS. 144 1.1. Conventions and Terminology 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 148 "OPTIONAL" in this document are to be interpreted as described in BCP 149 14 [RFC2119] [RFC8174] when, and only when, they appear in all 150 capitals, as shown here. 152 This specification uses the terms "access token", "refresh token", 153 "authorization server", "resource server", "authorization endpoint", 154 "authorization request", "authorization response", "token endpoint", 155 "grant type", "access token request", "access token response", and 156 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 158 2. Request parameter "authorization_details" 160 The request parameter "authorization_details" contains, in JSON 161 notation, an array of objects. Each JSON object contains the data to 162 specify the authorization requirements for a certain type of 163 resource. The type of resource or access requirement is determined 164 by the "type" field. 166 This example shows the specification of authorization details using 167 the payment authorization object shown above: 169 [ 170 { 171 "type": "payment_initiation", 172 "actions": [ 173 "initiate", 174 "status", 175 "cancel" 176 ], 177 "locations": [ 178 "https://example.com/payments" 179 ], 180 "instructedAmount": { 181 "currency": "EUR", 182 "amount": "123.50" 183 }, 184 "creditorName": "Merchant123", 185 "creditorAccount": { 186 "iban": "DE02100100109307118603" 187 }, 188 "remittanceInformationUnstructured": "Ref Number Merchant" 189 } 190 ] 191 This example shows a combined request asking for access to account 192 information and permission to initiate a payment: 194 [ 195 { 196 "type": "account_information", 197 "actions": [ 198 "list_accounts", 199 "read_balances", 200 "read_transactions" 201 ], 202 "locations": [ 203 "https://example.com/accounts" 204 ] 205 }, 206 { 207 "type": "payment_initiation", 208 "actions": [ 209 "initiate", 210 "status", 211 "cancel" 212 ], 213 "locations": [ 214 "https://example.com/payments" 215 ], 216 "instructedAmount": { 217 "currency": "EUR", 218 "amount": "123.50" 219 }, 220 "creditorName": "Merchant123", 221 "creditorAccount": { 222 "iban": "DE02100100109307118603" 223 }, 224 "remittanceInformationUnstructured": "Ref Number Merchant" 225 } 226 ] 228 The JSON objects with "type" fields of "account_information" and 229 "payment_initiation" represent the different authorization data to be 230 used by the AS to ask for consent and MUST subsequently also be made 231 available to the respective resource servers. The array MAY contain 232 several elements of the same "type". 234 2.1. Authorization data elements types 236 The allowable contents of the authorization details object are 237 determined by the "type" parameter. 239 "type": The type of resource request as a string. This field MAY 240 define which other elements are allowed in the request. This 241 element is REQUIRED. 243 This field MUST be compared using an exact byte match of the string 244 value against known types by the AS. The AS MUST ensure that there 245 is no collision between different authorization data types that it 246 supports. The AS MUST NOT do any collation or normalization of data 247 types during comparison. 249 This draft defines a set of common data elements that are designed to 250 be usable across different types of APIs. These data elements MAY be 251 combined in different ways depending on the needs of the API. All 252 data elements are OPTIONAL. 254 "locations": An array of strings representing the location of the 255 resource or resource server. This is typically composed of URIs. 257 "actions": An array of strings representing the kinds of actions to 258 be taken at the resource. The values of the strings are 259 determined by the API being protected. 261 "datatypes": An array of strings representing the kinds of data 262 being requested from the resource. 264 "identifier": A string identifier indicating a specific resource 265 available at the API. 267 When different element types are used in combination, the permissions 268 the client requests is the cartesian product of the values. In the 269 following example 271 [ 272 { 273 "type": "customer_information", 274 "locations": [ 275 "https://example.com/customers", 276 ] 277 "actions": [ 278 "read", 279 "write" 280 ], 281 "datatypes": [ 282 "contacts", 283 "photos" 284 ] 285 } 286 ] 287 the client is requesting read and write access to both the contacts 288 and photos belonging to customers in a customer information API. If 289 the client wishes to have finer control over its access, it can send 290 multiple objects. For example: 292 [ 293 { 294 "type": "customer_information", 295 "locations": [ 296 "https://example.com/customers" 297 ], 298 "actions": [ 299 "read" 300 ], 301 "datatypes": [ 302 "contacts" 303 ] 304 }, 305 { 306 "type": "customer_information", 307 "locations": [ 308 "https://example.com/customers" 309 ], 310 "actions": [ 311 "write" 312 ], 313 "datatypes": [ 314 "photos" 315 ] 316 } 317 ] 319 The client is asking for read access to the contacts and write access 320 to the photos in the same API endpoint. 322 An API MAY define its own extensions, subject to the "type" of the 323 respective authorization object. It is assumed that the full 324 structure of each of the authorization objects is tailored to the 325 needs of a certain application, API, or resource type, and can 326 contain a mix of general-purpose and api-specific elements within the 327 structure. The example structures shown above are based on certain 328 kinds of APIs that can be found in the Open Banking space. 330 2.2. Authorization Data Types 332 Interpretation of the value of the "type" parameter, and the object 333 elements that the "type" parameter allows, is under the control of 334 the AS. However, the value of the "type" parameter is also generally 335 documented and intended to be used by developers, it is RECOMMENDED 336 that API designers choose "type" values that are easily copied 337 without ambiguity. For example, some glyphs have multiple unicode 338 code points for the same visual character, and a developer could 339 potentially type a different character depending than what the AS has 340 defined. Possible means of reducing potential confusion are limiting 341 the value to ASCII characters, providing a machine-readable listing 342 of data type values, or instructing developers to copy and paste 343 directly from documentation. 345 If an application or API is expected to be deployed across different 346 servers, such as the case in an open standard, the API designer is 347 RECOMMENDED to use a collision-resistant namespace under their 348 control, such as a URI that the API designer controls. 350 The following example shows how an implementation could utilize the 351 namespace "https://scheme.example.org/" to ensure collision resistant 352 element names. 354 { 355 "type": "https://scheme.example.org/files", 356 "locations": [ 357 "https://example.com/files" 358 ], 359 "permissions": [ 360 { 361 "path": "/myfiles/A", 362 "access": [ 363 "read" 364 ] 365 }, 366 { 367 "path": "/myfiles/A/X", 368 "access": [ 369 "read", 370 "write" 371 ] 372 } 373 ] 374 } 376 2.3. Relationship to "scope" parameter 378 "authorization_details" and "scope" can be used in the same 379 authorization request for carrying independent authorization 380 requirements. 382 The AS MUST consider both sets of requirements in combination with 383 each other for the given authorization request. The details of how 384 the AS combines these parameters are specific to the APIs being 385 protected and outside the scope of this specification. 387 It is RECOMMENDED that a given API use only one form of requirement 388 specification. 390 When gathering user consent, the AS MUST present the merged set of 391 requirements represented by the authorization request. 393 2.3.1. Scope value "openid" and "claims" parameter 395 OpenID Connect [OIDC] specifies the JSON-based "claims" request 396 parameter that can be used to specify the claims a client (acting as 397 OpenID Connect Relying Party) wishes to receive in a fine-grained and 398 privacy preserving way as well as assign those claims to a certain 399 delivery mechanisms, i.e. ID Token or userinfo response. 401 The combination of the scope value "openid" and the additional 402 parameter "claims" can be used beside "authorization_details" in the 403 same way as every non-OIDC scope value. 405 Alternatively, there could be an authorization data type for OpenID 406 Connect. Appendix A.1 gives an example of how such an authorization 407 data type could look like. 409 2.4. Relationship to "resource" parameter 411 The request parameter "resource" as defined in 412 [I-D.ietf-oauth-resource-indicators] indicates to the AS the 413 resource(s) where the client intends to use the access tokens issued 414 based on a certain grant. This mechanism is a way to audience- 415 restrict access tokens and to allow the AS to create resource server 416 specific access tokens. 418 If a client uses "authorization_details" with "locations" elements 419 and the "resource" parameter in the same authorization request, the 420 "locations" data take precedence over the data conveyed in the 421 "resource" parameter for that particular authorization details 422 object. 424 If such a client uses the "resource" parameter in a subsequent token 425 requests, the AS MUST utilize the data provided in the "locations" 426 elements to filter the authorization data objects applicable to the 427 respective resource server. The AS will select all authorization 428 details object where the "resource" string matches as prefix of one 429 of the URLs provided in the respective "locations" element. 431 This shall be illustrated using an example. 433 The client has sent an authorization request using the following 434 example authorization details. 436 [ 437 { 438 "type": "account_information", 439 "actions": [ 440 "list_accounts", 441 "read_balances", 442 "read_transactions" 443 ], 444 "locations": [ 445 "https://example.com/accounts" 446 ] 447 }, 448 { 449 "type": "payment_initiation", 450 "actions": [ 451 "initiate", 452 "status", 453 "cancel" 454 ], 455 "locations": [ 456 "https://example.com/payments" 457 ], 458 "instructedAmount": { 459 "currency": "EUR", 460 "amount": "123.50" 461 }, 462 "creditorName": "Merchant123", 463 "creditorAccount": { 464 "iban": "DE02100100109307118603" 465 }, 466 "remittanceInformationUnstructured": "Ref Number Merchant" 467 } 468 ] 470 If this client then sends the following token request to the AS, 471 POST /token HTTP/1.1 472 Host: as.example.com 473 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 474 Content-Type: application/x-www-form-urlencoded 476 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 477 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 478 &resource=https%3A%2F%2Fexample%2Ecom%2Fpayments 480 that contains a resource parameter with the value of 481 "https://example.com/payments", this value will be matched against 482 the locations elements ("https://example.com/accounts" and 483 "https://example.com/payments") and will select the element of type 484 "payment_initiation" for inclusion in the access token as illustrated 485 by the following example JWT content. 487 { 488 "iss": "https://as.example.com", 489 "sub": "24400320", 490 "aud": "a7AfcPcsl2", 491 "exp": 1311281970, 492 ... 493 "authorization_details": [ 494 { 495 "type": "https://www.someorg.com/payment_initiation", 496 "actions": [ 497 "initiate", 498 "status", 499 "cancel" 500 ], 501 "locations": [ 502 "https://example.com/payments" 503 ], 504 "instructedAmount": { 505 "currency": "EUR", 506 "amount": "123.50" 507 }, 508 "creditorName": "Merchant123", 509 "creditorAccount": { 510 "iban": "DE02100100109307118603" 511 }, 512 "remittanceInformationUnstructured": "Ref Number Merchant" 513 } 514 ], 515 ... 516 } 518 3. Using "authorization_details" 520 3.1. Authorization Request 522 The request parameter can be used to specify authorization 523 requirements in all places where the "scope" parameter is used for 524 the same purpose, examples include: 526 * Authorization requests as specified in [RFC6749], 528 * Access token requests as specified in [RFC6749], if also used as 529 authorization requests, e.g. in the case of assertion grant types 530 [RFC7521], 532 * Request objects as specified in [I-D.ietf-oauth-jwsreq], 534 * Device Authorization Request as specified in [RFC8628], 536 * Backchannel Authentication Requests as defined in [OpenID.CIBA]. 538 Parameter encoding is determined by the respective context. 540 In the context of an authorization request according to [RFC6749], 541 the parameter is encoded using the "application/x-www-form- 542 urlencoded" format of the serialized JSON as shown in the following 543 example: 545 GET /authorize?response_type=code 546 &client_id=s6BhdRkqt3 547 &state=af0ifjsldkj 548 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 549 &code_challenge_method=S256 550 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U 551 &authorization_details=%5B%7B%22type%22%3A%22account%5Finformati 552 on%22%2C%22actions%22%3A%5B%22list%5Faccounts%22%2C%22read%5Fbal 553 ances%22%2C%22read%5Ftransactions%22%5D%2C%22locations%22%3A%5B% 554 22https%3A%2F%2Fexample%2Ecom%2Faccounts%22%5D%7D%5D HTTP/1.1 555 Host: server.example.com 557 Implementors MUST ensure to protect personal identifiable information 558 in transit. One way is to utilize encrypted request objects as 559 defined in [I-D.ietf-oauth-jwsreq]. In the context of a request 560 object, "authorization_details" is added as another top level JSON 561 element. 563 { 564 "iss": "s6BhdRkqt3", 565 "aud": "https://server.example.com", 566 "response_type": "code", 567 "client_id": "s6BhdRkqt3", 568 "redirect_uri": "https://client.example.com/cb", 569 "state": "af0ifjsldkj", 570 "code_challenge_method": "S256", 571 "code_challenge": "K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U", 572 "authorization_details": [ 573 { 574 "type": "account_information", 575 "actions": [ 576 "list_accounts", 577 "read_balances", 578 "read_transactions" 579 ], 580 "locations": [ 581 "https://example.com/accounts" 582 ] 583 }, 584 { 585 "type": "payment_initiation", 586 "actions": [ 587 "initiate", 588 "status", 589 "cancel" 590 ], 591 "locations": [ 592 "https://example.com/payments" 593 ], 594 "instructedAmount": { 595 "currency": "EUR", 596 "amount": "123.50" 597 }, 598 "creditorName": "Merchant123", 599 "creditorAccount": { 600 "iban": "DE02100100109307118603" 601 }, 602 "remittanceInformationUnstructured": "Ref Number Merchant" 603 } 604 ] 605 } 607 Authorization request URIs containing authorization details in a 608 request parameter or a request object can become very long. 609 Implementers SHOULD therefore consider using the "request_uri" 610 parameter as defined in [I-D.ietf-oauth-jwsreq] in combination with 611 the pushed request object mechanism as defined in 612 [I-D.lodderstedt-oauth-par] to pass authorization details in a 613 reliable and secure manner. Here is an example of such a pushed 614 authorization request that sends the authorization request data 615 directly to the AS via a HTTPS-protected connection: 617 POST /as/par HTTP/1.1 618 Host: as.example.com 619 Content-Type: application/x-www-form-urlencoded 620 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 622 response_type=code& 623 client_id=s6BhdRkqt3 624 &state=af0ifjsldkj 625 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 626 &code_challenge_method=S256 627 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U 628 &authorization_details=%5B%7B%22type%22%3A%22account_information%22 629 %2C%22actions%22%3A%5B%22list_accounts%22%2C%22read_balances%22%2C% 630 22read_transactions%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fe 631 xample.com%2Faccounts%22%5D%7D%2C%7B%22type%22%3A%22payment_initiat 632 ion%22%2C%22actions%22%3A%5B%22initiate%22%2C%22status%22%2C%22canc 633 el%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpaym 634 ents%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22EUR%22 635 %2C%22amount%22%3A%22123.50%22%7D%2C%22creditorName%22%3A%22Merchan 636 t123%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE021001001093 637 07118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%2 638 0Number%20Merchant%22%7D%5D 640 3.2. Authorization Request Processing 642 Based on the data provided in the "authorization_details" parameter 643 the AS will ask the user for consent to the requested access 644 permissions. 646 The AS MUST refuse to process any unknown authorization data type. 647 If the "authorization_details" contain any unknown authorization data 648 type, the AS MUST abort processing and respond with an error 649 "invalid_authorization_details" to the client. 651 Note: If the authorization request also contained the "scope" 652 parameter, the AS MUST present the merged set of requirements 653 represented by the authorization request in the user consent. 655 If the resource owner grants the client the requested access, the AS 656 will issue tokens to the client that are associated with the 657 respective "authorization_details" (and scope values, if applicable). 659 Note: The AS MUST make the "authorization_details" available to the 660 respective resource servers. The AS MAY add the 661 "authorization_details" element to access tokens in JWT format and to 662 Token Introspection responses (see below). 664 3.3. Token Request 666 Clients utilizing authorization details are RECOMMENDED to use the 667 "resource" token request parameter to allow the AS to issue audience 668 restricted access tokens as recommended in 669 [I-D.ietf-oauth-security-topics]. 671 For example the following token request selects authorization details 672 applicable for the resource server represented by the URI 673 "https://example.com/payments". 675 POST /token HTTP/1.1 676 Host: as.example.com 677 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 678 Content-Type: application/x-www-form-urlencoded 680 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 681 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 682 &resource=https%3A%2F%2Fexample%2Ecom%2Fpayments 684 3.4. Token Response 686 In addition to the token response parameters as defined in [RFC6749], 687 the authorization server MUST also return the authorization details 688 as granted by the resource owner and assigned to the respective 689 access token. 691 This is shown in the following example: 693 HTTP/1.1 200 OK 694 Content-Type: application/json 695 Cache-Control: no-cache, no-store 697 { 698 "access_token": "2YotnFZFEjr1zCsicMWpAA", 699 "token_type": "example", 700 "expires_in": 3600, 701 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 702 "authorization_details": [ 703 { 704 "type": "https://www.someorg.com/payment_initiation", 705 "actions": [ 706 "initiate", 707 "status", 708 "cancel" 709 ], 710 "locations": [ 711 "https://example.com/payments" 712 ], 713 "instructedAmount": { 714 "currency": "EUR", 715 "amount": "123.50" 716 }, 717 "creditorName": "Merchant123", 718 "creditorAccount": { 719 "iban": "DE02100100109307118603" 720 }, 721 "remittanceInformationUnstructured": "Ref Number Merchant" 722 } 723 ] 724 } 726 3.4.1. Token Content 728 In order to enable the RS to enforce the authorization details as 729 approved in the authorization process, the AS MUST make this data 730 available to the RS. 732 If the access token is a JWT [RFC7519], the AS is RECOMMENDED to add 733 the "authorization_details" object, filtered to the specific 734 audience, as top-level claim. 736 The AS will typically also add further claims to the JWT the RS 737 requires for request processing, e.g., user id, roles, and 738 transaction specific data. What claims the particular RS requires is 739 defined by the RS-specific policy with the AS. 741 The following shows the contents of an example JWT for the payment 742 initation example above: 744 { 745 "iss": "https://as.example.com", 746 "sub": "24400320", 747 "aud": "a7AfcPcsl2", 748 "exp": 1311281970, 749 "acr": "psd2_sca", 750 "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296", 751 "authorization_details": [ 752 { 753 "type": "https://www.someorg.com/payment_initiation", 754 "actions": [ 755 "initiate", 756 "status", 757 "cancel" 758 ], 759 "locations": [ 760 "https://example.com/payments" 761 ], 762 "instructedAmount": { 763 "currency": "EUR", 764 "amount": "123.50" 765 }, 766 "creditorName": "Merchant123", 767 "creditorAccount": { 768 "iban": "DE02100100109307118603" 769 }, 770 "remittanceInformationUnstructured": "Ref Number Merchant" 771 } 772 ], 773 "debtorAccount": { 774 "iban": "DE40100100103307118608", 775 "user_role": "owner" 776 } 777 } 779 In this case, the AS added the following example claims: 781 * "sub": conveys the user on which behalf the client is asking for 782 payment initation 784 * "txn": transaction id used to trace the transaction across the 785 services of provider "example.com" 787 * "debtorAccount": API-specific element containing the debtor 788 account. In the example, this account was not passed in the 789 authorization details but selected by the user during the 790 authorization process. The field "user_role" conveys the role the 791 user has with respect to this particuar account. In this case, 792 she is the owner. This data is used for access control at the 793 payment API (the RS). 795 3.5. Token Introspection Request 797 In case of opaque access tokens, the data provided to a certain RS is 798 determined using the RS's identifier with the AS (see 799 [I-D.ietf-oauth-jwt-introspection-response], section 3). 801 3.6. Token Introspection Response 803 The token endpoint response provides the RS with the authorization 804 details applicable to it as a top-level JSON element along with the 805 claims the RS requires for request processing. 807 Here is an example for the payment initation example RS: 809 { 810 "active": true, 811 "sub": "24400320", 812 "aud": "s6BhdRkqt3", 813 "exp": 1311281970, 814 "acr": "psd2_sca", 815 "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296", 816 "authorization_details": [ 817 { 818 "type": "https://www.someorg.com/payment_initiation", 819 "actions": [ 820 "initiate", 821 "status", 822 "cancel" 823 ], 824 "locations": [ 825 "https://example.com/payments" 826 ], 827 "instructedAmount": { 828 "currency": "EUR", 829 "amount": "123.50" 830 }, 831 "creditorName": "Merchant123", 832 "creditorAccount": { 833 "iban": "DE02100100109307118603" 834 }, 835 "remittanceInformationUnstructured": "Ref Number Merchant" 836 } 837 ], 838 "debtorAccount": { 839 "iban": "DE40100100103307118608", 840 "user_role": "owner" 841 } 842 } 844 4. Metadata 846 The AS advertises support for "authorization_details" using the 847 metadata parameter "authorization_details_supported" of type boolean. 849 The authorization data types supported can be determined using the 850 metadata parameter "authorization_data_types_supported", which is an 851 JSON array. 853 Clients announce the authorization data types they use in the new 854 dynamic client registration parameter "authorization_data_types". 856 The registration of new authorization data types with the AS is out 857 of scope of this draft. 859 5. Implementation Considerations 861 The scheme and processing will vary significantly among different 862 authorization data types. Any implementation of this draft is 863 therefore supposed to allow the customization of the user consent and 864 the handling of access token data. 866 One option would be to have a mechanism allowing the registration of 867 extension modules, each of them responsible for rendering the 868 respective user consent and any transformation needed to provide the 869 data needed to the resource server by way of structured access tokens 870 or token introspection responses. 872 6. Security Considerations 874 Authorization details are sent through the user agent in case of an 875 OAuth authorization request, which makes them vulnerable to 876 modifications by the user. In order to ensure their integrity, the 877 client SHOULD send authorization details in a signed request object 878 as defined in [I-D.ietf-oauth-jwsreq] or use the "request_uri" 879 authorization request parameter as defined in [I-D.ietf-oauth-jwsreq] 880 to pass the URI of the request object to the authorization server. 882 All strings MUST be compared using the exact byte representation of 883 the characters as defined by [RFC8259]. This is especially true for 884 the "type" field, which dictates which other fields and functions are 885 allowed in the request. The server MUST NOT perform any form of 886 collation, transformation, or equivalence on the string values. 888 7. Privacy Considerations 890 Implementers MUST design and use authorization details in a privacy 891 preserving manner. 893 Any sensitive personal data included in authorization details MUST be 894 prevented from leaking, e.g., through referrer headers. 895 Implementation options include encrypted request objects as defined 896 in [I-D.ietf-oauth-jwsreq] or transmission of authorization details 897 via end-to-end encrypted connections between client and authorization 898 server by utilizing the "request_uri" authorization request parameter 899 as defined in [I-D.ietf-oauth-jwsreq]. 901 Even if the request data are encrypted, an attacker could use the 902 authorization server to learn the user data by injecting the 903 encrypted request data into an authorization request on a device 904 under his control and use the authorization server's user consent 905 screens to show the (decrypted) user data in the clear. 906 Implementations MUST consider this attacker vector and implement 907 appropriate counter measures, e.g. by only showing portions of the 908 data or, if possible, determing whether the assumed user context is 909 still the same (after user authentication). 911 The AS MUST take into consideration the privacy implications when 912 sharing authorization details with the resource servers. The AS 913 SHOULD share this data with the resource servers on a "need to know" 914 basis. 916 8. Acknowledgements 918 We would would like to thank Daniel Fett, Sebastian Ebling, Dave 919 Tonge, Mike Jones, Nat Sakimura, and Rob Otto for their valuable 920 feedback during the preparation of this draft. 922 We would also like to thank Daniel Fett, Dave Tonge, Travis Spencer, 923 Jørgen Binningsbø, Aamund Bremer, Steinar Noem, and Aaron 924 Parecki for their valuable feedback to this draft. 926 9. IANA Considerations 928 TBD 930 * "authorization_details" as JWT claim 932 * "authorization_details_supported" and 933 "authorization_data_types_supported" as metadata parameters 935 * "authorization_data_types" as dynamic client registration 936 parameter 938 * [[ possibly establish authorization data type registry (and 939 declare: "type", "actions", "locations", "datatypes", 940 "identifier", others?) ]] 942 * [[ register type "openid_claims" on a URL by the OpenID 943 foundation? ]] 945 10. Normative References 947 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 948 Requirement Levels", BCP 14, RFC 2119, 949 DOI 10.17487/RFC2119, March 1997, 950 . 952 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 953 "Assertion Framework for OAuth 2.0 Client Authentication 954 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 955 May 2015, . 957 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 958 RFC 6749, DOI 10.17487/RFC6749, October 2012, 959 . 961 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 962 "OAuth 2.0 Device Authorization Grant", RFC 8628, 963 DOI 10.17487/RFC8628, August 2019, 964 . 966 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 967 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 968 May 2017, . 970 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 971 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 972 . 974 11. Informative References 976 [I-D.ietf-oauth-security-topics] 977 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 978 "OAuth 2.0 Security Best Current Practice", Work in 979 Progress, Internet-Draft, draft-ietf-oauth-security- 980 topics-15, 5 April 2020, . 983 [CSC] Consortium, C. S., "Architectures and protocols for remote 984 signature applications", 1 June 2019, 985 . 988 [I-D.lodderstedt-oauth-par] 989 Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 990 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 991 Work in Progress, Internet-Draft, draft-lodderstedt-oauth- 992 par-01, 3 November 2019, . 995 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 996 Interchange Format", STD 90, RFC 8259, 997 DOI 10.17487/RFC8259, December 2017, 998 . 1000 [ETSI] ETSI, "ETSI TS 119 432, Electronic Signatures and 1001 Infrastructures (ESI); Protocols for remote digital 1002 signature creation", 20 March 2019, 1003 . 1007 [transaction-authorization] 1008 Lodderstedt, T., "Transaction Authorization or why we need 1009 to re-think OAuth scopes", 20 April 2019, 1010 . 1013 [I-D.ietf-oauth-jwsreq] 1014 Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization 1015 Framework: JWT Secured Authorization Request (JAR)", Work 1016 in Progress, Internet-Draft, draft-ietf-oauth-jwsreq-26, 1017 27 July 2020, 1018 . 1020 [OpenID.CIBA] 1021 Fernandez, G., Walter, F., Nennker, A., Tonge, D., and B. 1022 Campbell, "OpenID Connect Client Initiated Backchannel 1023 Authentication Flow - Core 1.0", 16 January 2019, 1024 . 1027 [I-D.ietf-oauth-jwt-introspection-response] 1028 Lodderstedt, T. and V. Dzhuvinov, "JWT Response for OAuth 1029 Token Introspection", Work in Progress, Internet-Draft, 1030 draft-ietf-oauth-jwt-introspection-response-09, 25 April 1031 2020, . 1034 [I-D.ietf-oauth-resource-indicators] 1035 Campbell, B., Bradley, J., and H. Tschofenig, "Resource 1036 Indicators for OAuth 2.0", Work in Progress, Internet- 1037 Draft, draft-ietf-oauth-resource-indicators-08, 11 1038 September 2019, . 1041 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1042 C. Mortimore, "OpenID Connect Core 1.0 incorporating 1043 errata set 1", 8 November 2014, 1044 . 1046 Appendix A. Additional Examples 1047 A.1. OpenID Connect 1049 These hypothetical examples try to encapsulate all details specific 1050 to the OpenID Connect part of an authorization process into an 1051 authorization JSON object. 1053 The top-level elements are based on the definitions given in [OIDC]: 1055 * "claim_sets": names of predefined claim sets, replacement for 1056 respective scope values, such as "profile" 1058 * "max_age": Maximum Authentication Age 1060 * "acr_values": array of ACR values 1062 * "claims": the "claims" JSON structure as defined in [OIDC] 1064 This is a simple request for some claim sets. 1066 [ 1067 { 1068 "type": "openid", 1069 "locations": [ 1070 "https://op.example.com/userinfo" 1071 ], 1072 "claim_sets": [ 1073 "email", 1074 "profile" 1075 ] 1076 } 1077 ] 1079 Note: "locations" specifies the location of the userinfo endpoint 1080 since this is the only place where an access token is used by a 1081 client (RP) in OpenID Connect to obtain claims. 1083 A more sophisticated example is shown in the following 1085 [ 1086 { 1087 "type": "openid", 1088 "locations": [ 1089 "https://op.example.com/userinfo" 1090 ], 1091 "max_age": 86400, 1092 "acr_values": "urn:mace:incommon:iap:silver", 1093 "claims": { 1094 "userinfo": { 1095 "given_name": { 1096 "essential": true 1097 }, 1098 "nickname": null, 1099 "email": { 1100 "essential": true 1101 }, 1102 "email_verified": { 1103 "essential": true 1104 }, 1105 "picture": null, 1106 "http://example.info/claims/groups": null 1107 }, 1108 "id_token": { 1109 "auth_time": { 1110 "essential": true 1111 } 1112 } 1113 } 1114 } 1115 ] 1117 A.2. Remote Electronic Signing 1119 The following example is based on the concept layed out for remote 1120 electronic signing in ETSI TS 119 432 [ETSI] and the CSC API for 1121 remote signature creation [CSC]. 1123 [ 1124 { 1125 "type": "sign", 1126 "locations": [ 1127 "https://signing.example.com/signdoc" 1128 ], 1129 "credentialID": "60916d31-932e-4820-ba82-1fcead1c9ea3", 1130 "documentDigests": [ 1131 { 1132 "hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=", 1133 "label": "Credit Contract" 1134 }, 1135 { 1136 "hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=", 1137 "label": "Contract Payment Protection Insurance" 1138 } 1139 ], 1140 "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1" 1141 } 1142 ] 1144 The top-level elements have the following meaning: 1146 * "credentialID": identifier of the certificate to be used for 1147 signing 1149 * "documentDigests": array containing the hash of every document to 1150 be signed ("hash" elements). Additionally, the corresponding 1151 "label" element identifies the respective document to the user, 1152 e.g. to be used in user consent. 1154 * "hashAlgorithm": algomrithm that was used to calculate the hash 1155 values. 1157 The AS is supposed to ask the user for consent for the creation of 1158 signatues for the documents listed in the structure. The client uses 1159 the access token issued as result of the process to call the sign doc 1160 endpoint at the respective signing service to actually create the 1161 signature. This access token is bound to the client, the user id and 1162 the hashes (and signature algorithm) as consented by the user. 1164 A.3. Access to Tax Data 1166 This example is inspired by an API allowing third parties to access 1167 citizen's tax declarations and income statements, for example to 1168 determine their credit worthiness. 1170 [ 1171 { 1172 "type": "tax_data", 1173 "locations": [ 1174 "https://taxservice.govehub.no" 1175 ], 1176 "actions":"read_tax_declaration", 1177 "periods": ["2018"], 1178 "duration_of_access": 30, 1179 "tax_payer_id": "23674185438934" 1180 } 1181 ] 1183 The top-level elements have the following meaning: 1185 * "periods": determines the periods the client wants to access 1187 * "duration_of_access": how long does the client intend to access 1188 the data in days 1190 * "tax_payer_id": identifier of the tax payer (if known to the 1191 client) 1193 A.4. eHealth 1195 These two examples are inspired by requirements for APIs used in the 1196 Norwegian eHealth system. 1198 In this use case the physical therapist sits in front of her computer 1199 using a local Electronic Health Records (EHR) system. She wants to 1200 look at the electronic patient records of a certain patient and she 1201 also wants to fetch the patients journal entries in another system, 1202 perhaps at another institution or a national service. Access to this 1203 data is provided by an API. 1205 The information necessary to authorize the request at the API is only 1206 known by the EHR system, and must be presented to the API. 1208 In the first example the authorization details object contains the 1209 identifier of an organization. In this case the API needs to know if 1210 the given organization has the lawful basis for processing personal 1211 health information to give access to sensitive data. 1213 "authorization_details":{ 1214 "type":"patient_record", 1215 "requesting_entity": { 1216 "type": "Practitioner", 1217 "identifier": [ 1218 { 1219 "system": " urn:oid:2.16.578.1.12.4.1.4.4", 1220 "value": "1234567" 1221 }], 1222 "practitioner_role":{ 1223 "organization":{ 1224 "identifier": { 1225 "system":"urn:oid:2.16.578.1.12.4.1.2.101", 1226 "type":"ENH", 1227 "value":"[organizational number]" 1228 } 1229 } 1230 } 1231 } 1232 } 1234 In the second example the API requires more information to authorize 1235 the request. In this case the authorization details object contains 1236 additional information about the health institution and the current 1237 profession the user has at the time of the request. The additional 1238 level of detail could be used for both authorization and data 1239 minimization. 1241 [ 1242 { 1243 "type": "patient_record", 1244 "location": "https://fhir.example.com/patient", 1245 "actions": [ 1246 "read" 1247 ], 1248 "patient_identifier": [ 1249 { 1250 "system": "urn:oid:2.16.578.1.12.4.1.4.1", 1251 "value": "12345678901" 1252 } 1253 ], 1254 "reason_for_request": "Clinical treatment", 1255 "requesting_entity": { 1256 "type": "Practitioner", 1257 "identifier": [ 1258 { 1259 "system": " urn:oid:2.16.578.1.12.4.1.4.4", 1260 "value": "1234567" 1262 } 1263 ], 1264 "practitioner_role": { 1265 "organization": { 1266 "identifier": [ 1267 { 1268 "system": "urn:oid:2.16.578.1.12.4.1.2.101", 1269 "type": "ENH", 1270 "value": "" 1271 } 1272 ], 1273 "type": { 1274 "coding": [ 1275 { 1276 "system": 1277 "http://hl7.org/fhir/organization-type", 1278 "code": "dept", 1279 "display": "Hospital Department" 1280 } 1281 ] 1282 }, 1283 "name": "Akuttmottak" 1284 }, 1285 "profession": { 1286 "coding": [ 1287 { 1288 "system": "http://snomed.info/sct", 1289 "code": "36682004", 1290 "display": "Physical therapist" 1291 } 1292 ] 1293 } 1294 } 1295 } 1296 } 1297 ] 1299 Description of the elements: 1301 * "patient_identifier": the identifier of the patient composed of a 1302 system identifier in OID format (namespace) and the acutal value 1303 within this namespace. 1305 * "reason_for_request": the reason why the user wants to access a 1306 certain API 1308 * "requesting_entity": specification of the requester by means of 1309 identity, role and organizational context. This data is provided 1310 to facilitate authorization and for auditing purposes. 1312 In this use case, the AS authenticates the requester, who is not the 1313 patient, and approves access based on policies. 1315 Appendix B. Document History 1317 [[ To be removed from the final specification ]] 1319 -02 1321 * Clarify "type" parameter processing 1323 -01 1325 * Minor fix-up in a few examples 1327 -00 (WG draft) 1329 * initial WG revision 1331 -03 1333 * Reworked examples to illustrate privacy preserving use of 1334 "authorization_details" 1336 * Added text on audience restriction 1338 * Added description of relationship between "scope" and 1339 "authorization_details" 1341 * Added text on token request & response and "authorization_details" 1343 * Added text on how authorization details are conveyed to RSs by 1344 JWTs or token endpoint response 1346 * Added description of relationship between "claims" and 1347 "authorization_details" 1349 * Added more example from different sectors 1351 * Clarified string comparison to be byte-exact without collation 1353 -02 1355 * Added Security Considerations 1356 * Added Privacy Considerations 1358 * Added notes on URI size and authorization details 1360 * Added requirement to return the effective authorization details 1361 granted by the resource owner in the token response 1363 * changed "authorization_details" structure from object to array 1365 * added Justin Richer & Brian Campbell as Co-Authors 1367 -00 / -01 1369 * first draft 1371 Authors' Addresses 1373 Torsten Lodderstedt 1374 yes.com 1376 Email: torsten@lodderstedt.net 1378 Justin Richer 1379 Bespoke Engineering 1381 Email: ietf@justin.richer.org 1383 Brian Campbell 1384 Ping Identity 1386 Email: bcampbell@pingidentity.com