idnits 2.17.1 draft-ietf-oauth-dpop-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 (2 May 2022) is 725 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) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-19 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Web Authorization Protocol D. Fett 3 Internet-Draft yes.com 4 Intended status: Standards Track B. Campbell 5 Expires: 3 November 2022 Ping Identity 6 J. Bradley 7 Yubico 8 T. Lodderstedt 9 yes.com 10 M. Jones 11 Microsoft 12 D. Waite 13 Ping Identity 14 2 May 2022 16 OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer 17 (DPoP) 18 draft-ietf-oauth-dpop-08 20 Abstract 22 This document describes a mechanism for sender-constraining OAuth 2.0 23 tokens via a proof-of-possession mechanism on the application level. 24 This mechanism allows for the detection of replay attacks with access 25 and refresh tokens. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 3 November 2022. 44 Copyright Notice 46 Copyright (c) 2022 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Revised BSD License text as 55 described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Revised BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 4 62 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 4. DPoP Proof JWTs . . . . . . . . . . . . . . . . . . . . . . . 7 65 4.1. The DPoP HTTP Header . . . . . . . . . . . . . . . . . . 8 66 4.2. DPoP Proof JWT Syntax . . . . . . . . . . . . . . . . . . 8 67 4.3. Checking DPoP Proofs . . . . . . . . . . . . . . . . . . 10 68 5. DPoP Access Token Request . . . . . . . . . . . . . . . . . . 11 69 5.1. Authorization Server Metadata . . . . . . . . . . . . . . 14 70 5.2. Client Registration Metadata . . . . . . . . . . . . . . 14 71 6. Public Key Confirmation . . . . . . . . . . . . . . . . . . . 14 72 6.1. JWK Thumbprint Confirmation Method . . . . . . . . . . . 15 73 6.2. JWK Thumbprint Confirmation Method in Token 74 Introspection . . . . . . . . . . . . . . . . . . . . . . 16 75 7. Protected Resource Access . . . . . . . . . . . . . . . . . . 17 76 7.1. The DPoP Authentication Scheme . . . . . . . . . . . . . 17 77 7.2. Compatibility with the Bearer Authentication Scheme . . . 20 78 8. Authorization Server-Provided Nonce . . . . . . . . . . . . . 21 79 8.1. Providing a New Nonce Value . . . . . . . . . . . . . . . 23 80 9. Resource Server-Provided Nonce . . . . . . . . . . . . . . . 23 81 10. Authorization Code Binding to DPoP Key . . . . . . . . . . . 24 82 10.1. DPoP with Pushed Authorization Requests . . . . . . . . 25 83 11. Security Considerations . . . . . . . . . . . . . . . . . . . 25 84 11.1. DPoP Proof Replay . . . . . . . . . . . . . . . . . . . 26 85 11.2. DPoP Proof Pre-Generation . . . . . . . . . . . . . . . 26 86 11.3. DPoP Nonce Downgrade . . . . . . . . . . . . . . . . . . 27 87 11.4. Untrusted Code in the Client Context . . . . . . . . . . 27 88 11.5. Signed JWT Swapping . . . . . . . . . . . . . . . . . . 28 89 11.6. Signature Algorithms . . . . . . . . . . . . . . . . . . 28 90 11.7. Message Integrity . . . . . . . . . . . . . . . . . . . 28 91 11.8. Access Token and Public Key Binding . . . . . . . . . . 29 92 11.9. Authorization Code and Public Key Binding . . . . . . . 29 93 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 94 12.1. OAuth Access Token Type Registration . . . . . . . . . . 30 95 12.2. OAuth Extensions Error Registration . . . . . . . . . . 30 96 12.3. OAuth Parameters Registration . . . . . . . . . . . . . 31 97 12.4. HTTP Authentication Scheme Registration . . . . . . . . 31 98 12.5. Media Type Registration . . . . . . . . . . . . . . . . 31 99 12.6. JWT Confirmation Methods Registration . . . . . . . . . 32 100 12.7. JSON Web Token Claims Registration . . . . . . . . . . . 32 101 12.8. HTTP Message Header Field Names Registration . . . . . . 33 102 12.9. OAuth Authorization Server Metadata Registration . . . . 33 103 12.10. OAuth Dynamic Client Registration Metadata . . . . . . . 33 104 13. Normative References . . . . . . . . . . . . . . . . . . . . 33 105 14. Informative References . . . . . . . . . . . . . . . . . . . 35 106 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 37 107 Appendix B. Document History . . . . . . . . . . . . . . . . . . 38 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 110 1. Introduction 112 DPoP (for Demonstrating Proof-of-Possession at the Application Layer) 113 is an application-level mechanism for sender-constraining OAuth 114 access and refresh tokens. It enables a client to prove the 115 possession of a public/private key pair by including a DPoP header in 116 an HTTP request. The value of the header is a JSON Web Token (JWT) 117 [RFC7519] that enables the authorization server to bind issued tokens 118 to the public part of a client's key pair. Recipients of such tokens 119 are then able to verify the binding of the token to the key pair that 120 the client has demonstrated that it holds via the DPoP header, 121 thereby providing some assurance that the client presenting the token 122 also possesses the private key. In other words, the legitimate 123 presenter of the token is constrained to be the sender that holds and 124 can prove possession of the private part of the key pair. 126 The mechanism described herein can be used in cases where other 127 methods of sender-constraining tokens that utilize elements of the 128 underlying secure transport layer, such as [RFC8705] or 129 [I-D.ietf-oauth-token-binding], are not available or desirable. For 130 example, due to a sub-par user experience of TLS client 131 authentication in user agents and a lack of support for HTTP token 132 binding, neither mechanism can be used if an OAuth client is a Single 133 Page Application (SPA) running in a web browser. Native applications 134 installed and run on a user's device are another example well 135 positioned to benefit from DPoP-bound tokens to guard against misuse 136 of tokens by a compromised or malicious resource. Such applications 137 often have dedicated protected storage for cryptographic keys. 139 DPoP can be used to sender-constrain access tokens regardless of the 140 client authentication method employed, but DPoP itself is not used 141 for client authentication. DPoP can also be used to sender-constrain 142 refresh tokens issued to public clients (those without authentication 143 credentials associated with the client_id). 145 1.1. Conventions and Terminology 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in BCP 150 14 [RFC2119] [RFC8174] when, and only when, they appear in all 151 capitals, as shown here. 153 This specification uses the Augmented Backus-Naur Form (ABNF) 154 notation of [RFC5234]. 156 This specification uses the terms "access token", "refresh token", 157 "authorization server", "resource server", "authorization endpoint", 158 "authorization request", "authorization response", "token endpoint", 159 "grant type", "access token request", "access token response", 160 "client", "public client", and "confidential client" defined by The 161 OAuth 2.0 Authorization Framework [RFC6749]. 163 The terms "request", "response", "header field", "request URI" are 164 imported from [RFC7231]. 166 The terms "JOSE" and "JOSE header" are imported from [RFC7515]. 168 2. Objectives 170 The primary aim of DPoP is to prevent unauthorized or illegitimate 171 parties from using leaked or stolen access tokens, by binding a token 172 to a public key upon issuance and requiring that the client proves 173 possession of the corresponding private key when using the token. 174 This constrains the legitimate sender of the token to only the party 175 with access to the private key and gives the server receiving the 176 token added assurances that the sender is legitimately authorized to 177 use it. 179 Access tokens that are sender-constrained via DPoP thus stand in 180 contrast to the typical bearer token, which can be used by any party 181 in possession of such a token. Although protections generally exist 182 to prevent unintended disclosure of bearer tokens, unforeseen vectors 183 for leakage have occurred due to vulnerabilities and implementation 184 issues in other layers in the protocol or software stack (CRIME, 185 BREACH, Heartbleed, and the Cloudflare parser bug are some examples). 186 There have also been numerous published token theft attacks on OAuth 187 implementations themselves. DPoP provides a general defense in depth 188 against the impact of unanticipated token leakage. DPoP is not, 189 however, a substitute for a secure transport and MUST always be used 190 in conjunction with HTTPS. 192 The very nature of the typical OAuth protocol interaction 193 necessitates that the client discloses the access token to the 194 protected resources that it accesses. The attacker model in 195 [I-D.ietf-oauth-security-topics] describes cases where a protected 196 resource might be counterfeit, malicious or compromised and plays 197 received tokens against other protected resources to gain 198 unauthorized access. Properly audience restricting access tokens can 199 prevent such misuse, however, doing so in practice has proven to be 200 prohibitively cumbersome for many deployments (even despite 201 extensions such as [RFC8707]). Sender-constraining access tokens is 202 a more robust and straightforward mechanism to prevent such token 203 replay at a different endpoint and DPoP is an accessible application 204 layer means of doing so. 206 Due to the potential for cross-site scripting (XSS), browser-based 207 OAuth clients bring to bear added considerations with respect to 208 protecting tokens. The most straightforward XSS-based attack is for 209 an attacker to exfiltrate a token and use it themselves completely 210 independent of the legitimate client. A stolen access token is used 211 for protected resource access and a stolen refresh token for 212 obtaining new access tokens. If the private key is non-extractable 213 (as is possible with [W3C.WebCryptoAPI]), DPoP renders exfiltrated 214 tokens alone unusable. 216 XSS vulnerabilities also allow an attacker to execute code in the 217 context of the browser-based client application and maliciously use a 218 token indirectly through the client. That execution context has 219 access to utilize the signing key and thus can produce DPoP proofs to 220 use in conjunction with the token. At this application layer there 221 is most likely no feasible defense against this threat except 222 generally preventing XSS, therefore it is considered out of scope for 223 DPoP. 225 Malicious XSS code executed in the context of the browser-based 226 client application is also in a position to create DPoP proofs with 227 timestamp values in the future and exfiltrate them in conjunction 228 with a token. These stolen artifacts can later be used together 229 independent of the client application to access protected resources. 230 To prevent this, servers can optionally require clients to include a 231 server-chosen value into the proof that cannot be predicted by an 232 attacker (nonce). In the absence of the optional nonce, the impact 233 of pre-computed DPoP proofs is limited somewhat by the proof being 234 bound to an access token on protected resource access. Because a 235 proof covering an access token that does not yet exist cannot 236 feasibly be created, access tokens obtained with an exfiltrated 237 refresh token and pre-computed proofs will be unusable. 239 Additional security considerations are discussed in Section 11. 241 3. Concept 243 The main data structure introduced by this specification is a DPoP 244 proof JWT, described in detail below, which is sent as a header in an 245 HTTP request. A client uses a DPoP proof JWT to prove the possession 246 of a private key corresponding to a certain public key. 248 Roughly speaking, a DPoP proof is a signature over some data of the 249 HTTP request to which it is attached, a timestamp, a unique 250 identifier, an optional server-provided nonce, and a hash of the 251 associated access token when an access token is present within the 252 request. 254 +--------+ +---------------+ 255 | |--(A)-- Token Request ------------------->| | 256 | Client | (DPoP Proof) | Authorization | 257 | | | Server | 258 | |<-(B)-- DPoP-bound Access Token ----------| | 259 | | (token_type=DPoP) +---------------+ 260 | | 261 | | 262 | | +---------------+ 263 | |--(C)-- DPoP-bound Access Token --------->| | 264 | | (DPoP Proof) | Resource | 265 | | | Server | 266 | |<-(D)-- Protected Resource ---------------| | 267 | | +---------------+ 268 +--------+ 270 Figure 1: Basic DPoP Flow 272 The basic steps of an OAuth flow with DPoP (without the optional 273 nonce) are shown in Figure 1: 275 * (A) In the Token Request, the client sends an authorization grant 276 (e.g., an authorization code, refresh token, etc.) 277 to the authorization server in order to obtain an access token 278 (and potentially a refresh token). The client attaches a DPoP 279 proof to the request in an HTTP header. 280 * (B) The authorization server binds (sender-constrains) the access 281 token to the public key claimed by the client in the DPoP proof; 282 that is, the access token cannot be used without proving 283 possession of the respective private key. If a refresh token is 284 issued to a public client, it too is bound to the public key of 285 the DPoP proof. 286 * (C) To use the access token, the client has to prove possession of 287 the private key by, again, adding a header to the request that 288 carries a DPoP proof for that request. The resource server needs 289 to receive information about the public key to which the access 290 token is bound. This information may be encoded directly into the 291 access token (for JWT structured access tokens) or provided via 292 token introspection endpoint (not shown). The resource server 293 verifies that the public key to which the access token is bound 294 matches the public key of the DPoP proof. It also verifies that 295 the access token hash in the DPoP proof matches the access token 296 presented in the request. 297 * (D) The resource server refuses to serve the request if the 298 signature check fails or the data in the DPoP proof is wrong, 299 e.g., the request URI does not match the URI claim in the DPoP 300 proof JWT. The access token itself, of course, must also be valid 301 in all other respects. 303 The DPoP mechanism presented herein is not a client authentication 304 method. In fact, a primary use case of DPoP is for public clients 305 (e.g., single page applications and native applications) that do not 306 use client authentication. Nonetheless, DPoP is designed such that 307 it is compatible with private_key_jwt and all other client 308 authentication methods. 310 DPoP does not directly ensure message integrity but relies on the TLS 311 layer for that purpose. See Section 11 for details. 313 4. DPoP Proof JWTs 315 DPoP introduces the concept of a DPoP proof, which is a JWT created 316 by the client and sent with an HTTP request using the DPoP header 317 field. Each HTTP request requires a unique DPoP proof. 319 A valid DPoP proof demonstrates to the server that the client holds 320 the private key that was used to sign the DPoP proof JWT. This 321 enables authorization servers to bind issued tokens to the 322 corresponding public key (as described in Section 5) and for resource 323 servers to verify the key-binding of tokens that it receives (see 324 Section 7.1), which prevents said tokens from being used by any 325 entity that does not have access to the private key. 327 The DPoP proof demonstrates possession of a key and, by itself, is 328 not an authentication or access control mechanism. When presented in 329 conjunction with a key-bound access token as described in 330 Section 7.1, the DPoP proof provides additional assurance about the 331 legitimacy of the client to present the access token. However, a 332 valid DPoP proof JWT is not sufficient alone to make access control 333 decisions. 335 4.1. The DPoP HTTP Header 337 A DPoP proof is included in an HTTP request using the following 338 request header field. 340 DPoP A JWT that adheres to the structure and syntax of Section 4.2. 342 Figure 2 shows an example DPoP HTTP header field (line breaks and 343 extra whitespace for display purposes only). 345 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik 346 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR 347 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE 348 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj 349 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia 350 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg 351 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg 353 Figure 2: Example DPoP header 355 Note that per [RFC7230] header field names are case-insensitive; so 356 DPoP, DPOP, dpop, etc., are all valid and equivalent header field 357 names. Case is significant in the header field value, however. 359 4.2. DPoP Proof JWT Syntax 361 A DPoP proof is a JWT ([RFC7519]) that is signed (using JSON Web 362 Signature (JWS) [RFC7515]) with a private key chosen by the client 363 (see below). The JOSE header of a DPoP JWT MUST contain at least the 364 following parameters: 366 * typ: with value `dpop+jwt. 367 * alg: a digital signature algorithm identifier as per [RFC7518]. 368 MUST NOT be none or an identifier for a symmetric algorithm (MAC). 369 * jwk: representing the public key chosen by the client, in JSON Web 370 Key (JWK) [RFC7517] format, as defined in Section 4.1.3 of 371 [RFC7515]. MUST NOT contain a private key. 373 The payload of a DPoP proof MUST contain at least the following 374 claims: 376 * jti: Unique identifier for the DPoP proof JWT. The value MUST be 377 assigned such that there is a negligible probability that the same 378 value will be assigned to any other DPoP proof used in the same 379 context during the time window of validity. Such uniqueness can 380 be accomplished by encoding (base64url or any other suitable 381 encoding) at least 96 bits of pseudorandom data or by using a 382 version 4 UUID string according to [RFC4122]. The jti can be used 383 by the server for replay detection and prevention, see 384 Section 11.1. 385 * htm: The HTTP method of the request to which the JWT is attached, 386 as defined in [RFC7231]. 387 * htu: The HTTP request URI (Section 5.5 of [RFC7230]), without 388 query and fragment parts. 389 * iat: Creation timestamp of the JWT (Section 4.1.6 of [RFC7519]). 391 When the DPoP proof is used in conjunction with the presentation of 392 an access token, see Section 7, the DPoP proof MUST also contain the 393 following claim: 395 * ath: hash of the access token. The value MUST be the result of a 396 base64url encoding (as defined in Section 2 of [RFC7515]) the 397 SHA-256 [SHS] hash of the ASCII encoding of the associated access 398 token's value. 400 A DPoP proof MAY contain other JOSE header parameters or claims as 401 defined by extension, profile, or deployment specific requirements. 403 Figure 3 is a conceptual example showing the decoded content of the 404 DPoP proof in Figure 2. The JSON of the JWT header and payload are 405 shown, but the signature part is omitted. As usual, line breaks and 406 extra whitespace are included for formatting and readability. 408 { 409 "typ":"dpop+jwt", 410 "alg":"ES256", 411 "jwk": { 412 "kty":"EC", 413 "x":"l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs", 414 "y":"9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA", 415 "crv":"P-256" 416 } 417 } 418 . 419 { 420 "jti":"-BwC3ESc6acc2lTc", 421 "htm":"POST", 422 "htu":"https://server.example.com/token", 423 "iat":1562262616 424 } 426 Figure 3: Example JWT content of a DPoP proof 428 Of the HTTP request, only the HTTP method and URI are included in the 429 DPoP JWT, and therefore only these two message parts are covered by 430 the DPoP proof. The idea is sign just enough of the HTTP data to 431 provide reasonable proof-of-possession with respect to the HTTP 432 request. But that it be a minimal subset of the HTTP data so as to 433 avoid the substantial difficulties inherent in attempting to 434 normalize HTTP messages. Nonetheless, DPoP proofs can be extended to 435 contain other information of the HTTP request (see also 436 Section 11.7). 438 4.3. Checking DPoP Proofs 440 To validate a DPoP proof, the receiving server MUST ensure that 442 1. that there is not more than one DPoP HTTP request header field, 443 2. the header field value is a well-formed JWT, 444 3. all required claims per Section 4.2 are contained in the JWT, 445 4. the typ JOSE header parameter has the value dpop+jwt, 446 5. the alg JOSE header parameter indicates an asymmetric digital 447 signature algorithm, is not none, is supported by the 448 application, and is deemed secure, 449 6. the JWT signature verifies with the public key contained in the 450 jwk JOSE header parameter, 451 7. the jwk JOSE header parameter does not contain a private key, 452 8. the htm claim matches the HTTP method of the current request, 453 9. the htu claim matches the HTTPS URI value for the HTTP request 454 in which the JWT was received, ignoring any query and fragment 455 parts, 457 10. if the server provided a nonce value to the client, the nonce 458 claim matches the server-provided nonce value, 459 11. the creation time of the JWT, as determined by either the iat 460 claim or a server managed timestamp via the nonce claim, is 461 within an acceptable window (see Section 11.1), 462 12. if presented to a protected resource in conjunction with an 463 access token, 464 1. ensure that the value of the ath claim equals the hash of 465 that access token, 466 2. confirm that the public key to which the access token is 467 bound matches the public key from the DPoP proof. 469 Servers SHOULD employ Syntax-Based Normalization and Scheme-Based 470 Normalization in accordance with Section 6.2.2. and Section 6.2.3. of 471 [RFC3986] before comparing the htu claim. 473 5. DPoP Access Token Request 475 To request an access token that is bound to a public key using DPoP, 476 the client MUST provide a valid DPoP proof JWT in a DPoP header when 477 making an access token request to the authorization server's token 478 endpoint. This is applicable for all access token requests 479 regardless of grant type (including, for example, the common 480 authorization_code and refresh_token grant types but also extension 481 grants such as the JWT authorization grant [RFC7523]). The HTTP 482 request shown in Figure 4 illustrates such an access token request 483 using an authorization code grant with a DPoP proof JWT in the DPoP 484 header (extra line breaks and whitespace for display purposes only). 486 POST /token HTTP/1.1 487 Host: server.example.com 488 Content-Type: application/x-www-form-urlencoded 489 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik 490 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR 491 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE 492 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj 493 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia 494 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg 495 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg 497 grant_type=authorization_code 498 &code=SplxlOBeZQQYbYS6WxSbIA 499 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 500 &code_verifier=bEaL42izcC-o-xBk0K2vuJ6U-y1p9r_wW2dFWIWgjz- 502 Figure 4: Token Request for a DPoP sender-constrained token using an 503 authorization code 505 The DPoP HTTP header field MUST contain a valid DPoP proof JWT. If 506 the DPoP proof is invalid, the authorization server issues an error 507 response per Section 5.2 of [RFC6749] with invalid_dpop_proof as the 508 value of the error parameter. 510 To sender-constrain the access token, after checking the validity of 511 the DPoP proof, the authorization server associates the issued access 512 token with the public key from the DPoP proof, which can be 513 accomplished as described in Section 6. A token_type of DPoP MUST be 514 included in the access token response to signal to the client that 515 the access token was bound to its DPoP key and can be used as 516 described in Section 7.1. The example response shown in Figure 5 517 illustrates such a response. 519 HTTP/1.1 200 OK 520 Content-Type: application/json 521 Cache-Control: no-store 523 { 524 "access_token": "Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU", 525 "token_type": "DPoP", 526 "expires_in": 2677, 527 "refresh_token": "Q..Zkm29lexi8VnWg2zPW1x-tgGad0Ibc3s3EwM_Ni4-g" 528 } 530 Figure 5: Access Token Response 532 The example response in Figure 5 includes a refresh token which the 533 client can use to obtain a new access token when the previous one 534 expires. Refreshing an access token is a token request using the 535 refresh_token grant type made to the authorization server's token 536 endpoint. As with all access token requests, the client makes it a 537 DPoP request by including a DPoP proof, as shown in the Figure 6 538 example (extra line breaks and whitespace for display purposes only). 540 POST /token HTTP/1.1 541 Host: server.example.com 542 Content-Type: application/x-www-form-urlencoded 543 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik 544 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR 545 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE 546 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj 547 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia 548 WF0IjoxNTYyMjY1Mjk2fQ.pAqut2IRDm_De6PR93SYmGBPXpwrAk90e8cP2hjiaG5Qs 549 GSuKDYW7_X620BxqhvYC8ynrrvZLTk41mSRroapUA 551 grant_type=refresh_token 552 &refresh_token=Q..Zkm29lexi8VnWg2zPW1x-tgGad0Ibc3s3EwM_Ni4-g 553 Figure 6: Token Request for a DPoP-bound Token using a Refresh Token 555 When an authorization server supporting DPoP issues a refresh token 556 to a public client that presents a valid DPoP proof at the token 557 endpoint, the refresh token MUST be bound to the respective public 558 key. The binding MUST be validated when the refresh token is later 559 presented to get new access tokens. As a result, such a client MUST 560 present a DPoP proof for the same key that was used to obtain the 561 refresh token each time that refresh token is used to obtain a new 562 access token. The implementation details of the binding of the 563 refresh token are at the discretion of the authorization server. 564 Since the authorization server both produces and validates its 565 refresh tokens, there is no interoperability consideration in the 566 specific details of the binding. 568 An authorization server MAY elect to issue access tokens which are 569 not DPoP bound, which is signaled to the client with a value of 570 Bearer in the token_type parameter of the access token response per 571 [RFC6750]. For a public client that is also issued a refresh token, 572 this has the effect of DPoP-binding the refresh token alone, which 573 can improve the security posture even when protected resources are 574 not updated to support DPoP. 576 If the access token response contains a different token_type value 577 than DPoP, the access token protection provided by DPoP is not given. 578 The client must discard the response in this case, if this protection 579 is deemed important for the security of the application; otherwise, 580 it may continue as in a regular OAuth interaction. 582 Refresh tokens issued to confidential clients (those having 583 established authentication credentials with the authorization server) 584 are not bound to the DPoP proof public key because they are already 585 sender-constrained with a different existing mechanism. The OAuth 586 2.0 Authorization Framework [RFC6749] already requires that an 587 authorization server bind refresh tokens to the client to which they 588 were issued and that confidential clients authenticate to the 589 authorization server when presenting a refresh token. As a result, 590 such refresh tokens are sender-constrained by way of the client 591 identifier and the associated authentication requirement. This 592 existing sender-constraining mechanism is more flexible (e.g., it 593 allows credential rotation for the client without invalidating 594 refresh tokens) than binding directly to a particular public key. 596 5.1. Authorization Server Metadata 598 This document introduces the following authorization server metadata 599 [RFC8414] parameter to signal support for DPoP in general and the 600 specific JWS alg values the authorization server supports for DPoP 601 proof JWTs. 603 dpop_signing_alg_values_supported A JSON array containing a list of 604 the JWS alg values supported by the authorization server for DPoP 605 proof JWTs. 607 5.2. Client Registration Metadata 609 The Dynamic Client Registration Protocol [RFC7591] defines an API for 610 dynamically registering OAuth 2.0 client metadata with authorization 611 servers. The metadata defined by [RFC7591], and registered 612 extensions to it, also imply a general data model for clients that is 613 useful for authorization server implementations even when the Dynamic 614 Client Registration Protocol isn't in play. Such implementations 615 will typically have some sort of user interface available for 616 managing client configuration. 618 This document introduces the following client registration metadata 619 [RFC7591] parameter to indicate that the client always uses DPoP when 620 requesting tokens from the authorization server. 622 dpop_bound_access_tokens Boolean value specifying whether the client 623 always uses DPoP for token requests. If omitted, the default 624 value is false. 626 If true, the authorization server MUST reject token requests from 627 this client that do not contain the DPoP header. 629 6. Public Key Confirmation 631 Resource servers MUST be able to reliably identify whether an access 632 token is DPoP-bound and ascertain sufficient information to verify 633 the binding to the public key of the DPoP proof (see Section 7.1). 634 Such a binding is accomplished by associating the public key with the 635 token in a way that can be accessed by the protected resource, such 636 as embedding the JWK hash in the issued access token directly, using 637 the syntax described in Section 6.1, or through token introspection 638 as described in Section 6.2. Other methods of associating a public 639 key with an access token are possible, per agreement by the 640 authorization server and the protected resource, but are beyond the 641 scope of this specification. 643 Resource servers supporting DPoP MUST ensure that the public key from 644 the DPoP proof matches the one bound to the access token. 646 6.1. JWK Thumbprint Confirmation Method 648 When access tokens are represented as JSON Web Tokens (JWT) 649 [RFC7519], the public key information SHOULD be represented using the 650 jkt confirmation method member defined herein. To convey the hash of 651 a public key in a JWT, this specification introduces the following 652 JWT Confirmation Method [RFC7800] member for use under the cnf claim. 654 jkt JWK SHA-256 Thumbprint Confirmation Method. The value of the 655 jkt member MUST be the base64url encoding (as defined in 656 [RFC7515]) of the JWK SHA-256 Thumbprint (according to [RFC7638]) 657 of the DPoP public key (in JWK format) to which the access token 658 is bound. 660 The following example JWT in Figure 7 with decoded JWT payload shown 661 in Figure 8 contains a cnf claim with the jkt JWK Thumbprint 662 confirmation method member. The jkt value in these examples is the 663 hash of the public key from the DPoP proofs in the examples in 664 Section 5. 666 eyJhbGciOiJFUzI1NiIsImtpZCI6IkJlQUxrYiJ9.eyJzdWIiOiJzb21lb25lQGV4YW1 667 wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJuYmYiOjE 668 1NjIyNjI2MTEsImV4cCI6MTU2MjI2NjIxNiwiY25mIjp7ImprdCI6IjBaY09DT1JaTll 669 5LURXcHFxMzBqWnlKR0hUTjBkMkhnbEJWM3VpZ3VBNEkifX0.3Tyo8VTcn6u_PboUmAO 670 YUY1kfAavomW_YwYMkmRNizLJoQzWy2fCo79Zi5yObpIzjWb5xW4OGld7ESZrh0fsrA 672 Figure 7: JWT containing a JWK SHA-256 Thumbprint Confirmation 674 { 675 "sub":"someone@example.com", 676 "iss":"https://server.example.com", 677 "nbf":1562262611, 678 "exp":1562266216, 679 "cnf": 680 { 681 "jkt":"0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I" 682 } 683 } 685 Figure 8: JWT Claims Set with a JWK SHA-256 Thumbprint Confirmation 687 6.2. JWK Thumbprint Confirmation Method in Token Introspection 689 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 690 protected resource to query an authorization server about the active 691 state of an access token as well as to determine metainformation 692 about the token. 694 For a DPoP-bound access token, the hash of the public key to which 695 the token is bound is conveyed to the protected resource as 696 metainformation in a token introspection response. The hash is 697 conveyed using the same cnf content with jkt member structure as the 698 JWK Thumbprint confirmation method, described in Section 6.1, as a 699 top-level member of the introspection response JSON. Note that the 700 resource server does not send a DPoP proof with the introspection 701 request and the authorization server does not validate an access 702 token's DPoP binding at the introspection endpoint. Rather the 703 resource server uses the data of the introspection response to 704 validate the access token binding itself locally. 706 If the token_type member is included in the introspection response, 707 it MUST contain the value DPoP. 709 The example introspection request in Figure 9 and corresponding 710 response in Figure 10 illustrate an introspection exchange for the 711 example DPoP-bound access token that was issued in Figure 5. 713 POST /as/introspect.oauth2 HTTP/1.1 714 Host: server.example.com 715 Content-Type: application/x-www-form-urlencoded 716 Authorization: Basic cnM6cnM6TWt1LTZnX2xDektJZHo0ZnNON2tZY3lhK1Rp 718 token=Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU 720 Figure 9: Example Introspection Request 722 HTTP/1.1 200 OK 723 Content-Type: application/json 724 Cache-Control: no-store 726 { 727 "active": true, 728 "sub": "someone@example.com", 729 "iss": "https://server.example.com", 730 "nbf": 1562262611, 731 "exp": 1562266216, 732 "cnf": 733 { 734 "jkt": "0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I" 735 } 736 } 738 Figure 10: Example Introspection Response for a DPoP-Bound Access 739 Token 741 7. Protected Resource Access 743 Protected resource requests with a DPoP-bound access token MUST 744 include both a DPoP proof as per Section 4 and the access token as 745 described in Section 7.1. The DPoP proof MUST include the ath claim 746 with a valid hash of the associated access token. 748 7.1. The DPoP Authentication Scheme 750 A DPoP-bound access token is sent using the Authorization request 751 header field per Section 2 of [RFC7235] using an authentication 752 scheme of DPoP. The syntax of the Authorization header field for the 753 DPoP scheme uses the token68 syntax defined in Section 2.1 of 754 [RFC7235] (repeated below for ease of reference) for credentials. 755 The ABNF notation syntax for DPoP authentication scheme credentials 756 is as follows: 758 token68 = 1*( ALPHA / DIGIT / 759 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 761 credentials = "DPoP" 1*SP token68 763 Figure 11: DPoP Authentication Scheme ABNF 765 For such an access token, a resource server MUST check that a DPoP 766 proof was also received in the DPoP header field of the HTTP request, 767 check the DPoP proof according to the rules in Section 4.3, and check 768 that the public key of the DPoP proof matches the public key to which 769 the access token is bound per Section 6. 771 The resource server MUST NOT grant access to the resource unless all 772 checks are successful. 774 Figure 12 shows an example request to a protected resource with a 775 DPoP-bound access token in the Authorization header and the DPoP 776 proof in the DPoP header. Following that is Figure 13, which shows 777 the decoded content of that DPoP proof. The JSON of the JWT header 778 and payload are shown but the signature part is omitted. As usual, 779 line breaks and extra whitespace are included for formatting and 780 readability in both examples. 782 GET /protectedresource HTTP/1.1 783 Host: resource.example.org 784 Authorization: DPoP Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU 785 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik 786 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR 787 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE 788 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiJlMWozVl9iS2ljOC1MQUVCIiwiaHRtIj 789 oiR0VUIiwiaHR1IjoiaHR0cHM6Ly9yZXNvdXJjZS5leGFtcGxlLm9yZy9wcm90ZWN0Z 790 WRyZXNvdXJjZSIsImlhdCI6MTU2MjI2MjYxOCwiYXRoIjoiZlVIeU8ycjJaM0RaNTNF 791 c05yV0JiMHhXWG9hTnk1OUlpS0NBcWtzbVFFbyJ9.2oW9RP35yRqzhrtNP86L-Ey71E 792 OptxRimPPToA1plemAgR6pxHF8y6-yqyVnmcw6Fy1dqd-jfxSYoMxhAJpLjA 794 Figure 12: DPoP Protected Resource Request 796 { 797 "typ":"dpop+jwt", 798 "alg":"ES256", 799 "jwk": { 800 "kty":"EC", 801 "x":"l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs", 802 "y":"9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA", 803 "crv":"P-256" 804 } 805 } 806 . 807 { 808 "jti":"e1j3V_bKic8-LAEB", 809 "htm":"GET", 810 "htu":"https://resource.example.org/protectedresource", 811 "iat":1562262618, 812 "ath":"fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo" 813 } 815 Figure 13: Decoded Content of the DPoP Proof JWT in Figure 12 817 Upon receipt of a request to a protected resource within the 818 protection space requiring DPoP authentication, if the request does 819 not include valid credentials or does not contain an access token 820 sufficient for access, the server can respond with a challenge to the 821 client to provide DPoP authentication information. Such a challenge 822 is made using the 401 (Unauthorized) response status code ([RFC7235], 823 Section 3.1) and the WWW-Authenticate header field ([RFC7235], 824 Section 4.1). The server MAY include the WWW-Authenticate header in 825 response to other conditions as well. 827 In such challenges: 829 * The scheme name is DPoP. 830 * The authentication parameter realm MAY be included to indicate the 831 scope of protection in the manner described in [RFC7235], 832 Section 2.2. 833 * A scope authentication parameter MAY be included as defined in 834 [RFC6750], Section 3. 835 * An error parameter ([RFC6750], Section 3) SHOULD be included to 836 indicate the reason why the request was declined, if the request 837 included an access token but failed authentication. The error 838 parameter values described in Section 3.1 of [RFC6750] are 839 suitable as are any appropriate values defined by extension. The 840 value use_dpop_nonce can be used as described in Section 9 to 841 signal that a nonce is needed in the DPoP proof of subsequent 842 request(s). And invalid_dpop_proof is used to indicate that the 843 DPoP proof itself was deemed invalid based on the criteria of 844 Section 4.3. 845 * An error_description parameter ([RFC6750], Section 3) MAY be 846 included along with the error parameter to provide developers a 847 human-readable explanation that is not meant to be displayed to 848 end-users. 849 * An algs parameter SHOULD be included to signal to the client the 850 JWS algorithms that are acceptable for the DPoP proof JWT. The 851 value of the parameter is a space-delimited list of JWS alg 852 (Algorithm) header values ([RFC7515], Section 4.1.1). 853 * Additional authentication parameters MAY be used and unknown 854 parameters MUST be ignored by recipients. 856 For example, in response to a protected resource request without 857 authentication: 859 HTTP/1.1 401 Unauthorized 860 WWW-Authenticate: DPoP algs="ES256 PS256" 862 Figure 14: HTTP 401 Response to a Protected Resource Request without 863 Authentication 865 And in response to a protected resource request that was rejected 866 because the confirmation of the DPoP binding in the access token 867 failed: 869 HTTP/1.1 401 Unauthorized 870 WWW-Authenticate: DPoP error="invalid_token", 871 error_description="Invalid DPoP key binding", algs="ES256" 873 Figure 15: HTTP 401 Response to a Protected Resource Request with 874 an Invalid Token 876 This authentication scheme is for origin-server authentication only. 877 Therefore, this authentication scheme MUST NOT be used with the 878 Proxy-Authenticate or Proxy-Authorization header fields. 880 Note that the syntax of the Authorization header field for this 881 authentication scheme follows the usage of the Bearer scheme defined 882 in Section 2.1 of [RFC6750]. While not the preferred credential 883 syntax of [RFC7235], it is compatible with the general authentication 884 framework therein and was used for consistency and familiarity with 885 the Bearer scheme. 887 7.2. Compatibility with the Bearer Authentication Scheme 889 Protected resources simultaneously supporting both the DPoP and 890 Bearer schemes need to update how evaluation of bearer tokens is 891 performed to prevent downgraded usage of a DPoP-bound access token. 892 Specifically, such a protected resource MUST reject a DPoP-bound 893 access token received as a bearer token per [RFC6750]. 895 Section 4.1 of [RFC7235] allows a protected resource to indicate 896 support for multiple authentication schemes (i.e., Bearer and DPoP) 897 with the WWW-Authenticate header field of a 401 (Unauthorized) 898 response. 900 A protected resource that supports only [RFC6750] and is unaware of 901 DPoP would most presumably accept a DPoP-bound access token as a 902 bearer token (JWT [RFC7519] says to ignore unrecognized claims, 903 Introspection [RFC7662] says that other parameters might be present 904 while placing no functional requirements on their presence, and 905 [RFC6750] is effectively silent on the content of the access token as 906 it relates to validity). As such, a client can send a DPoP-bound 907 access token using the Bearer scheme upon receipt of a WWW- 908 Authenticate: Bearer challenge from a protected resource (or if it 909 has prior such knowledge about the capabilities of the protected 910 resource). The effect of this likely simplifies the logistics of 911 phased upgrades to protected resources in their support DPoP or even 912 prolonged deployments of protected resources with mixed token type 913 support. 915 8. Authorization Server-Provided Nonce 917 This section specifies a mechanism using opaque nonces provided by 918 the server that can be used to limit the lifetime of DPoP proofs. 919 Without employing such a mechanism, a malicious party controlling the 920 client (including potentially the end-user) can create DPoP proofs 921 for use arbitrarily far in the future. 923 Including a nonce value contributed by the authorization server in 924 the DPoP proof MAY be used by authorization servers to limit the 925 lifetime of DPoP proofs. The server is in control of when to require 926 the use of a new nonce value in subsequent DPoP proofs. 928 An authorization server MAY supply a nonce value to be included by 929 the client in DPoP proofs sent. In this case, the authorization 930 server responds to requests not including a nonce with an HTTP 400 931 (Bad Request) error response per Section 5.2 of [RFC6749] using 932 use_dpop_nonce as the error code value. The authorization server 933 includes a DPoP-Nonce HTTP header in the response supplying a nonce 934 value to be used when sending the subsequent request. This same 935 error code is used when supplying a new nonce value when there was a 936 nonce mismatch. The client will typically retry the request with the 937 new nonce value supplied upon receiving a use_dpop_nonce error with 938 an accompanying nonce value. 940 For example, in response to a token request without a nonce when the 941 authorization server requires one, the authorization server can 942 respond with a DPoP-Nonce value such as the following to provide a 943 nonce value to include in the DPoP proof: 945 HTTP/1.1 400 Bad Request 946 DPoP-Nonce: eyJ7S_zG.eyJH0-Z.HX4w-7v 948 { 949 "error": "use_dpop_nonce" 950 "error_description": 951 "Authorization server requires nonce in DPoP proof" 952 } 954 Figure 16: HTTP 400 Response to a Token Request without a Nonce 956 Other HTTP headers and JSON fields MAY also be included in the error 957 response, but there MUST NOT be more than one DPoP-Nonce header. 959 Upon receiving the nonce, the client is expected to retry its token 960 request using a DPoP proof including the supplied nonce value in the 961 nonce claim of the DPoP proof. An example unencoded JWT Payload of 962 such a DPoP proof including a nonce is: 964 { 965 "jti": "-BwC3ESc6acc2lTc", 966 "htm": "POST", 967 "htu": "https://server.example.com/token", 968 "iat": 1562262616, 969 "nonce": "eyJ7S_zG.eyJH0-Z.HX4w-7v" 970 } 972 Figure 17: DPoP Proof Payload Including a Nonce Value 974 The nonce syntax in ABNF as used by [RFC6749] (which is the same as 975 the scope-token syntax) is: 977 nonce = 1*NQCHAR 979 Figure 18: Nonce ABNF 981 The nonce is opaque to the client. 983 If the nonce claim in the DPoP proof does not exactly match a nonce 984 recently supplied by the authorization server to the client, the 985 authorization server MUST reject the request. The rejection response 986 MAY include a DPoP-Nonce HTTP header providing a new nonce value to 987 use for subsequent requests. 989 The intent is that both clients and servers need to keep only one 990 nonce value for one another. That said, transient circumstances may 991 arise in which the server's and client's stored nonce values differ. 992 However, this situation is self-correcting; with any rejection 993 message, the server can send the client the nonce value that the 994 server wants it to use and the client can store that nonce value and 995 retry the request with it. Even if the client and/or server discard 996 their stored nonce values, that situation is also self-correcting 997 because new nonce values can be communicated when responding to or 998 retrying failed requests. 1000 8.1. Providing a New Nonce Value 1002 It is up to the authorization server when to supply a new nonce value 1003 for the client to use. The client is expected to use the existing 1004 supplied nonce in DPoP proofs until the server supplies a new nonce 1005 value. 1007 The authorization server MAY supply the new nonce in the same way 1008 that the initial one was supplied: by using a DPoP-Nonce HTTP header 1009 in the response. Of course, each time this happens it requires an 1010 extra protocol round trip. 1012 A more efficient manner of supplying a new nonce value is also 1013 defined -- by including a DPoP-Nonce HTTP header in the HTTP 200 (OK) 1014 response from the previous request. The client MUST use the new 1015 nonce value supplied for the next token request, and for all 1016 subsequent token requests until the authorization server supplies a 1017 new nonce. 1019 Responses that include the DPoP-Nonce HTTP header should be 1020 uncacheable (e.g., using Cache-Control: no-store in response to a GET 1021 request) to prevent the response being used to serve a subsequent 1022 request and a stale nonce value being used as a result. 1024 An example 200 OK response providing a new nonce value is: 1026 HTTP/1.1 200 OK 1027 Cache-Control: no-store 1028 DPoP-Nonce: eyJ7S_zG.eyJbYu3.xQmBj-1 1030 Figure 19: HTTP 200 Response Providing the Next Nonce Value 1032 9. Resource Server-Provided Nonce 1034 Resource servers can also choose to provide a nonce value to be 1035 included in DPoP proofs sent to them. They provide the nonce using 1036 the DPoP-Nonce header in same way that authorization servers do. The 1037 error signaling is performed as described in Section 7.1. Resource 1038 servers use an HTTP 401 (Unauthorized) error code with an 1039 accompanying WWW-Authenticate: DPoP value and DPoP-Nonce value to 1040 accomplish this. 1042 For example, in response to a resource request without a nonce when 1043 the resource server requires one, the resource server can respond 1044 with a DPoP-Nonce value such as the following to provide a nonce 1045 value to include in the DPoP proof: 1047 HTTP/1.1 401 Unauthorized 1048 WWW-Authenticate: DPoP error="use_dpop_nonce", 1049 error_description="Resource server requires nonce in DPoP proof" 1050 DPoP-Nonce: eyJ7S_zG.eyJH0-Z.HX4w-7v 1052 Figure 20: HTTP 401 Response to a Resource Request without a Nonce 1054 Note that the nonces provided by an authorization server and a 1055 resource server are different and should not be confused with one 1056 another, since nonces will be only accepted by the server that issued 1057 them. Likewise, should a client use multiple authorization servers 1058 and/or resource servers, a nonce issued by any of them should be used 1059 only at the issuing server. Developers should also take care to not 1060 confuse DPoP nonces with the OpenID Connect [OpenID.Core] ID Token 1061 nonce. 1063 10. Authorization Code Binding to DPoP Key 1065 Binding the authorization code issued to the client's proof-of- 1066 possession key can enable end-to-end binding of the entire 1067 authorization flow. This specification defines the dpop_jkt 1068 authorization request parameter for this purpose. The value of the 1069 dpop_jkt authorization request parameter is the JSON Web Key (JWK) 1070 Thumbprint [RFC7638] of the proof-of-possession public key using the 1071 SHA-256 hash function - the same value as used for the jkt 1072 confirmation method defined in Section 6.1. 1074 When a token request is received, the authorization server computes 1075 the JWK thumbprint of the proof-of-possession public key in the DPoP 1076 proof and verifies that it matches the dpop_jkt parameter value in 1077 the authorization request. If they do not match, it MUST reject the 1078 request. 1080 An example authorization request using the dpop_jkt authorization 1081 request parameter is: 1083 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1084 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1085 &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM 1086 &code_challenge_method=S256 1087 &dpop_jkt=NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs HTTP/1.1 1088 Host: server.example.com 1089 Figure 21: Authorization Request using the dpop_jkt Parameter 1091 Use of the dpop_jkt authorization request parameter is OPTIONAL. 1092 Note that the dpop_jkt authorization request parameter MAY also be 1093 used in combination with PKCE [RFC7636], which is recommended by 1094 [I-D.ietf-oauth-security-topics] as a countermeasure to authorization 1095 code injection. The dpop_jkt authorization request parameter only 1096 provides similar protections when a unique DPoP key is used for each 1097 authorization request. 1099 10.1. DPoP with Pushed Authorization Requests 1101 When Pushed Authorization Requests (PAR, [RFC9126]) are used in 1102 conjunction with DPoP, there are two ways in which the DPoP key can 1103 be communicated in the PAR request: 1105 * The dpop_jkt parameter can be used as described above to bind the 1106 issued authorization code to a specific key. In this case, 1107 dpop_jkt MUST be included alongside other authorization request 1108 parameters in the POST body of the PAR request. 1109 * Alternatively, the DPoP header can be added to the PAR request. 1110 In this case, the authorization server MUST check the provided 1111 DPoP proof JWT as defined in Section 4.3. It MUST further behave 1112 as if the contained public key's thumbprint was provided using 1113 dpop_jkt, i.e., reject the subsequent token request unless a DPoP 1114 proof for the same key is provided. This can help to simplify the 1115 implementation of the client, as it can "blindly" attach the DPoP 1116 header to all requests to the authorization server regardless of 1117 the type of request. Additionally, it provides a stronger 1118 binding, as the DPoP header contains a proof of possession of the 1119 private key. 1121 Both mechanisms MUST be supported by an authorization server that 1122 supports PAR and DPoP. If both mechanisms are used at the same time, 1123 the authorization server MUST reject the request if the JWK 1124 Thumbprint in dpop_jkt does not match the public key in the DPoP 1125 header. 1127 11. Security Considerations 1129 In DPoP, the prevention of token replay at a different endpoint (see 1130 Section 2) is achieved through authentication of the server per 1131 [RFC6125] and binding of the DPoP proof to a certain URI and HTTP 1132 method. DPoP, however, has a somewhat different nature of protection 1133 than TLS-based methods such as OAuth Mutual TLS [RFC8705] or OAuth 1134 Token Binding [I-D.ietf-oauth-token-binding] (see also Section 11.1 1135 and Section 11.7). TLS-based mechanisms can leverage a tight 1136 integration between the TLS layer and the application layer to 1137 achieve a very high level of message integrity with respect to the 1138 transport layer to which the token is bound and replay protection in 1139 general. 1141 11.1. DPoP Proof Replay 1143 If an adversary is able to get hold of a DPoP proof JWT, the 1144 adversary could replay that token at the same endpoint (the HTTP 1145 endpoint and method are enforced via the respective claims in the 1146 JWTs). To limit this, servers MUST only accept DPoP proofs for a 1147 limited time after their creation (preferably only for a relatively 1148 brief period on the order of seconds or minutes). 1150 To prevent multiple uses of the same DPoP proof servers can store, in 1151 the context of the request URI, the jti value of each DPoP proof for 1152 the time window in which the respective DPoP proof JWT would be 1153 accepted and decline HTTP requests to the same URI for which the jti 1154 value has been seen before. In order to guard against memory 1155 exhaustion attacks a server that is tracking jti values should reject 1156 DPoP proof JWTs with unnecessarily large jti values or store only a 1157 hash thereof. 1159 Note: To accommodate for clock offsets, the server MAY accept DPoP 1160 proofs that carry an iat time in the reasonably near future (on the 1161 order of seconds or minutes). Because clock skews between servers 1162 and clients may be large, servers may choose to limit DPoP proof 1163 lifetimes by using server-provided nonce values containing the time 1164 at the server rather than comparing the client-supplied iat time to 1165 the time at the server, yielding intended results even in the face of 1166 arbitrarily large clock skews. 1168 Server-provided nonces are an effective means of preventing DPoP 1169 proof replay. 1171 11.2. DPoP Proof Pre-Generation 1173 An attacker in control of the client can pre-generate DPoP proofs for 1174 use arbitrarily far into the future by choosing the iat value in the 1175 DPoP proof to be signed by the proof-of-possession key. Note that 1176 one such attacker is the person who is the legitimate user of the 1177 client. The user may pre-generate DPoP proofs to exfiltrate from the 1178 machine possessing the proof-of-possession key upon which they were 1179 generated and copy them to another machine that does not possess the 1180 key. For instance, a bank employee might pre-generate DPoP proofs on 1181 a bank computer and then copy them to another machine for use in the 1182 future, thereby bypassing bank audit controls. When DPoP proofs can 1183 be pre-generated and exfiltrated, all that is actually being proved 1184 in DPoP protocol interactions is possession of a DPoP proof -- not of 1185 the proof-of-possession key. 1187 Use of server-provided nonce values that are not predictable by 1188 attackers can prevent this attack. By providing new nonce values at 1189 times of its choosing, the server can limit the lifetime of DPoP 1190 proofs, preventing pre-generated DPoP proofs from being used. When 1191 server-provided nonces are used, possession of the proof-of- 1192 possession key is being demonstrated -- not just possession of a DPoP 1193 proof. 1195 The ath claim limits the use of pre-generated DPoP proofs to the 1196 lifetime of the access token. Deployments that do not utilize the 1197 nonce mechanism SHOULD NOT issue long-lived DPoP constrained access 1198 tokens, preferring instead to use short-lived access tokens and 1199 refresh tokens. Whilst an attacker could pre-generate DPoP proofs to 1200 use the refresh token to obtain a new access token, they would be 1201 unable to realistically pre-generate DPoP proofs to use a newly 1202 issued access token. 1204 11.3. DPoP Nonce Downgrade 1206 A server MUST NOT accept any DPoP proofs without the nonce claim when 1207 a DPoP nonce has been provided to the client. 1209 11.4. Untrusted Code in the Client Context 1211 If an adversary is able to run code in the client's execution 1212 context, the security of DPoP is no longer guaranteed. Common issues 1213 in web applications leading to the execution of untrusted code are 1214 cross-site scripting and remote code inclusion attacks. 1216 If the private key used for DPoP is stored in such a way that it 1217 cannot be exported, e.g., in a hardware or software security module, 1218 the adversary cannot exfiltrate the key and use it to create 1219 arbitrary DPoP proofs. The adversary can, however, create new DPoP 1220 proofs as long as the client is online, and use these proofs 1221 (together with the respective tokens) either on the victim's device 1222 or on a device under the attacker's control to send arbitrary 1223 requests that will be accepted by servers. 1225 To send requests even when the client is offline, an adversary can 1226 try to pre-compute DPoP proofs using timestamps in the future and 1227 exfiltrate these together with the access or refresh token. 1229 An adversary might further try to associate tokens issued from the 1230 token endpoint with a key pair under the adversary's control. One 1231 way to achieve this is to modify existing code, e.g., by replacing 1232 cryptographic APIs. Another way is to launch a new authorization 1233 grant between the client and the authorization server in an iframe. 1234 This grant needs to be "silent", i.e., not require interaction with 1235 the user. With code running in the client's origin, the adversary 1236 has access to the resulting authorization code and can use it to 1237 associate their own DPoP keys with the tokens returned from the token 1238 endpoint. The adversary is then able to use the resulting tokens on 1239 their own device even if the client is offline. 1241 Therefore, protecting clients against the execution of untrusted code 1242 is extremely important even if DPoP is used. Besides secure coding 1243 practices, Content Security Policy [W3C.CSP] can be used as a second 1244 layer of defense against cross-site scripting. 1246 11.5. Signed JWT Swapping 1248 Servers accepting signed DPoP proof JWTs MUST check the typ field in 1249 the headers of the JWTs to ensure that adversaries cannot use JWTs 1250 created for other purposes. 1252 11.6. Signature Algorithms 1254 Implementers MUST ensure that only asymmetric digital signature 1255 algorithms that are deemed secure can be used for signing DPoP 1256 proofs. In particular, the algorithm none MUST NOT be allowed. 1258 11.7. Message Integrity 1260 DPoP does not ensure the integrity of the payload or headers of 1261 requests. The DPoP proof only contains claims for the HTTP URI and 1262 method, but not, for example, the message body or general request 1263 headers. 1265 This is an intentional design decision intended to keep DPoP simple 1266 to use, but as described, makes DPoP potentially susceptible to 1267 replay attacks where an attacker is able to modify message contents 1268 and headers. In many setups, the message integrity and 1269 confidentiality provided by TLS is sufficient to provide a good level 1270 of protection. 1272 Implementers that have stronger requirements on the integrity of 1273 messages are encouraged to either use TLS-based mechanisms or signed 1274 requests. TLS-based mechanisms are in particular OAuth Mutual TLS 1275 [RFC8705] and OAuth Token Binding [I-D.ietf-oauth-token-binding]. 1277 Note: While signatures covering other parts of requests are out of 1278 the scope of this specification, additional information to be signed 1279 can be added into DPoP proofs. 1281 11.8. Access Token and Public Key Binding 1283 The binding of the access token to the DPoP public key, which is 1284 specified in Section 6, uses a cryptographic hash of the JWK 1285 representation of the public key. It relies on the hash function 1286 having sufficient second-preimage resistance so as to make it 1287 computationally infeasible to find or create another key that 1288 produces to the same hash output value. The SHA-256 hash function 1289 was used because it meets the aforementioned requirement while being 1290 widely available. If, in the future, JWK Thumbprints need to be 1291 computed using hash function(s) other than SHA-256, it is suggested 1292 that an additional related JWT confirmation method member be defined 1293 for that purpose, registered in the respective IANA registry, and 1294 used in place of the jkt confirmation method defined herein. 1296 Similarly, the binding of the DPoP proof to the access token uses a 1297 hash of that access token as the value of the ath claim in the DPoP 1298 proof (see Section 4.2). This relies on the value of the hash being 1299 sufficiently unique so as to reliably identify the access token. The 1300 collision resistance of SHA-256 meets that requirement. If, in the 1301 future, access token digests need be computed using hash function(s) 1302 other than SHA-256, it is suggested that an additional related JWT 1303 claim be defined for that purpose, registered in the respective IANA 1304 registry, and used in place of the ath claim defined herein. 1306 11.9. Authorization Code and Public Key Binding 1308 Cryptographic binding of the authorization code to the DPoP public 1309 key, is specified in Section 10. This binding prevents attacks in 1310 which the attacker captures the authorization code and creates a DPoP 1311 proof using a proof-of-possession key other than that held by the 1312 client and redeems the authorization code using that DPoP proof. By 1313 ensuring end-to-end that only the client's DPoP key can be used, this 1314 prevents captured authorization codes from being exfiltrated and used 1315 at locations other than the one to which the authorization code was 1316 issued. 1318 Authorization codes can, for instance, be harvested by attackers from 1319 places that the HTTP messages containing them are logged. Even when 1320 efforts are made to make authorization codes one-time-use, in 1321 practice, there is often a time window during which attackers can 1322 replay them. For instance, when authorization servers are 1323 implemented as scalable replicated services, some replicas may 1324 temporarily not yet have the information needed to prevent replay. 1325 DPoP binding of the authorization code solves these problems. 1327 If an authorization server does not (or cannot) strictly enforce the 1328 single-use limitation for authorization codes and an attacker can 1329 access the authorization code (and if PKCE is used, the 1330 code_verifier), the attacker can create a forged token request, 1331 binding the resulting token to an attacker-controlled key. For 1332 example, using cross-site scripting, attackers might obtain access to 1333 the authorization code and PKCE parameters. Use of the dpop_jkt 1334 parameter prevents this attack. 1336 The binding of the authorization code to the DPoP public key uses a 1337 JWK Thumbprint of the public key, just as the access token binding 1338 does. The same JWK Thumbprint considerations apply. 1340 12. IANA Considerations 1342 12.1. OAuth Access Token Type Registration 1344 This specification requests registration of the following access 1345 token type in the "OAuth Access Token Types" registry 1346 [IANA.OAuth.Params] established by [RFC6749]. 1348 * Type name: DPoP 1349 * Additional Token Endpoint Response Parameters: (none) 1350 * HTTP Authentication Scheme(s): DPoP 1351 * Change controller: IESG 1352 * Specification document(s): [[ this specification ]] 1354 12.2. OAuth Extensions Error Registration 1356 This specification requests registration of the following error 1357 values in the "OAuth Extensions Error" registry [IANA.OAuth.Params] 1358 established by [RFC6749]. 1360 Invalid DPoP proof: 1362 * Name: invalid_dpop_proof 1363 * Usage Location: token error response, resource error response 1364 * Protocol Extension: Demonstrating Proof of Possession (DPoP) 1365 * Change controller: IETF 1366 * Specification document(s): [[ this specification ]] 1368 Use DPoP nonce: 1370 * Name: use_dpop_nonce 1371 * Usage Location: token error response, resource error response 1372 * Protocol Extension: Demonstrating Proof of Possession (DPoP) 1373 * Change controller: IETF 1374 * Specification document(s): [[ this specification ]] 1376 12.3. OAuth Parameters Registration 1378 This specification requests registration of the following 1379 authorization request parameter in the "OAuth Parameters" registry 1380 [IANA.OAuth.Params] established by [RFC6749]. 1382 * Name: dpop_jkt 1383 * Parameter Usage Location: authorization request 1384 * Change Controller: IESG 1385 * Reference: [[ {#dpop_jkt} of this specification ]] 1387 12.4. HTTP Authentication Scheme Registration 1389 This specification requests registration of the following scheme in 1390 the "Hypertext Transfer Protocol (HTTP) Authentication Scheme 1391 Registry" [RFC7235][IANA.HTTP.AuthSchemes]: 1393 * Authentication Scheme Name: DPoP 1394 * Reference: [[ Section 7.1 of this specification ]] 1396 12.5. Media Type Registration 1398 This section registers the application/dpop+jwt media type [RFC2046] 1399 in the IANA "Media Types" registry [IANA.MediaTypes] in the manner 1400 described in [RFC6838], which is used to indicate that the content is 1401 a DPoP JWT. 1403 * Type name: application 1404 * Subtype name: dpop+jwt 1405 * Required parameters: n/a 1406 * Optional parameters: n/a 1407 * Encoding considerations: binary; A DPoP JWT is a JWT; JWT values 1408 are encoded as a series of base64url-encoded values (some of which 1409 may be the empty string) separated by period ('.') characters. 1410 * Security considerations: See Section 11 of [[ this specification 1411 ]] 1412 * Interoperability considerations: n/a 1413 * Published specification: [[ this specification ]] 1414 * Applications that use this media type: Applications using [[ this 1415 specification ]] for application-level proof of possession 1416 * Fragment identifier considerations: n/a 1417 * Additional information: 1418 - File extension(s): n/a 1419 - Macintosh file type code(s): n/a 1420 * Person & email address to contact for further information: Michael 1421 B. Jones, mbj@microsoft.com 1422 * Intended usage: COMMON 1423 * Restrictions on usage: none 1424 * Author: Michael B. Jones, mbj@microsoft.com 1425 * Change controller: IETF 1426 * Provisional registration? No 1428 12.6. JWT Confirmation Methods Registration 1430 This specification requests registration of the following value in 1431 the IANA "JWT Confirmation Methods" registry [IANA.JWT] for JWT cnf 1432 member values established by [RFC7800]. 1434 * Confirmation Method Value: jkt 1435 * Confirmation Method Description: JWK SHA-256 Thumbprint 1436 * Change Controller: IESG 1437 * Specification Document(s): [[ Section 6 of this specification ]] 1439 12.7. JSON Web Token Claims Registration 1441 This specification requests registration of the following Claims in 1442 the IANA "JSON Web Token Claims" registry [IANA.JWT] established by 1443 [RFC7519]. 1445 HTTP method: 1447 * Claim Name: htm 1448 * Claim Description: The HTTP method of the request 1449 * Change Controller: IESG 1450 * Specification Document(s): [[ Section 4.2 of this specification ]] 1452 HTTP URI: 1454 * Claim Name: htu 1455 * Claim Description: The HTTP URI of the request (without query and 1456 fragment parts) 1457 * Change Controller: IESG 1458 * Specification Document(s): [[ Section 4.2 of this specification ]] 1460 Access token hash: 1462 * Claim Name: ath 1463 * Claim Description: The base64url encoded SHA-256 hash of the ASCII 1464 encoding of the associated access token's value 1465 * Change Controller: IESG 1466 * Specification Document(s): [[ Section 4.2 of this specification ]] 1468 12.8. HTTP Message Header Field Names Registration 1470 This document specifies the following HTTP header fields, 1471 registration of which is requested in the "Permanent Message Header 1472 Field Names" registry [IANA.Headers] defined in [RFC3864]. 1474 * Header Field Name: DPoP 1475 * Applicable protocol: HTTP 1476 * Status: standard 1477 * Author/change Controller: IETF 1478 * Specification Document(s): [[ this specification ]] 1480 12.9. OAuth Authorization Server Metadata Registration 1482 This specification requests registration of the following value in 1483 the IANA "OAuth Authorization Server Metadata" registry 1484 [IANA.OAuth.Parameters] established by [RFC8414]. 1486 * Metadata Name: dpop_signing_alg_values_supported 1487 * Metadata Description: JSON array containing a list of the JWS 1488 algorithms supported for DPoP proof JWTs 1489 * Change Controller: IESG 1490 * Specification Document(s): [[ Section 5.1 of this specification ]] 1492 12.10. OAuth Dynamic Client Registration Metadata 1494 This specification requests registration of the following value in 1495 the IANA "OAuth Dynamic Client Registration Metadata" registry 1496 [IANA.OAuth.Parameters] established by [RFC7591]. 1498 * Metadata Name: dpop_bound_access_tokens 1499 * Metadata Description: Boolean value specifying whether the client 1500 always uses DPoP for token requests 1501 * Change Controller: IESG 1502 * Specification Document(s): [[ Section 5.2 of this specification ]] 1504 13. Normative References 1506 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1507 Requirement Levels", BCP 14, RFC 2119, 1508 DOI 10.17487/RFC2119, March 1997, 1509 . 1511 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1512 Resource Identifier (URI): Generic Syntax", STD 66, 1513 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1514 . 1516 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1517 Specifications: ABNF", STD 68, RFC 5234, 1518 DOI 10.17487/RFC5234, January 2008, 1519 . 1521 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1522 Verification of Domain-Based Application Service Identity 1523 within Internet Public Key Infrastructure Using X.509 1524 (PKIX) Certificates in the Context of Transport Layer 1525 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 1526 2011, . 1528 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1529 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1530 . 1532 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1533 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1534 DOI 10.17487/RFC7231, June 2014, 1535 . 1537 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1538 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1539 2015, . 1541 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 1542 DOI 10.17487/RFC7517, May 2015, 1543 . 1545 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 1546 DOI 10.17487/RFC7518, May 2015, 1547 . 1549 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 1550 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 1551 2015, . 1553 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1554 Possession Key Semantics for JSON Web Tokens (JWTs)", 1555 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1556 . 1558 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1559 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1560 May 2017, . 1562 [SHS] National Institute of Standards and Technology, "Secure 1563 Hash Standard (SHS)", FIPS PUB 180-4, August 2015, 1564 . 1567 14. Informative References 1569 [I-D.ietf-oauth-security-topics] 1570 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 1571 "OAuth 2.0 Security Best Current Practice", Work in 1572 Progress, Internet-Draft, draft-ietf-oauth-security- 1573 topics-19, 16 December 2021, 1574 . 1577 [I-D.ietf-oauth-token-binding] 1578 Jones, M. B., Campbell, B., Bradley, J., and W. Denniss, 1579 "OAuth 2.0 Token Binding", Work in Progress, Internet- 1580 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 1581 . 1584 [IANA.HTTP.AuthSchemes] 1585 IANA, "Hypertext Transfer Protocol (HTTP) Authentication 1586 Scheme Registry", 1587 . 1589 [IANA.Headers] 1590 IANA, "Message Headers", 1591 . 1593 [IANA.JWT] IANA, "JSON Web Token Claims", 1594 . 1596 [IANA.MediaTypes] 1597 IANA, "Media Types", 1598 . 1600 [IANA.OAuth.Params] 1601 IANA, "OAuth Parameters", 1602 . 1604 [OpenID.Core] 1605 Sakimura, N., Bradley, J., Jones, M.B., Medeiros, B.d., 1606 and C. Mortimore, "OpenID Connect Core 1.0", November 1607 2014, 1608 . 1610 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1611 Extensions (MIME) Part Two: Media Types", RFC 2046, 1612 DOI 10.17487/RFC2046, November 1996, 1613 . 1615 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1616 Procedures for Message Header Fields", BCP 90, RFC 3864, 1617 DOI 10.17487/RFC3864, September 2004, 1618 . 1620 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1621 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1622 DOI 10.17487/RFC4122, July 2005, 1623 . 1625 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1626 Framework: Bearer Token Usage", RFC 6750, 1627 DOI 10.17487/RFC6750, October 2012, 1628 . 1630 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1631 Specifications and Registration Procedures", BCP 13, 1632 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1633 . 1635 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1636 Protocol (HTTP/1.1): Message Syntax and Routing", 1637 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1638 . 1640 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1641 Protocol (HTTP/1.1): Authentication", RFC 7235, 1642 DOI 10.17487/RFC7235, June 2014, 1643 . 1645 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1646 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1647 . 1649 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1650 (JWT) Profile for OAuth 2.0 Client Authentication and 1651 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1652 2015, . 1654 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1655 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1656 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1657 . 1659 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 1660 for Code Exchange by OAuth Public Clients", RFC 7636, 1661 DOI 10.17487/RFC7636, September 2015, 1662 . 1664 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1665 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1666 . 1668 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1669 Authorization Server Metadata", RFC 8414, 1670 DOI 10.17487/RFC8414, June 2018, 1671 . 1673 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 1674 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 1675 and Certificate-Bound Access Tokens", RFC 8705, 1676 DOI 10.17487/RFC8705, February 2020, 1677 . 1679 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 1680 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 1681 February 2020, . 1683 [RFC9126] Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., 1684 and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", 1685 RFC 9126, DOI 10.17487/RFC9126, September 2021, 1686 . 1688 [W3C.CSP] West, M., "Content Security Policy Level 3", World Wide 1689 Web Consortium Working Draft WD-CSP3-20181015, 15 October 1690 2018, . 1692 [W3C.WebCryptoAPI] 1693 Watson, M., "Web Cryptography API", World Wide Web 1694 Consortium Recommendation REC-WebCryptoAPI-20170126, 26 1695 January 2017, 1696 . 1698 Appendix A. Acknowledgements 1700 We would like to thank Annabelle Backman, Dominick Baier, Vittorio 1701 Bertocci, Jeff Corrigan, Andrii Deinega, William Denniss, Vladimir 1702 Dzhuvinov, Mike Engan, Nikos Fotiou, Mark Haine, Dick Hardt, Joseph 1703 Heenan, Bjorn Hjelm, Jacob Ideskog, Jared Jennings, Benjamin Kaduk, 1704 Pieter Kasselman, Steinar Noem, Neil Madden, Rohan Mahy, Karsten 1705 Meyer zu Selhausen, Nicolas Mora, Rob Otto, Aaron Parecki, Michael 1706 Peck, Roberto Polli, Paul Querna, Justin Richer, Filip Skokan, Dmitry 1707 Telegin, Dave Tonge, Jim Willeke, Philippe De Ryck, and others 1708 (please let us know, if you've been mistakenly omitted) for their 1709 valuable input, feedback and general support of this work. 1711 This document originated from discussions at the 4th OAuth Security 1712 Workshop in Stuttgart, Germany. We thank the organizers of this 1713 workshop (Ralf Kusters, Guido Schmitz). 1715 Appendix B. Document History 1717 [[ To be removed from the final specification ]] 1719 -08 1721 * Lots of editorial updates from WGLC feedback 1722 * Further clarify that either iat or nonce can be used alone in 1723 validating the timeliness of the proof and somewhat de-emphasize 1724 jti tracking 1726 -07 1728 * Registered the application/dpop+jwt media type. 1729 * Editorial updates/clarifications based on review feedback. 1730 * Added "(on the order of seconds or minutes)" to somewhat qualify 1731 "relatively brief period" and "reasonably near future" and give a 1732 general idea of expected timeframe without being overly 1733 prescriptive. 1734 * Added a step to Section 4.3 to reiterate that the jwk header 1735 cannot have a private key. 1737 -06 1739 * Editorial updates and fixes 1740 * Changed name of client metadata parameter to 1741 dpop_bound_access_tokens 1743 -05 1745 * Added Authorization Code binding via the dpop_jkt parameter. 1746 * Described the authorization code reuse attack and how dpop_jkt 1747 mitigates it. 1748 * Enhanced description of DPoP proof expiration checking. 1749 * Described nonce storage requirements and how nonce mismatches and 1750 missing nonces are self-correcting. 1751 * Specified the use of the use_dpop_nonce error for missing and 1752 mismatched nonce values. 1754 * Specified that authorization servers use 400 (Bad Request) errors 1755 to supply nonces and resource servers use 401 (Unauthorized) 1756 errors to do so. 1757 * Added a bit more about ath and pre-generated proofs to the 1758 security considerations. 1759 * Mentioned confirming the DPoP binding of the access token in the 1760 list in Section 4.3. 1761 * Added the always_uses_dpop client registration metadata parameter. 1762 * Described the relationship between DPoP and Pushed Authorization 1763 Requests (PAR). 1764 * Updated references for drafts that are now RFCs. 1766 -04 1768 * Added the option for a server-provided nonce in the DPoP proof. 1769 * Registered the invalid_dpop_proof and use_dpop_nonce error codes. 1770 * Removed fictitious uses of realm from the examples, as they added 1771 no value. 1772 * State that if the introspection response has a token_type, it has 1773 to be DPoP. 1774 * Mention that RFC7235 allows multiple authentication schemes in 1775 WWW-Authenticate with a 401. 1776 * Editorial fixes. 1778 -03 1780 * Add an access token hash (ath) claim to the DPoP proof when used 1781 in conjunction with the presentation of an access token for 1782 protected resource access 1783 * add Untrusted Code in the Client Context section to security 1784 considerations 1785 * Editorial updates and fixes 1787 -02 1789 * Lots of editorial updates and additions including expanding on the 1790 objectives, better defining the key confirmation representations, 1791 example updates and additions, better describing mixed bearer/dpop 1792 token type deployments, clarify RT binding only being done for 1793 public clients and why, more clearly allow for a bound RT but with 1794 bearer AT, explain/justify the choice of SHA-256 for key binding, 1795 and more 1796 * Require that a protected resource supporting bearer and DPoP at 1797 the same time must reject an access token received as bearer, if 1798 that token is DPoP-bound 1799 * Remove the case-insensitive qualification on the htm claim check 1800 * Relax the jti tracking requirements a bit and qualify it by URI 1801 -01 1803 * Editorial updates 1804 * Attempt to more formally define the DPoP Authorization header 1805 scheme 1806 * Define the 401/WWW-Authenticate challenge 1807 * Added invalid_dpop_proof error code for DPoP errors in token 1808 request 1809 * Fixed up and added to the IANA section 1810 * Added dpop_signing_alg_values_supported authorization server 1811 metadata 1812 * Moved the Acknowledgements into an Appendix and added a bunch of 1813 names (best effort) 1815 -00 [[ Working Group Draft ]] 1817 * Working group draft 1819 -04 1821 * Update OAuth MTLS reference to RFC 8705 1822 * Use the newish RFC v3 XML and HTML format 1824 -03 1826 * rework the text around uniqueness requirements on the jti claim in 1827 the DPoP proof JWT 1828 * make tokens a bit smaller by using htm, htu, and jkt rather than 1829 http_method, http_uri, and jkt#S256 respectively 1830 * more explicit recommendation to use mTLS if that is available 1831 * added David Waite as co-author 1832 * editorial updates 1834 -02 1836 * added normalization rules for URIs 1837 * removed distinction between proof and binding 1838 * "jwk" header again used instead of "cnf" claim in DPoP proof 1839 * renamed "Bearer-DPoP" token type to "DPoP" 1840 * removed ability for key rotation 1841 * added security considerations on request integrity 1842 * explicit advice on extending DPoP proofs to sign other parts of 1843 the HTTP messages 1844 * only use the jkt#S256 in ATs 1845 * iat instead of exp in DPoP proof JWTs 1846 * updated guidance on token_type evaluation 1848 -01 1849 * fixed inconsistencies 1850 * moved binding and proof messages to headers instead of parameters 1851 * extracted and unified definition of DPoP JWTs 1852 * improved description 1854 -00 1856 * first draft 1858 Authors' Addresses 1860 Daniel Fett 1861 yes.com 1862 Email: mail@danielfett.de 1864 Brian Campbell 1865 Ping Identity 1866 Email: bcampbell@pingidentity.com 1868 John Bradley 1869 Yubico 1870 Email: ve7jtb@ve7jtb.com 1872 Torsten Lodderstedt 1873 yes.com 1874 Email: torsten@lodderstedt.net 1876 Michael Jones 1877 Microsoft 1878 Email: mbj@microsoft.com 1879 URI: https://self-issued.info/ 1881 David Waite 1882 Ping Identity 1883 Email: david@alkaline-solutions.com