idnits 2.17.1 draft-ietf-oauth-token-binding-04.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 (July 3, 2017) is 2479 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) == Outdated reference: A later version (-18) exists of draft-ietf-tokbind-https-08 == Outdated reference: A later version (-14) exists of draft-ietf-tokbind-negotiation-07 == Outdated reference: A later version (-19) exists of draft-ietf-tokbind-protocol-13 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' == Outdated reference: A later version (-12) exists of draft-ietf-oauth-native-apps-08 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Bradley 5 Expires: January 4, 2018 B. Campbell 6 Ping Identity 7 W. Denniss 8 Google 9 July 3, 2017 11 OAuth 2.0 Token Binding 12 draft-ietf-oauth-token-binding-04 14 Abstract 16 This specification enables OAuth 2.0 implementations to apply Token 17 Binding to Access Tokens, Authorization Codes, and Refresh Tokens. 18 This cryptographically binds these tokens to a client's Token Binding 19 key pair, possession of which is proven on the TLS connections over 20 which the tokens are intended to be used. This use of Token Binding 21 protects these tokens from man-in-the-middle and token export and 22 replay attacks. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on January 4, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Token Binding for Refresh Tokens . . . . . . . . . . . . . . 3 62 2.1. Example Token Binding for Refresh Tokens . . . . . . . . 4 63 3. Token Binding for Access Tokens . . . . . . . . . . . . . . . 6 64 3.1. Access Tokens Issued from the Authorization Endpoint . . 7 65 3.1.1. Example Access Token Issued from the Authorization 66 Endpoint . . . . . . . . . . . . . . . . . . . . . . 8 67 3.2. Access Tokens Issued from the Token Endpoint . . . . . . 9 68 3.2.1. Example Access Token Issued from the Token Endpoint . 9 69 3.3. Protected Resource Token Binding Validation . . . . . . . 11 70 3.3.1. Example Protected Resource Request . . . . . . . . . 11 71 3.4. Representing Token Binding in JWT Access Tokens . . . . . 11 72 3.5. Representing Token Binding in Introspection Responses . . 12 73 4. Token Binding for Authorization Codes . . . . . . . . . . . . 13 74 4.1. Native Application Clients . . . . . . . . . . . . . . . 13 75 4.1.1. Code Challenge . . . . . . . . . . . . . . . . . . . 14 76 4.1.1.1. Example Code Challenge . . . . . . . . . . . . . 14 77 4.1.2. Code Verifier . . . . . . . . . . . . . . . . . . . . 14 78 4.1.2.1. Example Code Verifier . . . . . . . . . . . . . . 15 79 4.2. Web Server Clients . . . . . . . . . . . . . . . . . . . 15 80 4.2.1. Code Challenge . . . . . . . . . . . . . . . . . . . 16 81 4.2.1.1. Example Code Challenge . . . . . . . . . . . . . 16 82 4.2.2. Code Verifier . . . . . . . . . . . . . . . . . . . . 17 83 4.2.2.1. Example Code Verifier . . . . . . . . . . . . . . 18 84 5. Phasing in Token Binding and Preventing Downgrade Attacks . . 18 85 6. Token Binding Metadata . . . . . . . . . . . . . . . . . . . 19 86 6.1. Token Binding Client Metadata . . . . . . . . . . . . . . 19 87 6.2. Token Binding Authorization Server Metadata . . . . . . . 20 88 6.3. Token Binding Protected Resource Metadata . . . . . . . . 20 89 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 90 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 91 8.1. OAuth Dynamic Client Registration Metadata Registration . 20 92 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 93 8.2. OAuth Authorization Server Metadata Registration . . . . 21 94 8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 95 8.3. OAuth Protected Resource Metadata Registration . . . . . 21 96 8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 98 8.4. PKCE Code Challenge Method Registration . . . . . . . . . 22 99 8.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 100 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 101 9.1. Normative References . . . . . . . . . . . . . . . . . . 22 102 9.2. Informative References . . . . . . . . . . . . . . . . . 24 103 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 24 104 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 24 105 Appendix C. Document History . . . . . . . . . . . . . . . . . . 25 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 108 1. Introduction 110 This specification enables OAuth 2.0 [RFC6749] implementations to 111 apply Token Binding (TLS Extension for Token Binding Protocol 112 Negotiation [I-D.ietf-tokbind-negotiation], The Token Binding 113 Protocol Version 1.0 [I-D.ietf-tokbind-protocol] and Token Binding 114 over HTTP [I-D.ietf-tokbind-https]) to Access Tokens, Authorization 115 Codes, and Refresh Tokens. This cryptographically binds these tokens 116 to a client's Token Binding key pair, possession of which is proven 117 on the TLS connections over which the tokens are intended to be used. 118 This use of Token Binding protects these tokens from man-in-the- 119 middle and token export and replay attacks. 121 1.1. Requirements Notation and Conventions 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 125 "OPTIONAL" in this document are to be interpreted as described in RFC 126 2119 [RFC2119]. 128 1.2. Terminology 130 This specification uses the terms "Access Token", "Authorization 131 Code", "Authorization Endpoint", "Authorization Server", "Client", 132 "Protected Resource", "Refresh Token", and "Token Endpoint" defined 133 by OAuth 2.0 [RFC6749], the terms "Claim" and "JSON Web Token (JWT)" 134 defined by JSON Web Token (JWT) [JWT], the term "User Agent" defined 135 by RFC 7230 [RFC7230], and the terms "Provided", "Referred", "Token 136 Binding" and "Token Binding ID" defined by Token Binding over HTTP 137 [I-D.ietf-tokbind-https]. 139 2. Token Binding for Refresh Tokens 141 Token Binding of refresh tokens is a straightforward first-party 142 scenario, applying term "first-party" as used in Token Binding over 143 HTTP [I-D.ietf-tokbind-https]. It cryptographically binds the 144 refresh token to the client's Token Binding key pair, possession of 145 which is proven on the TLS connections between the client and the 146 token endpoint. This case is straightforward because the refresh 147 token is both retrieved by the client from the token endpoint and 148 sent by the client to the token endpoint. Unlike the federated 149 scenarios described in Section 4 (Federation Use Cases) of Token 150 Binding over HTTP [I-D.ietf-tokbind-https] and the access token case 151 described in the next section, only a single TLS connection is 152 involved in the refresh token case. 154 Token Binding a refresh token requires that the authorization server 155 do two things. First, when refresh token is sent to the client, the 156 authorization server needs to remember the Provided Token Binding ID 157 and remember its association with the issued refresh token. Second, 158 when a token request containing a refresh token is received at the 159 token endpoint, the authorization server needs to verify that the 160 Provided Token Binding ID for the request matches the remembered 161 Token Binding ID associated with the refresh token. If the Token 162 Binding IDs do not match, the authorization server should return an 163 error in response to the request. 165 How the authorization server remembers the association between the 166 refresh token and the Token Binding ID is an implementation detail 167 that beyond the scope of this specification. Some authorization 168 servers will choose to store the Token Binding ID (or a cryptographic 169 hash of it, such a SHA-256 hash [SHS]) in the refresh token itself, 170 provided it is integrity-protected, thus reducing the amount of state 171 to be kept by the server. Other authorization servers will add the 172 Token Binding ID value (or a hash of it) to an internal data 173 structure also containing other information about the refresh token, 174 such as grant type information. These choices make no difference to 175 the client, since the refresh token is opaque to it. 177 2.1. Example Token Binding for Refresh Tokens 179 This section provides an example of what the interactions around a 180 Token Bound refresh token might look like, along with some details of 181 the involved processing. Token Binding of refresh tokens is most 182 useful for native application clients so the example has protocol 183 elements typical of a native client flow. Extra line breaks in all 184 examples are for display purposes only. 186 A native application client makes the following access token request 187 with an authorization code using a TLS connection where Token Binding 188 has been negotiated. A PKCE "code_verifier" is included because use 189 of PKCE is considered best practice for native application clients 190 [I-D.ietf-oauth-native-apps]. The base64url-encoded representation 191 of the exported keying material (EKM) from that TLS connection is 192 "p6ZuSwfl6pIe8es5KyeV76T4swZmQp0_awd27jHfrbo", which is needed to 193 validate the Token Binding Message. 195 POST /as/token.oauth2 HTTP/1.1 196 Host: server.example.com 197 Content-Type: application/x-www-form-urlencoded 198 Sec-Token-Binding: AIkAAgBBQGto7hHRR0Y5nkOWqc9KNfwW95dEFmSI_tCZ_Cbl 199 7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8m7eqAAQOKiDK1Oi0z6v4X5B 200 P7uc0pFestVZ42TTOdJmoHpji06Qq3jsCiCRSJx9ck2fWJYx8tLVXRZPATB3x6c24 201 aY0ZEAAA 203 grant_type=authorization_code&code=4bwcZesc7Xacc330ltc66Wxk8EAfP9j2 204 &code_verifier=2x6_ylS390-8V7jaT9wj.8qP9nKmYCf.V-rD9O4r_1 205 &client_id=example-native-client-id 207 Figure 1: Initial Request with Code 209 A refresh token is issued in response to the prior request. Although 210 it looks like a typical response to the client, the authorization 211 server has bound the refresh token to the Provided Token Binding ID 212 from the encoded Token Binding message in the "Sec-Token-Binding" 213 header of the request. In this example, that binding is done by 214 saving the Token Binding ID alongside other information about the 215 refresh token in some server side persistent storage. The base64url- 216 encoded representation of that Token Binding ID is "AgBBQGto7hHRR0Y5n 217 kOWqc9KNfwW95dEFmSI_tCZ_Cbl7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8 218 m7eqA". 220 HTTP/1.1 200 OK 221 Content-Type: application/json 222 Cache-Control: no-cache, no-store 224 { 225 "access_token":"EdRs7qMrLb167Z9fV2dcwoLTC", 226 "refresh_token":"ACClZEIQTjW9arT9GOJGGd7QNwqOMmUYfsJTiv8his4", 227 "token_type":"Bearer", 228 "expires_in":3600 229 } 231 Figure 2: Successful Response 233 When the access token expires, the client requests a new one with a 234 refresh request to the token endpoint. In this example, the request 235 is made on a new TLS connection so the EKM (base64url-encoded: "va- 236 84Ukw4Zqfd7uWOtFrAJda96WwgbdaPDX2knoOiAE") and signature in the Token 237 Binding Message are different than in the initial request. 239 POST /as/token.oauth2 HTTP/1.1 240 Host: server.example.com 241 Content-Type: application/x-www-form-urlencoded 242 Sec-Token-Binding: AIkAAgBBQGto7hHRR0Y5nkOWqc9KNfwW95dEFmSI_tCZ_Cbl 243 7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8m7eqAAQCpGbaG_YRf27qOra 244 L0UT4fsKKjL6PukuOT00qzamoAXxOq7m_id7O3mLpnb_sM7kwSxLi7iNHzzDgCAkP 245 t3lHwAAA 247 refresh_token=ACClZEIQTjW9arT9GOJGGd7QNwqOMmUYfsJTiv8his4 248 &grant_type=refresh_token&client_id=example-native-client-id 250 Figure 3: Refresh Request 252 However, because the Token Binding ID is long-lived and may span 253 multiple TLS sessions and connections, it is the same as in the 254 initial request. That Token Binding ID is what the refresh token is 255 bound to, so the authorization server is able to verify it and issue 256 a new access token. 258 HTTP/1.1 200 OK 259 Content-Type: application/json 260 Cache-Control: no-cache, no-store 262 { 263 "access_token":"bwcESCwC4yOCQ8iPsgcn117k7", 264 "token_type":"Bearer", 265 "expires_in":3600 266 } 268 Figure 4: Successful Response 270 3. Token Binding for Access Tokens 272 Token Binding for access tokens cryptographically binds the access 273 token to the client's Token Binding key pair, possession of which is 274 proven on the TLS connections between the client and the protected 275 resource. Token Binding is applied to access tokens in a similar 276 manner to that described in Section 4 (Federation Use Cases) of Token 277 Binding over HTTP [I-D.ietf-tokbind-https]. It also builds upon the 278 mechanisms for Token Binding of ID Tokens defined in OpenID Connect 279 Token Bound Authentication 1.0 [OpenID.TokenBinding]. 281 In the OpenID Connect [OpenID.Core] use case, HTTP redirects are used 282 to pass information between the identity provider and the relying 283 party; this HTTP redirect makes the Token Binding ID of the relying 284 party available to the identity provider as the Referred Token 285 Binding ID, information about which is then added to the ID Token. 286 No such redirect occurs between the authorization server and the 287 protected resource in the access token case; therefore, information 288 about the Token Binding ID for the TLS connection between the client 289 and the protected resource needs to be explicitly communicated by the 290 client to the authorization server to achieve Token Binding of the 291 access token. 293 This information is passed to the authorization server using the 294 Referred Token Binding ID, just as in the ID Token case. The only 295 difference is that the client needs to explicitly communicate the 296 Token Binding ID of the TLS connection between the client and the 297 protected resource to the Token Binding implementation so that it is 298 sent as the Referred Token Binding ID in the request to the 299 authorization server. This functionality provided by Token Binding 300 implementations is described in Section 5 (Implementation 301 Considerations) of Token Binding over HTTP [I-D.ietf-tokbind-https]. 303 Note that to obtain this Token Binding ID, the client may need to 304 establish a TLS connection between itself and the protected resource 305 prior to making the request to the authorization server so that the 306 Provided Token Binding ID for the TLS connection to the protected 307 resource can be obtained. How the client retrieves this Token 308 Binding ID from the underlying Token Binding API is implementation 309 and operating system specific. An alternative, if supported, is for 310 the client to generate a Token Binding key to use for the protected 311 resource, use the Token Binding ID for that key, and then later use 312 that key when the TLS connection to the protected resource is 313 established. 315 3.1. Access Tokens Issued from the Authorization Endpoint 317 For access tokens returned directly from the authorization endpoint, 318 such as with the implicit grant defined in Section 4.2 of OAuth 2.0 319 [RFC6749], the Token Binding ID of the client's TLS channel to the 320 protected resource is sent with the authorization request as the 321 Referred Token Binding ID in the "Sec-Token-Binding" header, and is 322 used to Token Bind the access token. 324 Upon receiving the Referred Token Binding ID in an authorization 325 request, the authorization server associates (Token Binds) the ID 326 with the access token in a way that can be accessed by the protected 327 resource. Such methods include embedding the Referred Token Binding 328 ID (or a cryptographic hash of it) in the issued access token itself, 329 possibly using the syntax described in Section 3.4, or through token 330 introspection as described in Section 3.5. The method for 331 associating the referred token binding ID with the access token is 332 determined by the authorization server and the protected resource, 333 and is beyond the scope for this specification. 335 3.1.1. Example Access Token Issued from the Authorization Endpoint 337 This section provides an example of what the interactions around a 338 Token Bound access token issued from the authorization endpoint might 339 look like, along with some details of the involved processing. Extra 340 line breaks in all examples are for display purposes only. 342 The client directs the user-agent to make the following HTTP request 343 to the authorization endpoint. It is a typical authorization request 344 that, because Token Binding was negotiated on the underlying TLS 345 connection and the user-agent was signaled to reveal the Referred 346 Token Binding, also includes the "Sec-Token-Binding" header with a 347 Token Binding Message that contains both a Provided and Referred 348 Token Binding. The base64url-encoded EKM from the TLS connection 349 over which the request was made is 350 "jI5UAyjs5XCPISUGQIwgcSrOiVIWq4fhLVIFTQ4nLxc". 352 GET /as/authorization.oauth2?response_type=token 353 &client_id=example-client-id&state=rM8pZxG1c3gKy6rEbsD8s 354 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb HTTP/1.1 355 Host: server.example.com 356 Sec-Token-Binding: ARIAAgBBQIEE8mSMtDy2dj9EEBdXaQT9W3Rq1NS-jW8ebPoF 357 6FyL0jIfATVE55zlircgOTZmEg1xeIrC3DsGegwjs4bhw14AQGKDlAXFFMyQkZegC 358 wlbTlqX3F9HTt-lJxFU_pi16ezka7qVRCpSF0BQLfSqlsxMbYfSSCJX1BDtrIL7PX 359 j__fUAAAECAEFA1BNUnP3te5WrwlEwiejEz0OpesmC5PElWc7kZ5nlLSqQTj1ciIp 360 5vQ30LLUCyM_a2BYTUPKtd5EdS-PalT4t6ABADgeizRa5NkTMuX4zOdC-R4cLNWVV 361 O8lLu2Psko-UJLR_XAH4Q0H7-m0_nQR1zBN78nYMKPvHsz8L3zWKRVyXEgAA 363 Figure 5: Authorization Request 365 The authorization server issues an access token and delivers it to 366 the client by redirecting the user-agent with the following HTTP 367 response: 369 HTTP/1.1 302 Found 370 Location: https://client.example.org/cb#state=rM8pZxG1c3gKy6rEbsD8s 371 &expires_in=3600&token_type=Bearer 372 &access_token=eyJhbGciOiJFUzI[...omitted for brevity...]8xy5W5sQ 374 Figure 6: Authorization Response 376 The access token is bound to the Referred Token Binding ID from the 377 authorization request, which when represented as a JWT, as described 378 in Section 3.4, contains the SHA-256 hash of the Token Binding ID as 379 the value of the "tbh" (token binding hash) member of the "cnf" 380 (confirmation) claim. The confirmation claim portion of the JWT 381 Claims Set is shown in the following figure. 383 { 384 ...other claims omitted for brevity... 385 "cnf":{ 386 "tbh": "vowQESa_MgbGJwIXaFm_BTN2QDPwh8PhuBm-EtUAqxc" 387 } 388 } 390 Figure 7: Confirmation Claim 392 3.2. Access Tokens Issued from the Token Endpoint 394 For access tokens returned from the token endpoint, the Token Binding 395 ID of the client's TLS channel to the protected resource is sent as 396 the Referred Token Binding ID in the "Sec-Token-Binding" header, and 397 is used to Token Bind the access token. This applies to all the 398 grant types from OAuth 2.0 [RFC6749] using the token endpoint, 399 including, but not limited to the refresh and authorization code 400 token requests, as well as some extension grants, such as JWT 401 assertion authorization grants [RFC7523]. 403 Upon receiving the Referred Token Binding ID in a token request, the 404 authorization server associates (Token Binds) the ID with the access 405 token in a way that can be accessed by the protected resource. Such 406 methods include embedding the Referred Token Binding ID (or a 407 cryptographic hash of it) in the issued access token itself, possibly 408 using the syntax described in Section 3.4, or through token 409 introspection as described in Section 3.5. The method for 410 associating the referred token binding ID with the access token is 411 determined by the authorization server and the protected resource, 412 and is beyond the scope for this specification. 414 Note that if the request results in a new refresh token being 415 generated, it can be Token bound using the Provided Token Binding ID, 416 per Section 2. 418 3.2.1. Example Access Token Issued from the Token Endpoint 420 This section provides an example of what the interactions around a 421 Token Bound access token issued from the token endpoint might look 422 like, along with some details of the involved processing. Extra line 423 breaks in all examples are for display purposes only. 425 The client makes an access token request to the token endpoint and 426 includes the "Sec-Token-Binding" header with a Token Binding Message 427 that contains both Provided and Referred Token Binding IDs. The 428 Provided Token Binding ID is used to validate the token binding of 429 the refresh token in the request (and to Token Bind a new refresh 430 token, if one is issued), and the Referred Token Binding ID is used 431 to Token Bind the access token that is generated. The base64url- 432 encoded EKM from the TLS connection over which the access token 433 request was made is "4jTc5e1QpocqPTZ5l6jsb6pRP18IFKdwwPvasYjn1-E". 435 POST /as/token.oauth2 HTTP/1.1 436 Host: server.example.com 437 Content-Type: application/x-www-form-urlencoded 438 Sec-Token-Binding: ARIAAgBBQJFXJir2w4gbJ7grBx9uTYWIrs9V50-PW4ZijegQ 439 0LUM-_bGnGT6DizxUK-m5n3dQUIkeH7ybn6wb1C5dGyV_IAAQDDFToFrHt41Zppq7 440 u_SEMF_E-KimAB-HewWl2MvZzAQ9QKoWiJCLFiCkjgtr1RrA2-jaJvoB8o51DTGXQ 441 ydWYkAAAECAEFAuC1GlYU83rqTGHEau1oqvNwy0fDsdXzIyT_4x1FcldsMxjFkJac 442 IBJFGuYcccvnCak_duFi3QKFENuwxql-H9ABAMcU7IjJOUA4IyE6YoEcfz9BMPQqw 443 M5M6hw4RZNQd58fsTCCslQE_NmNCl9JXy4NkdkEZBxqvZGPr0y8QZ_bmAwAA 445 refresh_token=gZR_ZI8EAhLgWR-gWxBimbgZRZi_8EAhLgWRgWxBimbf 446 &grant_type=refresh_token&client_id=example-client-id 448 Figure 8: Access Token Request 450 The authorization server issues an access token bound to the Referred 451 Token Binding ID and delivers it in a response the client. 453 HTTP/1.1 200 OK 454 Content-Type: application/json 455 Cache-Control: no-cache, no-store 457 { 458 "access_token":"eyJhbGciOiJFUzI1NiIsImtp[...omitted...]1cs29j5c3", 459 "token_type":"Bearer", 460 "expires_in":3600 461 } 463 Figure 9: Response 465 The access token is bound to the Referred Token Binding ID of the 466 access token request, which when represented as a JWT, as described 467 in Section 3.4, contains the SHA-256 hash of the Token Binding ID as 468 the value of the "tbh" (token binding hash) member of the "cnf" 469 (confirmation) claim. The confirmation claim portion of the JWT 470 Claims Set of the access token is shown in the following figure. 472 { 473 ...other claims omitted for brevity... 474 "cnf":{ 475 "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" 476 } 477 } 479 Figure 10: Confirmation Claim 481 3.3. Protected Resource Token Binding Validation 483 Upon receiving a token bound access token, the protected resource 484 validates the binding by comparing the Provided Token Binding ID to 485 the Token Binding ID for the access token. Alternatively, 486 cryptographic hashes of these Token Binding ID values can be 487 compared. If the values do not match, the resource access attempt 488 MUST be rejected with an error. 490 3.3.1. Example Protected Resource Request 492 For example, a protected resource request using the access token from 493 Section 3.2.1 would look something like the following. The 494 base64url-encoded EKM from the TLS connection over which the request 495 was made is "7LsNP3BT1aHHdXdk6meEWjtSkiPVLb7YS6iHp-JXmuE". The 496 protected resource validates the binding by comparing the Provided 497 Token Binding ID from the "Sec-Token-Binding" header to the token 498 binding hash confirmation of the access token. Extra line breaks in 499 the example are for display purposes only. 501 GET /api/stuff HTTP/1.1 502 Host: resource.example.org 503 Authorization: Bearer eyJhbGciOiJFUzI1NiIsI[...omitted...]1cs29j5c3 504 Sec-Token-Binding: AIkAAgBBQLgtRpWFPN66kxhxGrtaKrzcMtHw7HV8yMk_-MdR 505 XJXbDMYxZCWnCASRRrmHHHL5wmpP3bhYt0ChRDbsMapfh_QAQN1He3Ftj4Wa_S_fz 506 ZVns4saLfj6aBoMSQW6rLs19IIvHze7LrGjKyCfPTKXjajebxp-TLPFZCc0JTqTY5 507 _0MBAAAA 509 Figure 11: Protected Resource Request 511 3.4. Representing Token Binding in JWT Access Tokens 513 If the access token is represented as a JWT, the token binding 514 information SHOULD be represented in the same way that it is in token 515 bound OpenID Connect ID Tokens [OpenID.TokenBinding]. That 516 specification defines the new JWT Confirmation Method RFC 7800 517 [RFC7800] member "tbh" (token binding hash) to represent the SHA-256 518 hash of a Token Binding ID in an ID Token. The value of the "tbh" 519 member is the base64url encoding of the SHA-256 hash of the Token 520 Binding ID. 522 The following example demonstrates the JWT Claims Set of an access 523 token containing the base64url encoding of the SHA-256 hash of a 524 Token Binding ID as the value of the "tbh" (token binding hash) 525 element in the "cnf" (confirmation) claim: 527 { 528 "iss": "https://server.example.com", 529 "aud": "https://resource.example.org", 530 "sub": "brian@example.com" 531 "iat": 1467324320, 532 "exp": 1467324920, 533 "cnf":{ 534 "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" 535 } 536 } 538 Figure 12: JWT with Token Binding Hash Confirmation Claim 540 3.5. Representing Token Binding in Introspection Responses 542 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 543 protected resource to query an authorization server about the active 544 state of an access token as well as to determine meta-information 545 about the token. 547 For a token bound access token, the hash of the Token Binding ID to 548 which the token is bound is conveyed to the protected resource as 549 meta-information in a token introspection response. The hash is 550 conveyed using same structure as the token binding hash confirmation 551 method, described in Section 3.4, as a top-level member of the 552 introspection response JSON. The protected resource compares that 553 token binding hash to a hash of the provided Token Binding ID and 554 rejects the request, if they do not match. 556 The following is an example of an introspection response for an 557 active token bound access token with an "tbh" token binding hash 558 confirmation method. 560 HTTP/1.1 200 OK 561 Content-Type: application/json 563 { 564 "active": true, 565 "iss": "https://server.example.com", 566 "aud": "https://resource.example.org", 567 "sub": "brian@example.com" 568 "iat": 1467324320, 569 "exp": 1467324920, 570 "cnf":{ 571 "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" 572 } 573 } 575 Figure 13: Example Introspection Response for a Token Bound Access 576 Token 578 4. Token Binding for Authorization Codes 580 There are two variations for Token Binding of an authorization code. 581 One is appropriate for native application clients and the other for 582 web server clients. The nature of where the various components 583 reside for the different client types demands different methods of 584 Token Binding the authorization code so that it is bound to a Token 585 Binding key on the end user's device. This ensures that a lost or 586 stolen authorization code cannot be successfully utilized from a 587 different device. For native application clients, the code is bound 588 to a Token Binding key pair that the native client itself possesses. 589 For web server clients, the code is bound to a Token Binding key pair 590 on the end user's browser. Both variations utilize the extensible 591 framework of Proof Key for Code Exchange (PKCE) [RFC7636], which 592 enables the client to show possession of a certain key when 593 exchanging the authorization code for tokens. The following 594 subsections individually describe each of the two PKCE methods 595 respectively. 597 4.1. Native Application Clients 599 This section describes a PKCE method suitable for native application 600 clients that cryptographically binds the authorization code to a 601 Token Binding key pair on the client, which the client proves 602 possession of on the TLS connection during the access token request 603 containing the authorization code. The authorization code is bound 604 to the Token Binding ID that the native application client uses to 605 resolve the authorization code at the token endpoint. This binding 606 ensures that the client that made the authorization request is the 607 same client that is presenting the authorization code. 609 4.1.1. Code Challenge 611 As defined in Proof Key for Code Exchange [RFC7636], the client sends 612 the code challenge as part of the OAuth 2.0 authorization request 613 with the two additional parameters: "code_challenge" and 614 "code_challenge_method". 616 For this Token Binding method of PKCE, "TB-S256" is used as the value 617 of the "code_challenge_method" parameter. 619 The value of the "code_challenge" parameter is the base64url encoding 620 (per Section 5 of [RFC4648] with all trailing padding ('=') 621 characters omitted and without the inclusion of any line breaks or 622 whitespace) of the SHA-256 hash of the Provided Token Binding ID that 623 the client will use when calling the authorization server's token 624 endpoint. Note that, prior to making the authorization request, the 625 client may need to establish a TLS connection between itself and the 626 authorization server's token endpoint in order to establish the 627 appropriate Token Binding ID. 629 When the authorization server issues the authorization code in the 630 authorization response, it associates the code challenge and method 631 values with the authorization code so they can be verified later when 632 the authorization code is presented in the access token request. 634 4.1.1.1. Example Code Challenge 636 For example, a native application client sends an authorization 637 request by sending the user's browser to the authorization endpoint. 638 The resulting HTTP request looks something like the following (with 639 extra line breaks for display purposes only). 641 GET /as/authorization.oauth2?response_type=code 642 &client_id=example-native-client-id&state=oUC2jyYtzRCrMyWrVnGj 643 &code_challenge=rBlgOyMY4teiuJMDgOwkrpsAjPyI07D2WsEM-dnq6eE 644 &code_challenge_method=TB-S256 HTTP/1.1 645 Host: server.example.com 647 Figure 14: Authorization Request with PKCE Challenge 649 4.1.2. Code Verifier 651 Upon receipt of the authorization code, the client sends the access 652 token request to the token endpoint. The Token Binding Protocol 653 [I-D.ietf-tokbind-protocol] is negotiated on the TLS connection 654 between the client and the authorization server and the "Sec-Token- 655 Binding" header, as defined in Token Binding over HTTP 656 [I-D.ietf-tokbind-https], is included in the access token request. 658 The authorization server extracts the Provided Token Binding ID from 659 the header value, hashes it with SHA-256, and compares it to the 660 "code_challenge" value previously associated with the authorization 661 code. If the values match, the token endpoint continues processing 662 as normal (as defined by OAuth 2.0 [RFC6749]). If the values do not 663 match, an error response indicating "invalid_grant" MUST be returned. 665 The "Sec-Token-Binding" header contains sufficient information for 666 verification of the authorization code and its association to the 667 original authorization request. However, PKCE [RFC7636] requires 668 that a "code_verifier" parameter be sent with the access token 669 request, so the static value "provided_tb" is used to meet that 670 requirement and indicate that the Provided Token Binding ID is used 671 for the verification. 673 4.1.2.1. Example Code Verifier 675 An example access token request, correlating to the authorization 676 request in the previous example, to the token endpoint over a TLS 677 connection for which Token Binding has been negotiated would look 678 like the following (with extra line breaks for display purposes 679 only). The base64url-encoded EKM from the TLS connection over which 680 the request was made is 681 "pNVKtPuQFvylNYn000QowWrQKoeMkeX9H32hVuU71Bs". 683 POST /as/token.oauth2 HTTP/1.1 684 Host: server.example.com 685 Content-Type: application/x-www-form-urlencoded 686 Sec-Token-Binding: AIkAAgBBQEOO9GRFP-LM0hoWw6-2i318BsuuUum5AL8bt1sz 687 lr1EFfp5DMXMNW3O8WjcIXr2DKJnI4xnuGsE6GywQd9RbD0AQJDb3xyo9PBxj8M6Y 688 jLt-6OaxgDkyoBoTkyrnNbLc8tJQ0JtXomKzBbj5qPtHDduXc6xz_lzvNpxSPxi42 689 8m7wkAAA 691 grant_type=authorization_code&code=mJAReTWKX7zI3oHUNd4o3PeNqNqxKGp6 692 &code_verifier=provided_tb&client_id=example-native-client-id 694 Figure 15: Token Request with PKCE Verifier 696 4.2. Web Server Clients 698 This section describes a PKCE method suitable for web server clients, 699 which cryptographically binds the authorization code to a Token 700 Binding key pair on the browser. The authorization code is bound to 701 the Token Binding ID that the browser uses to deliver the 702 authorization code to a web server client, which is sent to the 703 authorization server as the Referred Token Binding ID during the 704 authorization request. The web server client conveys the Token 705 Binding ID to the authorization server when making the access token 706 request containing the authorization code. This binding ensures that 707 the authorization code cannot successfully be played or replayed to 708 the web server client from a different browser than the one that made 709 the authorization request. 711 4.2.1. Code Challenge 713 As defined in Proof Key for Code Exchange [RFC7636], the client sends 714 the code challenge as part of the OAuth 2.0 Authorization Request 715 with the two additional parameters: "code_challenge" and 716 "code_challenge_method". 718 The client must send the authorization request through the browser 719 such that the Token Binding ID established between the browser and 720 itself is revealed to the authorization server's authorization 721 endpoint as the Referred Token Binding ID. Typically, this is done 722 with an HTTP redirection response and the "Include-Referred-Token- 723 Binding-ID" header, as defined in Section 5.3 of Token Binding over 724 HTTP [I-D.ietf-tokbind-https]. 726 For this Token Binding method of PKCE, "referred_tb" is used for the 727 value of the "code_challenge_method" parameter. 729 The value of the "code_challenge" parameter is "referred_tb". The 730 static value for the required PKCE parameter indicates that the 731 authorization code is to be bound to the Referred Token Binding ID 732 from the Token Binding Message sent in the "Sec-Token-Binding" header 733 of the authorization request. 735 When the authorization server issues the authorization code in the 736 authorization response, it associates the Token Binding ID (or hash 737 thereof) and code challenge method with the authorization code so 738 they can be verified later when the authorization code is presented 739 in the access token request. 741 4.2.1.1. Example Code Challenge 743 For example, the web server client sends the authorization request by 744 redirecting the browser to the authorization endpoint. That HTTP 745 redirection response looks like the following (with extra line breaks 746 for display purposes only). 748 HTTP/1.1 302 Found 749 Location: https://server.example.com?response_type=code 750 &client_id=example-web-client-id&state=P4FUFqYzs1ij3ffsYCP34d3 751 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 752 &code_challenge=referred_tb&code_challenge_method=referred_tb 753 Include-Referred-Token-Binding-ID: true 755 Figure 16: Redirect the Browser 757 The redirect includes the "Include-Referred-Token-Binding-ID" 758 response header field that signals to the user-agent that it should 759 reveal, to the authorization server, the Token Binding ID used on the 760 connection to the web server client. The resulting HTTP request to 761 the authorization server looks something like the following (with 762 extra line breaks for display purposes only). The base64url-encoded 763 EKM from the TLS connection over which the request was made is 764 "7gOdRzMhPeO-1YwZGmnVHyReN5vd2CxcsRBN69Ue4cI". 766 GET /as/authorization.oauth2?response_type=code 767 &client_id=example-web-client-id&state=dryo8YFpWacbUPjhBf4Nvt51 768 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 769 &code_challenge=referred_tb 770 &code_challenge_method=referred_tb HTTP/1.1 771 Host: server.example.com 772 Sec-Token-Binding: ARIAAgBBQB-XOPf5ePlf7ikATiAFEGOS503lPmRfkyymzdWw 773 HCxl0njjxC3D0E_OVfBNqrIQxzIfkF7tWby2ZfyaE6XpwTsAQBYqhFX78vMOgDX_F 774 d_b2dlHyHlMmkIz8iMVBY_reM98OUaJFz5IB7PG9nZ11j58LoG5QhmQoI9NXYktKZ 775 RXxrYAAAECAEFAdUFTnfQADkn1uDbQnvJEk6oQs38L92gv-KO-qlYadLoDIKe2h53 776 hSiKwIP98iRj_unedkNkAMyg9e2mY4Gp7WwBAeDUOwaSXNz1e6gKohwN4SAZ5eNyx 777 45Mh8VI4woL1BipLoqrJRoK6dxFkWgHRMuBROcLGUj5PiOoxybQH_Tom3gAA 779 Figure 17: Authorization Request 781 4.2.2. Code Verifier 783 The web server client receives the authorization code from the 784 browser and extracts the Provided Token Binding ID from the "Sec- 785 Token-Binding" header of the request. The client sends the 786 base64url-encoded (per Section 5 of [RFC4648] with all trailing 787 padding ('=') characters omitted and without the inclusion of any 788 line breaks or whitespace) Provided Token Binding ID as the value of 789 the "code_verifier" parameter in the access token request to the 790 authorization server's token endpoint. The authorization server 791 compares the value of the "code_verifier" parameter to the Token 792 Binding ID value previously associated with the authorization code. 793 If the values match, the token endpoint continues processing as 794 normal (as defined by OAuth 2.0 [RFC6749]). If the values do not 795 match, an error response indicating "invalid_grant" MUST be returned. 797 4.2.2.1. Example Code Verifier 799 Continuing the example from the previous section, the authorization 800 server sends the code to the web server client by redirecting the 801 browser to the client's "redirect_uri", which results in the browser 802 making a request like the following (with extra line breaks for 803 display purposes only) to the web server client over a TLS channel 804 for which Token Binding has been established. The base64url-encoded 805 EKM from the TLS connection over which the request was made is 806 "EzW60vyINbsb_tajt8ij3tV6cwy2KH-i8BdEMYXcNn0". 808 GET /cb?state=dryo8YFpWacbUPjhBf4Nvt51&code=jwD3oOa5cQvvLc81bwc4CMw 809 Host: client.example.org 810 Sec-Token-Binding: AIkAAgBBQHVBU530AA5J9bg20J7yRJOqELN_C_doL_ijvqpW 811 GnS6AyCntoed4UoisCD_fIkY_7p3nZDZADMoPXtpmOBqe1sAQEwgC9Zpg7QFCDBib 812 6GlZki3MhH32KNfLefLJc1vR1xE8l7OMfPLZHP2Woxh6rEtmgBcAABubEbTz7muNl 813 Ln8uoAAA 815 Figure 18: Authorization Response to Web Server Client 817 The web server client takes the Provided Token Binding ID from the 818 above request from the browser and sends it, base64url encoded, to 819 the authorization server in the "code_verifier" parameter of the 820 authorization code grant type request. Extra line breaks in the 821 example request are for display purposes only. 823 POST /as/token.oauth2 HTTP/1.1 824 Host: server.example.com 825 Content-Type: application/x-www-form-urlencoded 826 Authorization: Basic b3JnLmV4YW1wbGUuY2xpZW50OmlldGY5OGNoaWNhZ28= 828 grant_type=authorization_code&code=jwD3oOa5cQvvLc81bwc4CMw 829 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 830 &client_id=example-web-client-id 831 &code_verifier=AgBBQHVBU530AA5J9bg20J7yRJOqELN_C_doL_ijv 832 qpWGnS6AyCntoed4UoisCD_fIkY_7p3nZDZADMoPXtpmOBqe1s 834 Figure 19: Exchange Authorization Code 836 5. Phasing in Token Binding and Preventing Downgrade Attacks 838 Many OAuth implementations will be deployed in situations in which 839 not all participants support Token Binding. Any of combination of 840 the client, the authorization server, the protected resource, and the 841 user agent may not yet support Token Binding, in which case it will 842 not work end-to-end. 844 It is a context-dependent deployment choice whether to allow 845 interactions to proceed in which Token Binding is not supported or 846 whether to treat Token Binding failures at any step as fatal errors. 847 Particularly in dynamic deployment environments in which End Users 848 have choices of clients, authorization servers, protected resources, 849 and/or user agents, it is RECOMMENDED that authorizations using one 850 or more components that do not implement Token Binding be allowed to 851 successfully proceed. This enables different components to be 852 upgraded to supporting Token Binding at different times, providing a 853 smooth transition path for phasing in Token Binding. However, when 854 Token Binding has been performed, any Token Binding key mismatches 855 MUST be treated as fatal errors. 857 If all the participants in an authorization interaction support Token 858 Binding and yet one or more of them does not use it, this is likely 859 evidence of a downgrade attack. In this case, the authorization 860 SHOULD be aborted with an error. For instance, if the protected 861 resource knows that the authorization server and the user agent both 862 support Token Binding and yet the access token received does not 863 contain Token Binding information, this is almost certainly a sign of 864 an attack. 866 The authorization server, client, and protected resource can 867 determine whether the others support Token Binding using the metadata 868 values defined in the next section. They can determine whether the 869 user agent supports Token Binding by whether it negotiated Token 870 Binding for the TLS connection. 872 6. Token Binding Metadata 874 6.1. Token Binding Client Metadata 876 Clients supporting Token Binding that also support the OAuth 2.0 877 Dynamic Client Registration Protocol [RFC7591] use these metadata 878 values to declare their support for Token Binding of access tokens 879 and refresh tokens: 881 client_access_token_token_binding_supported 882 OPTIONAL. Boolean value specifying whether the client supports 883 Token Binding of access tokens. If omitted, the default value is 884 "false". 886 client_refresh_token_token_binding_supported 887 OPTIONAL. Boolean value specifying whether the client supports 888 Token Binding of refresh tokens. If omitted, the default value is 889 "false". 891 6.2. Token Binding Authorization Server Metadata 893 Authorization servers supporting Token Binding that also support 894 OAuth 2.0 Authorization Server Metadata [OAuth.AuthorizationMetadata] 895 use these metadata values to declare their support for Token Binding 896 of access tokens and refresh tokens: 898 as_access_token_token_binding_supported 899 OPTIONAL. Boolean value specifying whether the authorization 900 server supports Token Binding of access tokens. If omitted, the 901 default value is "false". 903 as_refresh_token_token_binding_supported 904 OPTIONAL. Boolean value specifying whether the authorization 905 server supports Token Binding of refresh tokens. If omitted, the 906 default value is "false". 908 6.3. Token Binding Protected Resource Metadata 910 Protected resources supporting Token Binding that also support the 911 OAuth 2.0 Protected Resource Metadata [OAuth.ResourceMetadata] use 912 this metadata value to declare their support for Token Binding of 913 access tokens: 915 resource_access_token_token_binding_supported 916 OPTIONAL. Boolean value specifying whether the protected resource 917 supports Token Binding of access tokens. If omitted, the default 918 value is "false". 920 7. Security Considerations 922 If a refresh request is received by the authorization server 923 containing a Referred Token Binding ID and the refresh token in the 924 request is not itself token bound, then it is not clear that token 925 binding the access token adds significant value. This situation 926 should be considered an open issue for discussion by the working 927 group. 929 8. IANA Considerations 931 8.1. OAuth Dynamic Client Registration Metadata Registration 933 This specification registers the following client metadata 934 definitions in the IANA "OAuth Dynamic Client Registration Metadata" 935 registry [IANA.OAuth.Parameters] established by [RFC7591]: 937 8.1.1. Registry Contents 939 o Client Metadata Name: 940 "client_access_token_token_binding_supported" 941 o Client Metadata Description: Boolean value specifying whether the 942 client supports Token Binding of access tokens 943 o Change Controller: IESG 944 o Specification Document(s): Section 6.1 of [[ this specification ]] 946 o Client Metadata Name: 947 "client_refresh_token_token_binding_supported" 948 o Client Metadata Description: Boolean value specifying whether the 949 client supports Token Binding of refresh tokens 950 o Change Controller: IESG 951 o Specification Document(s): Section 6.1 of [[ this specification ]] 953 8.2. OAuth Authorization Server Metadata Registration 955 This specification registers the following metadata definitions in 956 the IANA "OAuth Authorization Server Metadata" registry established 957 by [OAuth.AuthorizationMetadata]: 959 8.2.1. Registry Contents 961 o Metadata Name: "as_access_token_token_binding_supported" 962 o Metadata Description: Boolean value specifying whether the 963 authorization server supports Token Binding of access tokens 964 o Change Controller: IESG 965 o Specification Document(s): Section 6.2 of [[ this specification ]] 967 o Metadata Name: "as_refresh_token_token_binding_supported" 968 o Metadata Description: Boolean value specifying whether the 969 authorization server supports Token Binding of refresh tokens 970 o Change Controller: IESG 971 o Specification Document(s): Section 6.2 of [[ this specification ]] 973 8.3. OAuth Protected Resource Metadata Registration 975 This specification registers the following client metadata definition 976 in the IANA "OAuth Protected Resource Metadata" registry established 977 by [OAuth.ResourceMetadata]: 979 8.3.1. Registry Contents 981 o Resource Metadata Name: 982 "resource_access_token_token_binding_supported" 983 o Resource Metadata Description: Boolean value specifying whether 984 the protected resource supports Token Binding of access tokens 986 o Change Controller: IESG 987 o Specification Document(s): Section 6.3 of [[ this specification ]] 989 8.4. PKCE Code Challenge Method Registration 991 This specification requests registration of the following Code 992 Challenge Method Parameter Names in the IANA "PKCE Code Challenge 993 Methods" registry [IANA.OAuth.Parameters] established by [RFC7636]. 995 8.4.1. Registry Contents 997 o Code Challenge Method Parameter Name: TB-S256 998 o Change controller: IESG 999 o Specification document(s): Section 4.1.1 of [[ this specification 1000 ]] 1002 o Code Challenge Method Parameter Name: referred_tb 1003 o Change controller: IESG 1004 o Specification document(s): Section 4.2.1 of [[ this specification 1005 ]] 1007 9. References 1009 9.1. Normative References 1011 [I-D.ietf-tokbind-https] 1012 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 1013 Hodges, "Token Binding over HTTP", draft-ietf-tokbind- 1014 https-08 (work in progress), February 2017. 1016 [I-D.ietf-tokbind-negotiation] 1017 Popov, A., Nystrom, M., Balfanz, D., and A. Langley, 1018 "Transport Layer Security (TLS) Extension for Token 1019 Binding Protocol Negotiation", draft-ietf-tokbind- 1020 negotiation-07 (work in progress), February 2017. 1022 [I-D.ietf-tokbind-protocol] 1023 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 1024 Hodges, "The Token Binding Protocol Version 1.0", draft- 1025 ietf-tokbind-protocol-13 (work in progress), February 1026 2017. 1028 [IANA.OAuth.Parameters] 1029 IANA, "OAuth Parameters", 1030 . 1032 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1033 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1034 . 1036 [OAuth.AuthorizationMetadata] 1037 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1038 Authorization Server Metadata", draft-ietf-oauth- 1039 discovery-06 (work in progress), March 2017, 1040 . 1043 [OAuth.ResourceMetadata] 1044 Jones, M. and P. Hunt, "OAuth 2.0 Protected Resource 1045 Metadata", draft-jones-oauth-resource-metadata-01 (work in 1046 progress), January 2017, . 1049 [OpenID.TokenBinding] 1050 Jones, M., Bradley, J., and B. Campbell, "OpenID Connect 1051 Token Bound Authentication 1.0", July 2016, 1052 . 1055 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1056 Requirement Levels", BCP 14, RFC 2119, 1057 DOI 10.17487/RFC2119, March 1997, 1058 . 1060 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1061 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1062 . 1064 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1065 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1066 . 1068 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1069 Protocol (HTTP/1.1): Message Syntax and Routing", 1070 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1071 . 1073 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 1074 for Code Exchange by OAuth Public Clients", RFC 7636, 1075 DOI 10.17487/RFC7636, September 2015, 1076 . 1078 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1079 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1080 . 1082 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1083 Possession Key Semantics for JSON Web Tokens (JWTs)", 1084 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1085 . 1087 [SHS] National Institute of Standards and Technology, "Secure 1088 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 1089 . 1092 9.2. Informative References 1094 [I-D.ietf-oauth-native-apps] 1095 Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 1096 draft-ietf-oauth-native-apps-08 (work in progress), March 1097 2017. 1099 [OpenID.Core] 1100 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1101 C. Mortimore, "OpenID Connect Core 1.0", August 2015, 1102 . 1104 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1105 (JWT) Profile for OAuth 2.0 Client Authentication and 1106 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1107 2015, . 1109 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1110 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1111 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1112 . 1114 Appendix A. Acknowledgements 1116 The authors would like to thank the following people for their 1117 contributions to the specification: Dirk Balfanz, Andrei Popov, 1118 Justin Richer, and Nat Sakimura. 1120 Appendix B. Open Issues 1122 o What should we do in the case that a refresh request for a token 1123 bound access token is received when the refresh token used in the 1124 request is not token bound? 1126 o Currently the only way to request a token bound access token is 1127 via the referred token binding. By definition the referred token 1128 binding also comes with the provided token binding and the 1129 provided token binding is what is used to bind the refresh token. 1130 However, web server clients will typically be distributed/ 1131 clustered and very likely will not want to, or be capable of, 1132 dealing with token bound refresh tokens. Such clients will have 1133 credentials established with the AS for authenticating to the 1134 token endpoint and refresh tokens are already bound to the client. 1135 So token binding the refresh tokens doesn't add much, if anything, 1136 in this case. But accessing private token binding keys in a 1137 distributed system will be cumbersome or even impossible. 1138 Tracking and properly utilizing the association of a token binding 1139 key with each individual refresh token would also be exceptionally 1140 cumbersome (whereas client credentials are for the client and 1141 decoupled from individual refresh tokens) but without some such 1142 mechanism the token binding key cannot be changed without 1143 implicitly invalidating all the bound refresh tokens the web 1144 server client has stored for that AS. It seems necessary to 1145 provide some mechanism for a client to opt-out of having refresh 1146 tokens token bound while still allowing for token binding of 1147 access tokens. 1149 o Should the scope of this document include standardization or 1150 guidance on token binding of JWT Client Authentication and/or 1151 Authorization Grants from RFC 7523? 1153 o The Metadata (Section 6) and what can and cannot be reliably 1154 inferred from it (Section 5) need additional evaluation and work. 1155 OAuth 2.0 Protected Resource Metadata [OAuth.ResourceMetadata] is 1156 no longer a going concern, but is currently referenced herein. 1157 Boolean values do not adequately convey Token Binding support, as 1158 different components may support different key parameters types. 1159 And successful negotiation likely doesn't provide the application 1160 layer info about all the supported key parameters types but rather 1161 just the one that was negotiated. 1163 Appendix C. Document History 1165 [[ to be removed by the RFC Editor before publication as an RFC ]] 1167 -04 1169 o Define how to convey token binding information of an access token 1170 via RFC 7662 OAuth 2.0 Token Introspection (note that the 1171 Introspection Response Registration request for cnf/Confirmation 1172 is in https://tools.ietf.org/html/draft-ietf-oauth-mtls- 1173 02#section-4.3 which will likely be published and registered prior 1174 to this document). 1176 o Minor editorial fixes. 1178 o Added an open issue about needing to allow for web server clients 1179 to opt-out of having refresh tokens bound while still allowing for 1180 binding of access tokens (following from mention of the problem on 1181 slide 16 of the presentation from Chicago 1182 https://www.ietf.org/proceedings/98/slides/slides-98-oauth-sessb- 1183 token-binding-00.pdf). 1185 -03 1187 o Fix a few mistakes in and around the examples that were noticed 1188 preparing the slides for IETF 98 Chicago. 1190 -02 1192 o Added a section on Token Binding for authorization codes with one 1193 variation for native clients and one for web server clients. 1195 o Updated language to reflect that the binding is to the token 1196 binding key pair and that proof-of-possession of that key is done 1197 on the TLS connection. 1199 o Added a bunch of examples. 1201 o Added a few Open Issues so they are tracked in the document. 1203 o Updated the Token Binding and OAuth Metadata references. 1205 o Added William Denniss as an author. 1207 -01 1209 o Changed Token Binding for access tokens to use the Referred Token 1210 Binding ID, now that the Implementation Considerations in the 1211 Token Binding HTTPS specification make it clear that 1212 implementations will enable using the Referred Token Binding ID. 1214 o Defined Protected Resource Metadata value. 1216 o Changed to use the more specific term "protected resource" instead 1217 of "resource server". 1219 -00 1220 o Created the initial working group version from draft-jones-oauth- 1221 token-binding-00. 1223 Authors' Addresses 1225 Michael B. Jones 1226 Microsoft 1228 Email: mbj@microsoft.com 1229 URI: http://self-issued.info/ 1231 John Bradley 1232 Ping Identity 1234 Email: ve7jtb@ve7jtb.com 1235 URI: http://www.thread-safe.com/ 1237 Brian Campbell 1238 Ping Identity 1240 Email: brian.d.campbell@gmail.com 1241 URI: https://twitter.com/__b_c 1243 William Denniss 1244 Google 1245 1600 Amphitheatre Pkwy 1246 Mountain View, CA 94043 1247 USA 1249 Email: wdenniss@google.com 1250 URI: http://wdenniss.com/