idnits 2.17.1 draft-ietf-oauth-token-binding-07.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 (June 21, 2018) is 2107 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-17 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' Summary: 1 error (**), 0 flaws (~~), 2 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 B. Campbell 5 Expires: December 23, 2018 Ping Identity 6 J. Bradley 7 Yubico 8 W. Denniss 9 Google 10 June 21, 2018 12 OAuth 2.0 Token Binding 13 draft-ietf-oauth-token-binding-07 15 Abstract 17 This specification enables OAuth 2.0 implementations to apply Token 18 Binding to Access Tokens, Authorization Codes, Refresh Tokens, JWT 19 Authorization Grants, and JWT Client Authentication. This 20 cryptographically binds these tokens to a client's Token Binding key 21 pair, possession of which is proven on the TLS connections over which 22 the tokens are intended to be used. This use of Token Binding 23 protects these tokens from man-in-the-middle and token export and 24 replay attacks. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on December 23, 2018. 43 Copyright Notice 45 Copyright (c) 2018 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 62 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Token Binding for Refresh Tokens . . . . . . . . . . . . . . 4 64 2.1. Example Token Binding for Refresh Tokens . . . . . . . . 4 65 3. Token Binding for Access Tokens . . . . . . . . . . . . . . . 7 66 3.1. Access Tokens Issued from the Authorization Endpoint . . 8 67 3.1.1. Example Access Token Issued from the Authorization 68 Endpoint . . . . . . . . . . . . . . . . . . . . . . 8 69 3.2. Access Tokens Issued from the Token Endpoint . . . . . . 9 70 3.2.1. Example Access Token Issued from the Token Endpoint . 10 71 3.3. Protected Resource Token Binding Validation . . . . . . . 12 72 3.3.1. Example Protected Resource Request . . . . . . . . . 12 73 3.4. Representing Token Binding in JWT Access Tokens . . . . . 12 74 3.5. Representing Token Binding in Introspection Responses . . 13 75 4. Token Binding Metadata . . . . . . . . . . . . . . . . . . . 14 76 4.1. Token Binding Client Metadata . . . . . . . . . . . . . . 14 77 4.2. Token Binding Authorization Server Metadata . . . . . . . 14 78 5. Token Binding for Authorization Codes . . . . . . . . . . . . 15 79 5.1. Native Application Clients . . . . . . . . . . . . . . . 15 80 5.1.1. Code Challenge . . . . . . . . . . . . . . . . . . . 15 81 5.1.1.1. Example Code Challenge . . . . . . . . . . . . . 16 82 5.1.2. Code Verifier . . . . . . . . . . . . . . . . . . . . 16 83 5.1.2.1. Example Code Verifier . . . . . . . . . . . . . . 17 84 5.2. Web Server Clients . . . . . . . . . . . . . . . . . . . 17 85 5.2.1. Code Challenge . . . . . . . . . . . . . . . . . . . 18 86 5.2.1.1. Example Code Challenge . . . . . . . . . . . . . 18 87 5.2.2. Code Verifier . . . . . . . . . . . . . . . . . . . . 19 88 5.2.2.1. Example Code Verifier . . . . . . . . . . . . . . 19 89 6. Token Binding JWT Authorization Grants and Client 90 Authentication . . . . . . . . . . . . . . . . . . . . . . . 20 91 6.1. JWT Format and Processing Requirements . . . . . . . . . 20 92 6.2. Token Bound JWTs for Client Authentication . . . . . . . 21 93 6.3. Token Bound JWTs for as Authorization Grants . . . . . . 21 94 7. Security Considerations . . . . . . . . . . . . . . . . . . . 22 95 7.1. Phasing in Token Binding . . . . . . . . . . . . . . . . 22 96 7.2. Binding of Refresh Tokens . . . . . . . . . . . . . . . . 22 97 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 98 8.1. OAuth Dynamic Client Registration Metadata Registration . 23 99 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 100 8.2. OAuth Authorization Server Metadata Registration . . . . 24 101 8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 102 8.3. PKCE Code Challenge Method Registration . . . . . . . . . 24 103 8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 104 9. Token Endpoint Authentication Method Registration . . . . . . 24 105 9.1. Registry Contents . . . . . . . . . . . . . . . . . . . . 25 106 10. Sub-Namespace Registrations . . . . . . . . . . . . . . . . . 25 107 10.1. Registry Contents . . . . . . . . . . . . . . . . . . . 25 108 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 109 11.1. Normative References . . . . . . . . . . . . . . . . . . 25 110 11.2. Informative References . . . . . . . . . . . . . . . . . 27 111 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 28 112 Appendix B. Document History . . . . . . . . . . . . . . . . . . 28 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 115 1. Introduction 117 This specification enables OAuth 2.0 [RFC6749] implementations to 118 apply Token Binding (TLS Extension for Token Binding Protocol 119 Negotiation [I-D.ietf-tokbind-negotiation], The Token Binding 120 Protocol Version 1.0 [I-D.ietf-tokbind-protocol] and Token Binding 121 over HTTP [I-D.ietf-tokbind-https]) to Access Tokens, Authorization 122 Codes, Refresh Tokens, JWT Authorization Grants, and JWT Client 123 Authentication. This cryptographically binds these tokens to a 124 client's Token Binding key pair, possession of which is proven on the 125 TLS connections over which the tokens are intended to be used. This 126 use of Token Binding protects these tokens from man-in-the-middle and 127 token export and replay attacks. 129 1.1. Requirements Notation and Conventions 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 133 "OPTIONAL" in this document are to be interpreted as described in BCP 134 14 [RFC2119] [RFC8174] when, and only when, they appear in all 135 capitals, as shown here. 137 1.2. Terminology 139 This specification uses the terms "Access Token", "Authorization 140 Code", "Authorization Endpoint", "Authorization Server", "Client", 141 "Protected Resource", "Refresh Token", and "Token Endpoint" defined 142 by OAuth 2.0 [RFC6749], the terms "Claim" and "JSON Web Token (JWT)" 143 defined by JSON Web Token (JWT) [JWT], the term "User Agent" defined 144 by RFC 7230 [RFC7230], and the terms "Provided", "Referred", "Token 145 Binding" and "Token Binding ID" defined by Token Binding over HTTP 146 [I-D.ietf-tokbind-https]. 148 2. Token Binding for Refresh Tokens 150 Token Binding of refresh tokens is a straightforward first-party 151 scenario, applying term "first-party" as used in Token Binding over 152 HTTP [I-D.ietf-tokbind-https]. It cryptographically binds the 153 refresh token to the client's Token Binding key pair, possession of 154 which is proven on the TLS connections between the client and the 155 token endpoint. This case is straightforward because the refresh 156 token is both retrieved by the client from the token endpoint and 157 sent by the client to the token endpoint. Unlike the federation use 158 cases described in Token Binding over HTTP [I-D.ietf-tokbind-https], 159 Section 4, and the access token case described in the next section, 160 only a single TLS connection is involved in the refresh token case. 162 Token Binding a refresh token requires that the authorization server 163 do two things. First, when refresh token is sent to the client, the 164 authorization server needs to remember the Provided Token Binding ID 165 and remember its association with the issued refresh token. Second, 166 when a token request containing a refresh token is received at the 167 token endpoint, the authorization server needs to verify that the 168 Provided Token Binding ID for the request matches the remembered 169 Token Binding ID associated with the refresh token. If the Token 170 Binding IDs do not match, the authorization server should return an 171 error in response to the request. 173 How the authorization server remembers the association between the 174 refresh token and the Token Binding ID is an implementation detail 175 that beyond the scope of this specification. Some authorization 176 servers will choose to store the Token Binding ID (or a cryptographic 177 hash of it, such a SHA-256 hash [SHS]) in the refresh token itself, 178 provided it is integrity-protected, thus reducing the amount of state 179 to be kept by the server. Other authorization servers will add the 180 Token Binding ID value (or a hash of it) to an internal data 181 structure also containing other information about the refresh token, 182 such as grant type information. These choices make no difference to 183 the client, since the refresh token is opaque to it. 185 2.1. Example Token Binding for Refresh Tokens 187 This section provides an example of what the interactions around a 188 Token Bound refresh token might look like, along with some details of 189 the involved processing. Token Binding of refresh tokens is most 190 useful for native application clients so the example has protocol 191 elements typical of a native client flow. Extra line breaks in all 192 examples are for display purposes only. 194 A native application client makes the following access token request 195 with an authorization code using a TLS connection where Token Binding 196 has been negotiated. A PKCE "code_verifier" is included because use 197 of PKCE is considered best practice for native application clients 198 [BCP212]. The base64url-encoded representation of the exported 199 keying material (EKM) from that TLS connection is 200 "p6ZuSwfl6pIe8es5KyeV76T4swZmQp0_awd27jHfrbo", which is needed to 201 validate the Token Binding Message. 203 POST /as/token.oauth2 HTTP/1.1 204 Host: server.example.com 205 Content-Type: application/x-www-form-urlencoded 206 Sec-Token-Binding: AIkAAgBBQGto7hHRR0Y5nkOWqc9KNfwW95dEFmSI_tCZ_Cbl 207 7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8m7eqAAQOKiDK1Oi0z6v4X5B 208 P7uc0pFestVZ42TTOdJmoHpji06Qq3jsCiCRSJx9ck2fWJYx8tLVXRZPATB3x6c24 209 aY0ZEAAA 211 grant_type=authorization_code&code=4bwcZesc7Xacc330ltc66Wxk8EAfP9j2 212 &code_verifier=2x6_ylS390-8V7jaT9wj.8qP9nKmYCf.V-rD9O4r_1 213 &client_id=example-native-client-id 215 Figure 1: Initial Request with Code 217 A refresh token is issued in response to the prior request. Although 218 it looks like a typical response to the client, the authorization 219 server has bound the refresh token to the Provided Token Binding ID 220 from the encoded Token Binding message in the "Sec-Token-Binding" 221 header of the request. In this example, that binding is done by 222 saving the Token Binding ID alongside other information about the 223 refresh token in some server side persistent storage. The base64url- 224 encoded representation of that Token Binding ID is "AgBBQGto7hHRR0Y5n 225 kOWqc9KNfwW95dEFmSI_tCZ_Cbl7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8 226 m7eqA". 228 HTTP/1.1 200 OK 229 Content-Type: application/json 230 Cache-Control: no-cache, no-store 232 { 233 "access_token":"EdRs7qMrLb167Z9fV2dcwoLTC", 234 "refresh_token":"ACClZEIQTjW9arT9GOJGGd7QNwqOMmUYfsJTiv8his4", 235 "token_type":"Bearer", 236 "expires_in":3600 237 } 239 Figure 2: Successful Response 241 When the access token expires, the client requests a new one with a 242 refresh request to the token endpoint. In this example, the request 243 is made on a new TLS connection so the EKM (base64url-encoded: "va- 244 84Ukw4Zqfd7uWOtFrAJda96WwgbdaPDX2knoOiAE") and signature in the Token 245 Binding Message are different than in the initial request. 247 POST /as/token.oauth2 HTTP/1.1 248 Host: server.example.com 249 Content-Type: application/x-www-form-urlencoded 250 Sec-Token-Binding: AIkAAgBBQGto7hHRR0Y5nkOWqc9KNfwW95dEFmSI_tCZ_Cbl 251 7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8m7eqAAQCpGbaG_YRf27qOra 252 L0UT4fsKKjL6PukuOT00qzamoAXxOq7m_id7O3mLpnb_sM7kwSxLi7iNHzzDgCAkP 253 t3lHwAAA 255 refresh_token=ACClZEIQTjW9arT9GOJGGd7QNwqOMmUYfsJTiv8his4 256 &grant_type=refresh_token&client_id=example-native-client-id 258 Figure 3: Refresh Request 260 However, because the Token Binding ID is long-lived and may span 261 multiple TLS sessions and connections, it is the same as in the 262 initial request. That Token Binding ID is what the refresh token is 263 bound to, so the authorization server is able to verify it and issue 264 a new access token. 266 HTTP/1.1 200 OK 267 Content-Type: application/json 268 Cache-Control: no-cache, no-store 270 { 271 "access_token":"bwcESCwC4yOCQ8iPsgcn117k7", 272 "token_type":"Bearer", 273 "expires_in":3600 274 } 276 Figure 4: Successful Response 278 3. Token Binding for Access Tokens 280 Token Binding for access tokens cryptographically binds the access 281 token to the client's Token Binding key pair, possession of which is 282 proven on the TLS connections between the client and the protected 283 resource. Token Binding is applied to access tokens in a similar 284 manner to that described in Token Binding over HTTP 285 [I-D.ietf-tokbind-https], Section 4 (Federation Use Cases). It also 286 builds upon the mechanisms for Token Binding of ID Tokens defined in 287 OpenID Connect Token Bound Authentication 1.0 [OpenID.TokenBinding]. 289 In the OpenID Connect [OpenID.Core] use case, HTTP redirects are used 290 to pass information between the identity provider and the relying 291 party; this HTTP redirect makes the Token Binding ID of the relying 292 party available to the identity provider as the Referred Token 293 Binding ID, information about which is then added to the ID Token. 294 No such redirect occurs between the authorization server and the 295 protected resource in the access token case; therefore, information 296 about the Token Binding ID for the TLS connection between the client 297 and the protected resource needs to be explicitly communicated by the 298 client to the authorization server to achieve Token Binding of the 299 access token. 301 This information is passed to the authorization server using the 302 Referred Token Binding ID, just as in the ID Token case. The only 303 difference is that the client needs to explicitly communicate the 304 Token Binding ID of the TLS connection between the client and the 305 protected resource to the Token Binding implementation so that it is 306 sent as the Referred Token Binding ID in the request to the 307 authorization server. This functionality provided by Token Binding 308 implementations is described in Implementation Considerations of 309 Token Binding over HTTP [I-D.ietf-tokbind-https], Section 6. 311 Note that to obtain this Token Binding ID, the client may need to 312 establish a TLS connection between itself and the protected resource 313 prior to making the request to the authorization server so that the 314 Provided Token Binding ID for the TLS connection to the protected 315 resource can be obtained. How the client retrieves this Token 316 Binding ID from the underlying Token Binding API is implementation 317 and operating system specific. An alternative, if supported, is for 318 the client to generate a Token Binding key to use for the protected 319 resource, use the Token Binding ID for that key, and then later use 320 that key when the TLS connection to the protected resource is 321 established. 323 3.1. Access Tokens Issued from the Authorization Endpoint 325 For access tokens returned directly from the authorization endpoint, 326 such as with the implicit grant defined in OAuth 2.0 [RFC6749], 327 Section 4.2, the Token Binding ID of the client's TLS channel to the 328 protected resource is sent with the authorization request as the 329 Referred Token Binding ID in the "Sec-Token-Binding" header, and is 330 used to Token Bind the access token. 332 Upon receiving the Referred Token Binding ID in an authorization 333 request, the authorization server associates (Token Binds) the ID 334 with the access token in a way that can be accessed by the protected 335 resource. Such methods include embedding the Referred Token Binding 336 ID (or a cryptographic hash of it) in the issued access token itself, 337 possibly using the syntax described in Section 3.4, or through token 338 introspection as described in Section 3.5. The method for 339 associating the referred token binding ID with the access token is 340 determined by the authorization server and the protected resource, 341 and is beyond the scope for this specification. 343 3.1.1. Example Access Token Issued from the Authorization Endpoint 345 This section provides an example of what the interactions around a 346 Token Bound access token issued from the authorization endpoint might 347 look like, along with some details of the involved processing. Extra 348 line breaks in all examples are for display purposes only. 350 The client directs the user-agent to make the following HTTP request 351 to the authorization endpoint. It is a typical authorization request 352 that, because Token Binding was negotiated on the underlying TLS 353 connection and the user-agent was signaled to reveal the Referred 354 Token Binding, also includes the "Sec-Token-Binding" header with a 355 Token Binding Message that contains both a Provided and Referred 356 Token Binding. The base64url-encoded EKM from the TLS connection 357 over which the request was made is 358 "jI5UAyjs5XCPISUGQIwgcSrOiVIWq4fhLVIFTQ4nLxc". 360 GET /as/authorization.oauth2?response_type=token 361 &client_id=example-client-id&state=rM8pZxG1c3gKy6rEbsD8s 362 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb HTTP/1.1 363 Host: server.example.com 364 Sec-Token-Binding: ARIAAgBBQIEE8mSMtDy2dj9EEBdXaQT9W3Rq1NS-jW8ebPoF 365 6FyL0jIfATVE55zlircgOTZmEg1xeIrC3DsGegwjs4bhw14AQGKDlAXFFMyQkZegC 366 wlbTlqX3F9HTt-lJxFU_pi16ezka7qVRCpSF0BQLfSqlsxMbYfSSCJX1BDtrIL7PX 367 j__fUAAAECAEFA1BNUnP3te5WrwlEwiejEz0OpesmC5PElWc7kZ5nlLSqQTj1ciIp 368 5vQ30LLUCyM_a2BYTUPKtd5EdS-PalT4t6ABADgeizRa5NkTMuX4zOdC-R4cLNWVV 369 O8lLu2Psko-UJLR_XAH4Q0H7-m0_nQR1zBN78nYMKPvHsz8L3zWKRVyXEgAA 371 Figure 5: Authorization Request 373 The authorization server issues an access token and delivers it to 374 the client by redirecting the user-agent with the following HTTP 375 response: 377 HTTP/1.1 302 Found 378 Location: https://client.example.org/cb#state=rM8pZxG1c3gKy6rEbsD8s 379 &expires_in=3600&token_type=Bearer 380 &access_token=eyJhbGciOiJFUzI[...omitted for brevity...]8xy5W5sQ 382 Figure 6: Authorization Response 384 The access token is bound to the Referred Token Binding ID from the 385 authorization request, which when represented as a JWT, as described 386 in Section 3.4, contains the SHA-256 hash of the Token Binding ID as 387 the value of the "tbh" (token binding hash) member of the "cnf" 388 (confirmation) claim. The confirmation claim portion of the JWT 389 Claims Set is shown in the following figure. 391 { 392 ...other claims omitted for brevity... 393 "cnf":{ 394 "tbh": "vowQESa_MgbGJwIXaFm_BTN2QDPwh8PhuBm-EtUAqxc" 395 } 396 } 398 Figure 7: Confirmation Claim 400 3.2. Access Tokens Issued from the Token Endpoint 402 For access tokens returned from the token endpoint, the Token Binding 403 ID of the client's TLS channel to the protected resource is sent as 404 the Referred Token Binding ID in the "Sec-Token-Binding" header, and 405 is used to Token Bind the access token. This applies to all the 406 grant types from OAuth 2.0 [RFC6749] using the token endpoint, 407 including, but not limited to the refresh and authorization code 408 token requests, as well as some extension grants, such as JWT 409 assertion authorization grants [RFC7523]. 411 Upon receiving the Referred Token Binding ID in a token request, the 412 authorization server associates (Token Binds) the ID with the access 413 token in a way that can be accessed by the protected resource. Such 414 methods include embedding the Referred Token Binding ID (or a 415 cryptographic hash of it) in the issued access token itself, possibly 416 using the syntax described in Section 3.4, or through token 417 introspection as described in Section 3.5. The method for 418 associating the referred token binding ID with the access token is 419 determined by the authorization server and the protected resource, 420 and is beyond the scope for this specification. 422 Note that if the request results in a new refresh token being 423 generated, it can be Token bound using the Provided Token Binding ID, 424 per Section 2. 426 3.2.1. Example Access Token Issued from the Token Endpoint 428 This section provides an example of what the interactions around a 429 Token Bound access token issued from the token endpoint might look 430 like, along with some details of the involved processing. Extra line 431 breaks in all examples are for display purposes only. 433 The client makes an access token request to the token endpoint and 434 includes the "Sec-Token-Binding" header with a Token Binding Message 435 that contains both Provided and Referred Token Binding IDs. The 436 Provided Token Binding ID is used to validate the token binding of 437 the refresh token in the request (and to Token Bind a new refresh 438 token, if one is issued), and the Referred Token Binding ID is used 439 to Token Bind the access token that is generated. The base64url- 440 encoded EKM from the TLS connection over which the access token 441 request was made is "4jTc5e1QpocqPTZ5l6jsb6pRP18IFKdwwPvasYjn1-E". 443 POST /as/token.oauth2 HTTP/1.1 444 Host: server.example.com 445 Content-Type: application/x-www-form-urlencoded 446 Sec-Token-Binding: ARIAAgBBQJFXJir2w4gbJ7grBx9uTYWIrs9V50-PW4ZijegQ 447 0LUM-_bGnGT6DizxUK-m5n3dQUIkeH7ybn6wb1C5dGyV_IAAQDDFToFrHt41Zppq7 448 u_SEMF_E-KimAB-HewWl2MvZzAQ9QKoWiJCLFiCkjgtr1RrA2-jaJvoB8o51DTGXQ 449 ydWYkAAAECAEFAuC1GlYU83rqTGHEau1oqvNwy0fDsdXzIyT_4x1FcldsMxjFkJac 450 IBJFGuYcccvnCak_duFi3QKFENuwxql-H9ABAMcU7IjJOUA4IyE6YoEcfz9BMPQqw 451 M5M6hw4RZNQd58fsTCCslQE_NmNCl9JXy4NkdkEZBxqvZGPr0y8QZ_bmAwAA 453 refresh_token=gZR_ZI8EAhLgWR-gWxBimbgZRZi_8EAhLgWRgWxBimbf 454 &grant_type=refresh_token&client_id=example-client-id 456 Figure 8: Access Token Request 458 The authorization server issues an access token bound to the Referred 459 Token Binding ID and delivers it in a response the client. 461 HTTP/1.1 200 OK 462 Content-Type: application/json 463 Cache-Control: no-cache, no-store 465 { 466 "access_token":"eyJhbGciOiJFUzI1NiIsImtp[...omitted...]1cs29j5c3", 467 "token_type":"Bearer", 468 "expires_in":3600 469 } 471 Figure 9: Response 473 The access token is bound to the Referred Token Binding ID of the 474 access token request, which when represented as a JWT, as described 475 in Section 3.4, contains the SHA-256 hash of the Token Binding ID as 476 the value of the "tbh" (token binding hash) member of the "cnf" 477 (confirmation) claim. The confirmation claim portion of the JWT 478 Claims Set of the access token is shown in the following figure. 480 { 481 ...other claims omitted for brevity... 482 "cnf":{ 483 "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" 484 } 485 } 487 Figure 10: Confirmation Claim 489 3.3. Protected Resource Token Binding Validation 491 Upon receiving a token bound access token, the protected resource 492 validates the binding by comparing the Provided Token Binding ID to 493 the Token Binding ID for the access token. Alternatively, 494 cryptographic hashes of these Token Binding ID values can be 495 compared. If the values do not match, the resource access attempt 496 MUST be rejected with an error. 498 3.3.1. Example Protected Resource Request 500 For example, a protected resource request using the access token from 501 Section 3.2.1 would look something like the following. The 502 base64url-encoded EKM from the TLS connection over which the request 503 was made is "7LsNP3BT1aHHdXdk6meEWjtSkiPVLb7YS6iHp-JXmuE". The 504 protected resource validates the binding by comparing the Provided 505 Token Binding ID from the "Sec-Token-Binding" header to the token 506 binding hash confirmation of the access token. Extra line breaks in 507 the example are for display purposes only. 509 GET /api/stuff HTTP/1.1 510 Host: resource.example.org 511 Authorization: Bearer eyJhbGciOiJFUzI1NiIsI[...omitted...]1cs29j5c3 512 Sec-Token-Binding: AIkAAgBBQLgtRpWFPN66kxhxGrtaKrzcMtHw7HV8yMk_-MdR 513 XJXbDMYxZCWnCASRRrmHHHL5wmpP3bhYt0ChRDbsMapfh_QAQN1He3Ftj4Wa_S_fz 514 ZVns4saLfj6aBoMSQW6rLs19IIvHze7LrGjKyCfPTKXjajebxp-TLPFZCc0JTqTY5 515 _0MBAAAA 517 Figure 11: Protected Resource Request 519 3.4. Representing Token Binding in JWT Access Tokens 521 If the access token is represented as a JWT, the token binding 522 information SHOULD be represented in the same way that it is in token 523 bound OpenID Connect ID Tokens [OpenID.TokenBinding]. That 524 specification defines the new JWT Confirmation Method RFC 7800 525 [RFC7800] member "tbh" (token binding hash) to represent the SHA-256 526 hash of a Token Binding ID in an ID Token. The value of the "tbh" 527 member is the base64url encoding of the SHA-256 hash of the Token 528 Binding ID. All all trailing pad '=' characters are omitted from the 529 encoded value and no line breaks, whitespace, or other additional 530 characters are included. 532 The following example demonstrates the JWT Claims Set of an access 533 token containing the base64url encoding of the SHA-256 hash of a 534 Token Binding ID as the value of the "tbh" (token binding hash) 535 element in the "cnf" (confirmation) claim: 537 { 538 "iss": "https://server.example.com", 539 "aud": "https://resource.example.org", 540 "sub": "brian@example.com" 541 "iat": 1467324320, 542 "exp": 1467324920, 543 "cnf":{ 544 "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" 545 } 546 } 548 Figure 12: JWT with Token Binding Hash Confirmation Claim 550 3.5. Representing Token Binding in Introspection Responses 552 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 553 protected resource to query an authorization server about the active 554 state of an access token as well as to determine meta-information 555 about the token. 557 For a token bound access token, the hash of the Token Binding ID to 558 which the token is bound is conveyed to the protected resource as 559 meta-information in a token introspection response. The hash is 560 conveyed using same structure as the token binding hash confirmation 561 method, described in Section 3.4, as a top-level member of the 562 introspection response JSON. The protected resource compares that 563 token binding hash to a hash of the provided Token Binding ID and 564 rejects the request, if they do not match. 566 The following is an example of an introspection response for an 567 active token bound access token with a "tbh" token binding hash 568 confirmation method. 570 HTTP/1.1 200 OK 571 Content-Type: application/json 573 { 574 "active": true, 575 "iss": "https://server.example.com", 576 "aud": "https://resource.example.org", 577 "sub": "brian@example.com" 578 "iat": 1467324320, 579 "exp": 1467324920, 580 "cnf":{ 581 "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" 582 } 583 } 585 Figure 13: Example Introspection Response for a Token Bound Access 586 Token 588 4. Token Binding Metadata 590 4.1. Token Binding Client Metadata 592 Clients supporting Token Binding that also support the OAuth 2.0 593 Dynamic Client Registration Protocol [RFC7591] use these metadata 594 values to declare their support for Token Binding of access tokens 595 and refresh tokens: 597 client_access_token_token_binding_supported 598 OPTIONAL. Boolean value specifying whether the client supports 599 Token Binding of access tokens. If omitted, the default value is 600 "false". 602 client_refresh_token_token_binding_supported 603 OPTIONAL. Boolean value specifying whether the client supports 604 Token Binding of refresh tokens. If omitted, the default value is 605 "false". Authorization servers MUST NOT Token Bind refresh tokens 606 issued to a client that does not support Token Binding of refresh 607 tokens, but MAY reject requests completely from such clients if 608 token binding is required by authorization server policy by 609 returning an OAuth error response. 611 4.2. Token Binding Authorization Server Metadata 613 Authorization servers supporting Token Binding that also support 614 OAuth 2.0 Authorization Server Metadata [OAuth.AuthorizationMetadata] 615 use these metadata values to declare their support for Token Binding 616 of access tokens and refresh tokens: 618 as_access_token_token_binding_supported 619 OPTIONAL. Boolean value specifying whether the authorization 620 server supports Token Binding of access tokens. If omitted, the 621 default value is "false". 623 as_refresh_token_token_binding_supported 624 OPTIONAL. Boolean value specifying whether the authorization 625 server supports Token Binding of refresh tokens. If omitted, the 626 default value is "false". 628 5. Token Binding for Authorization Codes 630 There are two variations for Token Binding of an authorization code. 631 One is appropriate for native application clients and the other for 632 web server clients. The nature of where the various components 633 reside for the different client types demands different methods of 634 Token Binding the authorization code so that it is bound to a Token 635 Binding key on the end user's device. This ensures that a lost or 636 stolen authorization code cannot be successfully utilized from a 637 different device. For native application clients, the code is bound 638 to a Token Binding key pair that the native client itself possesses. 639 For web server clients, the code is bound to a Token Binding key pair 640 on the end user's browser. Both variations utilize the extensible 641 framework of Proof Key for Code Exchange (PKCE) [RFC7636], which 642 enables the client to show possession of a certain key when 643 exchanging the authorization code for tokens. The following 644 subsections individually describe each of the two PKCE methods 645 respectively. 647 5.1. Native Application Clients 649 This section describes a PKCE method suitable for native application 650 clients that cryptographically binds the authorization code to a 651 Token Binding key pair on the client, which the client proves 652 possession of on the TLS connection during the access token request 653 containing the authorization code. The authorization code is bound 654 to the Token Binding ID that the native application client uses to 655 resolve the authorization code at the token endpoint. This binding 656 ensures that the client that made the authorization request is the 657 same client that is presenting the authorization code. 659 5.1.1. Code Challenge 661 As defined in Proof Key for Code Exchange [RFC7636], the client sends 662 the code challenge as part of the OAuth 2.0 authorization request 663 with the two additional parameters: "code_challenge" and 664 "code_challenge_method". 666 For this Token Binding method of PKCE, "TB-S256" is used as the value 667 of the "code_challenge_method" parameter. 669 The value of the "code_challenge" parameter is the base64url encoding 670 (per Section 5 of [RFC4648] with all trailing padding ('=') 671 characters omitted and without the inclusion of any line breaks or 672 whitespace) of the SHA-256 hash of the Provided Token Binding ID that 673 the client will use when calling the authorization server's token 674 endpoint. Note that, prior to making the authorization request, the 675 client may need to establish a TLS connection between itself and the 676 authorization server's token endpoint in order to establish the 677 appropriate Token Binding ID. 679 When the authorization server issues the authorization code in the 680 authorization response, it associates the code challenge and method 681 values with the authorization code so they can be verified later when 682 the authorization code is presented in the access token request. 684 5.1.1.1. Example Code Challenge 686 For example, a native application client sends an authorization 687 request by sending the user's browser to the authorization endpoint. 688 The resulting HTTP request looks something like the following (with 689 extra line breaks for display purposes only). 691 GET /as/authorization.oauth2?response_type=code 692 &client_id=example-native-client-id&state=oUC2jyYtzRCrMyWrVnGj 693 &code_challenge=rBlgOyMY4teiuJMDgOwkrpsAjPyI07D2WsEM-dnq6eE 694 &code_challenge_method=TB-S256 HTTP/1.1 695 Host: server.example.com 697 Figure 14: Authorization Request with PKCE Challenge 699 5.1.2. Code Verifier 701 Upon receipt of the authorization code, the client sends the access 702 token request to the token endpoint. The Token Binding Protocol 703 [I-D.ietf-tokbind-protocol] is negotiated on the TLS connection 704 between the client and the authorization server and the "Sec-Token- 705 Binding" header, as defined in Token Binding over HTTP 706 [I-D.ietf-tokbind-https], is included in the access token request. 707 The authorization server extracts the Provided Token Binding ID from 708 the header value, hashes it with SHA-256, and compares it to the 709 "code_challenge" value previously associated with the authorization 710 code. If the values match, the token endpoint continues processing 711 as normal (as defined by OAuth 2.0 [RFC6749]). If the values do not 712 match, an error response indicating "invalid_grant" MUST be returned. 714 The "Sec-Token-Binding" header contains sufficient information for 715 verification of the authorization code and its association to the 716 original authorization request. However, PKCE [RFC7636] requires 717 that a "code_verifier" parameter be sent with the access token 718 request, so the static value "provided_tb" is used to meet that 719 requirement and indicate that the Provided Token Binding ID is used 720 for the verification. 722 5.1.2.1. Example Code Verifier 724 An example access token request, correlating to the authorization 725 request in the previous example, to the token endpoint over a TLS 726 connection for which Token Binding has been negotiated would look 727 like the following (with extra line breaks for display purposes 728 only). The base64url-encoded EKM from the TLS connection over which 729 the request was made is 730 "pNVKtPuQFvylNYn000QowWrQKoeMkeX9H32hVuU71Bs". 732 POST /as/token.oauth2 HTTP/1.1 733 Host: server.example.com 734 Content-Type: application/x-www-form-urlencoded 735 Sec-Token-Binding: AIkAAgBBQEOO9GRFP-LM0hoWw6-2i318BsuuUum5AL8bt1sz 736 lr1EFfp5DMXMNW3O8WjcIXr2DKJnI4xnuGsE6GywQd9RbD0AQJDb3xyo9PBxj8M6Y 737 jLt-6OaxgDkyoBoTkyrnNbLc8tJQ0JtXomKzBbj5qPtHDduXc6xz_lzvNpxSPxi42 738 8m7wkAAA 740 grant_type=authorization_code&code=mJAReTWKX7zI3oHUNd4o3PeNqNqxKGp6 741 &code_verifier=provided_tb&client_id=example-native-client-id 743 Figure 15: Token Request with PKCE Verifier 745 5.2. Web Server Clients 747 This section describes a PKCE method suitable for web server clients, 748 which cryptographically binds the authorization code to a Token 749 Binding key pair on the browser. The authorization code is bound to 750 the Token Binding ID that the browser uses to deliver the 751 authorization code to a web server client, which is sent to the 752 authorization server as the Referred Token Binding ID during the 753 authorization request. The web server client conveys the Token 754 Binding ID to the authorization server when making the access token 755 request containing the authorization code. This binding ensures that 756 the authorization code cannot successfully be played or replayed to 757 the web server client from a different browser than the one that made 758 the authorization request. 760 5.2.1. Code Challenge 762 As defined in Proof Key for Code Exchange [RFC7636], the client sends 763 the code challenge as part of the OAuth 2.0 Authorization Request 764 with the two additional parameters: "code_challenge" and 765 "code_challenge_method". 767 The client must send the authorization request through the browser 768 such that the Token Binding ID established between the browser and 769 itself is revealed to the authorization server's authorization 770 endpoint as the Referred Token Binding ID. Typically, this is done 771 with an HTTP redirection response and the "Include-Referred-Token- 772 Binding-ID" header, as defined in Token Binding over HTTP 773 [I-D.ietf-tokbind-https], Section 5.3. 775 For this Token Binding method of PKCE, "referred_tb" is used for the 776 value of the "code_challenge_method" parameter. 778 The value of the "code_challenge" parameter is "referred_tb". The 779 static value for the required PKCE parameter indicates that the 780 authorization code is to be bound to the Referred Token Binding ID 781 from the Token Binding Message sent in the "Sec-Token-Binding" header 782 of the authorization request. 784 When the authorization server issues the authorization code in the 785 authorization response, it associates the Token Binding ID (or hash 786 thereof) and code challenge method with the authorization code so 787 they can be verified later when the authorization code is presented 788 in the access token request. 790 5.2.1.1. Example Code Challenge 792 For example, the web server client sends the authorization request by 793 redirecting the browser to the authorization endpoint. That HTTP 794 redirection response looks like the following (with extra line breaks 795 for display purposes only). 797 HTTP/1.1 302 Found 798 Location: https://server.example.com?response_type=code 799 &client_id=example-web-client-id&state=P4FUFqYzs1ij3ffsYCP34d3 800 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 801 &code_challenge=referred_tb&code_challenge_method=referred_tb 802 Include-Referred-Token-Binding-ID: true 804 Figure 16: Redirect the Browser 806 The redirect includes the "Include-Referred-Token-Binding-ID" 807 response header field that signals to the user-agent that it should 808 reveal, to the authorization server, the Token Binding ID used on the 809 connection to the web server client. The resulting HTTP request to 810 the authorization server looks something like the following (with 811 extra line breaks for display purposes only). The base64url-encoded 812 EKM from the TLS connection over which the request was made is 813 "7gOdRzMhPeO-1YwZGmnVHyReN5vd2CxcsRBN69Ue4cI". 815 GET /as/authorization.oauth2?response_type=code 816 &client_id=example-web-client-id&state=dryo8YFpWacbUPjhBf4Nvt51 817 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 818 &code_challenge=referred_tb 819 &code_challenge_method=referred_tb HTTP/1.1 820 Host: server.example.com 821 Sec-Token-Binding: ARIAAgBBQB-XOPf5ePlf7ikATiAFEGOS503lPmRfkyymzdWw 822 HCxl0njjxC3D0E_OVfBNqrIQxzIfkF7tWby2ZfyaE6XpwTsAQBYqhFX78vMOgDX_F 823 d_b2dlHyHlMmkIz8iMVBY_reM98OUaJFz5IB7PG9nZ11j58LoG5QhmQoI9NXYktKZ 824 RXxrYAAAECAEFAdUFTnfQADkn1uDbQnvJEk6oQs38L92gv-KO-qlYadLoDIKe2h53 825 hSiKwIP98iRj_unedkNkAMyg9e2mY4Gp7WwBAeDUOwaSXNz1e6gKohwN4SAZ5eNyx 826 45Mh8VI4woL1BipLoqrJRoK6dxFkWgHRMuBROcLGUj5PiOoxybQH_Tom3gAA 828 Figure 17: Authorization Request 830 5.2.2. Code Verifier 832 The web server client receives the authorization code from the 833 browser and extracts the Provided Token Binding ID from the "Sec- 834 Token-Binding" header of the request. The client sends the 835 base64url-encoded (per Section 5 of [RFC4648] with all trailing 836 padding ('=') characters omitted and without the inclusion of any 837 line breaks or whitespace) Provided Token Binding ID as the value of 838 the "code_verifier" parameter in the access token request to the 839 authorization server's token endpoint. The authorization server 840 compares the value of the "code_verifier" parameter to the Token 841 Binding ID value previously associated with the authorization code. 842 If the values match, the token endpoint continues processing as 843 normal (as defined by OAuth 2.0 [RFC6749]). If the values do not 844 match, an error response indicating "invalid_grant" MUST be returned. 846 5.2.2.1. Example Code Verifier 848 Continuing the example from the previous section, the authorization 849 server sends the code to the web server client by redirecting the 850 browser to the client's "redirect_uri", which results in the browser 851 making a request like the following (with extra line breaks for 852 display purposes only) to the web server client over a TLS channel 853 for which Token Binding has been established. The base64url-encoded 854 EKM from the TLS connection over which the request was made is 855 "EzW60vyINbsb_tajt8ij3tV6cwy2KH-i8BdEMYXcNn0". 857 GET /cb?state=dryo8YFpWacbUPjhBf4Nvt51&code=jwD3oOa5cQvvLc81bwc4CMw 858 Host: client.example.org 859 Sec-Token-Binding: AIkAAgBBQHVBU530AA5J9bg20J7yRJOqELN_C_doL_ijvqpW 860 GnS6AyCntoed4UoisCD_fIkY_7p3nZDZADMoPXtpmOBqe1sAQEwgC9Zpg7QFCDBib 861 6GlZki3MhH32KNfLefLJc1vR1xE8l7OMfPLZHP2Woxh6rEtmgBcAABubEbTz7muNl 862 Ln8uoAAA 864 Figure 18: Authorization Response to Web Server Client 866 The web server client takes the Provided Token Binding ID from the 867 above request from the browser and sends it, base64url encoded, to 868 the authorization server in the "code_verifier" parameter of the 869 authorization code grant type request. Extra line breaks in the 870 example request are for display purposes only. 872 POST /as/token.oauth2 HTTP/1.1 873 Host: server.example.com 874 Content-Type: application/x-www-form-urlencoded 875 Authorization: Basic b3JnLmV4YW1wbGUuY2xpZW50OmlldGY5OGNoaWNhZ28= 877 grant_type=authorization_code&code=jwD3oOa5cQvvLc81bwc4CMw 878 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 879 &client_id=example-web-client-id 880 &code_verifier=AgBBQHVBU530AA5J9bg20J7yRJOqELN_C_doL_ijv 881 qpWGnS6AyCntoed4UoisCD_fIkY_7p3nZDZADMoPXtpmOBqe1s 883 Figure 19: Exchange Authorization Code 885 6. Token Binding JWT Authorization Grants and Client Authentication 887 The JWT Profile for OAuth 2.0 Client Authentication and Authorization 888 Grants [RFC7523] defines the use of bearer JWTs as a means for 889 requesting an OAuth 2.0 access token as well as for client 890 authentication. This section describes extensions to that 891 specification enabling the application of Token Binding to JWT client 892 authentication and JWT authorization grants. 894 6.1. JWT Format and Processing Requirements 896 In addition the requirements set forth in Section 3 of RFC 7523 897 [RFC7523], the following criteria must also be met for token bound 898 JWTs used as authorization grants or for client authentication. 900 o The JWT MUST contain a "cnf" (confirmation) claim with a "tbh" 901 (token binding hash) member identifying the Token Binding ID of 902 the Provided Token Binding used by the client on the TLS 903 connection to the authorization server. The authorization server 904 MUST reject any JWT that has a token binding hash confirmation 905 that does not match the corresponding hash of the Provided Token 906 Binding ID from the "Sec-Token-Binding" header of the request. 908 6.2. Token Bound JWTs for Client Authentication 910 To use a token bound JWT for client authentication, the client uses 911 the parameter values and encodings from Section 2.2 of RFC 7523 912 [RFC7523] with one exception: the value of the 913 "client_assertion_type" is "urn:ietf:params:oauth:client-assertion- 914 type:jwt-token-bound". 916 The "OAuth Token Endpoint Authentication Methods" registry 917 [IANA.OAuth.Parameters] contains values, each of which specify a 918 method of authenticating a client to the authorization server. The 919 values are used to indicated supported and utilized client 920 authentication methods in authorization server metadata, such as 921 [OpenID.Discovery] and [OAuth.AuthorizationMetadata], and in OAuth 922 2.0 Dynamic Client Registration Protocol [RFC7591]. The values 923 "private_key_jwt" and "client_secret_jwt" are designated by OpenID 924 Connect [OpenID.Core] as authentication method values for bearer JWT 925 client authentication using asymmetric and symmetric JWS [RFC7515] 926 algorithms respectively. For Token Bound JWT for client 927 authentication, this specification defines and registers the 928 following authentication method values. 930 private_key_token_bound_jwt 931 Indicates that client authentication to the authorization server 932 will occur with a Token Bound JWT, which is signed with a client's 933 private key. 935 client_secret_token_bound_jwt 936 Indicates that client authentication to the authorization server 937 will occur with a Token Bound JWT, which is integrity protected 938 with a MAC using the octets of the UTF-8 representation of the 939 client secret as the shared key. 941 Note that just as with the "private_key_jwt" and "client_secret_jwt" 942 authentication methods, the "token_endpoint_auth_signing_alg" client 943 registration parameter may be used to indicate the JWS algorithm used 944 for signing the client authentication JWT for the authentication 945 methods defined above. 947 6.3. Token Bound JWTs for as Authorization Grants 949 To use a token bound JWT for an authorization grant, the client uses 950 the parameter values and encodings from Section 2.1 of RFC 7523 951 [RFC7523] with one exception: the value of the "grant_type" is 952 "urn:ietf:params:oauth:grant-type:jwt-token-bound". 954 7. Security Considerations 956 7.1. Phasing in Token Binding 958 Many OAuth implementations will be deployed in situations in which 959 not all participants support Token Binding. Any of combination of 960 the client, the authorization server, the protected resource, and the 961 user agent may not yet support Token Binding, in which case it will 962 not work end-to-end. 964 It is a context-dependent deployment choice whether to allow 965 interactions to proceed in which Token Binding is not supported or 966 whether to treat the omission of Token Binding at any step as a fatal 967 error. Particularly in dynamic deployment environments in which End 968 Users have choices of clients, authorization servers, protected 969 resources, and/or user agents, it is recommended that, for some 970 reasonable period of time during which Token Binding technology is 971 being adopted, authorizations using one or more components that do 972 not implement Token Binding be allowed to successfully proceed. This 973 enables different components to be upgraded to supporting Token 974 Binding at different times, providing a smooth transition path for 975 phasing in Token Binding. However, when Token Binding has been 976 performed, any Token Binding key mismatches MUST be treated as fatal 977 errors. 979 In more controlled deployment environments where the participants in 980 an authorization interaction are known or expected to support Token 981 Binding and yet one or more of them does not use it, the 982 authorization SHOULD be aborted with an error. For instance, an 983 authorization server should reject a token request that does not 984 include the "Sec-Token-Binding" header, if the request is from a 985 client known to support Token Binding (via configuration or the 986 "client_access_token_token_binding_supported" metadata parameter). 988 7.2. Binding of Refresh Tokens 990 Section 6 of RFC 6749 [RFC6749] requires that a refresh token be 991 bound to the client to which it was issued and that, if the client 992 type is confidential or the client was issued client credentials (or 993 assigned other authentication requirements), the client must 994 authenticate with the authorization server when presenting the 995 refresh token. As a result, for non-public clients, refresh tokens 996 are indirectly bound to the client's credentials and cannot be used 997 without the associated client authentication. Non-public clients 998 then are afforded protections (equivalent to the strength of their 999 authentication credentials) against unauthorized replay of refresh 1000 tokens and it is reasonable to not Token Bind refresh tokens for such 1001 clients while still Toking Binding the issued access tokens. Refresh 1002 tokens issued to public clients, however, do not have the benefit of 1003 such protections and authorization servers MAY elect to disallow 1004 public clients from registering or establishing configuration that 1005 would allow Token Bound access tokens but unbound refresh tokens. 1007 Some web-based confidential clients implemented as distributed nodes 1008 may be perfectly capable of implementing access token binding (if the 1009 access token remains on the node it was bound to, the token binding 1010 keys would be locally available for that node to prove possession), 1011 but may struggle with refresh token binding due to an inability to 1012 share token binding key material between nodes. As confidential 1013 clients already have credentials which are required to use the 1014 refresh token, and those credentials should only ever be sent over 1015 TLS server-to-server between the client and the Token Endpoint, there 1016 is still value in token binding access tokens without token binding 1017 refresh tokens. Authorization servers SHOULD consider supporting 1018 access token binding without refresh token binding for confidential 1019 web clients as there are still security benefits to do so. 1021 Clients MUST declare through dynamic (Section 4.1) or static 1022 registration information what types of token bound tokens they 1023 support to enable the server to bind tokens accordingly, taking into 1024 account any phase-in policies. Authorization servers MAY reject 1025 requests from any client who does not support token binding (by 1026 returning an OAuth error response) per their own security policies. 1028 8. IANA Considerations 1030 8.1. OAuth Dynamic Client Registration Metadata Registration 1032 This specification registers the following client metadata 1033 definitions in the IANA "OAuth Dynamic Client Registration Metadata" 1034 registry [IANA.OAuth.Parameters] established by [RFC7591]: 1036 8.1.1. Registry Contents 1038 o Client Metadata Name: 1039 "client_access_token_token_binding_supported" 1040 o Client Metadata Description: Boolean value specifying whether the 1041 client supports Token Binding of access tokens 1042 o Change Controller: IESG 1043 o Specification Document(s): Section 4.1 of [[ this specification ]] 1045 o Client Metadata Name: 1046 "client_refresh_token_token_binding_supported" 1047 o Client Metadata Description: Boolean value specifying whether the 1048 client supports Token Binding of refresh tokens 1049 o Change Controller: IESG 1050 o Specification Document(s): Section 4.1 of [[ this specification ]] 1052 8.2. OAuth Authorization Server Metadata Registration 1054 This specification registers the following metadata definitions in 1055 the IANA "OAuth Authorization Server Metadata" registry established 1056 by [OAuth.AuthorizationMetadata]: 1058 8.2.1. Registry Contents 1060 o Metadata Name: "as_access_token_token_binding_supported" 1061 o Metadata Description: Boolean value specifying whether the 1062 authorization server supports Token Binding of access tokens 1063 o Change Controller: IESG 1064 o Specification Document(s): Section 4.2 of [[ this specification ]] 1066 o Metadata Name: "as_refresh_token_token_binding_supported" 1067 o Metadata Description: Boolean value specifying whether the 1068 authorization server supports Token Binding of refresh tokens 1069 o Change Controller: IESG 1070 o Specification Document(s): Section 4.2 of [[ this specification ]] 1072 8.3. PKCE Code Challenge Method Registration 1074 This specification requests registration of the following Code 1075 Challenge Method Parameter Names in the IANA "PKCE Code Challenge 1076 Methods" registry [IANA.OAuth.Parameters] established by [RFC7636]. 1078 8.3.1. Registry Contents 1080 o Code Challenge Method Parameter Name: TB-S256 1081 o Change controller: IESG 1082 o Specification document(s): Section 5.1.1 of [[ this specification 1083 ]] 1085 o Code Challenge Method Parameter Name: referred_tb 1086 o Change controller: IESG 1087 o Specification document(s): Section 5.2.1 of [[ this specification 1088 ]] 1090 9. Token Endpoint Authentication Method Registration 1092 This specification requests registration of the following values in 1093 the IANA "OAuth Token Endpoint Authentication Methods" registry 1094 [IANA.OAuth.Parameters] established by [RFC7591]. 1096 9.1. Registry Contents 1098 o Token Endpoint Authentication Method Name: 1099 "client_secret_token_bound_jwt" 1100 o Change Controller: IESG 1101 o Specification Document(s): Section 6 of [[ this specification ]] 1103 o Token Endpoint Authentication Method Name: 1104 "private_key_token_bound_jwt" 1105 o Change Controller: IESG 1106 o Specification Document(s): Section 6 of [[ this specification ]] 1108 10. Sub-Namespace Registrations 1110 This specification requests registration of the following values in 1111 the IANA "OAuth URI" registry [IANA.OAuth.Parameters] established in 1112 An IETF URN Sub-Namespace for OAuth [RFC6755]. 1114 10.1. Registry Contents 1116 o URN: urn:ietf:params:oauth:grant-type:jwt-token-bound 1117 o Common Name: Token Bound JWT Grant Type for OAuth 2.0 1118 o Change controller: IESG 1119 o Specification Document: Section 6 of [[ this specification ]] 1121 o URN: urn:ietf:params:oauth:client-assertion-type:jwt-token-bound 1122 o Common Name: Token Bound JWT for OAuth 2.0 Client Authentication 1123 o Change controller: IESG 1124 o Specification Document: Section 6 of [[ this specification ]] 1126 11. References 1128 11.1. Normative References 1130 [I-D.ietf-tokbind-https] 1131 Popov, A., Nystrom, M., Balfanz, D., Langley, A., Harper, 1132 N., and J. Hodges, "Token Binding over HTTP", draft-ietf- 1133 tokbind-https-17 (work in progress), June 2018. 1135 [I-D.ietf-tokbind-negotiation] 1136 Popov, A., Nystrom, M., Balfanz, D., and A. Langley, 1137 "Transport Layer Security (TLS) Extension for Token 1138 Binding Protocol Negotiation", draft-ietf-tokbind- 1139 negotiation-14 (work in progress), May 2018. 1141 [I-D.ietf-tokbind-protocol] 1142 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 1143 Hodges, "The Token Binding Protocol Version 1.0", draft- 1144 ietf-tokbind-protocol-19 (work in progress), May 2018. 1146 [IANA.OAuth.Parameters] 1147 IANA, "OAuth Parameters", 1148 . 1150 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1151 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1152 . 1154 [OAuth.AuthorizationMetadata] 1155 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1156 Authorization Server Metadata", draft-ietf-oauth- 1157 discovery-10 (work in progress), March 2017, 1158 . 1161 [OpenID.TokenBinding] 1162 Jones, M., Bradley, J., and B. Campbell, "OpenID Connect 1163 Token Bound Authentication 1.0", October 2017, 1164 . 1167 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1168 Requirement Levels", BCP 14, RFC 2119, 1169 DOI 10.17487/RFC2119, March 1997, 1170 . 1172 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1173 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1174 . 1176 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1177 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1178 . 1180 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1181 Protocol (HTTP/1.1): Message Syntax and Routing", 1182 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1183 . 1185 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1186 (JWT) Profile for OAuth 2.0 Client Authentication and 1187 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1188 2015, . 1190 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1191 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1192 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1193 . 1195 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 1196 for Code Exchange by OAuth Public Clients", RFC 7636, 1197 DOI 10.17487/RFC7636, September 2015, 1198 . 1200 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1201 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1202 . 1204 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1205 Possession Key Semantics for JSON Web Tokens (JWTs)", 1206 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1207 . 1209 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1210 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1211 May 2017, . 1213 [SHS] National Institute of Standards and Technology, "Secure 1214 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 1215 . 1218 11.2. Informative References 1220 [BCP212] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 1221 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 1222 . 1224 [OpenID.Core] 1225 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1226 C. Mortimore, "OpenID Connect Core 1.0", August 2015, 1227 . 1229 [OpenID.Discovery] 1230 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 1231 Connect Discovery 1.0", August 2015, 1232 . 1235 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 1236 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 1237 . 1239 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1240 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1241 2015, . 1243 Appendix A. Acknowledgements 1245 The authors would like to thank the following people for their 1246 contributions to the specification: Dirk Balfanz, Andrei Popov, 1247 Justin Richer, and Nat Sakimura. 1249 Appendix B. Document History 1251 [[ to be removed by the RFC Editor before publication as an RFC ]] 1253 -07 1255 o Explicitly state that the base64url encoding of the tbh value 1256 doesn't include any trailing pad characters, line breaks, 1257 whitespace, etc. 1259 o Update to latest references for tokbind drafts and draft-ietf- 1260 oauth-discovery. 1262 o Update reference to Implementation Considerations in draft-ietf- 1263 tokbind-https, which is section 6 rather than 5. 1265 o Try to tweak text that references specific sections in other 1266 documents so that the HTML generated by the ietf tools doesn't 1267 link to the current document (based on old suggestion from Barry 1268 https://www.ietf.org/mail-archive/web/jose/current/msg04571.html). 1270 -06 1272 o Use the boilerplate from RFC 8174. 1274 o Update reference for draft-ietf-tokbind-https to -12 and draft- 1275 ietf-oauth-discovery to -09. 1277 o Minor editorial fixes. 1279 -05 1281 o State that authorization servers should not token bind refresh 1282 tokens issued to a client that doesn't support bound refresh 1283 tokens, which can be indicated by the 1284 "client_refresh_token_token_binding_supported" client metadata 1285 parameter. 1287 o Add Token Binding for JWT Authorization Grants and JWT Client 1288 Authentication. 1290 o Adjust the language around aborting authorizations in Phasing in 1291 Token Binding to be somewhat more general and not only about 1292 downgrades. 1294 o Remove reference to, and usage of, 'OAuth 2.0 Protected Resource 1295 Metadata', which is no longer a going concern. 1297 o Moved "Token Binding Metadata" section before "Token Binding for 1298 Authorization Codes" to be closer to the "Token Binding for Access 1299 Tokens" and "Token Binding for Refresh Tokens", to which it is 1300 more closely related. 1302 o Update references for draft-ietf-tokbind- negotiation(-10), 1303 protocol(-16), and https(-10), as well as draft-ietf-oauth- 1304 discovery(-07), and BCP212/RFC8252 OAuth 2.0 for Native Apps. 1306 -04 1308 o Define how to convey token binding information of an access token 1309 via RFC 7662 OAuth 2.0 Token Introspection (note that the 1310 Introspection Response Registration request for cnf/Confirmation 1311 is in https://tools.ietf.org/html/draft-ietf-oauth-mtls- 1312 02#section-4.3 which will likely be published and registered prior 1313 to this document). 1315 o Minor editorial fixes. 1317 o Added an open issue about needing to allow for web server clients 1318 to opt-out of having refresh tokens bound while still allowing for 1319 binding of access tokens (following from mention of the problem on 1320 slide 16 of the presentation from Chicago 1321 https://www.ietf.org/proceedings/98/slides/slides-98-oauth-sessb- 1322 token-binding-00.pdf). 1324 -03 1326 o Fix a few mistakes in and around the examples that were noticed 1327 preparing the slides for IETF 98 Chicago. 1329 -02 1331 o Added a section on Token Binding for authorization codes with one 1332 variation for native clients and one for web server clients. 1334 o Updated language to reflect that the binding is to the token 1335 binding key pair and that proof-of-possession of that key is done 1336 on the TLS connection. 1338 o Added a bunch of examples. 1340 o Added a few Open Issues so they are tracked in the document. 1342 o Updated the Token Binding and OAuth Metadata references. 1344 o Added William Denniss as an author. 1346 -01 1348 o Changed Token Binding for access tokens to use the Referred Token 1349 Binding ID, now that the Implementation Considerations in the 1350 Token Binding HTTPS specification make it clear that 1351 implementations will enable using the Referred Token Binding ID. 1353 o Defined Protected Resource Metadata value. 1355 o Changed to use the more specific term "protected resource" instead 1356 of "resource server". 1358 -00 1360 o Created the initial working group version from draft-jones-oauth- 1361 token-binding-00. 1363 Authors' Addresses 1365 Michael B. Jones 1366 Microsoft 1368 Email: mbj@microsoft.com 1369 URI: http://self-issued.info/ 1371 Brian Campbell 1372 Ping Identity 1374 Email: brian.d.campbell@gmail.com 1375 John Bradley 1376 Yubico 1378 Email: ve7jtb@ve7jtb.com 1379 URI: http://www.thread-safe.com/ 1381 William Denniss 1382 Google 1383 1600 Amphitheatre Pkwy 1384 Mountain View, CA 94043 1385 USA 1387 Email: wdenniss@google.com 1388 URI: http://wdenniss.com/