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