idnits 2.17.1 draft-ietf-oauth-rar-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- 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 (January 21, 2020) is 1550 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-20 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-jwt-introspection-response-08 == Outdated reference: A later version (-25) exists of draft-ietf-oauth-security-topics-13 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: July 24, 2020 Bespoke Engineering 6 B. Campbell 7 Ping Identity 8 January 21, 2020 10 OAuth 2.0 Rich Authorization Requests 11 draft-ietf-oauth-rar-00 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 July 24, 2020. 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 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 . . . . . . . . . . . . . . . 4 55 2. Request parameter "authorization_details" . . . . . . . . . . 4 56 2.1. Authorization data elements types . . . . . . . . . . . . 5 57 2.2. Relationship to "scope" parameter . . . . . . . . . . . . 8 58 2.2.1. Scope value "openid" and "claims" parameter . . . . . 8 59 2.3. Relationship to "resource" parameter . . . . . . . . . . 9 60 3. Using "authorization_details" . . . . . . . . . . . . . . . . 11 61 3.1. Authorization Request . . . . . . . . . . . . . . . . . . 11 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. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 75 10.1. Normative References . . . . . . . . . . . . . . . . . . 21 76 10.2. Informative References . . . . . . . . . . . . . . . . . 22 77 Appendix A. Additional Examples . . . . . . . . . . . . . . . . 23 78 A.1. OpenID Connect . . . . . . . . . . . . . . . . . . . . . 23 79 A.2. Remote Electronic Signing . . . . . . . . . . . . . . . . 25 80 A.3. Access to Tax Data . . . . . . . . . . . . . . . . . . . 26 81 A.4. eHealth . . . . . . . . . . . . . . . . . . . . . . . . . 27 82 Appendix B. Document History . . . . . . . . . . . . . . . . . . 29 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 85 1. Introduction 87 The OAuth 2.0 authorization framework [RFC6749] defines the parameter 88 "scope" that allows OAuth clients to specify the requested scope, 89 i.e., the permission, of an access token. This mechanism is 90 sufficient to implement static scenarios and coarse-grained 91 authorization requests, such as "give me read access to the resource 92 owner's profile" but it is not sufficient to specify fine-grained 93 authorization requirements, such as "please let me make a payment 94 with the amount of 45 Euros" or "please give me read access to folder 95 A and write access to file X". 97 This draft introduces a new parameter "authorization_details" that 98 allows clients to specify their fine-grained authorization 99 requirements using the expressiveness of JSON data structures. 101 For example, a request for payment authorization can be represented 102 using a JSON object like this: 104 { 105 "type": "payment_initiation", 106 "locations": [ 107 "https://example.com/payments" 108 ], 109 "instructedAmount": { 110 "currency": "EUR", 111 "amount": "123.50" 112 }, 113 "creditorName": "Merchant123", 114 "creditorAccount": { 115 "iban": "DE02100100109307118603" 116 }, 117 "remittanceInformationUnstructured": "Ref Number Merchant" 118 } 120 This object contains detailed information about the intended payment, 121 such as amount, currency, and creditor, that are required to inform 122 the user and obtain her consent. The AS and the respective RS 123 (providing the payment initation API) will together enforce this 124 consent. 126 For a comprehensive discussion of the challenges arising from new use 127 cases in the open banking and electronic signing spaces see 128 [transaction-authorization]. 130 In addition to facilitating custom authorization requests, this draft 131 also introduces a set of common data type fields for use across 132 different APIs. 134 Most notably, the field "locations" allows a client to specify where 135 it intends to use a certain authorization, i.e., it is now possible 136 to unambiguously assign permissions to resource servers. In 137 situations with multiple resource servers, this prevents unintended 138 client authorizations (e.g. a "read" scope value potentially 139 applicable for an email as well as a cloud service). In combination 140 with the "resource" token request parameter as specified in 141 [I-D.ietf-oauth-resource-indicators] it enables the AS to mint RS- 142 specific structured access tokens that only contain the permissions 143 applicable to the respective RS. 145 1.1. Conventions and Terminology 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in BCP 150 14 [RFC2119] [RFC8174] when, and only when, they appear in all 151 capitals, as shown here. 153 This specification uses the terms "access token", "refresh token", 154 "authorization server", "resource server", "authorization endpoint", 155 "authorization request", "authorization response", "token endpoint", 156 "grant type", "access token request", "access token response", and 157 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 159 2. Request parameter "authorization_details" 161 The request parameter "authorization_details" contains, in JSON 162 notation, an array of objects. Each JSON object contains the data to 163 specify the authorization requirements for a certain type of 164 resource. The type of resource or access requirement is determined 165 by the "type" field. 167 This example shows the specification of authorization details using 168 the payment authorization object shown above: 170 [ 171 { 172 "type": "payment_initiation", 173 "actions": [ 174 "initiate", 175 "status", 176 "cancel" 177 ], 178 "locations": [ 179 "https://example.com/payments" 180 ], 181 "instructedAmount": { 182 "currency": "EUR", 183 "amount": "123.50" 184 }, 185 "creditorName": "Merchant123", 186 "creditorAccount": { 187 "iban": "DE02100100109307118603" 188 }, 189 "remittanceInformationUnstructured": "Ref Number Merchant" 190 } 191 ] 192 This example shows a combined request asking for access to account 193 information and permission to initiate a payment: 195 [ 196 { 197 "type": "account_information", 198 "actions": [ 199 "list_accounts", 200 "read_balances", 201 "read_transactions" 202 ], 203 "locations": [ 204 "https://example.com/accounts" 205 ] 206 }, 207 { 208 "type": "payment_initiation", 209 "actions": [ 210 "initiate", 211 "status", 212 "cancel" 213 ], 214 "locations": [ 215 "https://example.com/payments" 216 ], 217 "instructedAmount": { 218 "currency": "EUR", 219 "amount": "123.50" 220 }, 221 "creditorName": "Merchant123", 222 "creditorAccount": { 223 "iban": "DE02100100109307118603" 224 }, 225 "remittanceInformationUnstructured": "Ref Number Merchant" 226 } 227 ] 229 The JSON objects with "type" fields of "account_information" and 230 "payment_initiation" represent the different authorization data to be 231 used by the AS to ask for consent and MUST subsequently also be made 232 available to the respective resource servers. The array MAY contain 233 several elements of the same "type". 235 2.1. Authorization data elements types 237 This draft defines a set of common data elements that are designed to 238 be usable across different types of APIs. These data elements MAY be 239 combined in different ways depending on the needs of the API. Unless 240 otherwise noted, all data elements are OPTIONAL. 242 type: 243 The type of resource request as a string. This field MAY define 244 which other elements are allowed in the request. This element is 245 REQUIRED. 247 locations: 248 An array of strings representing the location of the resource or 249 resource server. This is typically composed of URIs. 251 actions: 252 An array of strings representing the kinds of actions to be taken 253 at the resource. The values of the strings are determined by the 254 API being protected. 256 datatypes: 257 An array of strings representing the kinds of data being requested 258 from the resource. 260 identifier: 261 A string identifier indicating a specific resource available at 262 the API. 264 When different element types are used in combination, the permissions 265 the client requests is the cartesian product of the values. In the 266 following example 268 [ 269 { 270 "type": "customer_information", 271 "locations": [ 272 "https://example.com/customers", 273 ] 274 "actions": [ 275 "read", 276 "write" 277 ], 278 "datatypes": [ 279 "contacts", 280 "photos" 281 ] 282 } 283 ] 284 the client is requesting read and write access to both the contacts 285 and photos belonging to customers in a customer information API. If 286 the client wishes to have finer control over its access, it can send 287 multiple objects. For example: 289 [ 290 { 291 "type": "customer_information", 292 "locations": [ 293 "https://example.com/customers" 294 ], 295 "actions": [ 296 "read" 297 ], 298 "datatypes": [ 299 "contacts" 300 ] 301 }, 302 { 303 "type": "customer_information", 304 "locations": [ 305 "https://example.com/customers" 306 ], 307 "actions": [ 308 "write" 309 ], 310 "datatypes": [ 311 "photos" 312 ] 313 } 314 ] 316 The client is asking for read access to the contacts and write access 317 to the photos in the same API endpoint. 319 An API MAY define its own extensions, subject to the "type" of the 320 respective authorization object. It is assumed that the full 321 structure of each of the authorization objects is tailored to the 322 needs of a certain application, API, or resource type. The example 323 structures shown above are based on certain kinds of APIs that can be 324 found in the Open Banking space. 326 Note: Applications MUST ensure that their authorization data types do 327 not collide. This is either achieved by using a namespace under the 328 control of the entity defining the type name or by registering the 329 type with the new "OAuth Authorization Data Type Registry" (see 330 Section 9). 332 The following example shows how an implementation could utilize the 333 namespace "https://scheme.example.org/" to ensure collision resistant 334 element names. 336 { 337 "type": "https://scheme.example.org/files", 338 "locations": [ 339 "https://example.com/files" 340 ], 341 "permissions": [ 342 { 343 "path": "/myfiles/A", 344 "access": [ 345 "read" 346 ] 347 }, 348 { 349 "path": "/myfiles/A/X", 350 "access": [ 351 "read", 352 "write" 353 ] 354 } 355 ] 356 } 358 2.2. Relationship to "scope" parameter 360 "authorization_details" and "scope" can be used in the same 361 authorization request for carrying independent authorization 362 requirements. 364 The AS MUST consider both sets of requirements in combination with 365 each other for the given authorization request. The details of how 366 the AS combines these parameters are specific to the APIs being 367 protected and outside the scope of this specification. 369 It is RECOMMENDED that a given API use only one form of requirement 370 specification. 372 When gathering user consent, the AS MUST present the merged set of 373 requirements represented by the authorization request. 375 2.2.1. Scope value "openid" and "claims" parameter 377 OpenID Connect [OIDC] specifies the JSON-based "claims" request 378 parameter that can be used to specify the claims a client (acting as 379 OpenID Connect Relying Party) wishes to receive in a fine-grained and 380 privacy preserving way as well as assign those claims to a certain 381 delivery mechanisms, i.e. ID Token or userinfo response. 383 The combination of the scope value "openid" and the additional 384 parameter "claims" can be used beside "authorization_details" in the 385 same way as every non-OIDC scope value. 387 Alternatively, there could be an authorization data type for OpenID 388 Connect. Appendix A.1 gives an example of how such an authorization 389 data type could look like. 391 2.3. Relationship to "resource" parameter 393 The request parameter "resource" as defined in 394 [I-D.ietf-oauth-resource-indicators] indicates to the AS the 395 resource(s) where the client intends to use the access tokens issued 396 based on a certain grant. This mechanism is a way to audience- 397 restrict access tokens and to allow the AS to create resource server 398 specific access tokens. 400 If a client uses "authorization_details" with "locations" elements 401 and the "resource" parameter in the same authorization request, the 402 "locations" data take precedence over the data conveyed in the 403 "resource" parameter for that particular authorization details 404 object. 406 If such a client uses the "resource" parameter in a subsequent token 407 requests, the AS MUST utilize the data provided in the "locations" 408 elements to filter the authorization data objects applicable to the 409 respective resource server. The AS will select all authorization 410 details object where the "resource" string matches as prefix of one 411 of the URLs provided in the respective "locations" element. 413 This shall be illustrated using an example. 415 The client has sent an authorization request using the following 416 example authorization details. 418 [ 419 { 420 "type": "account_information", 421 "actions": [ 422 "list_accounts", 423 "read_balances", 424 "read_transactions" 425 ], 426 "locations": [ 427 "https://example.com/accounts" 428 ] 429 }, 430 { 431 "type": "payment_initiation", 432 "actions": [ 433 "initiate", 434 "status", 435 "cancel" 436 ], 437 "locations": [ 438 "https://example.com/payments" 439 ], 440 "instructedAmount": { 441 "currency": "EUR", 442 "amount": "123.50" 443 }, 444 "creditorName": "Merchant123", 445 "creditorAccount": { 446 "iban": "DE02100100109307118603" 447 }, 448 "remittanceInformationUnstructured": "Ref Number Merchant" 449 } 450 ] 452 If this client then sends the following token request to the AS, 454 POST /token HTTP/1.1 455 Host: as.example.com 456 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 457 Content-Type: application/x-www-form-urlencoded 459 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 460 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 461 &resource=https%3A%2F%2Fexample%2Ecom%2Fpayments 463 that contains a resource parameter with the value of 464 "https://example.com/payments", this value will be matched against 465 the locations elements ("https://example.com/accounts" and 466 "https://example.com/payments") and will select the element of type 467 "payment_initiation" for inclusion in the access token as illustrated 468 by the following example JWT content. 470 { 471 "iss": "https://as.example.com", 472 "sub": "24400320", 473 "aud": "a7AfcPcsl2", 474 "exp": 1311281970, 475 ... 476 "authorization_details": [ 477 { 478 "type": "https://www.someorg.com/payment_initiation", 479 "actions": [ 480 "initiate", 481 "status", 482 "cancel" 483 ], 484 "locations": [ 485 "https://example.com/payments" 486 ], 487 "instructedAmount": { 488 "currency": "EUR", 489 "amount": "123.50" 490 }, 491 "creditorName": "Merchant123", 492 "creditorAccount": { 493 "iban": "DE02100100109307118603" 494 }, 495 "remittanceInformationUnstructured": "Ref Number Merchant" 496 } 497 ], 498 ... 499 } 501 3. Using "authorization_details" 503 3.1. Authorization Request 505 The request parameter can be used to specify authorization 506 requirements in all places where the "scope" parameter is used for 507 the same purpose, examples include: 509 o Authorization requests as specified in [RFC6749], 511 o Access token requests as specified in [RFC6749], if also used as 512 authorization requests, e.g. in the case of assertion grant types 513 [RFC7521], 515 o Request objects as specified in [I-D.ietf-oauth-jwsreq], 517 o Device Authorization Request as specified in [RFC8628], 519 o Backchannel Authentication Requests as defined in [OpenID.CIBA]. 521 Parameter encoding is determined by the respective context. 523 In the context of an authorization request according to [RFC6749], 524 the parameter is encoded using the "application/x-www-form- 525 urlencoded" format of the serialized JSON as shown in the following 526 example: 528 GET /authorize?response_type=code 529 &client_id=s6BhdRkqt3 530 &state=af0ifjsldkj 531 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 532 &code_challenge_method=S256 533 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U 534 &authorization_details=%5B%7B%22type%22%3A%22account%5Finformati 535 on%22%2C%22actions%22%3A%5B%22list%5Faccounts%22%2C%22read%5Fbal 536 ances%22%2C%22read%5Ftransactions%22%5D%2C%22locations%22%3A%5B% 537 22https%3A%2F%2Fexample%2Ecom%2Faccounts%22%5D%7D%5D HTTP/1.1 538 Host: server.example.com 540 Implementors MUST ensure to protect personal identifiable information 541 in transit. One way is to utilize encrypted request objects as 542 defined in [I-D.ietf-oauth-jwsreq]. In the context of a request 543 object, "authorization_details" is added as another top level JSON 544 element. 546 { 547 "iss": "s6BhdRkqt3", 548 "aud": "https://server.example.com", 549 "response_type": "code", 550 "client_id": "s6BhdRkqt3", 551 "redirect_uri": "https://client.example.com/cb", 552 "state": "af0ifjsldkj", 553 "code_challenge_method": "S256", 554 "code_challenge": "K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U", 555 "authorization_details": [ 556 { 557 "type": "account_information", 558 "actions": [ 559 "list_accounts", 560 "read_balances", 561 "read_transactions" 562 ], 563 "locations": [ 564 "https://example.com/accounts" 565 ] 566 }, 567 { 568 "type": "payment_initiation", 569 "actions": [ 570 "initiate", 571 "status", 572 "cancel" 573 ], 574 "locations": [ 575 "https://example.com/payments" 576 ], 577 "instructedAmount": { 578 "currency": "EUR", 579 "amount": "123.50" 580 }, 581 "creditorName": "Merchant123", 582 "creditorAccount": { 583 "iban": "DE02100100109307118603" 584 }, 585 "remittanceInformationUnstructured": "Ref Number Merchant" 586 } 587 ] 588 } 590 Authorization request URIs containing authorization details in a 591 request parameter or a request object can become very long. 592 Implementers SHOULD therefore consider using the "request_uri" 593 parameter as defined in [I-D.ietf-oauth-jwsreq] in combination with 594 the pushed request object mechanism as defined in 595 [I-D.lodderstedt-oauth-par] to pass authorization details in a 596 reliable and secure manner. Here is an example of such a pushed 597 authorization request that sends the authorization request data 598 directly to the AS via a HTTPS-protected connection: 600 POST /as/par HTTP/1.1 601 Host: as.example.com 602 Content-Type: application/x-www-form-urlencoded 603 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 605 response_type=code& 606 client_id=s6BhdRkqt3 607 &state=af0ifjsldkj 608 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 609 &code_challenge_method=S256 610 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U 611 &authorization_details=%5B%7B%22type%22%3A%22account_information%22 612 %2C%22actions%22%3A%5B%22list_accounts%22%2C%22read_balances%22%2C% 613 22read_transactions%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fe 614 xample.com%2Faccounts%22%5D%7D%2C%7B%22type%22%3A%22payment_initiat 615 ion%22%2C%22actions%22%3A%5B%22initiate%22%2C%22status%22%2C%22canc 616 el%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpaym 617 ents%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22EUR%22 618 %2C%22amount%22%3A%22123.50%22%7D%2C%22creditorName%22%3A%22Merchan 619 t123%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE021001001093 620 07118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%2 621 0Number%20Merchant%22%7D%5D 623 3.2. Authorization Request Processing 625 Based on the data provided in the "authorization_details" parameter 626 the AS will ask the user for consent to the requested access 627 permissions. 629 The AS MUST refuse to process any unknown authorization data type. 630 If the "authorization_details" contain any unknown authorization data 631 type, the AS MUST abort processing and respond with an error 632 "invalid_authorization_details" to the client. 634 Note: If the authorization request also contained the "scope" 635 parameter, the AS MUST present the merged set of requirements 636 represented by the authorization request in the user consent. 638 If the resource owner grants the client the requested access, the AS 639 will issue tokens to the client that are associated with the 640 respective "authorization_details" (and scope values, if applicable). 642 Note: The AS MUST make the "authorization_details" available to the 643 respective resource servers. The AS MAY add the 644 "authorization_details" element to access tokens in JWT format and to 645 Token Introspection responses (see below). 647 3.3. Token Request 649 Clients utilizing authorization details are RECOMMENDED to use the 650 "resource" token request parameter to allow the AS to issue audience 651 restricted access tokens as recommended in 652 [I-D.ietf-oauth-security-topics]. 654 For example the following token request selects authorization details 655 applicable for the resource server represented by the URI 656 "https://example.com/payments". 658 POST /token HTTP/1.1 659 Host: as.example.com 660 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 661 Content-Type: application/x-www-form-urlencoded 663 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 664 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 665 &resource=https%3A%2F%2Fexample%2Ecom%2Fpayments 667 3.4. Token Response 669 In addition to the token response parameters as defined in [RFC6749], 670 the authorization server MUST also return the authorization details 671 as granted by the resource owner and assigned to the respective 672 access token. 674 This is shown in the following example: 676 HTTP/1.1 200 OK 677 Content-Type: application/json 678 Cache-Control: no-cache, no-store 680 { 681 "access_token": "2YotnFZFEjr1zCsicMWpAA", 682 "token_type": "example", 683 "expires_in": 3600, 684 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 685 "authorization_details": [ 686 { 687 "type": "https://www.someorg.com/payment_initiation", 688 "actions": [ 689 "initiate", 690 "status", 691 "cancel" 692 ], 693 "locations": [ 694 "https://example.com/payments" 695 ], 696 "instructedAmount": { 697 "currency": "EUR", 698 "amount": "123.50" 699 }, 700 "creditorName": "Merchant123", 701 "creditorAccount": { 702 "iban": "DE02100100109307118603" 703 }, 704 "remittanceInformationUnstructured": "Ref Number Merchant" 705 } 706 ] 707 } 709 3.4.1. Token Content 711 In order to enable the RS to enforce the authorization details as 712 approved in the authorization process, the AS MUST make this data 713 available to the RS. 715 If the access token is a JWT [RFC7519], the AS is RECOMMENDED to add 716 the "authorization_details" object, filtered to the specific 717 audience, as top-level claim. 719 The AS will typically also add further claims to the JWT the RS 720 requires for request processing, e.g., user id, roles, and 721 transaction specific data. What claims the particular RS requires is 722 defined by the RS-specific policy with the AS. 724 The following shows the contents of an example JWT for the payment 725 initation example above: 727 { 728 "iss": "https://as.example.com", 729 "sub": "24400320", 730 "aud": "a7AfcPcsl2", 731 "exp": 1311281970, 732 "acr": "psd2_sca", 733 "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296", 734 "authorization_details": [ 735 { 736 "type": "https://www.someorg.com/payment_initiation", 737 "actions": [ 738 "initiate", 739 "status", 740 "cancel" 741 ], 742 "locations": [ 743 "https://example.com/payments" 744 ], 745 "instructedAmount": { 746 "currency": "EUR", 747 "amount": "123.50" 748 }, 749 "creditorName": "Merchant123", 750 "creditorAccount": { 751 "iban": "DE02100100109307118603" 752 }, 753 "remittanceInformationUnstructured": "Ref Number Merchant" 754 } 755 ], 756 "debtorAccount": { 757 "iban": "DE40100100103307118608", 758 "user_role": "owner" 759 } 760 ] 762 In this case, the AS added the following example claims: 764 o "sub": conveys the user on which behalf the client is asking for 765 payment initation 767 o "txn": transaction id used to trace the transaction across the 768 services of provider "example.com" 770 o "debtorAccount": API-specific element containing the debtor 771 account. In the example, this account was not passed in the 772 authorization details but selected by the user during the 773 authorization process. The field "user_role" conveys the role the 774 user has with respect to this particuar account. In this case, 775 she is the owner. This data is used for access control at the 776 payment API (the RS). 778 3.5. Token Introspection Request 780 In case of opaque access tokens, the data provided to a certain RS is 781 determined using the RS's identifier with the AS (see 782 [I-D.ietf-oauth-jwt-introspection-response], section 3). 784 3.6. Token Introspection Response 786 The token endpoint response provides the RS with the authorization 787 details applicable to it as a top-level JSON element along with the 788 claims the RS requires for request processing. 790 Here is an example for the payment initation example RS: 792 { 793 "active": true, 794 "sub": "24400320", 795 "aud": "s6BhdRkqt3", 796 "exp": 1311281970, 797 "acr": "psd2_sca", 798 "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296", 799 "authorization_details": [ 800 { 801 "type": "https://www.someorg.com/payment_initiation", 802 "actions": [ 803 "initiate", 804 "status", 805 "cancel" 806 ], 807 "locations": [ 808 "https://example.com/payments" 809 ], 810 "instructedAmount": { 811 "currency": "EUR", 812 "amount": "123.50" 813 }, 814 "creditorName": "Merchant123", 815 "creditorAccount": { 816 "iban": "DE02100100109307118603" 817 }, 818 "remittanceInformationUnstructured": "Ref Number Merchant" 819 } 820 ], 821 "debtorAccount": { 822 "iban": "DE40100100103307118608", 823 "user_role": "owner" 824 } 825 } 827 4. Metadata 829 The AS advertises support for "authorization_details" using the 830 metadata parameter "authorization_details_supported" of type boolean. 832 The authorization data types supported can be determined using the 833 metadata parameter "authorization_data_types_supported", which is an 834 JSON array. 836 Clients announce the authorization data types they use in the new 837 dynamic client registration parameter "authorization_data_types". 839 The registration of new authorization data types with the AS is out 840 of scope of this draft. 842 5. Implementation Considerations 844 The scheme and processing will vary significantly among different 845 authorization data types. Any implementation of this draft is 846 therefore supposed to allow the customization of the user consent and 847 the handling of access token data. 849 One option would be to have a mechanism allowing the registration of 850 extension modules, each of them responsible for rendering the 851 respective user consent and any transformation needed to provide the 852 data needed to the resource server by way of structured access tokens 853 or token introspection responses. 855 6. Security Considerations 857 Authorization details are sent through the user agent in case of an 858 OAuth authorization request, which makes them vulnerable to 859 modifications by the user. In order to ensure their integrity, the 860 client SHOULD send authorization details in a signed request object 861 as defined in [I-D.ietf-oauth-jwsreq] or use the "request_uri" 862 authorization request parameter as defined in [I-D.ietf-oauth-jwsreq] 863 to pass the URI of the request object to the authorization server. 865 All strings MUST be compared using the exact byte representation of 866 the characters as defined by [RFC8259]. This is especially true for 867 the "type" field, which dictates which other fields and functions are 868 allowed in the request. The server MUST NOT perform any form of 869 collation, transformation, or equivalence on the string values. 871 7. Privacy Considerations 873 Implementers MUST design and use authorization details in a privacy 874 preserving manner. 876 Any sensitive personal data included in authorization details MUST be 877 prevented from leaking, e.g., through referrer headers. 878 Implementation options include encrypted request objects as defined 879 in [I-D.ietf-oauth-jwsreq] or transmission of authorization details 880 via end-to-end encrypted connections between client and authorization 881 server by utilizing the "request_uri" authorization request parameter 882 as defined in [I-D.ietf-oauth-jwsreq]. 884 Even if the request data are encrypted, an attacker could use the 885 authorization server to learn the user data by injecting the 886 encrypted request data into an authorization request on a device 887 under his control and use the authorization server's user consent 888 screens to show the (decrypted) user data in the clear. 889 Implementations MUST consider this attacker vector and implement 890 appropriate counter measures, e.g. by only showing portions of the 891 data or, if possible, determing whether the assumed user context is 892 still the same (after user authentication). 894 The AS MUST take into consideration the privacy implications when 895 sharing authorization details with the resource servers. The AS 896 SHOULD share this data with the resource servers on a "need to know" 897 basis. 899 8. Acknowledgements 901 We would would like to thank Daniel Fett, Sebastian Ebling, Dave 902 Tonge, Mike Jones, Nat Sakimura, and Rob Otto for their valuable 903 feedback during the preparation of this draft. 905 We would also like to thank Daniel Fett, Dave Tonge, Travis Spencer, 906 Joergen Binningsboe, Aamund Bremer, Steinar Noem, and Aaron Parecki 907 for their valuable feedback to this draft. 909 9. IANA Considerations 911 TBD 913 o "authorization_details" as JWT claim 915 o "authorization_details_supported" and 916 "authorization_data_types_supported" as metadata parameters 918 o "authorization_data_types" as dynamic client registration 919 parameter 921 o establish authorization data type registry 923 o register type "openid_claims" 925 10. References 927 10.1. Normative References 929 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 930 Requirement Levels", BCP 14, RFC 2119, 931 DOI 10.17487/RFC2119, March 1997, 932 . 934 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 935 RFC 6749, DOI 10.17487/RFC6749, October 2012, 936 . 938 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 939 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 940 . 942 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 943 "Assertion Framework for OAuth 2.0 Client Authentication 944 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 945 May 2015, . 947 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 948 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 949 May 2017, . 951 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 952 "OAuth 2.0 Device Authorization Grant", RFC 8628, 953 DOI 10.17487/RFC8628, August 2019, 954 . 956 10.2. Informative References 958 [CSC] Consortium, C. S., "Architectures and protocols for remote 959 signature applications", Jun 2019, 960 . 963 [ETSI] ETSI, "ETSI TS 119 432, Electronic Signatures and 964 Infrastructures (ESI); Protocols for remote digital 965 signature creation", Mar 2019, 966 . 970 [I-D.ietf-oauth-jwsreq] 971 Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization 972 Framework: JWT Secured Authorization Request (JAR)", 973 draft-ietf-oauth-jwsreq-20 (work in progress), October 974 2019. 976 [I-D.ietf-oauth-jwt-introspection-response] 977 Lodderstedt, T. and V. Dzhuvinov, "JWT Response for OAuth 978 Token Introspection", draft-ietf-oauth-jwt-introspection- 979 response-08 (work in progress), September 2019. 981 [I-D.ietf-oauth-resource-indicators] 982 Campbell, B., Bradley, J., and H. Tschofenig, "Resource 983 Indicators for OAuth 2.0", draft-ietf-oauth-resource- 984 indicators-08 (work in progress), September 2019. 986 [I-D.ietf-oauth-security-topics] 987 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 988 "OAuth 2.0 Security Best Current Practice", draft-ietf- 989 oauth-security-topics-13 (work in progress), July 2019. 991 [I-D.lodderstedt-oauth-par] 992 Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 993 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 994 draft-lodderstedt-oauth-par-01 (work in progress), 995 November 2019. 997 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 998 C. Mortimore, "OpenID Connect Core 1.0 incorporating 999 errata set 1", Nov 2014, 1000 . 1002 [OpenID.CIBA] 1003 Fernandez, G., Walter, F., Nennker, A., Tonge, D., and B. 1004 Campbell, "OpenID Connect Client Initiated Backchannel 1005 Authentication Flow - Core 1.0", January 2019, 1006 . 1009 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1010 Interchange Format", STD 90, RFC 8259, 1011 DOI 10.17487/RFC8259, December 2017, 1012 . 1014 [transaction-authorization] 1015 Lodderstedt, T., "Transaction Authorization or why we need 1016 to re-think OAuth scopes", Apr 2019, . 1020 Appendix A. Additional Examples 1022 A.1. OpenID Connect 1024 These hypothetical examples try to encapsulate all details specific 1025 to the OpenID Connect part of an authorization process into an 1026 authorization JSON object. 1028 The top-level elements are based on the definitions given in [OIDC]: 1030 o "claim_sets": names of predefined claim sets, replacement for 1031 respective scope values, such as "profile" 1033 o "max_age": Maximum Authentication Age 1035 o "acr_values": array of ACR values 1037 o "claims": the "claims" JSON structure as defined in [OIDC] 1039 This is a simple request for some claim sets. 1041 [ 1042 { 1043 "type": "openid", 1044 "locations": [ 1045 "https://op.example.com/userinfo" 1046 ], 1047 "claim_sets": [ 1048 "email", 1049 "profile" 1050 ] 1051 } 1052 ] 1054 Note: "locations" specifies the location of the userinfo endpoint 1055 since this is the only place where an access token is used by a 1056 client (RP) in OpenID Connect to obtain claims. 1058 A more sophisticated example is shown in the following 1060 [ 1061 { 1062 "type": "openid", 1063 "locations": [ 1064 "https://op.example.com/userinfo" 1065 ], 1066 "max_age": 86400, 1067 "acr_values": "urn:mace:incommon:iap:silver", 1068 "claims": { 1069 "userinfo": { 1070 "given_name": { 1071 "essential": true 1072 }, 1073 "nickname": null, 1074 "email": { 1075 "essential": true 1076 }, 1077 "email_verified": { 1078 "essential": true 1079 }, 1080 "picture": null, 1081 "http://example.info/claims/groups": null 1082 }, 1083 "id_token": { 1084 "auth_time": { 1085 "essential": true 1086 } 1087 } 1088 } 1089 } 1090 ] 1092 A.2. Remote Electronic Signing 1094 The following example is based on the concept layed out for remote 1095 electronic signing in ETSI TS 119 432 [ETSI] and the CSC API for 1096 remote signature creation [CSC]. 1098 [ 1099 { 1100 "type": "sign", 1101 "locations": [ 1102 "https://signing.example.com/signdoc" 1103 ], 1104 "credentialID": "60916d31-932e-4820-ba82-1fcead1c9ea3", 1105 "documentDigests": [ 1106 { 1107 "hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=", 1108 "label": "Credit Contract" 1109 }, 1110 { 1111 "hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=", 1112 "label": "Contract Payment Protection Insurance" 1113 } 1114 ], 1115 "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1" 1116 } 1117 ] 1119 The top-level elements have the following meaning: 1121 o "credentialID": identifier of the certificate to be used for 1122 signing 1124 o "documentDigests": array containing the hash of every document to 1125 be signed ("hash" elements). Additionally, the corresponding 1126 "label" element identifies the respective document to the user, 1127 e.g. to be used in user consent. 1129 o "hashAlgorithm": algomrithm that was used to calculate the hash 1130 values. 1132 The AS is supposed to ask the user for consent for the creation of 1133 signatues for the documents listed in the structure. The client uses 1134 the access token issued as result of the process to call the sign doc 1135 endpoint at the respective signing service to actually create the 1136 signature. This access token is bound to the client, the user id and 1137 the hashes (and signature algorithm) as consented by the user. 1139 A.3. Access to Tax Data 1141 This example is inspired by an API allowing third parties to access 1142 citizen's tax declarations and income statements, for example to 1143 determine their credit worthiness. 1145 [ 1146 { 1147 "type": "tax_data", 1148 "locations": [ 1149 "https://taxservice.govehub.no" 1150 ], 1151 "actions":"read_tax_declaration", 1152 "periods": ["2018"], 1153 "duration_of_access": 30, 1154 "tax_payer_id": "23674185438934" 1155 } 1156 ] 1158 The top-level elements have the following meaning: 1160 o "periods": determines the periods the client wants to access 1162 o "duration_of_access": how long does the client intend to access 1163 the data in days 1165 o "tax_payer_id": identifier of the tax payer (if known to the 1166 client) 1168 A.4. eHealth 1170 This example is inspired by an API used in the Norwegian eHealth 1171 system. 1173 In this use case the physical therapist sits in front of her computer 1174 using a local Electronic Health Records (EHR) system. She wants to 1175 look at the electronic patient records of a certain patient and she 1176 also wants to fetch the patients journal entries in another system, 1177 perhaps at another institution or a national service. Access to this 1178 data is provided by an API. 1180 The information necessary to authorize the request at the API is only 1181 known by the EHR system, and must be presented to the API. 1183 Here is an example authorization details object: 1185 [ 1186 { 1187 "type": "patient_record", 1188 "location": "https://fhir.example.com/patient", 1189 "actions": [ 1190 "read" 1191 ], 1192 "patient_identifier": [ 1193 { 1194 "system": "urn:oid:2.16.578.1.12.4.1.4.1", 1195 "value": "12345678901" 1196 } 1197 ], 1198 "reason_for_request": "Clinical treatment", 1199 "requesting_entity": { 1200 "type": "Practitioner", 1201 "practicioner_identifier": [ 1202 { 1203 "system": " urn:oid:2.16.578.1.12.4.1.4.4", 1204 "value": "1234567" 1205 } 1206 ], 1207 "practitioner_role": { 1208 "organization": { 1209 "organization_identifier": [ 1210 { 1211 "system": "urn:oid:2.16.578.1.12.4.1.2.101", 1212 "value": "" 1213 } 1214 ], 1215 "organization_type": { 1216 "coding": [ 1217 { 1218 "system": 1219 "http://hl7.org/fhir/organization-type", 1220 "code": "dept", 1221 "display": "Hospital Department" 1222 } 1223 ] 1224 }, 1225 "name": "Akuttmottak" 1226 }, 1227 "role": { 1228 "coding": [ 1229 { 1230 "system": "http://snomed.info/sct", 1231 "code": "36682004", 1232 "display": "Physical therapist" 1233 } 1234 ] 1235 } 1236 } 1237 } 1238 } 1239 ] 1240 Description of the elements: 1242 o "patient_identifier": the identifier of the patient composed of a 1243 system identifier in OID format (namespace) and the acutal value 1244 within this namespace. 1246 o "reason_for_request": the reason why the user wants to access a 1247 certain API 1249 o "requesting_entity": specification of the requester by means of 1250 identity, role and organizational context. This data is provided 1251 to facilitate authorization and for auditing purposes. 1253 In this use case, the AS authenticates the requester, who is not the 1254 patient, and approves access based on policies. 1256 Appendix B. Document History 1258 [[ To be removed from the final specification ]] 1260 -00 (WG draft) 1262 o inital WG revision 1264 -03 1266 o Reworked examples to illustrate privacy preserving use of 1267 "authorization_details" 1269 o Added text on audience restriction 1271 o Added description of relationship between "scope" and 1272 "authorization_details" 1274 o Added text on token request & response and "authorization_details" 1276 o Added text on how authorization details are conveyed to RSs by 1277 JWTs or token endpoint response 1279 o Added description of relationship between "claims" and 1280 "authorization_details" 1282 o Added more example from different sectors 1284 o Clarified string comparison to be byte-exact without collation 1286 -02 1287 o Added Security Considerations 1289 o Added Privacy Considerations 1291 o Added notes on URI size and authorization details 1293 o Added requirement to return the effective authorization details 1294 granted by the resource owner in the token response 1296 o changed "authorization_details" structure from object to array 1298 o added Justin Richer & Brian Campbell as Co-Authors 1300 -00 / -01 1302 o first draft 1304 Authors' Addresses 1306 Torsten Lodderstedt 1307 yes.com 1309 Email: torsten@lodderstedt.net 1311 Justin Richer 1312 Bespoke Engineering 1314 Email: ietf@justin.richer.org 1316 Brian Campbell 1317 Ping Identity 1319 Email: bcampbell@pingidentity.com