idnits 2.17.00 (12 Aug 2021) /tmp/idnits1557/draft-ietf-oauth-rar-12.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: ---------------------------------------------------------------------------- == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- The document date (5 May 2022) is 9 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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: 6 November 2022 Bespoke Engineering 6 B. Campbell 7 Ping Identity 8 5 May 2022 10 OAuth 2.0 Rich Authorization Requests 11 draft-ietf-oauth-rar-12 13 Abstract 15 This document specifies a new parameter authorization_details that is 16 used to carry fine-grained authorization data in OAuth messages. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on 6 November 2022. 35 Copyright Notice 37 Copyright (c) 2022 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 42 license-info) in effect on the date of publication of this document. 43 Please review these documents carefully, as they describe your rights 44 and restrictions with respect to this document. Code Components 45 extracted from this document must include Revised BSD License text as 46 described in Section 4.e of the Trust Legal Provisions and are 47 provided without warranty as described in the Revised BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 4 53 2. Request parameter "authorization_details" . . . . . . . . . . 4 54 2.1. Authorization Details Types . . . . . . . . . . . . . . . 7 55 2.2. Common data fields . . . . . . . . . . . . . . . . . . . 8 56 3. Authorization Request . . . . . . . . . . . . . . . . . . . . 11 57 3.1. Relationship to "scope" parameter . . . . . . . . . . . . 13 58 3.2. Relationship to "resource" parameter . . . . . . . . . . 14 59 4. Authorization Response . . . . . . . . . . . . . . . . . . . 14 60 5. Authorization Error Response . . . . . . . . . . . . . . . . 14 61 6. Token Request . . . . . . . . . . . . . . . . . . . . . . . . 15 62 6.1. Comparing authorization details . . . . . . . . . . . . . 15 63 7. Token Response . . . . . . . . . . . . . . . . . . . . . . . 18 64 7.1. Enriched authorization details in Token Response . . . . 19 65 8. Token Error Response . . . . . . . . . . . . . . . . . . . . 22 66 9. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 23 67 9.1. JWT-based Access Tokens . . . . . . . . . . . . . . . . . 23 68 9.2. Token Introspection . . . . . . . . . . . . . . . . . . . 25 69 10. Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . 26 70 11. Implementation Considerations . . . . . . . . . . . . . . . . 27 71 11.1. Using authorization details in a certain deployment . . 27 72 11.2. Minimal product support . . . . . . . . . . . . . . . . 28 73 11.3. Use of Machine-readable Type Schemas . . . . . . . . . . 28 74 11.4. Large requests . . . . . . . . . . . . . . . . . . . . . 29 75 12. Security Considerations . . . . . . . . . . . . . . . . . . . 30 76 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 30 77 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 78 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 79 15.1. OAuth Parameters Registration . . . . . . . . . . . . . 31 80 15.2. JSON Web Token Claims Registration . . . . . . . . . . . 31 81 15.3. OAuth Token Introspection Response . . . . . . . . . . . 32 82 15.4. OAuth Authorization Server Metadata . . . . . . . . . . 32 83 15.5. OAuth Dynamic Client Registration Metadata . . . . . . . 32 84 15.6. OAuth Extensions Error registry . . . . . . . . . . . . 33 85 16. Normative References . . . . . . . . . . . . . . . . . . . . 33 86 17. Informative References . . . . . . . . . . . . . . . . . . . 33 87 Appendix A. Additional Examples . . . . . . . . . . . . . . . . 35 88 A.1. OpenID Connect . . . . . . . . . . . . . . . . . . . . . 35 89 A.2. Remote Electronic Signing . . . . . . . . . . . . . . . . 37 90 A.3. Access to Tax Data . . . . . . . . . . . . . . . . . . . 38 91 A.4. eHealth . . . . . . . . . . . . . . . . . . . . . . . . . 39 92 Appendix B. Document History . . . . . . . . . . . . . . . . . . 42 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 95 1. Introduction 97 The OAuth 2.0 authorization framework [RFC6749] defines the parameter 98 scope that allows OAuth clients to specify the requested scope, i.e., 99 the permission, of an access token. This mechanism is sufficient to 100 implement static scenarios and coarse-grained authorization requests, 101 such as "give me read access to the resource owner's profile" but it 102 is not sufficient to specify fine-grained authorization requirements, 103 such as "please let me transfer an amount of 45 Euros to Merchant A" 104 or "please give me read access to directory A and write access to 105 file X". 107 This specification introduces a new parameter authorization_details 108 that allows clients to specify their fine-grained authorization 109 requirements using the expressiveness of JSON data structures. 111 For example, an authorization request for a credit transfer 112 (designated as "payment initiation" in several open banking 113 initiatives) can be represented using a JSON object like this: 115 { 116 "type": "payment_initiation", 117 "locations": [ 118 "https://example.com/payments" 119 ], 120 "instructedAmount": { 121 "currency": "EUR", 122 "amount": "123.50" 123 }, 124 "creditorName": "Merchant A", 125 "creditorAccount": { 126 "iban": "DE02100100109307118603" 127 }, 128 "remittanceInformationUnstructured": "Ref Number Merchant" 129 } 131 Figure 1: Example authorization request for a credit transfer. 133 This object contains detailed information about the intended payment, 134 such as amount, currency, and creditor, that are required to inform 135 the user and obtain her consent. The AS and the respective RS 136 (providing the payment initiation API) will together enforce this 137 consent. 139 For a comprehensive discussion of the challenges arising from new use 140 cases in the open banking and electronic signing spaces see 141 [transaction-authorization]. 143 In addition to facilitating custom authorization requests, this 144 specification also introduces a set of common data type fields for 145 use across different APIs. 147 1.1. Conventions and Terminology 149 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 150 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 151 "OPTIONAL" in this document are to be interpreted as described in BCP 152 14 [RFC2119] [RFC8174] when, and only when, they appear in all 153 capitals, as shown here. 155 This specification uses the terms "access token", "refresh token", 156 "authorization server", "resource server", "authorization endpoint", 157 "authorization request", "authorization response", "token endpoint", 158 "grant type", "access token request", "access token response", and 159 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 161 2. Request parameter "authorization_details" 163 The request parameter authorization_details contains, in JSON 164 notation, an array of objects. Each JSON object contains the data to 165 specify the authorization requirements for a certain type of 166 resource. The type of resource or access requirement is determined 167 by the type field, which is defined as follow: 169 type: The type of authorization details as a string. The value of 170 the type field determines the allowable contents of the object 171 which contains it. This field is REQUIRED. 173 This field MUST be compared using an exact byte match of the string 174 value against known types by the AS. The AS MUST ensure that there 175 is no collision between different authorization details types that it 176 supports. The AS MUST NOT do any collation or normalization of data 177 types during comparison. 179 An authorization_details array MAY contain multiple entries of the 180 same type. 182 This example shows the specification of authorization details of type 183 payment_initiation using the example data shown above: 185 [ 186 { 187 "type": "payment_initiation", 188 "actions": [ 189 "initiate", 190 "status", 191 "cancel" 192 ], 193 "locations": [ 194 "https://example.com/payments" 195 ], 196 "instructedAmount": { 197 "currency": "EUR", 198 "amount": "123.50" 199 }, 200 "creditorName": "Merchant A", 201 "creditorAccount": { 202 "iban": "DE02100100109307118603" 203 }, 204 "remittanceInformationUnstructured": "Ref Number Merchant" 205 } 206 ] 208 Figure 2: Example authorization details for a credit transfer. 210 This example shows a combined request asking for access to account 211 information and permission to initiate a payment: 213 [ 214 { 215 "type": "account_information", 216 "actions": [ 217 "list_accounts", 218 "read_balances", 219 "read_transactions" 220 ], 221 "locations": [ 222 "https://example.com/accounts" 223 ] 224 }, 225 { 226 "type": "payment_initiation", 227 "actions": [ 228 "initiate", 229 "status", 230 "cancel" 231 ], 232 "locations": [ 233 "https://example.com/payments" 234 ], 235 "instructedAmount": { 236 "currency": "EUR", 237 "amount": "123.50" 238 }, 239 "creditorName": "Merchant A", 240 "creditorAccount": { 241 "iban": "DE02100100109307118603" 242 }, 243 "remittanceInformationUnstructured": "Ref Number Merchant" 244 } 245 ] 247 Figure 3: Example authorization details for a combined request. 249 The JSON objects with type fields of account_information and 250 payment_initiation represent the different authorization details to 251 be used by the AS to ask for consent. 253 Note: The AS will make this data subsequently available to the 254 respective resource servers (see Section 9). 256 2.1. Authorization Details Types 258 Interpretation of the value of the type parameter, and the object 259 fields that the type parameter allows, is under the control of the 260 AS. However, the value of the type parameter is also generally 261 documented and intended to be used by developers, it is RECOMMENDED 262 that API designers choose type values that are easily copied without 263 ambiguity. For example, some glyphs have multiple Unicode code 264 points for the same visual character, and a developer could 265 potentially type a different character than what the AS has defined. 266 Possible means of reducing potential confusion are limiting the value 267 to ASCII characters, providing a machine-readable listing of data 268 type values, or instructing developers to copy and paste directly 269 from the documentation. 271 If an application or API is expected to be deployed across different 272 servers, such as the case in an open standard, the API designer is 273 RECOMMENDED to use a collision-resistant namespace under their 274 control, such as a URI that the API designer controls. 276 The following example shows how an implementation could utilize the 277 namespace https://scheme.example.org/ to ensure collision-resistant 278 type values. 280 { 281 "type": "https://scheme.example.org/files", 282 "locations": [ 283 "https://example.com/files" 284 ], 285 "permissions": [ 286 { 287 "path": "/myfiles/A", 288 "access": [ 289 "read" 290 ] 291 }, 292 { 293 "path": "/myfiles/A/X", 294 "access": [ 295 "read", 296 "write" 297 ] 298 } 299 ] 300 } 302 Figure 4: Example for authorization details with a URL as type 303 identifier. 305 2.2. Common data fields 307 This specification defines a set of common data fields that are 308 designed to be usable across different types of APIs. These data 309 fields MAY be combined in different ways depending on the needs of 310 the API. All data fields are OPTIONAL for use by a given API 311 definition. The allowable values of all fields are determined by the 312 API being protected. 314 locations: An array of strings representing the location of the 315 resource or resource server. These strings are typically URIs 316 identifying the location of the RS. This field can allow a client 317 to specify a particular RS, as discussed in Section 12. 318 actions: An array of strings representing the kinds of actions to be 319 taken at the resource. 320 datatypes: An array of strings representing the kinds of data being 321 requested from the resource. 322 identifier: A string identifier indicating a specific resource 323 available at the API. 324 privileges: An array of strings representing the types or levels of 325 privilege being requested at the resource. 327 When different common data fields are used in combination, the 328 permissions the client requests is the cartesian product of the 329 values. That is to say, the object represents a request for all 330 action values listed within the object to be used at all locations 331 values listed within the object for all datatype values listed within 332 the object. In the following example, the client is requesting read 333 and write access to both the contacts and photos belonging to 334 customers in a customer_information API. If this request is granted, 335 the client would assume it would be able to use any combination of 336 rights defined by the API, such as reading the photos and writing the 337 contacts. 339 [ 340 { 341 "type": "customer_information", 342 "locations": [ 343 "https://example.com/customers" 344 ], 345 "actions": [ 346 "read", 347 "write" 348 ], 349 "datatypes": [ 350 "contacts", 351 "photos" 352 ] 353 } 354 ] 356 Figure 5: Example for authorization details with common data fields. 358 If the client wishes to have finer control over its access, it can 359 send multiple objects. In this example, the client is asking for 360 read access to the contacts and write access to the photos in the 361 same API endpoint. If this request is granted, the client would not 362 be able to write to the contacts. 364 [ 365 { 366 "type": "customer_information", 367 "locations": [ 368 "https://example.com/customers" 369 ], 370 "actions": [ 371 "read" 372 ], 373 "datatypes": [ 374 "contacts" 375 ] 376 }, 377 { 378 "type": "customer_information", 379 "locations": [ 380 "https://example.com/customers" 381 ], 382 "actions": [ 383 "write" 384 ], 385 "datatypes": [ 386 "photos" 387 ] 388 } 389 ] 391 Figure 6: Example for authorization details with common data 392 fields in multiple objects. 394 An API MAY define its own extensions, subject to the type of the 395 respective authorization object. It is anticipated that API 396 designers will use a combination of common data fields defined in 397 this specification as well as fields specific to the API itself. The 398 following non-normative example shows the use of both common and API- 399 specific fields as part of two different fictitious API type values. 400 The first access request includes the actions, locations, and 401 datatypes fields specified here as well as the API-specific 402 geolocation field. The second access request includes the actions 403 and identifier fields specified here as well as the API-specific 404 currency fields. 406 [ 407 { 408 "type":"photo-api", 409 "actions":[ 410 "read", 411 "write" 412 ], 413 "locations":[ 414 "https://server.example.net/", 415 "https://resource.local/other" 416 ], 417 "datatypes":[ 418 "metadata", 419 "images" 420 ], 421 "geolocation":[ 422 { 423 "lat":-32.364, 424 "lng":153.207 425 }, 426 { 427 "lat":-35.364, 428 "lng":158.207 429 } 430 ] 431 }, 432 { 433 "type":"financial-transaction", 434 "actions":[ 435 "withdraw" 436 ], 437 "identifier":"account-14-32-32-3", 438 "currency":"USD" 439 } 440 ] 442 Figure 7: Example for authorization details using common and 443 extension data fields. 445 If this request is approved, the resulting access token's access 446 rights will be the union of the requested types of access for each of 447 the two APIs, just as above. 449 3. Authorization Request 451 The authorization_details authorization request parameter can be used 452 to specify authorization requirements in all places where the scope 453 parameter is used for the same purpose, examples include: 455 * Authorization requests as specified in [RFC6749], 456 * Device Authorization Request as specified in [RFC8628], 457 * Backchannel Authentication Requests as defined in [OpenID.CIBA]. 459 In case of authorization requests as defined in [RFC6749], 460 implementors MAY consider to use pushed authorization requests 461 [RFC9126] to improve to security, privacy, and reliability of the 462 flow. See Section 12, Section 13, and Section 11.4 for details. 464 Parameter encoding is determined by the respective context. In the 465 context of an authorization request according to [RFC6749], the 466 parameter is encoded using the application/x-www-form-urlencoded 467 format of the serialized JSON as shown in the following using the 468 example from Section 2 (line breaks for display purposes only): 470 GET /authorize?response_type=code 471 &client_id=s6BhdRkqt3 472 &state=af0ifjsldkj 473 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 474 &code_challenge_method=S256 475 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U 476 &authorization_details=%5B%7B%22type%22%3A%22account%5Finfo 477 rmation%22%2C%22actions%22%3A%5B%22list%5Faccounts%22%2C%22 478 read%5Fbalances%22%2C%22read%5Ftransactions%22%5D%2C%22loca 479 tions%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Faccounts%22% 480 5D%7D%2C%7B%22type%22%3A%22payment%5Finitiation%22%2C%22act 481 ions%22%3A%5B%22initiate%22%2C%22status%22%2C%22cancel%22%5 482 D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Fp 483 ayments%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22% 484 3A%22EUR%22%2C%22amount%22%3A%22123%2E50%22%7D%2C%22credito 485 rName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B% 486 22iban%22%3A%22DE02100100109307118603%22%7D%2C%22remittance 487 InformationUnstructured%22%3A%22RefNumberMerchant%22%7D%5D HTTP/1.1 488 Host: server.example.com 490 Figure 8: Example authorization request with authorization_details. 492 Based on the data provided in the authorization_details parameter the 493 AS will ask the user for consent to the requested access permissions. 495 Note: the user may also grant a subset of the requested authorization 496 details. 498 In this example, the client wants to get access to account 499 information and intiate a payment: 501 [ 502 { 503 "type": "account_information", 504 "actions": [ 505 "list_accounts", 506 "read_balances", 507 "read_transactions" 508 ], 509 "locations": [ 510 "https://example.com/accounts" 511 ] 512 }, 513 { 514 "type": "payment_initiation", 515 "actions": [ 516 "initiate", 517 "status", 518 "cancel" 519 ], 520 "locations": [ 521 "https://example.com/payments" 522 ], 523 "instructedAmount": { 524 "currency": "EUR", 525 "amount": "123.50" 526 }, 527 "creditorName": "Merchant A", 528 "creditorAccount": { 529 "iban": "DE02100100109307118603" 530 }, 531 "remittanceInformationUnstructured": "Ref Number Merchant" 532 } 533 ] 535 Figure 9: URL decoded authorization details. 537 3.1. Relationship to "scope" parameter 539 authorization_details and scope can be used in the same authorization 540 request for carrying independent authorization requirements. 542 Combined use of authorization_details and scope is supported by this 543 specification in part to allow existing OAuth-based applications to 544 incrementally migrate towards using authorization_details 545 exclusively. It is RECOMMENDED that a given API use only one form of 546 requirement specification. 548 The AS MUST consider both sets of requirements in combination with 549 each other for the given authorization request. The details of how 550 the AS combines these parameters are specific to the APIs being 551 protected and outside the scope of this specification. 553 When gathering user consent, the AS MUST present the merged set of 554 requirements represented by the authorization request. 556 If the resource owner grants the client the requested access, the AS 557 will issue tokens to the client that are associated with the 558 respective authorization_details (and scope values, if applicable). 560 3.2. Relationship to "resource" parameter 562 The resource authorization request parameter as defined in [RFC8707] 563 can be used to further determine the resources where the requested 564 scope can be applied. The resource parameter does not have any 565 impact on the way the AS processes the authorization_details 566 authorization request parameter. 568 4. Authorization Response 570 This specification does not define extensions to the authorization 571 response. 573 5. Authorization Error Response 575 The AS MUST refuse to process any unknown authorization details type 576 or authorization details not conforming to the respective type 577 definition. The AS MUST abort processing and respond with an error 578 invalid_authorization_details to the client if any of the following 579 are true of any of the objects in authorization_details structure: 581 * Contains an unknown authorization details type value, 582 * An object of known type but containing unknown fields, 583 * Contains fields of the wrong type for the authorization details 584 type, 585 * Contains fields with invalid values for the authorization details 586 type, or 587 * Missing required fields for the authorization details type. 589 6. Token Request 591 The authorization_details token request parameter can be used to 592 specify the authorization details a client wants the AS to assign to 593 an access token. The AS checks whether the underlying grant (in case 594 of grant types authorization_code, refresh_token, ...) or the 595 client's policy (in case of grant type client_credential) allows the 596 issuance of an access token with the requested authorization details. 597 Otherwise, the AS refuses the request with the error code 598 invalid_authorization_details (similar to invalid_scope). 600 6.1. Comparing authorization details 602 Many actions in the OAuth protocol allow the AS and RS to make 603 security decisions based on whether or not the request is asking for 604 "more" or "less" than a previous, existing request. For example, 605 upon refreshing a token, the client can ask for a new access token 606 with "fewer permissions" than had been previously authorized by the 607 resource owner. Since the nature of an authorization details request 608 is based solely on the API or APIs that it is describing, there is 609 not a simple means of comparing any two arbitrary authorization 610 details requests. Authorization servers should not rely on simple 611 object comparison in most cases, as the intersection of some fields 612 within a request could have side effects on the access rights 613 granted, depending on how the API has been designed and deployed. 614 This is a similar effect to the scope values used with some APIs. 616 However, when comparing a new request to an existing request, 617 authorization servers can use the same processing techniques as used 618 in granting the request in the first place to determine if a resource 619 owner needs to authorize the request. The details of this comparison 620 are dependent on the definition of the type of authorization request 621 and outside the scope of this specification, but common patterns can 622 be applied. 624 This shall be illustrated using our running example. The example 625 authorization request in Section 3, if approved by the user, resulted 626 in the issuance of an authorization code associated with the 627 privileges to 629 * list accounts 630 * access the balance of one or more accounts, 631 * access the transactions of one or more accounts, and 632 * to initiate a payment. 634 The client could now request the AS to issue an access token assigned 635 with the privilege to just access a list of accounts as follows: 637 [ 638 { 639 "type": "account_information", 640 "actions": [ 641 "list_accounts" 642 ], 643 "locations": [ 644 "https://example.com/accounts" 645 ] 646 } 647 ] 649 Figure 10: Example for authorization details reduced privileges. 651 The example API is designed such that each field used by the 652 account_information type contains additive rights, with each value 653 within the actions and locations arrays specifying a different 654 element of access. To make a comparison in this instance, the AS 655 would perform the following steps: 657 * compare that the authorization code issued in the previous step 658 contains an authorization details object of type 659 account_information 660 * compare whether the approved list of actions contains 661 list_account, and 662 * whether the locations value includes only previously-approved 663 locations. 665 If all checks succeed, the AS would issue the requested access token 666 with the reduced set of access. 668 Note that this comparison is relevant to this specific API type 669 definition. A different API type definition could have different 670 processing rules. For example, the value of an action could subsume 671 the rights associated with another action value. For example, if a 672 client initially asks for a token with write access, which implies 673 both read and write access to this API: 675 [ 676 { 677 "type": "example_api", 678 "actions": [ 679 "write" 680 ] 681 } 682 ] 683 Figure 11: Example for authorization details requesting "write" 684 access to an API. 686 Later that same client makes a refresh request for read access: 688 [ 689 { 690 "type": "example_api", 691 "actions": [ 692 "read" 693 ] 694 } 695 ] 697 Figure 12: Example for authorization details requesting "read" 698 access to an API. 700 The AS would compare the type value and the action value to determine 701 that the read access is already covered by the write access 702 previously granted to the client. 704 This same API could be designed with a possible value for privileges 705 of admin, used in this example to denote that the resulting token is 706 allowed to perform any functions on the resources. If that client is 707 then granted such admin privileges to the API: 709 [ 710 { 711 "type": "example_api", 712 "privileges": [ 713 "admin" 714 ] 715 } 716 ] 718 Figure 13: Example for authorization details requesting "admin" 719 access to an API. 721 The AS would compare the type value and find the privileges value 722 subsumes any aspects of read or write access that had been granted to 723 the client previously. Note that other API definitions can use 724 privileges in a non-subsuming fashion. 726 The next example shows how the client can use the common data element 727 locations (see Section 2.2) to request the isaunce of an access token 728 restricted to a certain resource server. In our running example, the 729 client may ask for all permissions of the approved grant of type 730 payment_iniation applicable to the resource server residing at 731 https://example.com/payments as follows: 733 [ 734 { 735 "type": "payment_initiation", 736 "locations": [ 737 "https://example.com/payments" 738 ] 739 } 740 ] 742 Figure 14: Example for authorization details requesting an 743 audience restricted access token. 745 7. Token Response 747 In addition to the token response parameters as defined in [RFC6749], 748 the authorization server MUST also return the authorization details 749 as granted by the resource owner and assigned to the respective 750 access token. 752 The authorization details assigned to the access token issued in a 753 token response are determined by the authorization_details parameter 754 of the corresponding token request. If the client does not specify 755 the authorization_details token request parameters, the AS determines 756 the resulting authorization details at its discretion. The 757 authorization server MAY consider the values of other parameters such 758 as resource and scope if they are present during this processing, and 759 the details of such considerations are outside the scope of this 760 specification. 762 The AS MAY omit values in the authorization_details to the client in 763 the token Response if these are deemed of no intended use for the 764 client. 766 For our running example, this would look like this: 768 HTTP/1.1 200 OK 769 Content-Type: application/json 770 Cache-Control: no-store 772 { 773 "access_token": "2YotnFZFEjr1zCsicMWpAA", 774 "token_type": "example", 775 "expires_in": 3600, 776 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 777 "authorization_details": [ 778 { 779 "type": "https://scheme.example.com/payment_initiation", 780 "actions": [ 781 "initiate", 782 "status", 783 "cancel" 784 ], 785 "locations": [ 786 "https://example.com/payments" 787 ], 788 "instructedAmount": { 789 "currency": "EUR", 790 "amount": "123.50" 791 }, 792 "creditorName": "Merchant A", 793 "creditorAccount": { 794 "iban": "DE02100100109307118603" 795 }, 796 "remittanceInformationUnstructured": "Ref Number Merchant" 797 } 798 ] 799 } 801 Figure 15: Example token response. 803 7.1. Enriched authorization details in Token Response 805 The authorization details attached to the access token MAY differ 806 from what the client requests. In addition to the user authorizing 807 less than what the client requested, there are use cases where the 808 authorization server enriches the data in an authorization details 809 object. For example, a client may ask for access to account 810 information but leave the decision about the accounts it will be able 811 to access to the user. The user would select the sub set of accounts 812 they want the client to entitle to access in the course of the 813 authorization process. As one design option to convey the selected 814 accounts, the authorization server could add this information to the 815 respective authorization details object. 817 As an example, the requested authorization detail parameter could 818 look like this: 820 "authorization_details": [ 821 { 822 "type": "account_information", 823 "access": { 824 "accounts": [], 825 "balances": [], 826 "transactions": [] 827 }, 828 "recurringIndicator":true 829 } 830 ] 832 Figure 16: Example for requested authorization details. 834 The authorization server then would expand the authorization details 835 object and add the respective account identifiers. 837 HTTP/1.1 200 OK 838 Content-Type: application/json 839 Cache-Control: no-store 841 { 842 "access_token":"2YotnFZFEjr1zCsicMWpAA", 843 "token_type":"example", 844 "expires_in":3600, 845 "refresh_token":"tGzv3JokF0XG5Qx2TlKWIA", 846 "authorization_details":[ 847 { 848 "type":"account_information", 849 "access":{ 850 "accounts":[ 851 { 852 "iban":"DE2310010010123456789" 853 }, 854 { 855 "maskedPan":"123456xxxxxx1234" 856 } 857 ], 858 "balances":[ 859 { 860 "iban":"DE2310010010123456789" 861 } 862 ], 863 "transactions":[ 864 { 865 "iban":"DE2310010010123456789" 866 }, 867 { 868 "maskedPan":"123456xxxxxx1234" 869 } 870 ] 871 }, 872 "recurringIndicator":true 873 } 874 ] 875 } 877 Figure 17: Example for enriched authorization details. 879 For another example, the client is asking for access to a medical 880 record but does not know the record number at request time. In this 881 example, the client specifies the type of access it wants but doesn't 882 specify the location or identifier of that access. 884 { 885 "authorization_details": [ 886 { 887 "type": "medical_record", 888 "sens": [ "HIV", "ETH", "MART" ], 889 "actions": [ "read" ], 890 "datatypes": [ "Patient", "Observation", "Appointment" ] 891 } 892 ]} 894 Figure 18: Example for requested authorization details. 896 When the user interacts with the AS, they select which of the medical 897 records they are responsible for giving to the client. This 898 information gets returned with the access token. 900 { 901 "access_token":"2YotnFZFEjr1zCsicMWpAA", 902 "token_type":"example", 903 "expires_in":3600, 904 "refresh_token":"tGzv3JokF0XG5Qx2TlKWIA", 905 "authorization_details":[ 906 { 907 "type": "medical_record", 908 "sens": [ "HIV", "ETH", "MART" ], 909 "actions": [ "read" ], 910 "datatypes": [ "Patient", "Observation", "Appointment" ], 911 "identifier": "patient-541235", 912 "locations": [ "https://records.example.com/" ] 913 } 914 ] 915 } 917 Figure 19: Example for enriched authorization details. 919 Note: the client needs to be aware upfront of the possibility that a 920 certain authorization details object can be enriched. It is assumed 921 that this property is part of the definition of the respective 922 authorization details type. 924 8. Token Error Response 926 The AS MUST refuse to process any unknown authorization details type 927 or authorization details not conforming to the respective type 928 definition. If any of the objects in authorization_details contains 929 an unknown authorization details type or an object of known type but 930 containing unknown fields or fields of the wrong type, fields with 931 invalid values, or if required fields are missing, the AS MUST abort 932 processing and respond with an error invalid_authorization_details to 933 the client. 935 9. Resource Servers 937 In order to enable the RS to enforce the authorization details as 938 approved in the authorization process, the AS MUST make this data 939 available to the RS. The AS MAY add the authorization_details field 940 to access tokens in JWT format or to Token Introspection responses. 942 9.1. JWT-based Access Tokens 944 If the access token is a JWT [RFC7519], the AS is RECOMMENDED to add 945 the authorization_details object, filtered to the specific audience, 946 as a top-level claim. 948 The AS will typically also add further claims to the JWT the RS 949 requires for request processing, e.g., user id, roles, and 950 transaction-specific data. What claims the particular RS requires is 951 defined by the RS-specific policy with the AS. 953 The following shows the contents of an example JWT for the payment 954 initiation example above: 956 { 957 "iss": "https://as.example.com", 958 "sub": "24400320", 959 "aud": "a7AfcPcsl2", 960 "exp": 1311281970, 961 "acr": "psd2_sca", 962 "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296", 963 "authorization_details": [ 964 { 965 "type": "https://scheme.example.com/payment_initiation", 966 "actions": [ 967 "initiate", 968 "status", 969 "cancel" 970 ], 971 "locations": [ 972 "https://example.com/payments" 973 ], 974 "instructedAmount": { 975 "currency": "EUR", 976 "amount": "123.50" 977 }, 978 "creditorName": "Merchant A", 979 "creditorAccount": { 980 "iban": "DE02100100109307118603" 981 }, 982 "remittanceInformationUnstructured": "Ref Number Merchant" 983 } 984 ], 985 "debtorAccount": { 986 "iban": "DE40100100103307118608", 987 "user_role": "owner" 988 } 989 } 991 Figure 20: Example for authorization details in JWT-based access 992 token. 994 In this case, the AS added the following example claims to the JWT- 995 based access token: 997 * sub: conveys the user on which behalf the client is asking for 998 payment initiation 999 * txn: transaction id used to trace the transaction across the 1000 services of provider example.com 1001 * debtorAccount: API-specific field containing the debtor account. 1002 In the example, this account was not passed in the authorization 1003 details but selected by the user during the authorization process. 1005 The field user_role conveys the role the user has with respect to 1006 this particular account. In this case, they are the owner. This 1007 data is used for access control at the payment API (the RS). 1009 9.2. Token Introspection 1011 Token introspection [!@RFC7662] provides a means for an RS to inquire 1012 to the AS what a given access token is good for. The token 1013 introspection response provides the RS with the authorization details 1014 applicable to it as a top-level JSON element along with the claims 1015 the RS requires for request processing. The authorization_details 1016 member contains the same structure defined in Section 2, potentially 1017 filtered and extended for the RS making the introspection request. 1019 Here is an example for the payment initiation example RS: 1021 { 1022 "active": true, 1023 "sub": "24400320", 1024 "aud": "s6BhdRkqt3", 1025 "exp": 1311281970, 1026 "acr": "psd2_sca", 1027 "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296", 1028 "authorization_details": [ 1029 { 1030 "type": "https://scheme.example.com/payment_initiation", 1031 "actions": [ 1032 "initiate", 1033 "status", 1034 "cancel" 1035 ], 1036 "locations": [ 1037 "https://example.com/payments" 1038 ], 1039 "instructedAmount": { 1040 "currency": "EUR", 1041 "amount": "123.50" 1042 }, 1043 "creditorName": "Merchant123", 1044 "creditorAccount": { 1045 "iban": "DE02100100109307118603" 1046 }, 1047 "remittanceInformationUnstructured": "Ref Number Merchant" 1048 } 1049 ], 1050 "debtorAccount": { 1051 "iban": "DE40100100103307118608", 1052 "user_role": "owner" 1053 } 1054 } 1056 Figure 21: Example for authorization details in introspection 1057 response. 1059 10. Metadata 1061 The AS publishes the list of authorization details types it supports 1062 using the metadata parameter authorization_details_types_supported, 1063 which is a JSON array. 1065 This is illustrated by the following example: 1067 { 1068 ... 1069 "authorization_details_types_supported":[ 1070 "payment_initiation", 1071 "account_information" 1072 ] 1073 } 1075 Figure 22: Example for server metadata about authorization details. 1077 Clients announce the authorization details types they use in the new 1078 dynamic client registration parameter authorization_details_types. 1080 This is illustrated by the following example: 1082 { 1083 ... 1084 "authorization_details_types":[ 1085 "payment_initiation" 1086 ] 1087 } 1089 Figure 23: Example for server metadata about authorization details. 1091 The registration of authorization details types with the AS is out of 1092 scope of this specification. 1094 11. Implementation Considerations 1096 11.1. Using authorization details in a certain deployment 1098 Using authorization details in a certain deployment will require the 1099 following steps: 1101 * Define authorization details types 1102 * Publish authorization details types in the OAuth server metadata 1103 * Determine how authorization details are shown to the user in the 1104 user consent 1105 * (if needed) Enrich authorization details in the user consent 1106 process (e.g. add selected accounts or set expirations) 1107 * (if needed) Determine how authorization details are reflected in 1108 access token content or introspection responses 1109 * Determine how the resource server(s) process(s) the authorization 1110 details or token data derived from authorization details 1112 11.2. Minimal product support 1114 Products supporting this specification should provide the following 1115 basic functions: 1117 * Support advertisement of supported authorization details types in 1118 OAuth server metadata 1119 * Accept authorization_details parameter in authorization requests 1120 including basic syntax check for compliance with this 1121 specification 1122 * Support storage of consented authorization details as part of a 1123 grant 1124 * Implement default behavior for adding authorization details to 1125 access tokens and token introspection responses in order to make 1126 them available to resource servers (similar to scope values). 1127 This should work with any grant type, especially 1128 authorization_code and refresh_token. 1130 Processing and presentation of authorization details will vary 1131 significantly among different authorization details types. Products 1132 should therefore support customization of the respective behavior. 1133 In particular, products should 1135 * allow deployments to determine presentation of the authorization 1136 details 1137 * allow deployments to modify requested authorization details in the 1138 user consent process, e.g. adding fields 1139 * allow deployments to merge requested and pre-existing 1140 authorization details 1142 One option would be to have a mechanism allowing the registration of 1143 extension modules, each of them responsible for rendering the 1144 respective user consent and any transformation needed to provide the 1145 data needed to the resource server by way of structured access tokens 1146 or token introspection responses. 1148 11.3. Use of Machine-readable Type Schemas 1150 Products might allow deployments to use machine-readable schema 1151 languages for defining authorization details types to facilitate 1152 creating and validating authorization details objects against such 1153 schemas. For example, if an authorization details type were defined 1154 using JSON Schemas [JSON.Schema], the JSON schema id could be used as 1155 type value in the respective authorization details objects. 1157 Note however that type values are identifiers understood by the AS 1158 and, to the extent necessary, the client and RS. This specification 1159 makes no assumption that a type value point to a machine-readable 1160 schema format, or that any party in the system (such as the client, 1161 AS, or RS) dereference or process the contents of the type field in 1162 any specific way. 1164 11.4. Large requests 1166 Authorization request URIs containing authorization details in a 1167 request parameter or a request object can become very long. 1168 Implementers should therefore consider using the request_uri 1169 parameter as defined in [RFC9101] in combination with the pushed 1170 request object mechanism as defined in [RFC9126] to pass 1171 authorization details in a reliable and secure manner. Here is an 1172 example of such a pushed authorization request that sends the 1173 authorization request data directly to the AS via an HTTPS-protected 1174 connection: 1176 POST /as/par HTTP/1.1 1177 Host: as.example.com 1178 Content-Type: application/x-www-form-urlencoded 1179 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 1181 response_type=code& 1182 client_id=s6BhdRkqt3 1183 &state=af0ifjsldkj 1184 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 1185 &code_challenge_method=S256 1186 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U 1187 &authorization_details=%5B%7B%22type%22%3A%22account_information%22 1188 %2C%22actions%22%3A%5B%22list_accounts%22%2C%22read_balances%22%2C% 1189 22read_transactions%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fe 1190 xample.com%2Faccounts%22%5D%7D%2C%7B%22type%22%3A%22payment_initiat 1191 ion%22%2C%22actions%22%3A%5B%22initiate%22%2C%22status%22%2C%22canc 1192 el%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpaym 1193 ents%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22EUR%22 1194 %2C%22amount%22%3A%22123.50%22%7D%2C%22creditorName%22%3A%22Merchan 1195 t123%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE021001001093 1196 07118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%2 1197 0Number%20Merchant%22%7D%5D 1199 Figure 24: Example for large request including authorization details. 1201 12. Security Considerations 1203 Authorization details are sent through the user agent in case of an 1204 OAuth authorization request, which makes them vulnerable to 1205 modifications by the user. If integrity of the authorization details 1206 is a concern, clients MUST protect authorization details against 1207 tampering and swapping. This can be achieved by signing the request 1208 using signed request objects as defined in [RFC9101] or using the 1209 request_uri authorization request parameter as defined in [RFC9101] 1210 in conjunction with [RFC9126] to pass the URI of the request object 1211 to the authorization server. 1213 All strings MUST be compared using the exact byte representation of 1214 the characters as defined by [RFC8259]. This is especially true for 1215 the type field, which dictates which other fields and functions are 1216 allowed in the request. The server MUST NOT perform any form of 1217 collation, transformation, or equivalence on the string values. 1219 The common data field locations allows a client to specify where it 1220 intends to use a certain authorization, i.e., it is possible to 1221 unambiguously assign permissions to resource servers. In situations 1222 with multiple resource servers, this prevents unintended client 1223 authorizations (e.g. a read scope value potentially applicable for an 1224 email as well as a cloud service) through audience restriction. 1226 13. Privacy Considerations 1228 Implementers MUST design and use authorization details in a privacy- 1229 preserving manner. 1231 Any sensitive personal data included in authorization details MUST be 1232 prevented from leaking, e.g., through referrer headers. 1233 Implementation options include encrypted request objects as defined 1234 in [RFC9101] or transmission of authorization details via end-to-end 1235 encrypted connections between client and authorization server by 1236 utilizing [RFC9126] and the request_uri authorization request 1237 parameter as defined in [RFC9101]. The latter does not require 1238 application level encryption but it requires another message exchange 1239 between client and AS. 1241 Even if the request data is encrypted, an attacker could use the 1242 authorization server to learn the user data by injecting the 1243 encrypted request data into an authorization request on a device 1244 under his control and use the authorization server's user consent 1245 screens to show the (decrypted) user data in the clear. 1246 Implementations MUST consider this attacker vector and implement 1247 appropriate countermeasures, e.g. by only showing portions of the 1248 data or, if possible, determining whether the assumed user context is 1249 still the same (after user authentication). 1251 The AS MUST take into consideration the privacy implications when 1252 sharing authorization details with the client or resource servers. 1253 The AS SHOULD share this data with those parties on a "need to know" 1254 basis. 1256 14. Acknowledgements 1258 We would like to thank Daniel Fett, Sebastian Ebling, Dave Tonge, 1259 Mike Jones, Nat Sakimura, and Rob Otto for their valuable feedback 1260 during the preparation of this specification. 1262 We would also like to thank Vladimir Dzhuvinov, Takahiko Kawasaki, 1263 Daniel Fett, Dave Tonge, Travis Spencer, Joergen Binningsboe, Aamund 1264 Bremer, Steinar Noem, Francis Pouatcha, Jacob Ideskog, Hannes 1265 Tschofenig, and Aaron Parecki for their valuable feedback to this 1266 specification. 1268 15. IANA Considerations 1270 15.1. OAuth Parameters Registration 1272 This specification requests registration of the following parameter 1273 in the "OAuth Parameters" registry [IANA.OAuth.Parameters] 1274 established by [RFC6749]. 1276 Name: authorization_details 1277 Parameter Usage Location: authorization request, token request, 1278 token response 1279 Change Controller: IESG 1280 Specification Document(s): this document 1282 15.2. JSON Web Token Claims Registration 1284 This specification requests registration of the following value in 1285 the IANA "JSON Web Token Claims Registry" established by [RFC7519]. 1287 Claim Name: authorization_details 1288 Claim Description: The claim authorization_details contains a JSON 1289 array of JSON objects representing the rights of the access token. 1290 Each JSON object contains the data to specify the authorization 1291 requirements for a certain type of resource. 1292 Change Controller: IESG 1293 Specification Document(s): Section 9.1 of this document 1295 15.3. OAuth Token Introspection Response 1297 This specification requests registration of the following value in 1298 the IANA "OAuth Token Introspection Response Registry" established by 1299 [RFC7662]. 1301 Name: authorization_details 1302 Description: The member authorization_details contains a JSON array 1303 of JSON objects representing the rights of the access token. Each 1304 JSON object contains the data to specify the authorization 1305 requirements for a certain type of resource. 1306 Change Controller: IESG 1307 Specification Document(s): Section 9.2 of this document 1309 15.4. OAuth Authorization Server Metadata 1311 This specification requests registration of the following values in 1312 the IANA "OAuth Authorization Server Metadata" registry of 1313 [IANA.OAuth.Parameters] established by [RFC8414]. 1315 Metadata Name: authorization_details_types_supported 1316 Metadata Description: JSON array containing the authorization 1317 details types the AS supports 1318 Change Controller: IESG 1319 Specification Document(s): Section 10 of [[ this document ]] 1321 15.5. OAuth Dynamic Client Registration Metadata 1323 This specification requests registration of the following value in 1324 the IANA "OAuth Dynamic Client Registration Metadata" registry of 1325 [IANA.OAuth.Parameters] established by [RFC7591]. 1327 Metadata Name: authorization_details_types 1328 Metadata Description: Indicates what authorization details types the 1329 client uses. 1330 Change Controller: IESG 1331 Specification Document(s): Section 10 of [[ this document ]] 1333 15.6. OAuth Extensions Error registry 1335 This specification requests registration of the following value in 1336 the IANA "OAuth Extensions Error registry" registry of 1337 [IANA.OAuth.Parameters] established by [RFC6749]. 1339 Metadata Name: invalid_authorization_details 1340 Metadata Description: indicates invalid 1341 authorization_details_parameterto the client. 1342 Change Controller: IESG 1343 Specification Document(s): Section 5 of [[ this document ]] 1345 16. Normative References 1347 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1348 Requirement Levels", BCP 14, RFC 2119, 1349 DOI 10.17487/RFC2119, March 1997, 1350 . 1352 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1353 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1354 . 1356 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1357 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1358 . 1360 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1361 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1362 May 2017, . 1364 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1365 Authorization Server Metadata", RFC 8414, 1366 DOI 10.17487/RFC8414, June 2018, 1367 . 1369 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 1370 "OAuth 2.0 Device Authorization Grant", RFC 8628, 1371 DOI 10.17487/RFC8628, August 2019, 1372 . 1374 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 1375 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 1376 February 2020, . 1378 17. Informative References 1380 [CSC] Consortium, C. S., "Architectures and protocols for remote 1381 signature applications", 1 June 2019, 1382 . 1385 [ETSI] ETSI, "ETSI TS 119 432, Electronic Signatures and 1386 Infrastructures (ESI); Protocols for remote digital 1387 signature creation", 20 March 2019, 1388 . 1392 [IANA.OAuth.Parameters] 1393 IANA, "OAuth Parameters", 1394 . 1396 [JSON.Schema] 1397 json-schema.org, "JSON Schema", 1398 . 1400 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1401 C. Mortimore, "OpenID Connect Core 1.0 incorporating 1402 errata set 1", 8 November 2014, 1403 . 1405 [OpenID.CIBA] 1406 Fernandez, G., Walter, F., Nennker, A., Tonge, D., and B. 1407 Campbell, "OpenID Connect Client Initiated Backchannel 1408 Authentication Flow - Core 1.0", 16 January 2019, 1409 . 1412 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1413 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1414 . 1416 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1417 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1418 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1419 . 1421 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1422 Interchange Format", STD 90, RFC 8259, 1423 DOI 10.17487/RFC8259, December 2017, 1424 . 1426 [RFC9101] Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 1427 Authorization Framework: JWT-Secured Authorization Request 1428 (JAR)", RFC 9101, DOI 10.17487/RFC9101, August 2021, 1429 . 1431 [RFC9126] Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 1432 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 1433 RFC 9126, DOI 10.17487/RFC9126, September 2021, 1434 . 1436 [transaction-authorization] 1437 Lodderstedt, T., "Transaction Authorization or why we need 1438 to re-think OAuth scopes", 20 April 2019, 1439 . 1442 Appendix A. Additional Examples 1444 A.1. OpenID Connect 1446 OpenID Connect [OIDC] specifies the JSON-based claims request 1447 parameter that can be used to specify the claims a client (acting as 1448 OpenID Connect Relying Party) wishes to receive in a fine-grained and 1449 privacy-preserving way as well as assign those claims to certain 1450 delivery mechanisms, i.e. ID Token or userinfo response. 1452 The combination of the scope value openid and the additional 1453 parameter claims can be used beside authorization_details in the same 1454 way as every non-OIDC scope value. 1456 Alternatively, there could be an authorization details type for 1457 OpenID Connect. This section gives an example of what such an 1458 authorization details type could look like, but defining this 1459 authorization details type is outside the scope of this 1460 specification. 1462 These hypothetical examples try to encapsulate all details specific 1463 to the OpenID Connect part of an authorization process into an 1464 authorization JSON object. 1466 The top-level field are based on the definitions given in [OIDC]: 1468 * claim_sets: names of predefined claim sets, replacement for 1469 respective scope values, such as profile 1470 * max_age: Maximum Authentication Age 1471 * acr_values: array of ACR values 1472 * claims: the claims JSON structure as defined in [OIDC] 1473 This is a simple request for some claim sets. 1475 [ 1476 { 1477 "type": "openid", 1478 "locations": [ 1479 "https://op.example.com/userinfo" 1480 ], 1481 "claim_sets": [ 1482 "email", 1483 "profile" 1484 ] 1485 } 1486 ] 1488 Figure 25: Example for OpenID Connect request utilizing 1489 authorization details. 1491 Note: locations specifies the location of the userinfo endpoint since 1492 this is the only place where an access token is used by a client (RP) 1493 in OpenID Connect to obtain claims. 1495 A more sophisticated example is shown in the following 1497 [ 1498 { 1499 "type": "openid", 1500 "locations": [ 1501 "https://op.example.com/userinfo" 1502 ], 1503 "max_age": 86400, 1504 "acr_values": "urn:mace:incommon:iap:silver", 1505 "claims": { 1506 "userinfo": { 1507 "given_name": { 1508 "essential": true 1509 }, 1510 "nickname": null, 1511 "email": { 1512 "essential": true 1513 }, 1514 "email_verified": { 1515 "essential": true 1516 }, 1517 "picture": null, 1518 "http://example.info/claims/groups": null 1519 }, 1520 "id_token": { 1521 "auth_time": { 1522 "essential": true 1523 } 1524 } 1525 } 1526 } 1527 ] 1529 Figure 26: Advanced example for OpenID Connect request utilizing 1530 authorization details. 1532 A.2. Remote Electronic Signing 1534 The following example is based on the concept laid out for remote 1535 electronic signing in ETSI TS 119 432 [ETSI] and the CSC API for 1536 remote signature creation [CSC]. 1538 [ 1539 { 1540 "type": "sign", 1541 "locations": [ 1542 "https://signing.example.com/signdoc" 1543 ], 1544 "credentialID": "60916d31-932e-4820-ba82-1fcead1c9ea3", 1545 "documentDigests": [ 1546 { 1547 "hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=", 1548 "label": "Credit Contract" 1549 }, 1550 { 1551 "hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=", 1552 "label": "Contract Payment Protection Insurance" 1553 } 1554 ], 1555 "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1" 1556 } 1557 ] 1559 Figure 27: Example for electronic signing. 1561 The top-level fields have the following meaning: 1563 * credentialID: identifier of the certificate to be used for signing 1564 * documentDigests: array containing the hash of every document to be 1565 signed (hash fields). Additionally, the corresponding label field 1566 identifies the respective document to the user, e.g. to be used in 1567 user consent. 1568 * hashAlgorithm: algorithm that was used to calculate the hash 1569 values. 1571 The AS is supposed to ask the user for consent for the creation of 1572 signatures for the documents listed in the structure. The client 1573 uses the access token issued as a result of the process to call the 1574 sign doc endpoint at the respective signing service to actually 1575 create the signature. This access token is bound to the client, the 1576 user id and the hashes (and signature algorithm) as consented by the 1577 user. 1579 A.3. Access to Tax Data 1581 This example is inspired by an API allowing third parties to access 1582 citizen's tax declarations and income statements, for example, to 1583 determine their creditworthiness. 1585 [ 1586 { 1587 "type": "tax_data", 1588 "locations": [ 1589 "https://taxservice.govehub.no" 1590 ], 1591 "actions":"read_tax_declaration", 1592 "periods": ["2018"], 1593 "duration_of_access": 30, 1594 "tax_payer_id": "23674185438934" 1595 } 1596 ] 1598 Figure 28: Example for tax data access. 1600 The top-level fields have the following meaning: 1602 * periods: determines the periods the client wants to access 1603 * duration_of_access: how long does the client intend to access the 1604 data in days 1605 * tax_payer_id: identifier of the tax payer (if known to the client) 1607 A.4. eHealth 1609 These two examples are inspired by requirements for APIs used in the 1610 Norwegian eHealth system. 1612 In this use case, the physical therapist sits in front of her 1613 computer using a local Electronic Health Records (EHR) system. They 1614 want to look at the electronic patient records of a certain patient 1615 and they also want to fetch the patients journal entries in another 1616 system, perhaps at another institution or a national service. Access 1617 to this data is provided by an API. 1619 The information necessary to authorize the request at the API is only 1620 known by the EHR system, and must be presented to the API. 1622 In the first example, the authorization details object contains the 1623 identifier of an organization. In this case, the API needs to know 1624 if the given organization has the lawful basis for processing 1625 personal health information to give access to sensitive data. 1627 "authorization_details": { 1628 "type": "patient_record", 1629 "requesting_entity": { 1630 "type": "Practitioner", 1631 "identifier": [ 1632 { 1633 "system": "urn:oid:2.16.578.1.12.4.1.4.4", 1634 "value": "1234567" 1635 }], 1636 "practitioner_role": { 1637 "organization": { 1638 "identifier": { 1639 "system": "urn:oid:2.16.578.1.12.4.1.2.101", 1640 "type": "ENH", 1641 "value": "[organizational number]" 1642 } 1643 } 1644 } 1645 } 1646 } 1648 Figure 29: eHealth Example. 1650 In the second example, the API requires more information to authorize 1651 the request. In this case, the authorization details object contains 1652 additional information about the health institution and the current 1653 profession the user has at the time of the request. The additional 1654 level of detail could be used for both authorization and data 1655 minimization. 1657 [ 1658 { 1659 "type": "patient_record", 1660 "location": "https://fhir.example.com/patient", 1661 "actions": [ 1662 "read" 1663 ], 1664 "patient_identifier": [ 1665 { 1666 "system": "urn:oid:2.16.578.1.12.4.1.4.1", 1667 "value": "12345678901" 1668 } 1669 ], 1670 "reason_for_request": "Clinical treatment", 1671 "requesting_entity": { 1672 "type": "Practitioner", 1673 "identifier": [ 1674 { 1675 "system": "urn:oid:2.16.578.1.12.4.1.4.4", 1676 "value": "1234567" 1677 } 1678 ], 1679 "practitioner_role": { 1680 "organization": { 1681 "identifier": [ 1682 { 1683 "system": "urn:oid:2.16.578.1.12.4.1.2.101", 1684 "type": "ENH", 1685 "value": "" 1686 } 1687 ], 1688 "type": { 1689 "coding": [ 1690 { 1691 "system": 1692 "http://hl7.org/fhir/organization-type", 1693 "code": "dept", 1694 "display": "Hospital Department" 1695 } 1696 ] 1697 }, 1698 "name": "Akuttmottak" 1699 }, 1700 "profession": { 1701 "coding": [ 1702 { 1703 "system": "http://snomed.info/sct", 1704 "code": "36682004", 1705 "display": "Physical therapist" 1706 } 1707 ] 1708 } 1709 } 1710 } 1711 } 1712 ] 1714 Figure 30: Advanced eHaelth example. 1716 Description of the fields: 1718 * patient_identifier: the identifier of the patient composed of a 1719 system identifier in OID format (namespace) and the actual value 1720 within this namespace. 1721 * reason_for_request: the reason why the user wants to access a 1722 certain API 1724 * requesting_entity: specification of the requester by means of 1725 identity, role and organizational context. This data is provided 1726 to facilitate authorization and for auditing purposes. 1728 In this use case, the AS authenticates the requester, who is not the 1729 patient, and approves access based on policies. 1731 Appendix B. Document History 1733 [[ To be removed from the final specification ]] 1735 -12 1737 * Clarify introspection response. 1739 -11 1741 * Updated IANA registrations adding authorization_details parameter 1743 -10 1745 * Updated IANA registrations 1747 -09 1749 * Incorporated feedback by Hannes as document shepherd 1751 -08 1753 * formatting in authorization details type section 1754 * added example for privileges common data element 1756 -07 1758 * incorporated review feedback from WGLC 1759 * fixed wording in token introspection section 1760 * added privacy considerations re authorization details in token 1761 response 1763 -06 1765 * removed use of resource indicators to filter authorization details 1766 in token response 1768 -05 1770 * added authorization_details token request parameter and discussion 1771 on authorization details comparison 1773 * added privileges field to authorization details (to align with 1774 GNAP) 1775 * added IANA text and changed metadata parameter names 1776 * added text about use of machine-readable type schemas, e.g. JSON 1777 Schema 1778 * added text on how authorization details are determined for access 1779 token issued with token response 1780 * added token error response and further error conditions to 1781 authorization error response 1783 -04 1785 * restructured draft for better readability 1786 * simplified normative text about use of the resource parameter with 1787 authorization_details 1788 * added implementation considerations for deployments and products 1789 * added type union language from GNAP 1790 * added recommendation to use PAR to cope with large requests and 1791 for request protection 1793 -03 1795 * Updated references to current revisions or RFC numbers 1796 * Added section about enrichment of authorization details objects by 1797 the AS 1798 * Clarified processing of unknown authorization details parameters 1799 * clarified dependencies between resource and authorization_details 1800 parameters 1802 -02 1804 * Clarify "type" parameter processing 1806 -01 1808 * Minor fix-up in a few examples 1810 -00 (WG draft) 1812 * initial WG revision 1814 -03 1816 * Reworked examples to illustrate privacy preserving use of 1817 authorization_details 1818 * Added text on audience restriction 1819 * Added description of relationship between scope and 1820 authorization_details 1822 * Added text on token request & response and authorization_details 1823 * Added text on how authorization details are conveyed to RSs by 1824 JWTs or token introspection endpoint response 1825 * Added description of relationship between claims and 1826 authorization_details 1827 * Added more example from different sectors 1828 * Clarified string comparison to be byte-exact without collation 1830 -02 1832 * Added Security Considerations 1833 * Added Privacy Considerations 1834 * Added notes on URI size and authorization details 1835 * Added requirement to return the effective authorization details 1836 granted by the resource owner in the token response 1837 * changed authorization_details structure from object to array 1838 * added Justin Richer & Brian Campbell as Co-Authors 1840 -00 / -01 1842 * first draft 1844 Authors' Addresses 1846 Torsten Lodderstedt 1847 yes.com 1848 Email: torsten@lodderstedt.net 1850 Justin Richer 1851 Bespoke Engineering 1852 Email: ietf@justin.richer.org 1854 Brian Campbell 1855 Ping Identity 1856 Email: bcampbell@pingidentity.com