idnits 2.17.1 draft-ietf-oauth-dpop-03.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 (7 April 2021) is 1115 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 7231 (Obsoleted by RFC 9110) -- 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) == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-16 == Outdated reference: A later version (-34) exists of draft-ietf-oauth-jwsreq-30 == Outdated reference: A later version (-13) exists of draft-ietf-oauth-access-token-jwt-11 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 3 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: 9 October 2021 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 7 April 2021 16 OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer 17 (DPoP) 18 draft-ietf-oauth-dpop-03 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 9 October 2021. 44 Copyright Notice 46 Copyright (c) 2021 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 Simplified BSD License text 55 as described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 62 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 4. DPoP Proof JWTs . . . . . . . . . . . . . . . . . . . . . . . 7 65 4.1. The DPoP HTTP Header . . . . . . . . . . . . . . . . . . 7 66 4.2. DPoP Proof JWT Syntax . . . . . . . . . . . . . . . . . . 8 67 4.3. Checking DPoP Proofs . . . . . . . . . . . . . . . . . . 10 68 5. DPoP Access Token Request . . . . . . . . . . . . . . . . . . 10 69 5.1. Authorization Server Metadata . . . . . . . . . . . . . . 13 70 6. Public Key Confirmation . . . . . . . . . . . . . . . . . . . 13 71 6.1. JWK Thumbprint Confirmation Method . . . . . . . . . . . 14 72 6.2. JWK Thumbprint Confirmation Method in Token 73 Introspection . . . . . . . . . . . . . . . . . . . . . . 14 74 7. Protected Resource Access . . . . . . . . . . . . . . . . . . 16 75 7.1. The DPoP Authorization Request Header Scheme . . . . . . 16 76 7.2. The Bearer Authorization Request Header Scheme . . . . . 19 77 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 78 8.1. DPoP Proof Replay . . . . . . . . . . . . . . . . . . . . 19 79 8.2. Untrusted Code in the Client Context . . . . . . . . . . 20 80 8.3. Signed JWT Swapping . . . . . . . . . . . . . . . . . . . 21 81 8.4. Signature Algorithms . . . . . . . . . . . . . . . . . . 21 82 8.5. Message Integrity . . . . . . . . . . . . . . . . . . . . 21 83 8.6. Access Token and Public Key Binding . . . . . . . . . . . 22 84 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 85 9.1. OAuth Access Token Type Registration . . . . . . . . . . 22 86 9.2. HTTP Authentication Scheme Registration . . . . . . . . . 22 87 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 23 88 9.4. JWT Confirmation Methods Registration . . . . . . . . . . 23 89 9.5. JSON Web Token Claims Registration . . . . . . . . . . . 23 90 9.6. HTTP Message Header Field Names Registration . . . . . . 24 91 9.7. Authorization Server Metadata Registration . . . . . . . 24 92 10. Normative References . . . . . . . . . . . . . . . . . . . . 25 93 11. Informative References . . . . . . . . . . . . . . . . . . . 25 94 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 29 95 Appendix B. Document History . . . . . . . . . . . . . . . . . . 29 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 98 1. Introduction 100 DPoP, an abbreviation for Demonstrating Proof-of-Possession at the 101 Application Layer, is an application-level mechanism for sender- 102 constraining OAuth access and refresh tokens. It enables a client to 103 demonstrate proof-of-possession of a public/private key pair by 104 including a "DPoP" header in an HTTP request. The value of the 105 header is a JWT [RFC7519] that enables the authorization server to 106 bind issued tokens to the public part of a client's key pair. 107 Recipients of such tokens are then able to verify the binding of the 108 token to the key pair that the client has demonstrated that it holds 109 via the "DPoP" header, thereby providing some assurance that the 110 client presenting the token also possesses the private key. In other 111 words, the legitimate presenter of the token is constrained to be the 112 sender that holds and can prove possession of the private part of the 113 key pair. 115 The mechanism described herein can be used in cases where other 116 methods of sender-constraining tokens that utilize elements of the 117 underlying secure transport layer, such as [RFC8705] or 118 [I-D.ietf-oauth-token-binding], are not available or desirable. For 119 example, due to a sub-par user experience of TLS client 120 authentication in user agents and a lack of support for HTTP token 121 binding, neither mechanism can be used if an OAuth client is a Single 122 Page Application (SPA) running in a web browser. Native applications 123 installed and run on a user's device, which often have dedicated 124 protected storage for cryptographic keys are another example well 125 positioned to benefit from DPoP-bound tokens to guard against misuse 126 of tokens by a compromised or malicious resource. 128 DPoP can be used to sender-constrain access tokens regardless of the 129 client authentication method employed. Furthermore, DPoP can also be 130 used to sender-constrain refresh tokens issued to public clients 131 (those without authentication credentials associated with the 132 "client_id"). 134 1.1. Conventions and Terminology 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 138 "OPTIONAL" in this document are to be interpreted as described in BCP 139 14 [RFC2119] [RFC8174] when, and only when, they appear in all 140 capitals, as shown here. 142 This specification uses the terms "access token", "refresh token", 143 "authorization server", "resource server", "authorization endpoint", 144 "authorization request", "authorization response", "token endpoint", 145 "grant type", "access token request", "access token response", and 146 "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 148 2. Objectives 150 The primary aim of DPoP is to prevent unauthorized or illegitimate 151 parties from using leaked or stolen access tokens by binding a token 152 to a public key upon issuance and requiring that the client 153 demonstrate possession of the corresponding private key when using 154 the token. This constrains the legitimate sender of the token to 155 only the party with access to the private key and gives the server 156 receiving the token added assurances that the sender is legitimately 157 authorized to use it. 159 Access tokens that are sender-constrained via DPoP thus stand in 160 contrast to the typical bearer token, which can be used by any party 161 in possession of such a token. Although protections generally exist 162 to prevent unintended disclosure of bearer tokens, unforeseen vectors 163 for leakage have occurred due to vulnerabilities and implementation 164 issues in other layers in the protocol or software stack (CRIME, 165 BREACH, Heartbleed, and the Cloudflare parser bug are some examples). 166 There have also been numerous published token theft attacks on OAuth 167 implementations themselves. DPoP provides a general defense in depth 168 against the impact of unanticipated token leakage. DPoP is not, 169 however, a substitute for a secure transport and MUST always be used 170 in conjunction with HTTPS. 172 The very nature of the typical OAuth protocol interaction 173 necessitates that the client disclose the access token to the 174 protected resources that it accesses. The attacker model in 175 [I-D.ietf-oauth-security-topics] describes cases where a protected 176 resource might be counterfeit, malicious or compromised and play 177 received tokens against other protected resources to gain 178 unauthorized access. Properly audience restricting access tokens can 179 prevent such misuse, however, doing so in practice has proven to be 180 prohibitively cumbersome (even despite extensions such as [RFC8707]) 181 for many deployments. Sender-constraining access tokens is a more 182 robust and straightforward mechanism to prevent such token replay at 183 a different endpoint and DPoP is an accessible application layer 184 means of doing so. 186 Due to the potential for cross-site scripting (XSS), browser-based 187 OAuth clients bring to bear added considerations with respect to 188 protecting tokens. The most straightforward XSS-based attack is for 189 an attacker to exfiltrate a token and use it themselves completely 190 independent from the legitimate client. A stolen access token is 191 used for protected resource access and a stolen refresh token for 192 obtaining new access tokens. If the private key is non-extractable 193 (as is possible with [W3C.WebCryptoAPI]), DPoP renders exfiltrated 194 tokens alone unusable. 196 XXS vulnerabilities also allow an attacker to execute code in the 197 context of the browser-based client application and maliciously use a 198 token indirectly through the client. That execution context has 199 access to utilize the signing key and thus can produce DPoP proofs to 200 use in conjunction with the token. At this application layer there 201 is most likely no feasible defense against this threat except 202 generally preventing XSS, therefore it is considered out of scope for 203 DPoP. 205 Malicious XSS code executed in the context of the browser-based 206 client application is also in a position to create DPoP proofs with 207 timestamp values in the future and exfiltrate them in conjunction 208 with a token. These stolen artifacts can later be used together 209 independent of the client application to access protected resources. 210 The impact of such precomputed DPoP proofs is limited somewhat by the 211 proof being bound to an access token on protected resource access. 212 Because a proof covering an access token that don't yet exist cannot 213 feasibly be created, access tokens obtained with an exfiltrated 214 refresh token and pre-computed proofs will be unusable. 216 Additional security considerations are discussed in Section 8. 218 3. Concept 220 The main data structure introduced by this specification is a DPoP 221 proof JWT, described in detail below, which is sent as a header in an 222 HTTP request. A client uses a DPoP proof JWT to prove the possession 223 of a private key corresponding to a certain public key. Roughly 224 speaking, a DPoP proof is a signature over a timestamp and some data 225 of the HTTP request to which it is attached. 227 +--------+ +---------------+ 228 | |--(A)-- Token Request ------------------->| | 229 | Client | (DPoP Proof) | Authorization | 230 | | | Server | 231 | |<-(B)-- DPoP-bound Access Token ----------| | 232 | | (token_type=DPoP) +---------------+ 233 | | 234 | | 235 | | +---------------+ 236 | |--(C)-- DPoP-bound Access Token --------->| | 237 | | (DPoP Proof) | Resource | 238 | | | Server | 239 | |<-(D)-- Protected Resource ---------------| | 240 | | +---------------+ 241 +--------+ 243 Figure 1: Basic DPoP Flow 245 The basic steps of an OAuth flow with DPoP are shown in Figure 1: 247 * (A) In the Token Request, the client sends an authorization grant 248 (e.g., an authorization code, refresh token, etc.) 249 to the authorization server in order to obtain an access token 250 (and potentially a refresh token). The client attaches a DPoP 251 proof to the request in an HTTP header. 253 * (B) The authorization server binds (sender-constrains) the access 254 token to the public key claimed by the client in the DPoP proof; 255 that is, the access token cannot be used without proving 256 possession of the respective private key. If a refresh token is 257 issued to a public client, it too is bound to the public key of 258 the DPoP proof. 260 * (C) To use the access token the client has to prove possession of 261 the private key by, again, adding a header to the request that 262 carries a DPoP proof for that request. The resource server needs 263 to receive information about the public key to which the access 264 token is bound. This information may be encoded directly into the 265 access token (for JWT structured access tokens) or provided via 266 token introspection endpoint (not shown). The resource server 267 verifies that the public key to which the access token is bound 268 matches the public key of the DPoP proof. 270 * (D) The resource server refuses to serve the request if the 271 signature check fails or the data in the DPoP proof is wrong, 272 e.g., the request URI does not match the URI claim in the DPoP 273 proof JWT. The access token itself, of course, must also be valid 274 in all other respects. 276 The DPoP mechanism presented herein is not a client authentication 277 method. In fact, a primary use case of DPoP is for public clients 278 (e.g., single page applications and native applications) that do not 279 use client authentication. Nonetheless, DPoP is designed such that 280 it is compatible with "private_key_jwt" and all other client 281 authentication methods. 283 DPoP does not directly ensure message integrity but relies on the TLS 284 layer for that purpose. See Section 8 for details. 286 4. DPoP Proof JWTs 288 DPoP introduces the concept of a DPoP proof, which is a JWT created 289 by the client and sent with an HTTP request using the "DPoP" header 290 field. Each HTTP request requires a unique DPoP proof. A valid DPoP 291 proof demonstrates to the server that the client holds the private 292 key that was used to sign the DPoP proof JWT. This enables 293 authorization servers to bind issued tokens to the corresponding 294 public key (as described in Section 5) and for resource servers to 295 verify the key-binding of tokens that it receives (see Section 7.1), 296 which prevents said tokens from being used by any entity that does 297 not have access to the private key. 299 The DPoP proof demonstrates possession of a key and, by itself, is 300 not an authentication or access control mechanism. When presented in 301 conjunction with a key-bound access token as described in 302 Section 7.1, the DPoP proof provides additional assurance about the 303 legitimacy of the client to present the access token. However, a 304 valid DPoP proof JWT is not sufficient alone to make access control 305 decisions. 307 4.1. The DPoP HTTP Header 309 A DPoP proof is included in an HTTP request using the following 310 message header field. 312 "DPoP" A JWT that adheres to the structure and syntax of 313 Section 4.2. 315 Figure 2 shows an example DPoP HTTP header field (line breaks and 316 extra whitespace for display purposes only). 318 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik 319 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR 320 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE 321 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj 322 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia 323 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg 324 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg 326 Figure 2: Example "DPoP" header 328 Note that per [RFC7230] header field names are case-insensitive; so 329 "DPoP", "DPOP", "dpop", etc., are all valid and equivalent header 330 field names. Case is significant in the header field value, however. 332 4.2. DPoP Proof JWT Syntax 334 A DPoP proof is a JWT ([RFC7519]) that is signed (using JWS, 335 [RFC7515]) with a private key chosen by the client (see below). The 336 header of a DPoP JWT contains at least the following parameters: 338 * "typ": type header, value "dpop+jwt" (REQUIRED). 340 * "alg": a digital signature algorithm identifier as per [RFC7518] 341 (REQUIRED). MUST NOT be "none" or an identifier for a symmetric 342 algorithm (MAC). 344 * "jwk": representing the public key chosen by the client, in JWK 345 format, as defined in Section 4.1.3 of [RFC7515] (REQUIRED). MUST 346 NOT contain the private key. 348 The payload of a DPoP proof contains at least the following claims: 350 * "jti": Unique identifier for the DPoP proof JWT (REQUIRED). The 351 value MUST be assigned such that there is a negligible probability 352 that the same value will be assigned to any other DPoP proof used 353 in the same context during the time window of validity. Such 354 uniqueness can be accomplished by encoding (base64url or any other 355 suitable encoding) at least 96 bits of pseudorandom data or by 356 using a version 4 UUID string according to [RFC4122]. The "jti" 357 can be used by the server for replay detection and prevention, see 358 Section 8.1. 360 * "htm": The HTTP method for the request to which the JWT is 361 attached, as defined in [RFC7231] (REQUIRED). 363 * "htu": The HTTP URI used for the request, without query and 364 fragment parts (REQUIRED). 366 * "iat": Time at which the JWT was created (REQUIRED). 368 When the DPoP proof is used in conjunction with the presentation of 369 an access token, see Section 7, the DPoP proof also contains the 370 following claim: 372 * "ath": hash of the access token (REQUIRED). The value MUST be the 373 result of a base64url encoding (with no padding) the SHA-256 hash 374 of the ASCII encoding of the associated access token's value. 376 Figure 3 is a conceptual example showing the decoded content of the 377 DPoP proof in Figure 2. The JSON of the JOSE header and payload are 378 shown but the signature part is omitted. As usual, line breaks and 379 extra whitespace are included for formatting and readability. 381 { 382 "typ":"dpop+jwt", 383 "alg":"ES256", 384 "jwk": { 385 "kty":"EC", 386 "x":"l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs", 387 "y":"9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA", 388 "crv":"P-256" 389 } 390 } 391 . 392 { 393 "jti":"-BwC3ESc6acc2lTc", 394 "htm":"POST", 395 "htu":"https://server.example.com/token", 396 "iat":1562262616 397 } 399 Figure 3: Example JWT content of a "DPoP" proof 401 Of the HTTP content in the request, only the HTTP method and URI are 402 included in the DPoP JWT, and therefore only these 2 headers of the 403 request are covered by the DPoP proof and its signature. The idea is 404 sign just enough of the HTTP data to provide reasonable proof-of- 405 possession with respect to the HTTP request. But that it be a 406 minimal subset of the HTTP data so as to avoid the substantial 407 difficulties inherent in attempting to normalize HTTP messages. 408 Nonetheless, DPoP proofs can be extended to contain other information 409 of the HTTP request (see also Section 8.5). 411 4.3. Checking DPoP Proofs 413 To check if a string that was received as part of an HTTP Request is 414 a valid DPoP proof, the receiving server MUST ensure that 416 1. the string value is a well-formed JWT, 418 2. all required claims per Section 4.2 are contained in the JWT, 420 3. the "typ" field in the header has the value "dpop+jwt", 422 4. the algorithm in the header of the JWT indicates an asymmetric 423 digital signature algorithm, is not "none", is supported by the 424 application, and is deemed secure, 426 5. the JWT signature verifies with the public key contained in the 427 "jwk" header of the JWT, 429 6. the "htm" claim matches the HTTP method value of the HTTP request 430 in which the JWT was received, 432 7. the "htu" claims matches the HTTPS URI value for the HTTP request 433 in which the JWT was received, ignoring any query and fragment 434 parts, 436 8. the token was issued within an acceptable timeframe and, within a 437 reasonable consideration of accuracy and resource utilization, a 438 proof JWT with the same "jti" value has not previously been 439 received at the same resource during that time period (see 440 Section 8.1). 442 Servers SHOULD employ Syntax-Based Normalization and Scheme-Based 443 Normalization in accordance with Section 6.2.2. and Section 6.2.3. of 444 [RFC3986] before comparing the "htu" claim. 446 If presented with an access token to a protected resource, the server 447 MUST ensure that the value of the "ath" claim equals the hash of the 448 access token that has been presented along side the DPoP proof. 450 5. DPoP Access Token Request 452 To request an access token that is bound to a public key using DPoP, 453 the client MUST provide a valid DPoP proof JWT in a "DPoP" header 454 when making an access token request to the authorization server's 455 token endpoint. This is applicable for all access token requests 456 regardless of grant type (including, for example, the common 457 "authorization_code" and "refresh_token" grant types but also 458 extension grants such as the JWT authorization grant [RFC7523]). The 459 HTTPS request shown in Figure 4 illustrates such an access token 460 request using an authorization code grant with a DPoP proof JWT in 461 the "DPoP" header (extra line breaks and whitespace for display 462 purposes only). 464 POST /token HTTP/1.1 465 Host: server.example.com 466 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 467 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik 468 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR 469 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE 470 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj 471 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia 472 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg 473 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg 475 grant_type=authorization_code 476 &code=SplxlOBeZQQYbYS6WxSbIA 477 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 478 &code_verifier=bEaL42izcC-o-xBk0K2vuJ6U-y1p9r_wW2dFWIWgjz- 480 Figure 4: Token Request for a DPoP sender-constrained token using an 481 authorization code 483 The "DPoP" HTTP header MUST contain a valid DPoP proof JWT. If the 484 DPoP proof is invalid, the authorization server issues an error 485 response per Section 5.2 of [RFC6749] with "invalid_dpop_proof" as 486 the value of the "error" parameter. 488 To sender-constrain the access token, after checking the validity of 489 the DPoP proof, the authorization server associates the issued access 490 token with the public key from the DPoP proof, which can be 491 accomplished as described in Section 6. A "token_type" of "DPoP" in 492 the access token response signals to the client that the access token 493 was bound to its DPoP key and can used as described in Section 7.1. 494 The example response shown in Figure 5 illustrates such a response. 496 HTTP/1.1 200 OK 497 Content-Type: application/json 498 Cache-Control: no-store 500 { 501 "access_token": "Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU", 502 "token_type": "DPoP", 503 "expires_in": 2677, 504 "refresh_token": "Q..Zkm29lexi8VnWg2zPW1x-tgGad0Ibc3s3EwM_Ni4-g" 505 } 506 Figure 5: Access Token Response 508 The example response in Figure 5 included a refresh token, which the 509 client can use to obtain a new access token when the previous one 510 expires. Refreshing an access token is a token request using the 511 "refresh_token" grant type made to the authorization server's token 512 endpoint. As with all access token requests, the client makes it a 513 DPoP request by including a DPoP proof, which is shown in the 514 Figure 6 example (extra line breaks and whitespace for display 515 purposes only). 517 POST /token HTTP/1.1 518 Host: server.example.com 519 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 520 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik 521 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR 522 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE 523 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj 524 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia 525 WF0IjoxNTYyMjY1Mjk2fQ.pAqut2IRDm_De6PR93SYmGBPXpwrAk90e8cP2hjiaG5Qs 526 GSuKDYW7_X620BxqhvYC8ynrrvZLTk41mSRroapUA 528 grant_type=refresh_token 529 &refresh_token=Q..Zkm29lexi8VnWg2zPW1x-tgGad0Ibc3s3EwM_Ni4-g 531 Figure 6: Token Request for a DPoP-bound token using a refresh token 533 When an authorization server supporting DPoP issues a refresh token 534 to a public client that presents a valid DPoP proof at the token 535 endpoint, the refresh token MUST be bound to the respective public 536 key. The binding MUST be validated when the refresh token is later 537 presented to get new access tokens. As a result, such a client MUST 538 present a DPoP proof for the same key that was used to obtain the 539 refresh token each time that refresh token is used to obtain a new 540 access token. The implementation details of the binding of the 541 refresh token are at the discretion of the authorization server. The 542 server both produces and validates the refresh tokens that it issues 543 so there's no interoperability consideration in the specific details 544 of the binding. 546 An authorization server MAY elect to issue access tokens which are 547 not DPoP bound, which is signaled to the client with a value of 548 "Bearer" in the "token_type" parameter of the access token response 549 per [RFC6750]. For a public client that is also issued a refresh 550 token, this has the effect of DPoP-binding the refresh token alone, 551 which can improve the security posture even when protected resources 552 are not updated to support DPoP. 554 A client expecting a DPoP-bound access token MAY discard the 555 response, if a "Bearer" token type is received. 557 Refresh tokens issued to confidential clients (those having 558 established authentication credentials with the authorization server) 559 are not bound to the DPoP proof public key because they are already 560 sender-constrained with a different existing mechanism. The OAuth 561 2.0 Authorization Framework [RFC6749] already requires that an 562 authorization server bind refresh tokens to the client to which they 563 were issued and that confidential clients authenticate to the 564 authorization server when presenting a refresh token. As a result, 565 such refresh tokens are sender-constrained by way of the client ID 566 and the associated authentication requirement. This existing sender- 567 constraining mechanism is more flexible (e.g., it allows credential 568 rotation for the client without invalidating refresh tokens) than 569 binding directly to a particular public key. 571 5.1. Authorization Server Metadata 573 This document introduces the following new authorization server 574 metadata [RFC8414] parameter to signal support for DPoP in general 575 and the specific JWS "alg" values the authorization server supports 576 for DPoP proof JWTs. 578 "dpop_signing_alg_values_supported" A JSON array containing a list 579 of the JWS "alg" values supported by the authorization server for 580 DPoP proof JWTs. 582 6. Public Key Confirmation 584 Resource servers MUST be able to reliably identify whether an access 585 token is bound using DPoP and ascertain sufficient information about 586 the public key to which the token is bound in order to verify the 587 binding with respect to the presented DPoP proof (see Section 7.1). 588 Such a binding is accomplished by associating the public key with the 589 token in a way that can be accessed by the protected resource, such 590 as embedding the JWK hash in the issued access token directly, using 591 the syntax described in Section 6.1, or through token introspection 592 as described in Section 6.2. Other methods of associating a public 593 key with an access token are possible, per agreement by the 594 authorization server and the protected resource, but are beyond the 595 scope of this specification. 597 Resource servers supporting DPoP MUST ensure that the public key from 598 the DPoP proof matches the public key to which the access token is 599 bound. 601 6.1. JWK Thumbprint Confirmation Method 603 When access tokens are represented as JSON Web Tokens (JWT) 604 [RFC7519], the public key information SHOULD be represented using the 605 "jkt" confirmation method member defined herein. To convey the hash 606 of a public key in a JWT, this specification introduces the following 607 new JWT Confirmation Method [RFC7800] member for use under the "cnf" 608 claim. 610 "jkt" JWK SHA-256 Thumbprint Confirmation Method. The value of the 611 "jkt" member MUST be the base64url encoding (as defined in 612 [RFC7515]) of the JWK SHA-256 Thumbprint (according to [RFC7638]) 613 of the DPoP public key (in JWK format) to which the access token 614 is bound. 616 The following example JWT in Figure 7 with decoded JWT payload shown 617 in Figure 8 contains a "cnf" claim with the "jkt" JWK thumbprint 618 confirmation method member. The "jkt" value in these examples is the 619 hash of the public key from the DPoP proofs in the examples in 620 Section 5. 622 eyJhbGciOiJFUzI1NiIsImtpZCI6IkJlQUxrYiJ9.eyJzdWIiOiJzb21lb25lQGV4YW1 623 wbGUuY29tIiwiaXNzIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJuYmYiOjE 624 1NjIyNjI2MTEsImV4cCI6MTU2MjI2NjIxNiwiY25mIjp7ImprdCI6IjBaY09DT1JaTll 625 5LURXcHFxMzBqWnlKR0hUTjBkMkhnbEJWM3VpZ3VBNEkifX0.3Tyo8VTcn6u_PboUmAO 626 YUY1kfAavomW_YwYMkmRNizLJoQzWy2fCo79Zi5yObpIzjWb5xW4OGld7ESZrh0fsrA 628 Figure 7: JWT containing a JWK SHA-256 Thumbprint Confirmation 630 { 631 "sub":"someone@example.com", 632 "iss":"https://server.example.com", 633 "nbf":1562262611, 634 "exp":1562266216, 635 "cnf":{"jkt":"0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"} 636 } 638 Figure 8: JWT Claims Set with a JWK SHA-256 Thumbprint Confirmation 640 6.2. JWK Thumbprint Confirmation Method in Token Introspection 642 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 643 protected resource to query an authorization server about the active 644 state of an access token as well as to determine metainformation 645 about the token. 647 For a DPoP-bound access token, the hash of the public key to which 648 the token is bound is conveyed to the protected resource as 649 metainformation in a token introspection response. The hash is 650 conveyed using the same "cnf" content with "jkt" member structure as 651 the JWK thumbprint confirmation method, described in Section 6.1, as 652 a top-level member of the introspection response JSON. Note that the 653 resource server does not send a DPoP proof with the introspection 654 request and the authorization server does not validate an access 655 token's DPoP binding at the introspection endpoint. Rather the 656 resource server uses the data of the introspection response to 657 validate the access token binding itself locally. 659 The example introspection request in Figure 9 and corresponding 660 response in Figure 10 illustrate an introspection exchange for the 661 example DPoP-bound access token that was issued in Figure 5. 663 POST /as/introspect.oauth2 HTTP/1.1 664 Host: server.example.com 665 Content-Type: application/x-www-form-urlencoded 666 Authorization: Basic cnM6cnM6TWt1LTZnX2xDektJZHo0ZnNON2tZY3lhK1Rp 668 token=Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU 670 Figure 9: Example Introspection Request 672 HTTP/1.1 200 OK 673 Content-Type: application/json 674 Cache-Control: no-store 676 { 677 "active": true, 678 "sub": "someone@example.com", 679 "iss": "https://server.example.com", 680 "nbf": 1562262611, 681 "exp": 1562266216, 682 "cnf": {"jkt": "0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"} 683 } 685 Figure 10: Example Introspection Response for a DPoP-Bound Access 686 Token 688 7. Protected Resource Access 690 To make use of an access token that is bound to a public key using 691 DPoP, a client MUST prove possession of the corresponding private key 692 by providing a DPoP proof in the "DPoP" request header. As such, 693 protected resource requests with a DPoP-bound access token 694 necessarily must include both a DPoP proof as per Section 4 and the 695 access token as described in Section 7.1. The DPoP proof MUST 696 include the "ath" claim with a valid hash of the associated access 697 token. 699 7.1. The DPoP Authorization Request Header Scheme 701 A DPoP-bound access token is sent using the "Authorization" request 702 header field per Section 2 of [RFC7235] using an authentication 703 scheme of "DPoP". The syntax of the "Authorization" header field for 704 the "DPoP" scheme uses the "token68" syntax defined in Section 2.1 of 705 [RFC7235] (repeated below for ease of reference) for credentials. 706 The Augmented Backus-Naur Form (ABNF) notation [RFC5234] syntax for 707 DPoP Authorization scheme credentials is as follows: 709 token68 = 1*( ALPHA / DIGIT / 710 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 712 credentials = "DPoP" 1*SP token68 714 Figure 11: DPoP Authorization Scheme ABNF 716 For such an access token, a resource server MUST check that a DPoP 717 proof was also received in the "DPoP" header field of the HTTP 718 request, check the DPoP proof according to the rules in Section 4.3, 719 and check that the public key of the DPoP proof matches the public 720 key to which the access token is bound per Section 6. 722 The resource server MUST NOT grant access to the resource unless all 723 checks are successful. 725 Figure 12 shows an example request to a protected resource with a 726 DPoP-bound access token in the "Authorization" header and the DPoP 727 proof in the "DPoP" header. Following that is Figure 13, which shows 728 the decoded content of that DPoP proof. The JSON of the JOSE header 729 and payload are shown but the signature part is omitted. As usual, 730 line breaks and extra whitespace are included for formatting and 731 readability in both examples. 733 GET /protectedresource HTTP/1.1 734 Host: resource.example.org 735 Authorization: DPoP Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU 736 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik 737 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR 738 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE 739 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiJlMWozVl9iS2ljOC1MQUVCIiwiaHRtIj 740 oiR0VUIiwiaHR1IjoiaHR0cHM6Ly9yZXNvdXJjZS5leGFtcGxlLm9yZy9wcm90ZWN0Z 741 WRyZXNvdXJjZSIsImlhdCI6MTU2MjI2MjYxOCwiYXRoIjoiZlVIeU8ycjJaM0RaNTNF 742 c05yV0JiMHhXWG9hTnk1OUlpS0NBcWtzbVFFbyJ9.2oW9RP35yRqzhrtNP86L-Ey71E 743 OptxRimPPToA1plemAgR6pxHF8y6-yqyVnmcw6Fy1dqd-jfxSYoMxhAJpLjA 745 Figure 12: DPoP Protected Resource Request 747 { 748 "typ":"dpop+jwt", 749 "alg":"ES256", 750 "jwk": { 751 "kty":"EC", 752 "x":"l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs", 753 "y":"9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA", 754 "crv":"P-256" 755 } 756 } 757 . 758 { 759 "jti":"e1j3V_bKic8-LAEB", 760 "htm":"GET", 761 "htu":"https://resource.example.org/protectedresource", 762 "iat":1562262618, 763 "ath":"fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo" 764 } 766 Figure 13: Decoded Content of the "DPoP" proof JWT in Figure 12 768 Upon receipt of a request for a URI of a protected resource within 769 the protection space requiring DPoP authorization, if the request 770 does not include valid credentials or does not contain an access 771 token sufficient for access to the protected resource, the server can 772 reply with a challenge using the 401 (Unauthorized) status code 773 ([RFC7235], Section 3.1) and the "WWW-Authenticate" header field 774 ([RFC7235], Section 4.1). The server MAY include the "WWW- 775 Authenticate" header in response to other conditions as well. 777 In such challenges: 779 * The scheme name is "DPoP". 781 * The authentication parameter "realm" MAY be included to indicate 782 the scope of protection in the manner described in [RFC7235], 783 Section 2.2. 785 * A "scope" authentication parameter MAY be included as defined in 786 [RFC6750], Section 3. 788 * An "error" parameter ([RFC6750], Section 3) SHOULD be included to 789 indicate the reason why the request was declined, if the request 790 included an access token but failed authorization. Parameter 791 values are described in Section 3.1 of [RFC6750]. 793 * An "error_description" parameter ([RFC6750], Section 3) MAY be 794 included along with the "error" parameter to provide developers a 795 human-readable explanation that is not meant to be displayed to 796 end-users. 798 * An "algs" parameter SHOULD be included to signal to the client the 799 JWS algorithms that are acceptable for the DPoP proof JWT. The 800 value of the parameter is a space-delimited list of JWS "alg" 801 (Algorithm) header values ([RFC7515], Section 4.1.1). 803 * Additional authentication parameters MAY be used and unknown 804 parameters MUST be ignored by recipients 806 For example, in response to a protected resource request without 807 authentication: 809 HTTP/1.1 401 Unauthorized 810 WWW-Authenticate: DPoP realm="WallyWorld", algs="ES256 PS256" 812 Figure 14: HTTP 401 Response To A Protected Resource Request Without 813 Authentication 815 And in response to a protected resource request that was rejected 816 because the confirmation of the DPoP binding in the access token 817 failed: 819 HTTP/1.1 401 Unauthorized 820 WWW-Authenticate: DPoP realm="WallyWorld", error="invalid_token", 821 error_description="Invalid DPoP key binding", algs="ES256" 823 Figure 15: HTTP 401 Response To A Protected Resource Request With 824 An Invalid Token 826 7.2. The Bearer Authorization Request Header Scheme 828 Protected resources simultaneously supporting both the "DPoP" and 829 "Bearer" schemes need to update how evaluation of bearer tokens is 830 performed to prevent downgraded usage of a DPoP-bound access tokens. 831 Specifically, such a protected resource MUST reject an access token 832 received as a bearer token per [!@RFC6750], if that token is 833 determined to be DPoP-bound. 835 A protected resource that supports only [RFC6750] and is unaware of 836 DPoP would most presumably accept a DPoP-bound access token as a 837 bearer token (JWT [RFC7519] says to ignore unrecognized claims, 838 Introspection [RFC7662] says that other parameters might be present 839 while placing no functional requirements on their presence, and 840 [RFC6750] is effectively silent on the content of the access token as 841 it relates to validity). As such, a client MAY send a DPoP-bound 842 access token using the "Bearer" scheme upon receipt of a "WWW- 843 Authenticate: Bearer" challenge from a protected resource (or if it 844 has prior such knowledge about the capabilities of the protected 845 resource). The effect of this likely simplifies the logistics of 846 phased upgrades to protected resources in their support DPoP or even 847 prolonged deployments of protected resources with mixed token type 848 support. 850 8. Security Considerations 852 In DPoP, the prevention of token replay at a different endpoint (see 853 Section 2) is achieved through the binding of the DPoP proof to a 854 certain URI and HTTP method. DPoP, however, has a somewhat different 855 nature of protection than TLS-based methods such as OAuth Mutual TLS 856 [RFC8705] or OAuth Token Binding [I-D.ietf-oauth-token-binding] (see 857 also Section 8.1 and Section 8.5). TLS-based mechanisms can leverage 858 a tight integration between the TLS layer and the application layer 859 to achieve a very high level of message integrity with respect to the 860 transport layer to which the token is bound and replay protection in 861 general. 863 8.1. DPoP Proof Replay 865 If an adversary is able to get hold of a DPoP proof JWT, the 866 adversary could replay that token at the same endpoint (the HTTP 867 endpoint and method are enforced via the respective claims in the 868 JWTs). To prevent this, servers MUST only accept DPoP proofs for a 869 limited time window after their "iat" time, preferably only for a 870 relatively brief period (on the order of a few seconds). Servers 871 SHOULD store, in the context of the request URI, the "jti" value of 872 each DPoP proof for the time window in which the respective DPoP 873 proof JWT would be accepted and decline HTTP requests to the same URI 874 for which the "jti" value has been seen before. In order to guard 875 against memory exhaustion attacks a server SHOULD reject DPoP proof 876 JWTs with unnecessarily large "jti" values or store only a hash 877 thereof. 879 Note: To accommodate for clock offsets, the server MAY accept DPoP 880 proofs that carry an "iat" time in the reasonably near future (e.g., 881 a few seconds in the future). 883 8.2. Untrusted Code in the Client Context 885 If an adversary is able to run code in the client's execution 886 context, the security of DPoP is no longer guaranteed. Common issues 887 in web applications leading to the execution of untrusted code are 888 cross-site scripting and remote code inclusion attacks. 890 If the private key used for DPoP is stored in such a way that it 891 cannot be exported, e.g., in a hardware or software security module, 892 the adversary cannot exfiltrate the key and use it to create 893 arbitrary DPoP proofs. The adversary can, however, create new DPoP 894 proofs as long as the client is online, and use these proofs 895 (together with the respective tokens) either on the victim's device 896 or on a device under the attacker's control to send arbitrary 897 requests that will be accepted by servers. 899 To send requests even when the client is offline, an adversary can 900 try to pre-compute DPoP proofs using timestamps in the future and 901 exfiltrate these together with the access or refresh token. 903 An adversary might further try to associate tokens issued from the 904 token endpoint with a key pair under the adversary's control. One 905 way to achieve this is to modify existing code, e.g., by replacing 906 cryptographic APIs. Another way is to launch a new authorization 907 grant between the client and the authorization server in an iframe. 908 This grant needs to be "silent", i.e., not require interaction with 909 the user. With code running in the client's origin, the adversary 910 has access to the resulting authorization code and can use it to 911 associate their own DPoP keys with the tokens returned from the token 912 endpoint. The adversary is then able to use the resulting tokens on 913 their own device even if the client is offline. 915 Therefore, protecting clients against the execution of untrusted code 916 is extremely important even if DPoP is used. Besides secure coding 917 practices, Content Security Policy [W3C.CSP] can be used as a second 918 layer of defense against cross-site scripting. 920 8.3. Signed JWT Swapping 922 Servers accepting signed DPoP proof JWTs MUST check the "typ" field 923 in the headers of the JWTs to ensure that adversaries cannot use JWTs 924 created for other purposes. 926 8.4. Signature Algorithms 928 Implementers MUST ensure that only asymmetric digital signature 929 algorithms that are deemed secure can be used for signing DPoP 930 proofs. In particular, the algorithm "none" MUST NOT be allowed. 932 8.5. Message Integrity 934 DPoP does not ensure the integrity of the payload or headers of 935 requests. The DPoP proof only contains claims for the HTTP URI and 936 method, but not, for example, the message body or general request 937 headers. 939 This is an intentional design decision intended to keep DPoP simple 940 to use, but as described, makes DPoP potentially susceptible to 941 replay attacks where an attacker is able to modify message contents 942 and headers. In many setups, the message integrity and 943 confidentiality provided by TLS is sufficient to provide a good level 944 of protection. 946 Implementers that have stronger requirements on the integrity of 947 messages are encouraged to either use TLS-based mechanisms or signed 948 requests. TLS-based mechanisms are in particular OAuth Mutual TLS 949 [RFC8705] and OAuth Token Binding [I-D.ietf-oauth-token-binding]. 951 Note: While signatures covering other parts of requests are out of 952 the scope of this specification, additional information to be signed 953 can be added into DPoP proofs. 955 8.6. Access Token and Public Key Binding 957 The binding of the access token to the DPoP public key, which is 958 specified in Section 6, uses a cryptographic hash of the JWK 959 representation of the public key. It relies on the hash function 960 having sufficient second-preimage resistance so as to make it 961 computationally infeasible to find or create another key that 962 produces to the same hash output value. The SHA-256 hash function 963 was used because it meets the aforementioned requirement while being 964 widely available. If, in the future, JWK thumbprints need to be 965 computed using hash function(s) other than SHA-256, it is suggested 966 that an additional related JWT confirmation method member be defined 967 for that purpose, registered in the respective IANA registry, and 968 used in place of the "jkt" confirmation method defined herein. 970 Similarly, the binding of the DPoP proof to the access token uses a 971 hash of that access token as the value of the "ath" claim in the DPoP 972 proof (see Section 4.2). This relies on the value of the hash being 973 sufficiently unique so as to reliably identify the access token. The 974 collision resistance of SHA-256 meets that requirement. If, in the 975 future, access token digests need be computed using hash function(s) 976 other than SHA-256, it is suggested that an additional related JWT 977 claim be defined for that purpose, registered in the respective IANA 978 registry, and used in place of the "ath" claim defined herein. 980 9. IANA Considerations 982 9.1. OAuth Access Token Type Registration 984 This specification requests registration of the following access 985 token type in the "OAuth Access Token Types" registry 986 [IANA.OAuth.Params] established by [RFC6749]. 988 * Type name: "DPoP" 990 * Additional Token Endpoint Response Parameters: (none) 992 * HTTP Authentication Scheme(s): "DPoP" 994 * Change controller: IESG 996 * Specification document(s): [[ this specification ]] 998 9.2. HTTP Authentication Scheme Registration 1000 This specification requests registration of the following scheme in 1001 the "Hypertext Transfer Protocol (HTTP) Authentication Scheme 1002 Registry" [RFC7235][IANA.HTTP.AuthSchemes]: 1004 * Authentication Scheme Name: "DPoP" 1006 * Reference: [[ Section 7.1 of this specification ]] 1008 9.3. Media Type Registration 1010 [[ Is a media type registration at [IANA.MediaTypes] necessary for 1011 "application/dpop+jwt"? There is a "+jwt" structured syntax suffix 1012 registered already at [IANA.MediaType.StructuredSuffix] by 1013 Section 7.2 of [RFC8417], which is maybe sufficient? A full-blown 1014 registration of "application/dpop+jwt" seems like it'd be overkill. 1015 The "dpop+jwt" is used in the JWS/JWT "typ" header for explicit 1016 typing of the JWT per Section 3.11 of [RFC8725] but it is not used 1017 anywhere else (such as the "Content-Type" of HTTP messages). 1019 Note that there does seem to be some precedence for [IANA.MediaTypes] 1020 registration with [I-D.ietf-oauth-access-token-jwt], 1021 [I-D.ietf-oauth-jwsreq], [RFC8417], and of course [RFC7519]. But 1022 precedence isn't always right. ]] 1024 9.4. JWT Confirmation Methods Registration 1026 This specification requests registration of the following value in 1027 the IANA "JWT Confirmation Methods" registry [IANA.JWT] for JWT "cnf" 1028 member values established by [RFC7800]. 1030 * Confirmation Method Value: "jkt" 1032 * Confirmation Method Description: JWK SHA-256 Thumbprint 1034 * Change Controller: IESG 1036 * Specification Document(s): [[ Section 6 of this specification ]] 1038 9.5. JSON Web Token Claims Registration 1040 This specification requests registration of the following Claims in 1041 the IANA "JSON Web Token Claims" registry [IANA.JWT] established by 1042 [RFC7519]. 1044 HTTP method: 1046 * Claim Name: "htm" 1048 * Claim Description: The HTTP method of the request 1050 * Change Controller: IESG 1051 * Specification Document(s): [[ Section 4.2 of this specification ]] 1053 HTTP URI: 1055 * Claim Name: "htu" 1057 * Claim Description: The HTTP URI of the request (without query and 1058 fragment parts) 1060 * Change Controller: IESG 1062 * Specification Document(s): [[ Section 4.2 of this specification ]] 1064 Access token hash: 1066 * Claim Name: "ath" 1068 * Claim Description: The base64url encoded SHA-256 hash of the ASCII 1069 encoding of the associated access token's value 1071 * Change Controller: IESG 1073 * Specification Document(s): [[ Section 4.2 of this specification ]] 1075 9.6. HTTP Message Header Field Names Registration 1077 This document specifies the following new HTTP header fields, 1078 registration of which is requested in the "Permanent Message Header 1079 Field Names" registry [IANA.Headers] defined in [RFC3864]. 1081 * Header Field Name: "DPoP" 1083 * Applicable protocol: HTTP 1085 * Status: standard 1087 * Author/change Controller: IETF 1089 * Specification Document(s): [[ this specification ]] 1091 9.7. Authorization Server Metadata Registration 1093 This specification requests registration of the following values in 1094 the IANA "OAuth Authorization Server Metadata" registry 1095 [IANA.OAuth.Parameters] established by [RFC8414]. 1097 * Metadata Name: "dpop_signing_alg_values_supported" 1098 * Metadata Description: JSON array containing a list of the JWS 1099 algorithms supported for DPoP proof JWTs 1101 * Change Controller: IESG 1103 * Specification Document(s): [[ Section 5.1 of this specification ]] 1105 10. Normative References 1107 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1108 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1109 . 1111 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1112 Specifications: ABNF", STD 68, RFC 5234, 1113 DOI 10.17487/RFC5234, January 2008, 1114 . 1116 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1117 Resource Identifier (URI): Generic Syntax", STD 66, 1118 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1119 . 1121 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1122 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1123 2015, . 1125 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1126 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1127 DOI 10.17487/RFC7231, June 2014, 1128 . 1130 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 1131 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 1132 2015, . 1134 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1135 Possession Key Semantics for JSON Web Tokens (JWTs)", 1136 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1137 . 1139 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 1140 DOI 10.17487/RFC7518, May 2015, 1141 . 1143 11. Informative References 1145 [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource 1146 Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, 1147 February 2020, . 1149 [W3C.WebCryptoAPI] 1150 Watson, M., "Web Cryptography API", 26 January 2017, 1151 . 1153 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1154 Protocol (HTTP/1.1): Message Syntax and Routing", 1155 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1156 . 1158 [W3C.CSP] West, M., "Content Security Policy Level 3", 15 October 1159 2018, . 1161 [IANA.HTTP.AuthSchemes] 1162 IANA, "Hypertext Transfer Protocol (HTTP) Authentication 1163 Scheme Registry", 1164 . 1166 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1167 Procedures for Message Header Fields", BCP 90, RFC 3864, 1168 DOI 10.17487/RFC3864, September 2004, 1169 . 1171 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 1172 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 1173 and Certificate-Bound Access Tokens", RFC 8705, 1174 DOI 10.17487/RFC8705, February 2020, 1175 . 1177 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1178 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1179 DOI 10.17487/RFC4122, July 2005, 1180 . 1182 [IANA.MediaTypes] 1183 IANA, "Media Types", 1184 . 1186 [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 1187 Current Practices", BCP 225, RFC 8725, 1188 DOI 10.17487/RFC8725, February 2020, 1189 . 1191 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1192 Protocol (HTTP/1.1): Authentication", RFC 7235, 1193 DOI 10.17487/RFC7235, June 2014, 1194 . 1196 [I-D.ietf-oauth-security-topics] 1197 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 1198 "OAuth 2.0 Security Best Current Practice", Work in 1199 Progress, Internet-Draft, draft-ietf-oauth-security- 1200 topics-16, 5 October 2020, . 1203 [IANA.OAuth.Params] 1204 IANA, "OAuth Parameters", 1205 . 1207 [IANA.MediaType.StructuredSuffix] 1208 IANA, "Structured Syntax Suffix Registry", 1209 . 1212 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1213 Framework: Bearer Token Usage", RFC 6750, 1214 DOI 10.17487/RFC6750, October 2012, 1215 . 1217 [RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, 1218 "Security Event Token (SET)", RFC 8417, 1219 DOI 10.17487/RFC8417, July 2018, 1220 . 1222 [I-D.ietf-oauth-jwsreq] 1223 Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 1224 Authorization Framework: JWT Secured Authorization Request 1225 (JAR)", Work in Progress, Internet-Draft, draft-ietf- 1226 oauth-jwsreq-30, 10 September 2020, 1227 . 1229 [IANA.JWT] IANA, "JSON Web Token Claims", 1230 . 1232 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1233 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1234 May 2017, . 1236 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1237 (JWT) Profile for OAuth 2.0 Client Authentication and 1238 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1239 2015, . 1241 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1242 Authorization Server Metadata", RFC 8414, 1243 DOI 10.17487/RFC8414, June 2018, 1244 . 1246 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1247 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1248 . 1250 [I-D.ietf-oauth-access-token-jwt] 1251 Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 1252 Access Tokens", Work in Progress, Internet-Draft, draft- 1253 ietf-oauth-access-token-jwt-11, 22 January 2021, 1254 . 1257 [IANA.Headers] 1258 IANA, "Message Headers", 1259 . 1261 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1262 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1263 . 1265 [I-D.ietf-oauth-token-binding] 1266 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 1267 "OAuth 2.0 Token Binding", Work in Progress, Internet- 1268 Draft, draft-ietf-oauth-token-binding-08, 19 October 2018, 1269 . 1272 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1273 Requirement Levels", BCP 14, RFC 2119, 1274 DOI 10.17487/RFC2119, March 1997, 1275 . 1277 Appendix A. Acknowledgements 1279 We would like to thank Annabelle Backman, Dominick Baier, Andrii 1280 Deinega, William Denniss, Vladimir Dzhuvinov, Mike Engan, Nikos 1281 Fotiou, Mark Haine, Dick Hardt, Bjorn Hjelm, Jared Jennings, Steinar 1282 Noem, Neil Madden, Rob Otto, Aaron Parecki, Michael Peck, Paul 1283 Querna, Justin Richer, Filip Skokan, Dave Tonge, Jim Willeke, 1284 Philippe De Ryck, and others (please let us know, if you've been 1285 mistakenly omitted) for their valuable input, feedback and general 1286 support of this work. 1288 This document resulted from discussions at the 4th OAuth Security 1289 Workshop in Stuttgart, Germany. We thank the organizers of this 1290 workshop (Ralf Kusters, Guido Schmitz). 1292 Appendix B. Document History 1294 [[ To be removed from the final specification ]] 1296 -03 1298 * Add an access token hash ("ath") claim to the DPoP proof when used 1299 in conjunction with the presentation of an access token for 1300 protected resource access 1302 * add Untrusted Code in the Client Context section to security 1303 considerations 1305 * Editorial updates and fixes 1307 -02 1309 * Lots of editorial updates and additions including expanding on the 1310 objectives, better defining the key confirmation representations, 1311 example updates and additions, better describing mixed bearer/dpop 1312 token type deployments, clarify RT binding only being done for 1313 public clients and why, more clearly allow for a bound RT but with 1314 bearer AT, explain/justify the choice of SHA-256 for key binding, 1315 and more 1317 * Require that a protected resource supporting bearer and DPoP at 1318 the same time must reject an access token received as bearer, if 1319 that token is DPoP-bound 1321 * Remove the case-insensitive qualification on the "htm" claim check 1323 * Relax the jti tracking requirements a bit and qualify it by URI 1324 -01 1326 * Editorial updates 1328 * Attempt to more formally define the DPoP Authorization header 1329 scheme 1331 * Define the 401/WWW-Authenticate challenge 1333 * Added "invalid_dpop_proof" error code for DPoP errors in token 1334 request 1336 * Fixed up and added to the IANA section 1338 * Added "dpop_signing_alg_values_supported" authorization server 1339 metadata 1341 * Moved the Acknowledgements into an Appendix and added a bunch of 1342 names (best effort) 1344 -00 [[ Working Group Draft ]] 1346 * Working group draft 1348 -04 1350 * Update OAuth MTLS reference to RFC 8705 1352 * Use the newish RFC v3 XML and HTML format 1354 -03 1356 * rework the text around uniqueness requirements on the jti claim in 1357 the DPoP proof JWT 1359 * make tokens a bit smaller by using "htm", "htu", and "jkt" rather 1360 than "http_method", "http_uri", and "jkt#S256" respectively 1362 * more explicit recommendation to use mTLS if that is available 1364 * added David Waite as co-author 1366 * editorial updates 1368 -02 1370 * added normalization rules for URIs 1371 * removed distinction between proof and binding 1373 * "jwk" header again used instead of "cnf" claim in DPoP proof 1375 * renamed "Bearer-DPoP" token type to "DPoP" 1377 * removed ability for key rotation 1379 * added security considerations on request integrity 1381 * explicit advice on extending DPoP proofs to sign other parts of 1382 the HTTP messages 1384 * only use the jkt#S256 in ATs 1386 * iat instead of exp in DPoP proof JWTs 1388 * updated guidance on token_type evaluation 1390 -01 1392 * fixed inconsistencies 1394 * moved binding and proof messages to headers instead of parameters 1396 * extracted and unified definition of DPoP JWTs 1398 * improved description 1400 -00 1402 * first draft 1404 Authors' Addresses 1406 Daniel Fett 1407 yes.com 1409 Email: mail@danielfett.de 1411 Brian Campbell 1412 Ping Identity 1414 Email: bcampbell@pingidentity.com 1415 John Bradley 1416 Yubico 1418 Email: ve7jtb@ve7jtb.com 1420 Torsten Lodderstedt 1421 yes.com 1423 Email: torsten@lodderstedt.net 1425 Michael Jones 1426 Microsoft 1428 Email: mbj@microsoft.com 1429 URI: https://self-issued.info/ 1431 David Waite 1432 Ping Identity 1434 Email: david@alkaline-solutions.com