idnits 2.17.1 draft-ietf-oauth-rar-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (18 October 2021) is 914 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: 21 April 2022 Bespoke Engineering 6 B. Campbell 7 Ping Identity 8 18 October 2021 10 OAuth 2.0 Rich Authorization Requests 11 draft-ietf-oauth-rar-08 13 Abstract 15 This document specifies a new parameter authorization_details that is 16 used to carry fine-grained authorization data in the OAuth 17 authorization request. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 21 April 2022. 36 Copyright Notice 38 Copyright (c) 2021 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 4 54 2. Request parameter "authorization_details" . . . . . . . . . . 4 55 2.1. Authorization data elements types . . . . . . . . . . . . 6 56 2.2. Authorization Data Types . . . . . . . . . . . . . . . . 10 57 3. Authorization Request . . . . . . . . . . . . . . . . . . . . 11 58 3.1. Relationship to "scope" parameter . . . . . . . . . . . . 13 59 3.2. Relationship to "resource" parameter . . . . . . . . . . 14 60 4. Authorization Response . . . . . . . . . . . . . . . . . . . 14 61 5. Authorization Error Response . . . . . . . . . . . . . . . . 14 62 6. Token Request . . . . . . . . . . . . . . . . . . . . . . . . 14 63 6.1. Comparing authorization details . . . . . . . . . . . . . 15 64 7. Token Response . . . . . . . . . . . . . . . . . . . . . . . 18 65 7.1. Enriched authorization details in Token Response . . . . 19 66 8. Token Error Response . . . . . . . . . . . . . . . . . . . . 22 67 9. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 23 68 9.1. JWT-based Access Tokens . . . . . . . . . . . . . . . . . 23 69 9.2. Token Introspection . . . . . . . . . . . . . . . . . . . 25 70 10. Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . 26 71 11. Scope value "openid" and "claims" parameter . . . . . . . . . 27 72 12. Implementation Considerations . . . . . . . . . . . . . . . . 27 73 12.1. Using authorization details in a certain deployment . . 27 74 12.2. Minimal product support . . . . . . . . . . . . . . . . 27 75 12.3. Use of Machine-readable Type Schemas . . . . . . . . . . 28 76 12.4. Large requests . . . . . . . . . . . . . . . . . . . . . 29 77 13. Security Considerations . . . . . . . . . . . . . . . . . . . 29 78 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 30 79 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 80 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 81 16.1. JSON Web Token Claims Registration . . . . . . . . . . . 31 82 16.2. OAuth Authorization Server Metadata . . . . . . . . . . 31 83 16.3. OAuth Dynamic Client Registration Metadata . . . . . . . 31 84 16.4. OAuth Extensions Error registry . . . . . . . . . . . . 31 85 17. Normative References . . . . . . . . . . . . . . . . . . . . 32 86 18. Informative References . . . . . . . . . . . . . . . . . . . 32 87 Appendix A. Additional Examples . . . . . . . . . . . . . . . . 34 88 A.1. OpenID Connect . . . . . . . . . . . . . . . . . . . . . 34 89 A.2. Remote Electronic Signing . . . . . . . . . . . . . . . . 35 90 A.3. Access to Tax Data . . . . . . . . . . . . . . . . . . . 36 91 A.4. eHealth . . . . . . . . . . . . . . . . . . . . . . . . . 37 92 Appendix B. Document History . . . . . . . . . . . . . . . . . . 40 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 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 folder A and write access to file 105 X". 107 This draft introduces a new parameter authorization_details that 108 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 This object contains detailed information about the intended payment, 132 such as amount, currency, and creditor, that are required to inform 133 the user and obtain her consent. The AS and the respective RS 134 (providing the payment initiation API) will together enforce this 135 consent. 137 For a comprehensive discussion of the challenges arising from new use 138 cases in the open banking and electronic signing spaces see 139 [transaction-authorization]. 141 In addition to facilitating custom authorization requests, this draft 142 also introduces a set of common data type fields for use across 143 different APIs. 145 Most notably, the field locations allows a client to specify where it 146 intends to use a certain authorization, i.e., it is now possible to 147 unambiguously assign permissions to resource servers. In situations 148 with multiple resource servers, this prevents unintended client 149 authorizations (e.g. a read scope value potentially applicable for an 150 email as well as a cloud service). In combination with the resource 151 token request parameter as specified in [RFC8707] or by specifying 152 authorization details with a single location only in the token 153 request, it enables the AS to issue RS-specific structured access 154 tokens that only contain the permissions applicable to the respective 155 RS. 157 1.1. Conventions and Terminology 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 161 "OPTIONAL" in this document are to be interpreted as described in BCP 162 14 [RFC2119] [RFC8174] when, and only when, they appear in all 163 capitals, as shown here. 165 This specification uses the terms "access token", "refresh token", 166 "authorization server", "resource server", "authorization endpoint", 167 "authorization request", "authorization response", "token endpoint", 168 "grant type", "access token request", "access token response", and 169 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 171 2. Request parameter "authorization_details" 173 The request parameter authorization_details contains, in JSON 174 notation, an array of objects. Each JSON object contains the data to 175 specify the authorization requirements for a certain type of 176 resource. The type of resource or access requirement is determined 177 by the type field. 179 This example shows the specification of authorization details using 180 the payment authorization object shown above: 182 [ 183 { 184 "type": "payment_initiation", 185 "actions": [ 186 "initiate", 187 "status", 188 "cancel" 189 ], 190 "locations": [ 191 "https://example.com/payments" 192 ], 193 "instructedAmount": { 194 "currency": "EUR", 195 "amount": "123.50" 196 }, 197 "creditorName": "Merchant A", 198 "creditorAccount": { 199 "iban": "DE02100100109307118603" 200 }, 201 "remittanceInformationUnstructured": "Ref Number Merchant" 202 } 203 ] 205 This example shows a combined request asking for access to account 206 information and permission to initiate a payment: 208 [ 209 { 210 "type": "account_information", 211 "actions": [ 212 "list_accounts", 213 "read_balances", 214 "read_transactions" 215 ], 216 "locations": [ 217 "https://example.com/accounts" 218 ] 219 }, 220 { 221 "type": "payment_initiation", 222 "actions": [ 223 "initiate", 224 "status", 225 "cancel" 226 ], 227 "locations": [ 228 "https://example.com/payments" 229 ], 230 "instructedAmount": { 231 "currency": "EUR", 232 "amount": "123.50" 233 }, 234 "creditorName": "Merchant A", 235 "creditorAccount": { 236 "iban": "DE02100100109307118603" 237 }, 238 "remittanceInformationUnstructured": "Ref Number Merchant" 239 } 240 ] 242 The JSON objects with type fields of account_information and 243 payment_initiation represent the different authorization data to be 244 used by the AS to ask for consent and MUST subsequently also be made 245 available to the respective resource servers. The array MAY contain 246 several elements of the same type. 248 2.1. Authorization data elements types 250 The allowable contents of the authorization details object are 251 determined by the type parameter. 253 type: The type of authorization data as a string. This field MAY 254 define which other elements are allowed in the request. This 255 element is REQUIRED. 257 This field MUST be compared using an exact byte match of the string 258 value against known types by the AS. The AS MUST ensure that there 259 is no collision between different authorization data types that it 260 supports. The AS MUST NOT do any collation or normalization of data 261 types during comparison. 263 The value of the type field determines the allowable contents of the 264 object which contains it. 266 This draft defines a set of common data elements that are designed to 267 be usable across different types of APIs. These data elements MAY be 268 combined in different ways depending on the needs of the API. All 269 data elements are OPTIONAL for use by a given API definition. The 270 allowable values of all elements are determined by the API being 271 protected. 273 locations: An array of strings representing the location of the 274 resource or resource server. These strings are typically URIs 275 identifying the location of the RS. 277 actions: An array of strings representing the kinds of actions to be 278 taken at the resource. 280 datatypes: An array of strings representing the kinds of data being 281 requested from the resource. 283 identifier: A string identifier indicating a specific resource 284 available at the API. 286 privileges: An array of strings representing the types or levels of 287 privilege being requested at the resource. 289 When different element types are used in combination, the permissions 290 the client requests is the cartesian product of the values. That is 291 to say, the object represents a request for all action values listed 292 within the object to be used at all locations values listed within 293 the object for all datatype values listed within the object. In the 294 following example, the client is requesting read and write access to 295 both the contacts and photos belonging to customers in a 296 customer_information API. If this request is granted, the client 297 would assume it would be able to use any combination of rights 298 defined by the API, such as reading the photos and writing the 299 contacts. 301 [ 302 { 303 "type": "customer_information", 304 "locations": [ 305 "https://example.com/customers" 306 ], 307 "actions": [ 308 "read", 309 "write" 310 ], 311 "datatypes": [ 312 "contacts", 313 "photos" 314 ] 315 } 316 ] 318 If the client wishes to have finer control over its access, it can 319 send multiple objects. In this example, the client is asking for 320 read access to the contacts and write access to the photos in the 321 same API endpoint. If this request is granted, the client would not 322 be able to write to the contacts. 324 [ 325 { 326 "type": "customer_information", 327 "locations": [ 328 "https://example.com/customers" 329 ], 330 "actions": [ 331 "read" 332 ], 333 "datatypes": [ 334 "contacts" 335 ] 336 }, 337 { 338 "type": "customer_information", 339 "locations": [ 340 "https://example.com/customers" 341 ], 342 "actions": [ 343 "write" 344 ], 345 "datatypes": [ 346 "photos" 347 ] 348 } 349 ] 351 An API MAY define its own extensions, subject to the type of the 352 respective authorization object. It is anticipated that API 353 designers will use a combination of common fields defined in this 354 specification as well as fields specific to the API itself. The 355 following non-normative example shows the use of both common and API- 356 specific fields as part of two different fictitious API type values. 357 The first access request includes the actions, locations, and 358 datatypes fields specified here as well as the API-specific 359 geolocation field. The second access request includes the actions 360 and identifier fields specified here as well as the API-specific 361 currency field. 363 [ 364 { 365 "type":"photo-api", 366 "actions":[ 367 "read", 368 "write" 369 ], 370 "locations":[ 371 "https://server.example.net/", 372 "https://resource.local/other" 373 ], 374 "datatypes":[ 375 "metadata", 376 "images" 377 ], 378 "geolocation":[ 379 { 380 "lat":-32.364, 381 "lng":153.207 382 }, 383 { 384 "lat":-35.364, 385 "lng":158.207 386 } 387 ] 388 }, 389 { 390 "type":"financial-transaction", 391 "actions":[ 392 "withdraw" 393 ], 394 "identifier":"account-14-32-32-3", 395 "currency":"USD" 396 } 397 ] 399 If this request is approved, the resulting access token's access 400 rights will be the union of the requested types of access for each of 401 the two APIs, just as above. 403 2.2. Authorization Data Types 405 Interpretation of the value of the type parameter, and the object 406 elements that the type parameter allows, is under the control of the 407 AS. However, the value of the type parameter is also generally 408 documented and intended to be used by developers, it is RECOMMENDED 409 that API designers choose type values that are easily copied without 410 ambiguity. For example, some glyphs have multiple Unicode code 411 points for the same visual character, and a developer could 412 potentially type a different character than what the AS has defined. 413 Possible means of reducing potential confusion are limiting the value 414 to ASCII characters, providing a machine-readable listing of data 415 type values, or instructing developers to copy and paste directly 416 from the documentation. 418 If an application or API is expected to be deployed across different 419 servers, such as the case in an open standard, the API designer is 420 RECOMMENDED to use a collision-resistant namespace under their 421 control, such as a URI that the API designer controls. 423 The following example shows how an implementation could utilize the 424 namespace https://scheme.example.org/ to ensure collision-resistant 425 element names. 427 { 428 "type": "https://scheme.example.org/files", 429 "locations": [ 430 "https://example.com/files" 431 ], 432 "permissions": [ 433 { 434 "path": "/myfiles/A", 435 "access": [ 436 "read" 437 ] 438 }, 439 { 440 "path": "/myfiles/A/X", 441 "access": [ 442 "read", 443 "write" 444 ] 445 } 446 ] 447 } 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], 457 * Device Authorization Request as specified in [RFC8628], 458 * Backchannel Authentication Requests as defined in [OpenID.CIBA]. 460 In case of a authorization requests as defined in [RFC6749], 461 implementors MAY consider to use pushed authorization requests 462 [I-D.ietf-oauth-par] to improve to security, privacy, and reliability 463 of the flow. See Section 13, Section 14, and Section 12.4 for 464 details. 466 Parameter encoding is determined by the respective context. In the 467 context of an authorization request according to [RFC6749], the 468 parameter is encoded using the application/x-www-form-urlencoded 469 format of the serialized JSON as shown in the following using the 470 example from Section 2 (line breaks for display purposes only): 472 GET /authorize?response_type=code 473 &client_id=s6BhdRkqt3 474 &state=af0ifjsldkj 475 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 476 &code_challenge_method=S256 477 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U 478 &authorization_details=%5B%7B%22type%22%3A%22account%5Finfo 479 rmation%22%2C%22actions%22%3A%5B%22list%5Faccounts%22%2C%22 480 read%5Fbalances%22%2C%22read%5Ftransactions%22%5D%2C%22loca 481 tions%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Faccounts%22% 482 5D%7D%2C%7B%22type%22%3A%22payment%5Finitiation%22%2C%22act 483 ions%22%3A%5B%22initiate%22%2C%22status%22%2C%22cancel%22%5 484 D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Fp 485 ayments%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22% 486 3A%22EUR%22%2C%22amount%22%3A%22123%2E50%22%7D%2C%22credito 487 rName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B% 488 22iban%22%3A%22DE02100100109307118603%22%7D%2C%22remittance 489 InformationUnstructured%22%3A%22RefNumberMerchant%22%7D%5D HTTP/1.1 490 Host: server.example.com 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 3.1. Relationship to "scope" parameter 537 authorization_details and scope can be used in the same authorization 538 request for carrying independent authorization requirements. 540 The AS MUST consider both sets of requirements in combination with 541 each other for the given authorization request. The details of how 542 the AS combines these parameters are specific to the APIs being 543 protected and outside the scope of this specification. 545 It is RECOMMENDED that a given API uses only one form of requirement 546 specification. 548 When gathering user consent, the AS MUST present the merged set of 549 requirements represented by the authorization request. 551 If the resource owner grants the client the requested access, the AS 552 will issue tokens to the client that are associated with the 553 respective authorization_details (and scope values, if applicable). 555 3.2. Relationship to "resource" parameter 557 The resource authorization request parameter as defined in [RFC8707] 558 can be used to further determine the resources where the requested 559 scope can be applied. The resource parameter does not have any 560 impact on the way the AS processes the authorization_details 561 authorization request parameter. 563 4. Authorization Response 565 This specification does not define extensions to the authorization 566 response. 568 5. Authorization Error Response 570 The AS MUST refuse to process any unknown authorization data type or 571 authorization details not conforming to the respective type 572 definition. If any of the objects in authorization_details contains 573 an unknown authorization data type or an object of known type but 574 containing unknown elements or elements of the wrong type or elements 575 with invalid values or if required elements are missing, the AS MUST 576 abort processing and respond with an error 577 invalid_authorization_details to the client. 579 6. Token Request 581 The authorization_details token request parameter can be used to 582 specify the authorization details a client wants the AS to assign to 583 an access token. The AS checks whether the underlying grant (in case 584 of grant types authorization_code, refresh_token, ...) or the 585 client's policy (in case of grant type client_credential) allows the 586 issuance of an access token with the requested authorization details. 587 Otherwise, the AS refuses the request with the error code 588 invalid_authorization_details (similar to invalid_scope). 590 6.1. Comparing authorization details 592 Many actions in the OAuth protocol allow the AS and RS to make 593 security decisions based on whether or not the request is asking for 594 "more" or "less" than a previous, existing request. For example, 595 upon refreshing a token, the client can ask for a new access token 596 with "fewer permissions" than had been previously authorized by the 597 resource owner. Since the nature of an authorization details request 598 is based solely on the API or APIs that it is describing, there is 599 not a simple means of comparing any two arbitrary authorization 600 details requests. Authorization servers should not rely on simple 601 object comparison in most cases, as the intersection of some elements 602 within a request could have side effects in the access rights 603 granted, depending on how the API has been designed and deployed. 604 This is a similar effect to the scope values used with some APIs. 606 However, when comparing a new request to an existing request, 607 authorization servers can use the same processing techniques as used 608 in granting the request in the first place to determine if a resource 609 owner needs to authorize the request. The details of this comparison 610 are dependent on the definition of the type of authorization request 611 and outside the scope of this specification, but common patterns can 612 be applied. 614 This shall be illustrated using our running example. The example 615 authorization request in Section 3, if approved by the user, resulted 616 in the issuance of an authorization code associated with the 617 privileges to 619 * list accounts 621 * access the balance of one or more accounts, 623 * access the transactions of one or more accounts, and 625 * to initiate a payment. 627 The client could now request the AS to issue an access token assigned 628 with the privilege to just access a list of accounts as follows: 630 [ 631 { 632 "type":"account_information", 633 "actions":[ 634 "list_accounts" 635 ], 636 "locations":[ 637 "https://example.com/accounts" 638 ] 639 } 640 ] 642 The example API is designed such that each field used by the 643 account_information type contains additive rights, with each value 644 within the actions and locations arrays specifying a different 645 element of access. To make a comparison in this instance, the AS 646 would perform the following steps: 648 * compare that the authorization code issued in the previous step 649 contains an authorization details object of type 650 account_information 652 * compare whether the approved list of actions contains 653 list_account, and 655 * whether the locations value includes only previously-approved 656 locations. 658 If all checks succeed, the AS would issue the requested access token 659 with the reduced set of access. 661 Note that this comparison is relevant to this specific API type 662 definition. A different API type definition could have different 663 processing rules. For example, the value of an action could subsume 664 the rights associated with another action value. For example, if a 665 client initially asks for a token with write access, which implies 666 both read and write access to this API: 668 [ 669 { 670 "type": "example_api", 671 "actions": [ 672 "write" 673 ] 674 } 675 ] 677 Later that same client makes a refresh request for read access: 679 [ 680 { 681 "type": "example_api", 682 "actions": [ 683 "read" 684 ] 685 } 686 ] 688 The AS would compare the type value and the action value to determine 689 that the read access is already covered by the write access 690 previously granted to the client. 692 This same API could be designed with a possible value for privileges 693 of admin, used in this example to denote that the resulting token is 694 allowed to perform any functions on the resources. If that client is 695 then granted such admin privileges to the API: 697 [ 698 { 699 "type": "example_api", 700 "privileges": [ 701 "admin" 702 ] 703 } 704 ] 706 The AS would compare the type value and find the privileges value 707 subsumes any aspects of read or write access that had been granted to 708 the client previously. Note that other API definitions can use 709 privileges in a non-subsuming fashion. 711 The predefined authorization data element locations MAY be used by 712 the client to request an access token valid for a certain resource 713 server, i.e. it is the recommended way to request issuance of 714 audience restricted access tokens. 716 For our running example, the client MAY ask for all permissions of 717 the approved grant of type payment_iniation applicable to the 718 resource server residing at https://example.com/payments as follows: 720 [ 721 { 722 "type": "payment_initiation", 723 "locations": [ 724 "https://example.com/payments" 725 ] 726 } 727 ] 729 7. Token Response 731 In addition to the token response parameters as defined in [RFC6749], 732 the authorization server MUST also return the authorization details 733 as granted by the resource owner and assigned to the respective 734 access token. 736 The authorization details assigned to the access token issued in a 737 token response are determined by the authorization_details parameter 738 of the corresponding token request. If the client does not specify 739 the authorization_details token request parameters, the AS determines 740 the resulting authorization details at its discretion. The 741 authorization server MAY consider the values of other parameters such 742 as resource and scope if they are present during this processing, and 743 the details of such considerations are outside the scope of this 744 specification. 746 The AS MAY omit values in the authorization_details to the client in 747 the token Response if these are deemed of no intended use for the 748 client. 750 For our running example, this would look like this: 752 HTTP/1.1 200 OK 753 Content-Type: application/json 754 Cache-Control: no-cache, no-store 756 { 757 "access_token": "2YotnFZFEjr1zCsicMWpAA", 758 "token_type": "example", 759 "expires_in": 3600, 760 "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", 761 "authorization_details": [ 762 { 763 "type": "https://www.someorg.com/payment_initiation", 764 "actions": [ 765 "initiate", 766 "status", 767 "cancel" 768 ], 769 "locations": [ 770 "https://example.com/payments" 771 ], 772 "instructedAmount": { 773 "currency": "EUR", 774 "amount": "123.50" 775 }, 776 "creditorName": "Merchant A", 777 "creditorAccount": { 778 "iban": "DE02100100109307118603" 779 }, 780 "remittanceInformationUnstructured": "Ref Number Merchant" 781 } 782 ] 783 } 785 7.1. Enriched authorization details in Token Response 787 The authorization details attached to the access token MAY differ 788 from what the client requests. In addition to the user authorizing 789 less than what the client requested, there are use cases where the 790 authorization server enriches the data in an authorization details 791 object. For example, a client may ask for access to account 792 information but leave the decision about the accounts it will be able 793 to access to the user. The user would select the sub set of accounts 794 they wants the client to entitle to access in the course of the 795 authorization process. As one design option to convey the selected 796 accounts, the authorization server could add this information to the 797 respective authorization details object. 799 As an example, the requested authorization detail parameter could 800 look like this: 802 "authorization_details": [ 803 { 804 "type": "account_information", 805 "access": { 806 "accounts": [], 807 "balances": [], 808 "transactions": [] 809 }, 810 "recurringIndicator":true 811 } 812 ] 814 The authorization server then would expand the authorization details 815 object and add the respective account identifiers. 817 HTTP/1.1 200 OK 818 Content-Type: application/json 819 Cache-Control: no-cache, no-store 821 { 822 "access_token":"2YotnFZFEjr1zCsicMWpAA", 823 "token_type":"example", 824 "expires_in":3600, 825 "refresh_token":"tGzv3JokF0XG5Qx2TlKWIA", 826 "authorization_details":[ 827 { 828 "type":"account_information", 829 "access":{ 830 "accounts":[ 831 { 832 "iban":"DE2310010010123456789" 833 }, 834 { 835 "maskedPan":"123456xxxxxx1234" 836 } 837 ], 838 "balances":[ 839 { 840 "iban":"DE2310010010123456789" 841 } 842 ], 843 "transactions":[ 844 { 845 "iban":"DE2310010010123456789" 846 }, 847 { 848 "maskedPan":"123456xxxxxx1234" 849 } 850 ] 851 }, 852 "recurringIndicator":true 853 } 854 ] 855 } 857 For another example, the client is asking for access to a medical 858 record but does not know the record number at request time. In this 859 example, the client specifies the type of access it wants but doesn't 860 specify the location or identifier of that access. 862 { 863 "authorization_details": [ 864 { 865 "type": "medical_record", 866 "sens": [ "HIV", "ETH", "MART" ], 867 "actions": [ "read" ], 868 "datatypes": [ "Patient", "Observation", "Appointment" ] 869 } 870 ]} 872 When the user interacts with the AS, they select which of the medical 873 records they are responsible for to give to the client. This 874 information gets returned with the access token. 876 { 877 "access_token":"2YotnFZFEjr1zCsicMWpAA", 878 "token_type":"example", 879 "expires_in":3600, 880 "refresh_token":"tGzv3JokF0XG5Qx2TlKWIA", 881 "authorization_details":[ 882 { 883 "type": "medical_record", 884 "sens": [ "HIV", "ETH", "MART" ], 885 "actions": [ "read" ], 886 "datatypes": [ "Patient", "Observation", "Appointment" ], 887 "identifier": "patient-541235", 888 "locations": [ "https://records.example.com/" ] 889 } 890 ] 891 } 893 Note: the client needs to be aware upfront of the possibility that a 894 certain authorization details object can be enriched. It is assumed 895 that this property is part of the definition of the respective 896 authorization details type. 898 8. Token Error Response 900 The AS MUST refuse to process any unknown authorization data type or 901 authorization details not conforming to the respective type 902 definition. If any of the objects in authorization_details contains 903 an unknown authorization data type or an object of known type but 904 containing unknown elements or elements of the wrong type, elements 905 with invalid values, or if required elements are missing, the AS MUST 906 abort processing and respond with an error 907 invalid_authorization_details to the client. 909 9. Resource Servers 911 In order to enable the RS to enforce the authorization details as 912 approved in the authorization process, the AS MUST make this data 913 available to the RS. The AS MAY add the authorization_details 914 element to access tokens in JWT format or to Token Introspection 915 responses. 917 9.1. JWT-based Access Tokens 919 If the access token is a JWT [RFC7519], the AS is RECOMMENDED to add 920 the authorization_details object, filtered to the specific audience, 921 as a top-level claim. 923 The AS will typically also add further claims to the JWT the RS 924 requires for request processing, e.g., user id, roles, and 925 transaction-specific data. What claims the particular RS requires is 926 defined by the RS-specific policy with the AS. 928 The following shows the contents of an example JWT for the payment 929 initiation example above: 931 { 932 "iss": "https://as.example.com", 933 "sub": "24400320", 934 "aud": "a7AfcPcsl2", 935 "exp": 1311281970, 936 "acr": "psd2_sca", 937 "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296", 938 "authorization_details": [ 939 { 940 "type": "https://www.someorg.com/payment_initiation", 941 "actions": [ 942 "initiate", 943 "status", 944 "cancel" 945 ], 946 "locations": [ 947 "https://example.com/payments" 948 ], 949 "instructedAmount": { 950 "currency": "EUR", 951 "amount": "123.50" 952 }, 953 "creditorName": "Merchant A", 954 "creditorAccount": { 955 "iban": "DE02100100109307118603" 956 }, 957 "remittanceInformationUnstructured": "Ref Number Merchant" 958 } 959 ], 960 "debtorAccount": { 961 "iban": "DE40100100103307118608", 962 "user_role": "owner" 963 } 964 } 966 In this case, the AS added the following example claims: 968 * sub: conveys the user on which behalf the client is asking for 969 payment initation 971 * txn: transaction id used to trace the transaction across the 972 services of provider example.com 974 * debtorAccount: API-specific element containing the debtor account. 975 In the example, this account was not passed in the authorization 976 details but selected by the user during the authorization process. 977 The field user_role conveys the role the user has with respect to 978 this particular account. In this case, they is the owner. This 979 data is used for access control at the payment API (the RS). 981 9.2. Token Introspection 983 In the case of opaque access tokens, the data provided to a certain 984 RS is determined using the RS's identifier with the AS (see 985 [I-D.ietf-oauth-jwt-introspection-response], section 3). 987 The token introspection response provides the RS with the 988 authorization details applicable to it as a top-level JSON element 989 along with the claims the RS requires for request processing. 991 Here is an example for the payment initiation example RS: 993 { 994 "active": true, 995 "sub": "24400320", 996 "aud": "s6BhdRkqt3", 997 "exp": 1311281970, 998 "acr": "psd2_sca", 999 "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296", 1000 "authorization_details": [ 1001 { 1002 "type": "https://www.someorg.com/payment_initiation", 1003 "actions": [ 1004 "initiate", 1005 "status", 1006 "cancel" 1007 ], 1008 "locations": [ 1009 "https://example.com/payments" 1010 ], 1011 "instructedAmount": { 1012 "currency": "EUR", 1013 "amount": "123.50" 1014 }, 1015 "creditorName": "Merchant123", 1016 "creditorAccount": { 1017 "iban": "DE02100100109307118603" 1018 }, 1019 "remittanceInformationUnstructured": "Ref Number Merchant" 1020 } 1021 ], 1022 "debtorAccount": { 1023 "iban": "DE40100100103307118608", 1024 "user_role": "owner" 1025 } 1026 } 1028 10. Metadata 1030 The AS publishes the list of authorization details types it supports 1031 using the metadata parameter authorization_details_types_supported, 1032 which is a JSON array. 1034 Clients announce the authorization data types they use in the new 1035 dynamic client registration parameter authorization_details_types. 1037 The registration of authorization data types with the AS is out of 1038 scope of this draft. 1040 11. Scope value "openid" and "claims" parameter 1042 OpenID Connect [OIDC] specifies the JSON-based claims request 1043 parameter that can be used to specify the claims a client (acting as 1044 OpenID Connect Relying Party) wishes to receive in a fine-grained and 1045 privacy-preserving way as well as assign those claims to certain 1046 delivery mechanisms, i.e. ID Token or userinfo response. 1048 The combination of the scope value openid and the additional 1049 parameter claims can be used beside authorization_details in the same 1050 way as every non-OIDC scope value. 1052 Alternatively, there could be an authorization data type for OpenID 1053 Connect. Appendix A.1 gives an example of what such an authorization 1054 data type could look like. 1056 12. Implementation Considerations 1058 12.1. Using authorization details in a certain deployment 1060 Using authorization details in a certain deployment will require the 1061 following steps: 1063 * Define authorization details types 1065 * Publish authorization details types in the OAuth server metadata 1067 * Determine how authorization details are shown to the user in the 1068 user consent 1070 * (if needed) Enrich authorization details in the user consent 1071 process (e.g. add selected accounts or set expirations) 1073 * (if needed) Determine how authorization details are reflected in 1074 access token content or introspection responses 1076 * Determine how the resource server(s) process(s) the authorization 1077 details or token data derived from authorization details 1079 12.2. Minimal product support 1081 Products supporting this specification should provide the following 1082 basic functions: 1084 * Support advertisement of supported authorization details types in 1085 OAuth server metadata 1087 * Accept authorization_details parameter in authorization requests 1088 including basic syntax check for compliance with this 1089 specification 1091 * Support storage of consented authorization details as part of a 1092 grant 1094 * Implement default behavior for adding authorization details to 1095 access tokens and token introspection responses in order to make 1096 them available to resource servers (similar to scope values). 1097 This should work with any grant type, especially 1098 authorization_code and refresh_token. 1100 Processing and presentation of authorization details will vary 1101 significantly among different authorization data types. Products 1102 should therefore support customization of the respective behavior. 1103 In particular, products should 1105 * allow deployments to determine presentation of the authorization 1106 details 1108 * allow deployments to modify requested authorization details in the 1109 user consent process, e.g. adding fields 1111 * allow deployments to merge requested and pre-existing 1112 authorization details 1114 One option would be to have a mechanism allowing the registration of 1115 extension modules, each of them responsible for rendering the 1116 respective user consent and any transformation needed to provide the 1117 data needed to the resource server by way of structured access tokens 1118 or token introspection responses. 1120 12.3. Use of Machine-readable Type Schemas 1122 Products might allow deployments to use machine-readable schema 1123 languages for defining authorization details types to facilitate 1124 creating and validating authorization details objects against such 1125 schemas. For example, if an authorization details type were defined 1126 using JSON Schemas [JSON.Schema], the JSON schema id could be used as 1127 type value in the respective authorization details objects. 1129 Note however that type values are identifiers understood by the AS 1130 and, to the extent necessary, the client and RS. This specification 1131 makes no assumption that a type value point to a machine-readable 1132 schema format, or that any party in the system (such as the client, 1133 AS, or RS) dereference or process the contents of the type field in 1134 any specific way. 1136 12.4. Large requests 1138 Authorization request URIs containing authorization details in a 1139 request parameter or a request object can become very long. 1140 Implementers SHOULD therefore consider using the request_uri 1141 parameter as defined in [I-D.ietf-oauth-jwsreq] in combination with 1142 the pushed request object mechanism as defined in 1143 [I-D.ietf-oauth-par] to pass authorization details in a reliable and 1144 secure manner. Here is an example of such a pushed authorization 1145 request that sends the authorization request data directly to the AS 1146 via a HTTPS-protected connection: 1148 POST /as/par HTTP/1.1 1149 Host: as.example.com 1150 Content-Type: application/x-www-form-urlencoded 1151 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 1153 response_type=code& 1154 client_id=s6BhdRkqt3 1155 &state=af0ifjsldkj 1156 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 1157 &code_challenge_method=S256 1158 &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U 1159 &authorization_details=%5B%7B%22type%22%3A%22account_information%22 1160 %2C%22actions%22%3A%5B%22list_accounts%22%2C%22read_balances%22%2C% 1161 22read_transactions%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fe 1162 xample.com%2Faccounts%22%5D%7D%2C%7B%22type%22%3A%22payment_initiat 1163 ion%22%2C%22actions%22%3A%5B%22initiate%22%2C%22status%22%2C%22canc 1164 el%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpaym 1165 ents%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22EUR%22 1166 %2C%22amount%22%3A%22123.50%22%7D%2C%22creditorName%22%3A%22Merchan 1167 t123%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE021001001093 1168 07118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%2 1169 0Number%20Merchant%22%7D%5D 1171 13. Security Considerations 1173 Authorization details are sent through the user agent in case of an 1174 OAuth authorization request, which makes them vulnerable to 1175 modifications by the user. In order to ensure their integrity, the 1176 client SHOULD send authorization details in a signed request object 1177 as defined in [I-D.ietf-oauth-jwsreq] or use the request_uri 1178 authorization request parameter as defined in [I-D.ietf-oauth-jwsreq] 1179 in conjunction with [I-D.ietf-oauth-par] to pass the URI of the 1180 request object to the authorization server. 1182 All strings MUST be compared using the exact byte representation of 1183 the characters as defined by [RFC8259]. This is especially true for 1184 the type field, which dictates which other fields and functions are 1185 allowed in the request. The server MUST NOT perform any form of 1186 collation, transformation, or equivalence on the string values. 1188 14. Privacy Considerations 1190 Implementers MUST design and use authorization details in a privacy- 1191 preserving manner. 1193 Any sensitive personal data included in authorization details MUST be 1194 prevented from leaking, e.g., through referrer headers. 1195 Implementation options include encrypted request objects as defined 1196 in [I-D.ietf-oauth-jwsreq] or transmission of authorization details 1197 via end-to-end encrypted connections between client and authorization 1198 server by utilizing [I-D.ietf-oauth-par] and the request_uri 1199 authorization request parameter as defined in 1200 [I-D.ietf-oauth-jwsreq]. 1202 Even if the request data is encrypted, an attacker could use the 1203 authorization server to learn the user data by injecting the 1204 encrypted request data into an authorization request on a device 1205 under his control and use the authorization server's user consent 1206 screens to show the (decrypted) user data in the clear. 1207 Implementations MUST consider this attacker vector and implement 1208 appropriate countermeasures, e.g. by only showing portions of the 1209 data or, if possible, determining whether the assumed user context is 1210 still the same (after user authentication). 1212 The AS MUST take into consideration the privacy implications when 1213 sharing authorization details with the client or resource servers. 1214 The AS SHOULD share this data with those parties on a "need to know" 1215 basis. 1217 15. Acknowledgements 1219 We would like to thank Daniel Fett, Sebastian Ebling, Dave Tonge, 1220 Mike Jones, Nat Sakimura, and Rob Otto for their valuable feedback 1221 during the preparation of this draft. 1223 We would also like to thank Vladimir Dzhuvinov, Takahiko Kawasaki, 1224 Daniel Fett, Dave Tonge, Travis Spencer, Jørgen Binningsbø, 1225 Aamund Bremer, Steinar Noem, Francis Pouatcha, Jacob Ideskog, and 1226 Aaron Parecki for their valuable feedback to this draft. 1228 16. IANA Considerations 1229 16.1. JSON Web Token Claims Registration 1231 This specification requests registration of the following value in 1232 the IANA "JSON Web Token Claims Registry" established by [RFC7519]. 1234 Claim Name: authorization_details 1235 Claim Description: The request parameter authorization_details 1236 contains, in JSON notation, an array of objects. Each JSON object 1237 contains the data to specify the authorization requirements for a 1238 certain type of resource. 1239 Change Controller: IESG 1240 Specification Document(s): Section 2 of this document 1242 16.2. OAuth Authorization Server Metadata 1244 This specification requests registration of the following values in 1245 the IANA "OAuth Authorization Server Metadata" registry of 1246 [IANA.OAuth.Parameters] established by [RFC8414]. 1248 Metadata Name: authorization_details_types_supported 1249 Metadata Description: JSON array containing the authorization 1250 details types the AS supports 1251 Change Controller: IESG 1252 Specification Document(s): Section 10 of [[ this document ]] 1254 16.3. OAuth Dynamic Client Registration Metadata 1256 This specification requests registration of the following value in 1257 the IANA "OAuth Dynamic Client Registration Metadata" registry of 1258 [IANA.OAuth.Parameters] established by [RFC7591]. 1260 Metadata Name: authorization_details_types 1261 Metadata Description: Indicates what authorization details types the 1262 client uses. 1263 Change Controller: IESG 1264 Specification Document(s): Section 10 of [[ this document ]] 1266 16.4. OAuth Extensions Error registry 1268 This specification requests registration of the following value in 1269 the IANA "OAuth Extensions Error registry" registry of 1270 [IANA.OAuth.Parameters] established by [RFC6749]. 1272 Metadata Name: invalid_authorization_details 1273 Metadata Description: indicates invalid 1274 authorization_details_parameterto the client. 1275 Change Controller: IESG 1276 Specification Document(s): Section 5 of [[ this document ]] 1278 17. Normative References 1280 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1281 Requirement Levels", BCP 14, RFC 2119, 1282 DOI 10.17487/RFC2119, March 1997, 1283 . 1285 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 1286 "OAuth 2.0 Device Authorization Grant", RFC 8628, 1287 DOI 10.17487/RFC8628, August 2019, 1288 . 1290 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1291 Authorization Server Metadata", RFC 8414, 1292 DOI 10.17487/RFC8414, June 2018, 1293 . 1295 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 1296 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 1297 February 2020, . 1299 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1300 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1301 May 2017, . 1303 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1304 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1305 . 1307 18. Informative References 1309 [transaction-authorization] 1310 Lodderstedt, T., "Transaction Authorization or why we need 1311 to re-think OAuth scopes", 20 April 2019, 1312 . 1315 [I-D.ietf-oauth-jwt-introspection-response] 1316 Lodderstedt, T. and V. Dzhuvinov, "JWT Response for OAuth 1317 Token Introspection", Work in Progress, Internet-Draft, 1318 draft-ietf-oauth-jwt-introspection-response-12, 4 1319 September 2021, . 1322 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1323 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1324 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1325 . 1327 [OpenID.CIBA] 1328 Fernandez, G., Walter, F., Nennker, A., Tonge, D., and B. 1329 Campbell, "OpenID Connect Client Initiated Backchannel 1330 Authentication Flow - Core 1.0", 16 January 2019, 1331 . 1334 [I-D.ietf-oauth-jwsreq] 1335 Sakimura, N., Bradley, J., and M. B. Jones, "The OAuth 2.0 1336 Authorization Framework: JWT-Secured Authorization Request 1337 (JAR)", Work in Progress, Internet-Draft, draft-ietf- 1338 oauth-jwsreq-34, 8 April 2021, 1339 . 1342 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1343 Interchange Format", STD 90, RFC 8259, 1344 DOI 10.17487/RFC8259, December 2017, 1345 . 1347 [CSC] Consortium, C. S., "Architectures and protocols for remote 1348 signature applications", 1 June 2019, 1349 . 1352 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1353 C. Mortimore, "OpenID Connect Core 1.0 incorporating 1354 errata set 1", 8 November 2014, 1355 . 1357 [JSON.Schema] 1358 json-schema.org, "JSON Schema", 1359 . 1361 [ETSI] ETSI, "ETSI TS 119 432, Electronic Signatures and 1362 Infrastructures (ESI); Protocols for remote digital 1363 signature creation", 20 March 2019, 1364 . 1368 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1369 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1370 . 1372 [I-D.ietf-oauth-par] 1373 Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 1374 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 1375 Work in Progress, Internet-Draft, draft-ietf-oauth-par-10, 1376 29 July 2021, . 1379 [IANA.OAuth.Parameters] 1380 IANA, "OAuth Parameters", 1381 . 1383 Appendix A. Additional Examples 1385 A.1. OpenID Connect 1387 These hypothetical examples try to encapsulate all details specific 1388 to the OpenID Connect part of an authorization process into an 1389 authorization JSON object. 1391 The top-level elements are based on the definitions given in [OIDC]: 1393 * claim_sets: names of predefined claim sets, replacement for 1394 respective scope values, such as profile 1396 * max_age: Maximum Authentication Age 1398 * acr_values: array of ACR values 1400 * claims: the claims JSON structure as defined in [OIDC] 1402 This is a simple request for some claim sets. 1404 [ 1405 { 1406 "type": "openid", 1407 "locations": [ 1408 "https://op.example.com/userinfo" 1409 ], 1410 "claim_sets": [ 1411 "email", 1412 "profile" 1413 ] 1414 } 1415 ] 1417 Note: locations specifies the location of the userinfo endpoint since 1418 this is the only place where an access token is used by a client (RP) 1419 in OpenID Connect to obtain claims. 1421 A more sophisticated example is shown in the following 1423 [ 1424 { 1425 "type": "openid", 1426 "locations": [ 1427 "https://op.example.com/userinfo" 1428 ], 1429 "max_age": 86400, 1430 "acr_values": "urn:mace:incommon:iap:silver", 1431 "claims": { 1432 "userinfo": { 1433 "given_name": { 1434 "essential": true 1435 }, 1436 "nickname": null, 1437 "email": { 1438 "essential": true 1439 }, 1440 "email_verified": { 1441 "essential": true 1442 }, 1443 "picture": null, 1444 "http://example.info/claims/groups": null 1445 }, 1446 "id_token": { 1447 "auth_time": { 1448 "essential": true 1449 } 1450 } 1451 } 1452 } 1453 ] 1455 A.2. Remote Electronic Signing 1457 The following example is based on the concept laid out for remote 1458 electronic signing in ETSI TS 119 432 [ETSI] and the CSC API for 1459 remote signature creation [CSC]. 1461 [ 1462 { 1463 "type": "sign", 1464 "locations": [ 1465 "https://signing.example.com/signdoc" 1466 ], 1467 "credentialID": "60916d31-932e-4820-ba82-1fcead1c9ea3", 1468 "documentDigests": [ 1469 { 1470 "hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=", 1471 "label": "Credit Contract" 1472 }, 1473 { 1474 "hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=", 1475 "label": "Contract Payment Protection Insurance" 1476 } 1477 ], 1478 "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1" 1479 } 1480 ] 1482 The top-level elements have the following meaning: 1484 * credentialID: identifier of the certificate to be used for signing 1486 * documentDigests: array containing the hash of every document to be 1487 signed (hash elements). Additionally, the corresponding label 1488 element identifies the respective document to the user, e.g. to be 1489 used in user consent. 1491 * hashAlgorithm: algorithm that was used to calculate the hash 1492 values. 1494 The AS is supposed to ask the user for consent for the creation of 1495 signatures for the documents listed in the structure. The client 1496 uses the access token issued as a result of the process to call the 1497 sign doc endpoint at the respective signing service to actually 1498 create the signature. This access token is bound to the client, the 1499 user id and the hashes (and signature algorithm) as consented by the 1500 user. 1502 A.3. Access to Tax Data 1504 This example is inspired by an API allowing third parties to access 1505 citizen's tax declarations and income statements, for example, to 1506 determine their creditworthiness. 1508 [ 1509 { 1510 "type": "tax_data", 1511 "locations": [ 1512 "https://taxservice.govehub.no" 1513 ], 1514 "actions":"read_tax_declaration", 1515 "periods": ["2018"], 1516 "duration_of_access": 30, 1517 "tax_payer_id": "23674185438934" 1518 } 1519 ] 1521 The top-level elements have the following meaning: 1523 * periods: determines the periods the client wants to access 1525 * duration_of_access: how long does the client intend to access the 1526 data in days 1528 * tax_payer_id: identifier of the tax payer (if known to the client) 1530 A.4. eHealth 1532 These two examples are inspired by requirements for APIs used in the 1533 Norwegian eHealth system. 1535 In this use case, the physical therapist sits in front of her 1536 computer using a local Electronic Health Records (EHR) system. They 1537 want to look at the electronic patient records of a certain patient 1538 and they also want to fetch the patients journal entries in another 1539 system, perhaps at another institution or a national service. Access 1540 to this data is provided by an API. 1542 The information necessary to authorize the request at the API is only 1543 known by the EHR system, and must be presented to the API. 1545 In the first example, the authorization details object contains the 1546 identifier of an organization. In this case, the API needs to know 1547 if the given organization has the lawful basis for processing 1548 personal health information to give access to sensitive data. 1550 "authorization_details":{ 1551 "type":"patient_record", 1552 "requesting_entity": { 1553 "type": "Practitioner", 1554 "identifier": [ 1555 { 1556 "system": " urn:oid:2.16.578.1.12.4.1.4.4", 1557 "value": "1234567" 1558 }], 1559 "practitioner_role":{ 1560 "organization":{ 1561 "identifier": { 1562 "system":"urn:oid:2.16.578.1.12.4.1.2.101", 1563 "type":"ENH", 1564 "value":"[organizational number]" 1565 } 1566 } 1567 } 1568 } 1569 } 1571 In the second example, the API requires more information to authorize 1572 the request. In this case, the authorization details object contains 1573 additional information about the health institution and the current 1574 profession the user has at the time of the request. The additional 1575 level of detail could be used for both authorization and data 1576 minimization. 1578 [ 1579 { 1580 "type": "patient_record", 1581 "location": "https://fhir.example.com/patient", 1582 "actions": [ 1583 "read" 1584 ], 1585 "patient_identifier": [ 1586 { 1587 "system": "urn:oid:2.16.578.1.12.4.1.4.1", 1588 "value": "12345678901" 1589 } 1590 ], 1591 "reason_for_request": "Clinical treatment", 1592 "requesting_entity": { 1593 "type": "Practitioner", 1594 "identifier": [ 1595 { 1596 "system": " urn:oid:2.16.578.1.12.4.1.4.4", 1597 "value": "1234567" 1599 } 1600 ], 1601 "practitioner_role": { 1602 "organization": { 1603 "identifier": [ 1604 { 1605 "system": "urn:oid:2.16.578.1.12.4.1.2.101", 1606 "type": "ENH", 1607 "value": "" 1608 } 1609 ], 1610 "type": { 1611 "coding": [ 1612 { 1613 "system": 1614 "http://hl7.org/fhir/organization-type", 1615 "code": "dept", 1616 "display": "Hospital Department" 1617 } 1618 ] 1619 }, 1620 "name": "Akuttmottak" 1621 }, 1622 "profession": { 1623 "coding": [ 1624 { 1625 "system": "http://snomed.info/sct", 1626 "code": "36682004", 1627 "display": "Physical therapist" 1628 } 1629 ] 1630 } 1631 } 1632 } 1633 } 1634 ] 1636 Description of the elements: 1638 * patient_identifier: the identifier of the patient composed of a 1639 system identifier in OID format (namespace) and the actual value 1640 within this namespace. 1642 * reason_for_request: the reason why the user wants to access a 1643 certain API 1645 * requesting_entity: specification of the requester by means of 1646 identity, role and organizational context. This data is provided 1647 to facilitate authorization and for auditing purposes. 1649 In this use case, the AS authenticates the requester, who is not the 1650 patient, and approves access based on policies. 1652 Appendix B. Document History 1654 [[ To be removed from the final specification ]] 1656 -08 1658 * formatting in authorization details type section 1660 * added example for privileges common data element 1662 -07 1664 * incorporated review feedback from WGLC 1666 * fixed wording in token introspection section 1668 * added privacy considerations re authorization details in token 1669 response 1671 -06 1673 * removed use of resource indicators to filter authorization details 1674 in token response 1676 -05 1678 * added authorization_details token request parameter and discussion 1679 on authorization details comparison 1681 * added privileges field to authorization details (to align with 1682 GNAP) 1684 * added IANA text and changed metadata parameter names 1686 * added text about use of machine-readable type schemas, e.g JSON 1687 Schema 1689 * added text on how authorization details are determined for access 1690 token issued with token response 1692 * added token error response and further error conditions to 1693 authorization error response 1695 -04 1697 * restructured draft for better readability 1699 * simplified normative text about use of the resource parameter with 1700 authorization_details 1702 * added implementation considerations for deployments and products 1704 * added type union language from GNAP 1706 * added recommendation to use PAR to cope with large requests and 1707 for request protection 1709 -03 1711 * Updated references to current revisions or RFC numbers 1713 * Added section about enrichment of authorization details objects by 1714 the AS 1716 * Clarified processing of unknown authorization details parameters 1718 * clarified dependencies between resource and authorization_details 1719 parameters 1721 -02 1723 * Clarify "type" parameter processing 1725 -01 1727 * Minor fix-up in a few examples 1729 -00 (WG draft) 1731 * initial WG revision 1733 -03 1735 * Reworked examples to illustrate privacy preserving use of 1736 authorization_details 1738 * Added text on audience restriction 1739 * Added description of relationship between scope and 1740 authorization_details 1742 * Added text on token request & response and authorization_details 1744 * Added text on how authorization details are conveyed to RSs by 1745 JWTs or token introspection endpoint response 1747 * Added description of relationship between claims and 1748 authorization_details 1750 * Added more example from different sectors 1752 * Clarified string comparison to be byte-exact without collation 1754 -02 1756 * Added Security Considerations 1758 * Added Privacy Considerations 1760 * Added notes on URI size and authorization details 1762 * Added requirement to return the effective authorization details 1763 granted by the resource owner in the token response 1765 * changed authorization_details structure from object to array 1767 * added Justin Richer & Brian Campbell as Co-Authors 1769 -00 / -01 1771 * first draft 1773 Authors' Addresses 1775 Torsten Lodderstedt 1776 yes.com 1778 Email: torsten@lodderstedt.net 1780 Justin Richer 1781 Bespoke Engineering 1783 Email: ietf@justin.richer.org 1784 Brian Campbell 1785 Ping Identity 1787 Email: bcampbell@pingidentity.com