idnits 2.17.1 draft-richer-transactional-authz-05.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 : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** There are 8 instances of too long lines in the document, the longest one being 804 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 284 has weird spacing: '...tatypes types...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 18, 2020) is 1522 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) == Unused Reference: 'BCP195' is defined on line 1245, but no explicit reference was found in the text == Unused Reference: 'RFC6749' is defined on line 1282, but no explicit reference was found in the text == Unused Reference: 'RFC7519' is defined on line 1291, but no explicit reference was found in the text == Unused Reference: 'RFC7662' is defined on line 1295, but no explicit reference was found in the text == Unused Reference: 'RFC8126' is defined on line 1303, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7525 (ref. 'BCP195') (Obsoleted by RFC 9325) == Outdated reference: A later version (-04) exists of draft-fett-oauth-dpop-03 ** Obsolete normative reference: RFC 3230 (Obsoleted by RFC 9530) Summary: 4 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Richer, Ed. 3 Internet-Draft Bespoke Engineering 4 Intended status: Standards Track February 18, 2020 5 Expires: August 21, 2020 7 Transactional Authorization 8 draft-richer-transactional-authz-05 10 Abstract 12 This document defines a mechanism for delegating authorization to a 13 piece of software, and conveying that delegation to the software. 15 Requirements Language 17 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 18 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 19 "OPTIONAL" in this document are to be interpreted as described in BCP 20 14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they 21 appear in all capitals, as shown here. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on August 21, 2020. 40 Copyright Notice 42 Copyright (c) 2020 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.2. Sequence . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Transaction request . . . . . . . . . . . . . . . . . . . . . 4 61 2.1. Display . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.2. Resource . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.3. User . . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.4. Interact . . . . . . . . . . . . . . . . . . . . . . . . 7 65 2.5. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 2.6. Capabilities . . . . . . . . . . . . . . . . . . . . . . 10 67 2.7. Claims . . . . . . . . . . . . . . . . . . . . . . . . . 10 68 3. Interaction response . . . . . . . . . . . . . . . . . . . . 11 69 3.1. Redirect interaction . . . . . . . . . . . . . . . . . . 12 70 3.2. Interaction URI return . . . . . . . . . . . . . . . . . 13 71 3.3. Calculating the interaction hash . . . . . . . . . . . . 14 72 3.3.1. SHA3 . . . . . . . . . . . . . . . . . . . . . . . . 15 73 3.3.2. SHA2 . . . . . . . . . . . . . . . . . . . . . . . . 15 74 3.4. Secondary device interaction . . . . . . . . . . . . . . 15 75 4. Wait response . . . . . . . . . . . . . . . . . . . . . . . . 16 76 5. Interaction at the AS . . . . . . . . . . . . . . . . . . . . 17 77 6. Error response . . . . . . . . . . . . . . . . . . . . . . . 17 78 7. Transaction continue request . . . . . . . . . . . . . . . . 18 79 8. Transaction response . . . . . . . . . . . . . . . . . . . . 19 80 8.1. Presenting Tokens to the RS . . . . . . . . . . . . . . . 20 81 8.2. Additional user information . . . . . . . . . . . . . . . 20 82 9. Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 83 9.1. Presenting handles . . . . . . . . . . . . . . . . . . . 21 84 9.2. Validating handles . . . . . . . . . . . . . . . . . . . 21 85 9.3. Transaction handles . . . . . . . . . . . . . . . . . . . 21 86 9.4. Display handles . . . . . . . . . . . . . . . . . . . . . 21 87 9.5. Resource handles . . . . . . . . . . . . . . . . . . . . 22 88 9.5.1. Resource-first . . . . . . . . . . . . . . . . . . . 24 89 9.6. User handles . . . . . . . . . . . . . . . . . . . . . . 24 90 9.7. Key handles . . . . . . . . . . . . . . . . . . . . . . . 25 91 10. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 25 92 10.1. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 26 93 10.2. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 26 94 10.3. DPoP . . . . . . . . . . . . . . . . . . . . . . . . . . 27 95 10.4. HTTP Signing . . . . . . . . . . . . . . . . . . . . . . 27 96 10.5. OAuth PoP . . . . . . . . . . . . . . . . . . . . . . . 27 98 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 99 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 100 13. Security Considerations . . . . . . . . . . . . . . . . . . . 27 101 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 27 102 15. Normative References . . . . . . . . . . . . . . . . . . . . 28 103 Appendix A. Document History . . . . . . . . . . . . . . . . . . 29 104 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30 106 1. Protocol 108 This protocol allows a piece of software to request delegated 109 authorization to an API, protected by an authorization server usually 110 on behalf of a resource owner. 112 1.1. Parties 114 The Authorization Server (AS) manages the transactions. It is 115 defined by its transaction endpoint, a single URL that accepts a POST 116 request with a JSON payload. The AS MAY also have other endpoints, 117 including interaction endpoints and user code endpoints, and these 118 are introduced to the RC as needed during the transaction process. 120 The Resource Client (RC) requests tokens from the AS and uses tokens 121 at the RS. 123 The Resource Server (RS) accepts tokens from the RC and validates 124 them (potentially at the AS). 126 The Resource Owner (RO) authorizes the request from the RC to the RS, 127 often interactively at the AS. 129 1.2. Sequence 131 1. The RC creates a transaction request and sends it to the AS 133 2. The AS processes the transaction request and determines if the RO 134 needs to interact 136 3. If interaction is required, the AS interacts with the RO, 137 possibly by directing the RC to send the RO there 139 4. The RC continues the transaction at the AS 141 5. The AS processes the transaction again, determining that a token 142 can be issued 144 6. The AS issues a token to the RC 145 7. The RC uses the token with the RS 147 2. Transaction request 149 To start a transaction, the RC makes a transaction request to the 150 transaction endpoint of the AS. The RC creates a JSON [RFC8259] 151 document with five primary sections, included as members of a root 152 JSON object. 154 resources Information about the RS's the resulting token will be 155 applied to, including locations, extents of access, types of data 156 being accessed, and other API information. This section is 157 REQUIRED. 159 keys Information about the keys known to the RC and able to be 160 presented in future parts of the transaction. This section is 161 REQUIRED. (Note: I can't think of a good reason for this to be 162 optional.) 164 interact Information about how the RC is able to interact with the 165 RO, including callback URI's and nonce if applicable. This 166 section is REQUIRED if the RC is capable of driving interaction 167 with the user. 169 display Information about the RC making the request, including 170 display name, home page, logo, and other user-facing information. 171 This section is RECOMMENDED. 173 user Information about the RO as known to or provided to the RC, in 174 the form of assertions or references to external data. This 175 section is OPTIONAL. 177 claims Information about the RO as known to or provided to the AS 178 being requested by the RS. This section is OPTIONAL. 180 capabilities Information about the capabilities of the RC. This 181 section is OPTIONAL. 183 Each section consists of either a JSON object or an array of JSON 184 objects, as described in the subsections below. Many sections MAY be 185 represented by an appropriate handle instead as described in 186 Section 9. In such cases, the section is replaced entirely by the 187 handle presentation, which is a single string instead of a JSON 188 object. The RC MAY present additional sections as defined by 189 extensions of this specification. The AS MUST ignore any sections 190 that it does not understand. 192 A non-normative example of a transaction request is below: 194 { 195 "resources": [ 196 { 197 "actions": [ 198 "read", 199 "write", 200 "dolphin" 201 ], 202 "locations": [ 203 "https://server.example.net/", 204 "https://resource.local/other" 205 ], 206 "datatypes": [ 207 "metadata", 208 "images" 209 ] 210 }, 211 "dolphin-metadata" 212 ], 213 "key": { 214 "proof": "jwsd", 215 "jwks": { 216 "keys": [ 217 { 218 "kty": "RSA", 219 "e": "AQAB", 220 "kid": "xyz-1", 221 "alg": "RS256", 222 "n": "kOB5rR4Jv0GMeL...." 223 } 224 ] 225 } 226 }, 227 "interact": { 228 "redirect": true, 229 "callback": { 230 "uri": "https://client.example.net/return/123455", 231 "nonce": "LKLTI25DK82FX4T4QFZC" 232 } 233 }, 234 "display": { 235 "name": "My Client Display Name", 236 "uri": "https://example.net/client" 237 }, 238 "capabilities": 239 ["ext1", "ext2"], 240 "claims": { 241 "subject": true, 242 "email": true, 243 "oidc_id_token": true 244 } 245 } 247 2.1. Display 249 This section provides descriptive details of the RC software making 250 the call, useful for displaying information about the client to the 251 user during the authorization request. This section is a JSON 252 object, and all fields are OPTIONAL. The RC MAY send additional 253 fields, and the AS MUST ignore all fields that it does not 254 understand. 256 name Display name of the RC software 258 uri User-facing web page of the RC software 260 logo_uri Display image to represent the RC software 262 "display": { 263 "name": "My Client Display Name", 264 "uri": "https://example.net/client" 265 } 267 The AS SHOULD use this information in presenting any authorization 268 screens to the RO during interaction. 270 The display information MAY instead be presented as a display handle 271 reference Section 9.4. 273 2.2. Resource 275 This section identifies what the RC wants to do with the API hosted 276 at the RS. This section is a JSON array of objects, each object 277 representing a single resource or resource set. That AS MUST 278 interpret the request as being for all of the resources listed. 280 actions The types of actions the RC will take at the RS 282 locations URIs the RC will call at the RS 284 datatypes types of data available to the RC at the RS's API 285 "resources": [ 286 { 287 "actions": [ 288 "read", 289 "write", 290 "dolphin" 291 ], 292 "locations": [ 293 "https://server.example.net/", 294 "https://resource.local/other" 295 ], 296 "datatypes": [ 297 "metadata", 298 "images" 299 ] 300 }, 301 "dolphin-metadata" 302 ] 304 This can also be presented as a set of resource handle references 305 Section 9.5, or a combination of handles and resource structures. 307 2.3. User 309 This section provides a verifiable assertion about the person 310 interacting with the RC on behalf of the request. This person MAY be 311 the RO or MAY be another party. 313 assertion The value of the assertion as a string. 315 type The type of the assertion. Possible values include 316 "oidc_id_token"... 318 "user": { 319 "assertion": "eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUlMyNTYifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAsCiAibmFtZSI6ICJKYW5lIERvZSIsCiAiZ2l2ZW5fbmFtZSI6ICJKYW5lIiwKICJmYW1pbHlfbmFtZSI6ICJEb2UiLAogImdlbmRlciI6ICJmZW1hbGUiLAogImJpcnRoZGF0ZSI6ICIwMDAwLTEwLTMxIiwKICJlbWFpbCI6ICJqYW5lZG9lQGV4YW1wbGUuY29tIiwKICJwaWN0dXJlIjogImh0dHA6Ly9leGFtcGxlLmNvbS9qYW5lZG9lL21lLmpwZyIKfQ.rHQjEmBqn9Jre0OLykYNnspA10Qql2rvx4FsD00jwlB0Sym4NzpgvPKsDjn_wMkHxcp6CilPcoKrWHcipR2iAjzLvDNAReF97zoJqq880ZD1bwY82JDauCXELVR9O6_B0w3K-E7yM2macAAgNCUwtik6SjoSUZRcf-O5lygIyLENx882p6MtmwaL1hd6qn5RZOQ0TLrOYu0532g9Exxcm-ChymrB4xLykpDj3lUivJt63eEGGN6DH5K6o33TcxkIjNrCD4XB1CKKumZvCedgHHF3IAK4dVEDSUoGlH9z4pP_eWYNXvqQOjGs-rDaQzUHl6cQQWNiDpWOl_lxXjQEvQ", 320 "type": "oidc_id_token" 321 } 323 This can also be presented as a user handle reference Section 9.6. 325 2.4. Interact 327 This section provides details of how the RC can interact with the RO. 328 All fields are OPTIONAL, and the RC MAY include multiple possible 329 interaction modes. If a field is not present, it is interpreted as 330 negative support for that feature. 332 callback If this object is present, it indicates the RC is capable 333 of receiving inbound messages from the RO's browser in response to 334 user interaction. This object contains the following fields: 336 uri REQUIRED. Indicates the URI to send the RO to after 337 interaction. This URI MAY be unique per transaction and MUST 338 be hosted or accessible by the RC. This URI MUST NOT contain 339 any fragment component. This URI MUST be protected by HTTPS, 340 be hosted on a server local to the user's browser 341 ("localhost"), or use an application-specific URI scheme. If 342 the RC needs any state information to tie to the front channel 343 interaction response, it MUST encode that into the callback 344 URI. The allowable URIs and URI patterns MAY be limited by the 345 AS based on the RC's presented key information. The callback 346 URI SHOULD be presented to the RO during the interaction phase 347 before redirect. 349 nonce REQUIRED. Unique value to be used in the calculation of 350 the "hash" query parameter on the callback URL, must be 351 sufficiently random to be unguessable by an attacker. MUST be 352 generated by the RC as a unique value for this transaction. 354 hash_method OPTIONAL. The signature mechanism to be used for the 355 callback hash in Section 3.3. Can be one of sha3 or sha2. If 356 absent, the default value is sha3. 358 redirect If this is set to true, the RC is capable of redirecting 359 the RO to an arbitrary interaction URL as described in Section 5. 360 The RC MAY communicate the URI to the user through a browser 361 redirection, a QR code, or some other mechanism. 363 user_code If this is set to true, the RC is capable of displaying a 364 short user code to the user and directing them to a fixed URL as 365 described in Section 5. 367 didcomm If this is set to true, the RC is capable of relaying a 368 DIDComm message to an agent or wallet. 370 didcomm_query If this is set to true, the RC is capable of relaying 371 a DIDComm query to an agent or wallet. 373 This section MUST NOT be represented by a handle reference. (Note: 374 this decision is largely due to the "callback" section being variable 375 per transaction. We could allow a handle but restrict it to non- 376 callback methods -- but in that case, it's simpler and shorter to 377 just send the booleans instead of having a special case.) 378 The following example is from an RC that can redirect to the 379 interaction endpoint and receive returns on a callback URI: 381 "interact": { 382 "redirect": true, 383 "callback": { 384 "uri": "https://example.com/client/123456", 385 "nonce": "VJLO6A4CAYLBXHTR0KRO" 386 } 387 } 389 2.5. Keys 391 This section lists the keys that the RC can present proof of 392 ownership. The RC MUST send at least one key format. The RC MAY 393 send more than one key format, but all keys MUST be equivalent. 395 proof The form of proof that the RC will use when presenting the key 396 to the AS. The valid values of this field and the processing 397 requirements for each are detailed in Section 10. This field is 398 REQUIRED. 400 jwks Value of the public key as a JWK Set JSON object [Note: should 401 this be a single JWK instead? And do we want to bother with url- 402 based references?]. MUST contain an "alg" field which is used to 403 validate the signature. MUST contain the "kid" field to identify 404 the key in the signed object. 406 cert PEM serialized value of the certificate used for TLS 407 transactions, with optional internal whitespace. 409 cert#256 The certificate thumbprint calculated as per OAuth-MTLS 410 [I-D.ietf-oauth-mtls]. 412 did The DID URL identifying the key (or keys) used to sign this 413 request. 415 The RC MUST provide proof of possession of all presented 416 keysSection 10. All presented keys MUST be validated by the AS using 417 the method defined by proof. 419 This section MAY also be presented as a key handle reference 420 Section 9.7. The keys referenced by a handle MUST be validated by 421 the AS. 423 The following non-normative example shows three key types, with the 424 detached JWS proofing mechanism: 426 "keys": { 427 "proof": "jwsd", 428 "jwks": { 429 "keys": [ 430 { 431 "kty": "RSA", 432 "e": "AQAB", 433 "kid": "xyz-1", 434 "alg": "RS256", 435 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 436 } 437 ] 438 }, 439 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA...", 440 "did": "did:example:CV3BVVXK2PWWLCRQLRFU#xyz-1" 441 } 443 2.6. Capabilities 445 This section lists the extensions and special features supported by 446 the RC. Values of extensions MUST be listed in [[ a registry ]]. 448 "capabilities": ["ext1", "ext2"] 450 2.7. Claims 452 This section allows the RC to request identity and authentication 453 information about the RO. All fields are OPTIONAL and consist of 454 boolean values. A "true" value indicates that the RC is requesting 455 that claim be returned in the transaction response. A "false" or 456 omitted value indicates that the RC is not requesting that claim be 457 returned. 459 subject A subject identifier for the current user. 461 email An email address for the current user. 463 phone A phone number for the current user. 465 oidc_id_token An OpenID Connect ID Token for the current user. 467 The following non-normative example shows how to request the subject 468 and email address of the current user. 470 "claims": { 471 "subject": true, 472 "email": true 473 } 475 3. Interaction response 477 When evaluating a transaction request, the AS MAY determine that it 478 needs to have the RO present to interact with the AS before issuing a 479 token. This interaction can include the RO logging in to the AS, 480 authorizing the transaction, providing proof claims, determining if 481 the transaction decision should be remembered for the future, and 482 other items. 484 The AS responds to the RC based on the type of interaction supported 485 by the RC in the transaction request. The AS MAY respond with 486 multiple possible interaction methods to be chosen by the RC. For 487 example, if the RC indicates that it can handle redirects and user 488 codes and has a callback URI, it would send a transaction request 489 like this: 491 { 492 "interact": { 493 "redirect": true, 494 "user_code": true, 495 "callback": { 496 "uri": "https://client.example.net/return/123455", 497 "nonce": "LKLTI25DK82FX4T4QFZC" 498 } 499 }, 500 "resources": [ 501 "dolphin-metadata" 502 ], 503 "key": "7C7C4AZ9KHRS6X63AJAO", 504 "display": { 505 "name": "My Client Display Name", 506 "uri": "https://example.net/client" 507 } 508 } 510 The AS would then respond with a transaction response like this: 512 { 513 "interaction_url": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 514 "server_nonce": "MBDOFXG4Y5CVJCX821LH", 515 "user_code": { 516 "url": "https://server.example.com/interact/device", 517 "code": "A1BC-3DFF" 518 }, 519 "handle": { 520 "value": "80UPRY5NM33OMUKMKSKU", 521 "type": "bearer" 522 } 523 } 525 This response MUST include a transaction handle as described in 526 Section 9.3 so that the transaction can continue after the user has 527 interacted. 529 3.1. Redirect interaction 531 If the RC supports a "redirect" style interaction, the AS creates a 532 unique interaction URL and returns it to the RC. This URL MUST be 533 associated with the current transaction and no other transaction. 535 interaction_url REQUIRED. The interaction URL that the RC will 536 direct the RO to. This URL MUST be unique to this transaction 537 request. The URL SHOULD contain a random portion of sufficient 538 entropy so as not to be guessable by the user. The URL MUST NOT 539 contain the transaction handle or any RC identifying information. 540 This URL MUST be protected by HTTPS. This URL MUST NOT contain 541 any fragment component. 543 handle REQUIRED. The transaction handle to use in the continue the 544 transaction Section 7. 546 { 547 "interaction_url": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 548 "handle": { 549 "value": "80UPRY5NM33OMUKMKSKU", 550 "type": "bearer" 551 } 552 } 554 When the RC receives this response, it MUST launch the system 555 browser, redirect the RO through an HTTP 302 response, display the 556 URL through a scannable barcode, or otherwise send the RO to the 557 interaction URL. The RC MUST NOT modify the interaction URL or 558 append anything to it, including any query parameters, fragments, or 559 special headers. 561 The interaction URL MUST be reachable from the RO's browser, though 562 note that the RO MAY open the interaction URL on a separate device 563 from the RC itself. The interaction URL MUST be accessible from an 564 HTTP GET request, and MUST be protected by HTTPS or equivalent means. 566 Upon receiving an incoming request at the interaction URL, the AS 567 MUST determine the transaction associated with this unique URL. If 568 the transaction is not found, an error is returned to the end user 569 through the browser and the AS MUST NOT attempt to redirect to a 570 callback URL. When interacting with the RO, the AS MAY perform any 571 of the behaviors in the User Interaction section Section 5. 573 3.2. Interaction URI return 575 If the RC has supplied a callback URL in its interact request 576 Section 2.4, the AS returns a nonce in its interaction response. 578 server_nonce REQUIRED. A unique value from the server included in 579 the calculation of the "hash" value returned in the callback 580 response. REQUIRED if the client has sent a "callback" parameter 581 in its interaction request. 583 This example also includes the interaction URL from Section 3.1. 585 { 586 "interaction_url": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 587 "server_nonce": "MBDOFXG4Y5CVJCX821LH", 588 "handle": { 589 "value": "80UPRY5NM33OMUKMKSKU", 590 "type": "bearer" 591 } 592 } 594 When interaction has concluded, the AS returns the user to the RC by 595 redirecting the RO's browser to the RC's callback URL presented at 596 the start of the transaction, with the addition of two query 597 parameters. 599 hash REQUIRED. The interaction hash value as described in 600 Section 3.3. 602 interact_ref REQUIRED. A shared secret associated with this 603 interaction. This value MUST be sufficiently random so as not to 604 be guessable by an attacker. This value MUST be associated by the 605 AS with the underlying transaction that is associated to with this 606 interaction. 608 The AS MUST properly process the callback parameter from the 609 interaction request as a URL, adding these values as query 610 parameters. The AS MUST NOT use simple string concatenation. For 611 example, for the callback URL of "https://example.com/client/123456", 612 the AS would add query parameters as follows (newlines added for 613 display purposes only): 615 https://example.com/client/123456 616 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 617 &interact_ref=4IFWWIKYBC2PQ6U56NL1 619 Upon processing this request to the callback URL, the RC MUST 620 calculate the expected value of the "hash" parameter as described in 621 Section 3.3 and compare that value to the "hash" parameter on the 622 incoming request. 624 The RC also sends (the hash of? example here is not hashed) the 625 interaction reference as the "interact_ref" field of the transaction 626 continuation requestSection 7, using the transaction handle 627 Section 9.3 returned in the most recent transaction response from the 628 AS. 630 { 631 "handle": "80UPRY5NM33OMUKMKSKU", 632 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 633 } 635 3.3. Calculating the interaction hash 637 The "hash" parameter in the interaction response ties the front 638 channel response to a transaction by using values known only to the 639 parties in the transaction. To calculate the "hash" value for the 640 interaction response, the party doing the calculation first takes the 641 "nonce" value sent by the RC in the interaction section of the 642 initial transaction request Section 2.4, the "server_nonce" value 643 returned in the transaction response Section 3.2, and the 644 "interact_ref" returned in the callback response Section 3.2. These 645 three values are concatenated to each other in this order using a 646 single newline character as a separator between the fields. There is 647 no padding or whitespace before or after any of the lines, and no 648 trailing newline character. 650 VJLO6A4CAYLBXHTR0KRO 651 MBDOFXG4Y5CVJCX821LH 652 4IFWWIKYBC2PQ6U56NL1 654 The party then hashes this string with the appropriate algorithm 655 based on the "hash_method" parameter of the "callback" section of the 656 interaction request (Section 2.4). If the "hash_method" value is not 657 present in the RC's request, the AS defaults to "sha3". 659 3.3.1. SHA3 661 The "sha3" hash method consists of hashing the string with the 662 512-bit SHA3 algorithm. The byte array is then encoded using URL 663 Safe Base64 with no padding. The resulting string is the hash value. 665 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 667 3.3.2. SHA2 669 The "sha2" hash method consists of hashing the string with the 670 512-bit SHA2 algorithm. The byte array is then encoded using URL 671 Safe Base64 with no padding. The resulting string is the hash value. 673 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bpj84rh4mC9aE9x7HPBFcIHw 675 3.4. Secondary device interaction 677 If the RC supports a "user_code" style interaction, the AS creates a 678 unique user interaction code and returns it to the RC. The RC 679 communicates this code to the RO and instructs the RO to enter the 680 code at a URL hosted by the AS. 682 user_code REQUIRED. An object containing the user code information. 684 user_code REQUIRED. A short code that the user can type into an 685 authorization server. This string MUST be case-insensitive, 686 MUST consist of only easily typeable characters (such as 687 letters or numbers). The time in which this code will be 688 accepted SHOULD be short lived, such as several minutes. 690 user_code_url RECOMMENDED. The interaction URL that the RC will 691 direct the RO to. This URL SHOULD be stable at the AS such 692 that clients can be statically configured with it. 694 wait RECOMMENDED. The amount of time to wait before polling again, 695 in integer seconds. If not specified, the default is 30 seconds. 696 See Section 4. 698 handle REQUIRED. The transaction handle to use in the continue 699 request. See the section on transaction handlesSection 9.3. 701 { 702 "user_code": { 703 "url": "https://server.example.com/interact/device", 704 "code": "A1BC-3DFF" 705 }, 706 "wait": 30, 707 "handle": { 708 "value": "80UPRY5NM33OMUKMKSKU", 709 "type": "bearer" 710 } 711 } 713 When the RC receives this response, it MUST communicate the user code 714 to the RO. If possible the RC SHOULD communicate the interaction URL 715 to the user as well. However, the URL is generally understood to be 716 stable over time for a given service, and this URL MAY be 717 communicated through a static means such as the device's 718 documentation or packaging. 720 When the RO enters the unique user code at the user code URL, the AS 721 MUST determine which active transaction is associated with the user 722 code. If a transaction is not found, the AS MUST return an error 723 page to the user and MUST NOT attempt to redirect to a callback URL. 724 The AS MAY use any mechanism to interact with the RO as listed in 725 Section 5. 727 Note that this method is strictly for allowing the user to enter a 728 code at a static URL. If the AS wishes to communicate a pre-composed 729 URL to the RO containing both the user code and the URL at which to 730 enter it, the AS MUST use the "interaction_url" Section 3.1 redirect 731 mechanism instead as this allows the client to communicate an 732 arbitrary interaction URL to the RO. 734 4. Wait response 736 If the AS needs the RC to wait before it can give a definitive 737 response to a transaction continue requestSection 7, the AS replies 738 to the transaction request with a wait response. This tells the RC 739 that it can poll the transaction after a set amount of time. 741 This response includes a transaction handle as in Transaction Handle 742 Section 9.3. 744 wait REQUIRED. The amount of time to wait before polling again, in 745 integer seconds. 747 handle REQUIRED. The transaction handle to use in the continue 748 request. This MUST be a newly-created handle and MUST replace any 749 existing handle for this transaction. See the section on 750 transaction handles. 752 { 753 "wait": 30, 754 "handle": { 755 "value": "80UPRY5NM33OMUKMKSKU", 756 "type": "bearer" 757 } 758 } 760 5. Interaction at the AS 762 When the RO is interacting with the AS at the interaction uri, the AS 763 MAY perform whatever actions it sees fit, including but not limited 764 to: 766 o authenticate the RO 768 o gather identity claims about the RO 770 o gather consent and authorization from the RO 772 o allow the RO to modify the parameters of the requested transaction 773 (such as disallowing some requested resources) 775 When the AS has concluded interacting with the RO, the AS MUST 776 determine if the RC has registered a callback URL and nonce parameter 777 for this transaction. If so, the AS MUST redirect the RO's browser 778 to the callback URL as described in Section 3. If the AS detects an 779 error condition, such as an unknown transaction, an untrustworthy 780 callback URL, an untrustworthy client, or suspicious RO behavior, the 781 AS MUST return an error to the RO's browser and MUST NOT redirect to 782 the callback URL. 784 6. Error response 786 If the AS determines that the token cannot be issued for any reason, 787 it responds to the RC with an error message. This message does not 788 include a transaction handle, and the RC can no longer poll for this 789 transaction. The RC MAY create a new transaction and start again. 791 error The error code. 793 { 795 "error": "user_denied" 797 } 799 TODO: we should have a more robust error mechanism. Current 800 candidate list of errors: 802 user_denied The RO denied the transaction request. 804 too_fast The RC did not respect the timeout in the wait response. 806 unknown_transaction The transaction continuation request referenced 807 an unknown transaction. 809 unknown_handle The request referenced an unknown handle. 811 7. Transaction continue request 813 Once a transaction has begun, the AS associates that transaction with 814 a transaction handleSection 9.3 which is returned to the RC in one of 815 the transaction responses Section 3.1, Section 3.4, Section 4. This 816 handle MUST be unique, MUST be associated with a single transaction, 817 and MUST be one time use. 819 The RC continues the transaction by making a request with the 820 transaction handle in the body of the request. The RC MAY add 821 additional fields to the transaction continuation request, such as 822 the interaction reference return in the callback response Section 3. 824 handle REQUIRED. The (hash of?) transaction handle indicating which 825 transaction to continue. 827 interaction_ref OPTIONAL. If the RC has received an interaction 828 reference from the callback response of the interaction URL, the 829 RC MUST include the (hash of?) that reference in its transaction 830 continue request. 832 { 834 "handle": "tghji76ytghj9876tghjko987yh" 836 } 838 The RC MUST prove all keys initially sent in the transaction 839 requestSection 2.5 as described in Section 10. 841 [[ Note: should we allow the client to mutate the transaction at this 842 point? We already allow the presentation of the interaction handle, 843 and any messaging protocols like DIDComm would allow additional work 844 to be done here. But do we want the client to be able to specify 845 additional resources, or new interaction methods, or anything like 846 that? I'm inclined not to so that's been left out for now. ]] 848 8. Transaction response 850 access_token The access token that the RC uses to call the RS. The 851 access token follows the handle structure described in Section 9. 853 handle The transaction handle to use in the continue 854 requestSection 7 to get a new access token once the one issued is 855 no longer usable. See the section on transaction 856 handlesSection 9.3. 858 claims The set of claims that the AS asserts for the current user. 859 This field is returned only if the RC has requested using the 860 "claims" object. This object contains the following OPTIONAL 861 fields: 863 updated_at ISO-formatted timestamp string of when the user's 864 profile information was last updated. The RC SHOULD compare 865 this value to previous values when determining whether to get 866 additional user information from an external endpoint. 868 subject The machine-readable unique subject identifier of the 869 user. 871 email The email address of the user. 873 phone The phone number of the user. 875 oidc_id_token An OpenID Connect ID Token representing the user. 877 { 878 "access_token": { 879 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 880 "type": "bearer" 881 }, 882 "handle": { 883 "value": "80UPRY5NM33OMUKMKSKU", 884 "type": "bearer" 885 }, 886 "claims": { 887 "subject": "UR64TB8N6BW7OZB8CDFONP-MHKUR6", 888 "email": "alice@example.com" 889 } 890 } 892 8.1. Presenting Tokens to the RS 894 A bearer style access token MUST be presented using the Header method 895 of OAuth 2 Bearer Tokens [RFC6750]. A sha3 style access token is 896 hashed as described in Section 9.1 and presented using the Header 897 method of OAuth 2 Bearer Tokens [RFC6750]. 899 An access token MAY be bound to any keys presented by the client 900 during the transaction request. A bound access token MUST be 901 presented with proof of the key as described in Section 10. 903 8.2. Additional user information 905 Additional user information MAY be made available to the RC through 906 use of an access token at a protected resource representing the user. 907 This endpoint could be an OpenID Connect UserInfo Endpoint, a SCIM 908 endpoint, or another similar resource. Specification of this 909 resource is outside the scope of this specification. 911 9. Handles 913 A handle in this protocol is a value presented from one party to 914 another as proof that they are the appropriate party for part of the 915 transaction. Handles can be used to reference the transaction as a 916 whole, or one of its constituent parts. When a handle is used to 917 represent a part of a transaction request, the handle presentation 918 replaces the original value. In practical terms, this often means 919 that the values of a transaction request are either an object (when 920 the full value is used) or a single string (when the handle is used). 922 value The value of the handle as a string. 924 method The verification method, MUST be one of "bearer" or "sha3". 926 9.1. Presenting handles 928 Bearer handles are presented by giving the exact string value of the 929 handle in the appropriate place. 931 SHA3 handles are validated by taking the SHA3 hash of the handle 932 value and encoding it in Base64URL with no padding, and presenting 933 the encoded value. 935 9.2. Validating handles 937 Bearer handles are validated by doing an exact byte comparison of the 938 string representation of the handle value. 940 SHA3 handles are validated by taking the SHA3 hash of the handle 941 value and encoding it in Base64URL with no padding, and comparing 942 that using an exact byte comparison with the presented value. 944 9.3. Transaction handles 946 Transaction handles are issued by the AS to the RC to allow the RC to 947 continue a transaction after every step. A transaction handle MUST 948 be discarded after it is used by both the AS and the RC. A 949 transaction MUST have only a single handle associated with it at any 950 time. If the AS determines that the RC can still continue the 951 transaction after a handle has been used, a new transaction handle 952 will be issued in its place. If the AS does not issue a transaction 953 handle in its response to the RC, the RC MUST NOT continue that 954 transaction. 956 Transaction handles always represent the current state of the 957 transaction which they reference. 959 Transactions can be continued by the RC if the AS needs to interact 960 with the ROSection 5 and the RC is expecting a callbackSection 3 or 961 if the AS is still waiting on some external conditionSection 4 while 962 the RC is polling. The transaction MAY also be continued after an 963 access token is issued Section 8 as a means of refreshing an access 964 token with the same rights associated with the transaction. 966 9.4. Display handles 968 RC handles stand in for the display section of the initial 969 transaction requestSection 2.1. The AS MAY issue a display handle to 970 a RC as part of a static registration process, analogous to a client 971 ID in OAuth 2, allowing the RC to be associated with an AS-side 972 configuration that does not change at runtime. Such static processes 973 SHOULD be bound to a set of keys known only to the RC software. 975 Display handles MAY be issued by the RS in response to a transaction 976 request. The AS MAY associate the display handle to the interact, 977 resource, and key handles issued in the same response, requiring them 978 to be used together. When the RC receives this handle, it MAY 979 present the handle in future transaction requests instead of sending 980 its information again. 982 { 983 "handle": { 984 "value": "80UPRY5NM33OMUKMKSKU", 985 "type": "bearer" 986 }, 987 "display_handle": { 988 "value": "VBUEOIQA82PBY2ZDJW7Q", 989 "type": "bearer" 990 } 991 } 993 The RC sends its handle in lieu of the display block of the 994 transaction request: 996 { 998 "display": "absc2948afgdkjnasdf9082ur3kjasdfasdf89" 1000 } 1002 9.5. Resource handles 1004 Resource handles stand in for the detailed resource request in the 1005 transaction requestSection 2.2. Resource handles MAY be created by 1006 the authorization server as static stand-ins for specific resource 1007 requests, analogous to OAuth2 scopes. 1009 Resource handles MAY be issued by the RS in response to a transaction 1010 request. In such cases, the resource handle returned represents the 1011 total of all resources 1012 { 1013 "wait": 30, 1014 "handle": { 1015 "value": "80UPRY5NM33OMUKMKSKU", 1016 "type": "bearer" 1017 }, 1018 "resources_handle": { 1019 "value": "KLKP36N7GPOKRF3KGH5N", 1020 "type": "bearer" 1021 } 1022 } 1024 The RC sends its handle in lieu of the resource block of the future 1025 transaction request: 1027 { 1029 "resources": ["KLKP36N7GPOKRF3KGH5N"] 1031 } 1033 Note that handles and object values MAY be combined in a single 1034 request. 1036 { 1037 "resources": [ 1038 { 1039 "actions": [ 1040 "read", 1041 "write", 1042 "dolphin" 1043 ], 1044 "locations": [ 1045 "https://server.example.net/", 1046 "https://resource.local/other" 1047 ], 1048 "datatypes": [ 1049 "metadata", 1050 "images" 1051 ] 1052 }, 1053 "dolphin-metadata", 1054 "KLKP36N7GPOKRF3KGH5N" 1055 ] 1056 } 1058 9.5.1. Resource-first 1060 [[ Strawman idea: ]] 1062 In order to facilitate dynamic API protection, an RS MAY pre-register 1063 a resource handle in response to an unauthorized request from the RC. 1064 In this scenario, the RS creates a transaction request with no client 1065 information but describing the resources being protected [[Note: this 1066 is currently at odds with the required format above, perhaps this 1067 should be a special mode or flag? We could still use the "keys" 1068 section here though.]] The AS returns a resource handle to the RS, 1069 which then communicates both the resource handle and the AS 1070 transaction endpoint to the RC. The RC then begins its transaction 1071 as normal, using the resource handle as one of perhaps several 1072 resources it requests. 1074 9.6. User handles 1076 User handles MAY be issued by the AS in response to validating a 1077 specific RO during a transaction and stand in for the user section of 1078 a transaction requestSection 2.3. This handle MAY refer to the RO 1079 that interacted with the AS, the user presented by claims in the 1080 transaction request, or a combination of these. This handle can be 1081 used in future transactions to represent the current user, analogous 1082 to the persistent claims token of UMA 2. 1084 { 1085 "wait": 30, 1086 "handle": { 1087 "value": "80UPRY5NM33OMUKMKSKU", 1088 "type": "bearer" 1089 }, 1090 "user_handle": { 1091 "value": "XUT2MFM1XBIKJKSDU8QM", 1092 "type": "bearer" 1093 } 1094 } 1096 The RC sends its handle in lieu of the user block of the transaction 1097 request: 1099 { 1101 "user": "XUT2MFM1XBIKJKSDU8QM" 1103 } 1105 9.7. Key handles 1107 Key handles stand in for the keys section of the initial transaction 1108 requestSection 2.5. The AS MAY issue a key handle to a RC as part of 1109 a static registration process, allowing the RC to be associated with 1110 an AS-side configuration that does not change at runtime. 1112 Key handles MAY be issued by the AS in response to a transaction 1113 request. The AS SHOULD bind this handle to the display, resource, 1114 and user handles issued in the same response. When the RC receives 1115 this handle, it MAY present the handle in future transaction requests 1116 instead of sending its information again. 1118 { 1119 "wait": 30, 1120 "handle": { 1121 "value": "80UPRY5NM33OMUKMKSKU", 1122 "type": "bearer" 1123 }, 1124 "key_handle": { 1125 "value": "7C7C4AZ9KHRS6X63AJAO", 1126 "type": "bearer" 1127 } 1128 } 1130 The RC sends its handle in lieu of the keys block of the transaction 1131 request: 1133 { 1135 "keys": "7C7C4AZ9KHRS6X63AJAO" 1137 } 1139 When the AS receives a key handle, it MUST validate that the keys 1140 referenced by the handle are bound to the current transaction request 1141 using the proof method referenced by the handle. 1143 10. Binding Keys 1145 Any keys presented by the RC to the AS or RS MUST be validated as 1146 part of the transaction in which they are presented.The type of 1147 binding used is indicated by the proof parameter of the keys section 1148 in the transaction request. Values defined by this specification are 1149 as follows: 1151 jwsd A detached JWS signature header 1152 mtls Mutual TLS certificate verification 1154 dpop OAuth DPoP key proof header 1156 httpsig HTTP Signing signature header 1158 oauthpop OAuth PoP key proof authentication header 1160 Additional values can be defined by a registry. 1162 All keys presented by the RC in the transaction requestSection 2 MUST 1163 be proved in all transaction continuation requestsSection 7 for that 1164 transaction. The AS MUST validate all keys presented by the RC or 1165 referenced in the transaction at each call to the transaction 1166 endpoint. The client MUST NOT use a different key during the 1167 transaction. 1169 10.1. Detached JWS 1171 This method is indicated by "jwsd" in the "proof" field of a key 1172 request. To sign a request to the transaction endpoint, the RC takes 1173 the serialized body of the request and signs it using detached JWS 1174 [RFC7797]. The header of the JWS MUST contain the kid field of the 1175 key bound to this RC during this transaction. The JWS header MUST 1176 contain an alg field appropriate for the key identified by kid and 1177 MUST NOT be none. 1179 The RC presents the signature in the JWS-Signature HTTP Header field. 1180 [Note: this is a custom header field, do we need this?] 1182 JWS-Signature: eyj0.... 1184 When the AS receives the JWS-Signature header, it MUST parse its 1185 contents as a detached JWS object. The HTTP Body is used as the 1186 payload for purposes of validating the JWS, with no transformations. 1188 10.2. Mutual TLS 1190 This method is indicated by "mtls" in the "proof" field of a key 1191 request. The RC presents its client certificate during TLS 1192 negotiation with the server (either AS or RS). The AS or RS takes 1193 the thumbprint of the client certificate presented during mutual TLS 1194 negotiation and compares that thumbprint to the thumbprint presented 1195 by the RC application as described in [I-D.ietf-oauth-mtls] section 1196 3. 1198 10.3. DPoP 1200 This method is indicated by "dpop" in the "proof" field of a key 1201 request. The RC creates a DPoP signature header as described in 1202 [I-D.fett-oauth-dpop] section 2. 1204 10.4. HTTP Signing 1206 This method is indicated by "httpsig" in the "proof" field of a key 1207 request. The RC creates an HTTP Signature header as described in 1208 [I-D.cavage-http-signatures] section 4. The RC MUST calculate and 1209 present the Digest header as defined in [RFC3230]. 1211 10.5. OAuth PoP 1213 This method is indicated by "oauthpop" in the "proof" field of a key 1214 request. The RC creates an HTTP Authorization PoP header as 1215 described in [I-D.ietf-oauth-signed-http-request] section 4, with the 1216 following additional requirements: 1218 o The at (access token) field MUST be omitted [note: this is in 1219 contrast to the requirements in the existing spec] 1221 o The b (body hash) field MUST be calculated and supplied 1223 11. Acknowledgements 1225 12. IANA Considerations 1227 [We'll want a registry for key proof types, and maybe some other 1228 field names. We'll need to register at least one header and maybe 1229 some others?] 1231 13. Security Considerations 1233 All requests have to be over TLS or equivalent. Many handles act as 1234 shared secrets, though they can be combined with a requirement to 1235 provide proof of a key as well. 1237 14. Privacy Considerations 1239 Handles are passed between parties and therefore should be stateful 1240 and not contain any internal structure or information, which could 1241 leak private data. 1243 15. Normative References 1245 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 1246 "Recommendations for Secure Use of Transport Layer 1247 Security (TLS) and Datagram Transport Layer Security 1248 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1249 2015, . 1251 [I-D.cavage-http-signatures] 1252 Cavage, M. and M. Sporny, "Signing HTTP Messages", draft- 1253 cavage-http-signatures-12 (work in progress), October 1254 2019. 1256 [I-D.fett-oauth-dpop] 1257 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 1258 Jones, M., and D. Waite, "OAuth 2.0 Demonstration of 1259 Proof-of-Possession at the Application Layer (DPoP)", 1260 draft-fett-oauth-dpop-03 (work in progress), October 2019. 1262 [I-D.ietf-oauth-mtls] 1263 Campbell, B., Bradley, J., Sakimura, N., and T. 1264 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 1265 and Certificate-Bound Access Tokens", draft-ietf-oauth- 1266 mtls-17 (work in progress), August 2019. 1268 [I-D.ietf-oauth-signed-http-request] 1269 Richer, J., Bradley, J., and H. Tschofenig, "A Method for 1270 Signing HTTP Requests for OAuth", draft-ietf-oauth-signed- 1271 http-request-03 (work in progress), August 2016. 1273 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1274 Requirement Levels", BCP 14, RFC 2119, 1275 DOI 10.17487/RFC2119, March 1997, 1276 . 1278 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 1279 RFC 3230, DOI 10.17487/RFC3230, January 2002, 1280 . 1282 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1283 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1284 . 1286 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1287 Framework: Bearer Token Usage", RFC 6750, 1288 DOI 10.17487/RFC6750, October 2012, 1289 . 1291 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1292 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1293 . 1295 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1296 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1297 . 1299 [RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload 1300 Option", RFC 7797, DOI 10.17487/RFC7797, February 2016, 1301 . 1303 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1304 Writing an IANA Considerations Section in RFCs", BCP 26, 1305 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1306 . 1308 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1309 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1310 May 2017, . 1312 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1313 Interchange Format", STD 90, RFC 8259, 1314 DOI 10.17487/RFC8259, December 2017, 1315 . 1317 Appendix A. Document History 1319 -05 1321 o Added "claims" request and response for identity support. 1323 o Added "capabilities" request for inline discovery support. 1325 - 04 1327 o Added crypto agility for callback return hash. 1329 o Changed "interaction_handle" to "interaction_ref". 1331 - 03 1333 o Removed "state" in favor of "nonce". 1335 o Created signed return parameter for front channel return. 1337 o Changed "client" section to "display" section, as well as 1338 associated handle. 1340 o Changed "key" to "keys". 1342 o Separated key proofing from key presentation. 1344 o Separated interaction methods into booleans instead of "type" 1345 field. 1347 - 02 1349 o Minor editorial cleanups. 1351 - 01 1353 o Made JSON multimodal for handle requests. 1355 o Major updates to normative language and references throughout 1356 document. 1358 o Allowed interaction to split between how the user gets to the AS 1359 and how the user gets back. 1361 - 00 1363 o Initial submission. 1365 Author's Address 1367 Justin Richer (editor) 1368 Bespoke Engineering 1370 Email: ietf@justin.richer.org