idnits 2.17.1 draft-ietf-oauth-token-binding-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- 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 (October 26, 2017) is 2373 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-10 == Outdated reference: A later version (-14) exists of draft-ietf-tokbind-negotiation-10 == Outdated reference: A later version (-19) exists of draft-ietf-tokbind-protocol-16 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' Summary: 1 error (**), 0 flaws (~~), 4 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: April 29, 2018 Ping Identity 6 J. Bradley 7 Yubico 8 W. Denniss 9 Google 10 October 26, 2017 12 OAuth 2.0 Token Binding 13 draft-ietf-oauth-token-binding-05 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 April 29, 2018. 43 Copyright Notice 45 Copyright (c) 2017 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 RFC 134 2119 [RFC2119]. 136 1.2. Terminology 138 This specification uses the terms "Access Token", "Authorization 139 Code", "Authorization Endpoint", "Authorization Server", "Client", 140 "Protected Resource", "Refresh Token", and "Token Endpoint" defined 141 by OAuth 2.0 [RFC6749], the terms "Claim" and "JSON Web Token (JWT)" 142 defined by JSON Web Token (JWT) [JWT], the term "User Agent" defined 143 by RFC 7230 [RFC7230], and the terms "Provided", "Referred", "Token 144 Binding" and "Token Binding ID" defined by Token Binding over HTTP 145 [I-D.ietf-tokbind-https]. 147 2. Token Binding for Refresh Tokens 149 Token Binding of refresh tokens is a straightforward first-party 150 scenario, applying term "first-party" as used in Token Binding over 151 HTTP [I-D.ietf-tokbind-https]. It cryptographically binds the 152 refresh token to the client's Token Binding key pair, possession of 153 which is proven on the TLS connections between the client and the 154 token endpoint. This case is straightforward because the refresh 155 token is both retrieved by the client from the token endpoint and 156 sent by the client to the token endpoint. Unlike the federated 157 scenarios described in Section 4 (Federation Use Cases) of Token 158 Binding over HTTP [I-D.ietf-tokbind-https] and the access token case 159 described in the next section, only a single TLS connection is 160 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 Section 4 (Federation Use Cases) of Token 285 Binding over HTTP [I-D.ietf-tokbind-https]. It also builds upon the 286 mechanisms for Token Binding of ID Tokens defined in OpenID Connect 287 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 Section 5 (Implementation 309 Considerations) of Token Binding over HTTP [I-D.ietf-tokbind-https]. 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 Section 4.2 of OAuth 2.0 327 [RFC6749], 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. 530 The following example demonstrates the JWT Claims Set of an access 531 token containing the base64url encoding of the SHA-256 hash of a 532 Token Binding ID as the value of the "tbh" (token binding hash) 533 element in the "cnf" (confirmation) claim: 535 { 536 "iss": "https://server.example.com", 537 "aud": "https://resource.example.org", 538 "sub": "brian@example.com" 539 "iat": 1467324320, 540 "exp": 1467324920, 541 "cnf":{ 542 "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" 543 } 544 } 546 Figure 12: JWT with Token Binding Hash Confirmation Claim 548 3.5. Representing Token Binding in Introspection Responses 550 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 551 protected resource to query an authorization server about the active 552 state of an access token as well as to determine meta-information 553 about the token. 555 For a token bound access token, the hash of the Token Binding ID to 556 which the token is bound is conveyed to the protected resource as 557 meta-information in a token introspection response. The hash is 558 conveyed using same structure as the token binding hash confirmation 559 method, described in Section 3.4, as a top-level member of the 560 introspection response JSON. The protected resource compares that 561 token binding hash to a hash of the provided Token Binding ID and 562 rejects the request, if they do not match. 564 The following is an example of an introspection response for an 565 active token bound access token with a "tbh" token binding hash 566 confirmation method. 568 HTTP/1.1 200 OK 569 Content-Type: application/json 571 { 572 "active": true, 573 "iss": "https://server.example.com", 574 "aud": "https://resource.example.org", 575 "sub": "brian@example.com" 576 "iat": 1467324320, 577 "exp": 1467324920, 578 "cnf":{ 579 "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" 580 } 581 } 583 Figure 13: Example Introspection Response for a Token Bound Access 584 Token 586 4. Token Binding Metadata 588 4.1. Token Binding Client Metadata 590 Clients supporting Token Binding that also support the OAuth 2.0 591 Dynamic Client Registration Protocol [RFC7591] use these metadata 592 values to declare their support for Token Binding of access tokens 593 and refresh tokens: 595 client_access_token_token_binding_supported 596 OPTIONAL. Boolean value specifying whether the client supports 597 Token Binding of access tokens. If omitted, the default value is 598 "false". 600 client_refresh_token_token_binding_supported 601 OPTIONAL. Boolean value specifying whether the client supports 602 Token Binding of refresh tokens. If omitted, the default value is 603 "false". Authorization servers MUST NOT Token Bind refresh tokens 604 issued to a client that does not support Token Binding of refresh 605 tokens, but MAY reject requests completely from such clients if 606 token binding is required by authorization server policy by 607 returning an OAuth error response. 609 4.2. Token Binding Authorization Server Metadata 611 Authorization servers supporting Token Binding that also support 612 OAuth 2.0 Authorization Server Metadata [OAuth.AuthorizationMetadata] 613 use these metadata values to declare their support for Token Binding 614 of access tokens and refresh tokens: 616 as_access_token_token_binding_supported 617 OPTIONAL. Boolean value specifying whether the authorization 618 server supports Token Binding of access tokens. If omitted, the 619 default value is "false". 621 as_refresh_token_token_binding_supported 622 OPTIONAL. Boolean value specifying whether the authorization 623 server supports Token Binding of refresh tokens. If omitted, the 624 default value is "false". 626 5. Token Binding for Authorization Codes 628 There are two variations for Token Binding of an authorization code. 629 One is appropriate for native application clients and the other for 630 web server clients. The nature of where the various components 631 reside for the different client types demands different methods of 632 Token Binding the authorization code so that it is bound to a Token 633 Binding key on the end user's device. This ensures that a lost or 634 stolen authorization code cannot be successfully utilized from a 635 different device. For native application clients, the code is bound 636 to a Token Binding key pair that the native client itself possesses. 637 For web server clients, the code is bound to a Token Binding key pair 638 on the end user's browser. Both variations utilize the extensible 639 framework of Proof Key for Code Exchange (PKCE) [RFC7636], which 640 enables the client to show possession of a certain key when 641 exchanging the authorization code for tokens. The following 642 subsections individually describe each of the two PKCE methods 643 respectively. 645 5.1. Native Application Clients 647 This section describes a PKCE method suitable for native application 648 clients that cryptographically binds the authorization code to a 649 Token Binding key pair on the client, which the client proves 650 possession of on the TLS connection during the access token request 651 containing the authorization code. The authorization code is bound 652 to the Token Binding ID that the native application client uses to 653 resolve the authorization code at the token endpoint. This binding 654 ensures that the client that made the authorization request is the 655 same client that is presenting the authorization code. 657 5.1.1. Code Challenge 659 As defined in Proof Key for Code Exchange [RFC7636], the client sends 660 the code challenge as part of the OAuth 2.0 authorization request 661 with the two additional parameters: "code_challenge" and 662 "code_challenge_method". 664 For this Token Binding method of PKCE, "TB-S256" is used as the value 665 of the "code_challenge_method" parameter. 667 The value of the "code_challenge" parameter is the base64url encoding 668 (per Section 5 of [RFC4648] with all trailing padding ('=') 669 characters omitted and without the inclusion of any line breaks or 670 whitespace) of the SHA-256 hash of the Provided Token Binding ID that 671 the client will use when calling the authorization server's token 672 endpoint. Note that, prior to making the authorization request, the 673 client may need to establish a TLS connection between itself and the 674 authorization server's token endpoint in order to establish the 675 appropriate Token Binding ID. 677 When the authorization server issues the authorization code in the 678 authorization response, it associates the code challenge and method 679 values with the authorization code so they can be verified later when 680 the authorization code is presented in the access token request. 682 5.1.1.1. Example Code Challenge 684 For example, a native application client sends an authorization 685 request by sending the user's browser to the authorization endpoint. 686 The resulting HTTP request looks something like the following (with 687 extra line breaks for display purposes only). 689 GET /as/authorization.oauth2?response_type=code 690 &client_id=example-native-client-id&state=oUC2jyYtzRCrMyWrVnGj 691 &code_challenge=rBlgOyMY4teiuJMDgOwkrpsAjPyI07D2WsEM-dnq6eE 692 &code_challenge_method=TB-S256 HTTP/1.1 693 Host: server.example.com 695 Figure 14: Authorization Request with PKCE Challenge 697 5.1.2. Code Verifier 699 Upon receipt of the authorization code, the client sends the access 700 token request to the token endpoint. The Token Binding Protocol 701 [I-D.ietf-tokbind-protocol] is negotiated on the TLS connection 702 between the client and the authorization server and the "Sec-Token- 703 Binding" header, as defined in Token Binding over HTTP 704 [I-D.ietf-tokbind-https], is included in the access token request. 705 The authorization server extracts the Provided Token Binding ID from 706 the header value, hashes it with SHA-256, and compares it to the 707 "code_challenge" value previously associated with the authorization 708 code. If the values match, the token endpoint continues processing 709 as normal (as defined by OAuth 2.0 [RFC6749]). If the values do not 710 match, an error response indicating "invalid_grant" MUST be returned. 712 The "Sec-Token-Binding" header contains sufficient information for 713 verification of the authorization code and its association to the 714 original authorization request. However, PKCE [RFC7636] requires 715 that a "code_verifier" parameter be sent with the access token 716 request, so the static value "provided_tb" is used to meet that 717 requirement and indicate that the Provided Token Binding ID is used 718 for the verification. 720 5.1.2.1. Example Code Verifier 722 An example access token request, correlating to the authorization 723 request in the previous example, to the token endpoint over a TLS 724 connection for which Token Binding has been negotiated would look 725 like the following (with extra line breaks for display purposes 726 only). The base64url-encoded EKM from the TLS connection over which 727 the request was made is 728 "pNVKtPuQFvylNYn000QowWrQKoeMkeX9H32hVuU71Bs". 730 POST /as/token.oauth2 HTTP/1.1 731 Host: server.example.com 732 Content-Type: application/x-www-form-urlencoded 733 Sec-Token-Binding: AIkAAgBBQEOO9GRFP-LM0hoWw6-2i318BsuuUum5AL8bt1sz 734 lr1EFfp5DMXMNW3O8WjcIXr2DKJnI4xnuGsE6GywQd9RbD0AQJDb3xyo9PBxj8M6Y 735 jLt-6OaxgDkyoBoTkyrnNbLc8tJQ0JtXomKzBbj5qPtHDduXc6xz_lzvNpxSPxi42 736 8m7wkAAA 738 grant_type=authorization_code&code=mJAReTWKX7zI3oHUNd4o3PeNqNqxKGp6 739 &code_verifier=provided_tb&client_id=example-native-client-id 741 Figure 15: Token Request with PKCE Verifier 743 5.2. Web Server Clients 745 This section describes a PKCE method suitable for web server clients, 746 which cryptographically binds the authorization code to a Token 747 Binding key pair on the browser. The authorization code is bound to 748 the Token Binding ID that the browser uses to deliver the 749 authorization code to a web server client, which is sent to the 750 authorization server as the Referred Token Binding ID during the 751 authorization request. The web server client conveys the Token 752 Binding ID to the authorization server when making the access token 753 request containing the authorization code. This binding ensures that 754 the authorization code cannot successfully be played or replayed to 755 the web server client from a different browser than the one that made 756 the authorization request. 758 5.2.1. Code Challenge 760 As defined in Proof Key for Code Exchange [RFC7636], the client sends 761 the code challenge as part of the OAuth 2.0 Authorization Request 762 with the two additional parameters: "code_challenge" and 763 "code_challenge_method". 765 The client must send the authorization request through the browser 766 such that the Token Binding ID established between the browser and 767 itself is revealed to the authorization server's authorization 768 endpoint as the Referred Token Binding ID. Typically, this is done 769 with an HTTP redirection response and the "Include-Referred-Token- 770 Binding-ID" header, as defined in Section 5.3 of Token Binding over 771 HTTP [I-D.ietf-tokbind-https]. 773 For this Token Binding method of PKCE, "referred_tb" is used for the 774 value of the "code_challenge_method" parameter. 776 The value of the "code_challenge" parameter is "referred_tb". The 777 static value for the required PKCE parameter indicates that the 778 authorization code is to be bound to the Referred Token Binding ID 779 from the Token Binding Message sent in the "Sec-Token-Binding" header 780 of the authorization request. 782 When the authorization server issues the authorization code in the 783 authorization response, it associates the Token Binding ID (or hash 784 thereof) and code challenge method with the authorization code so 785 they can be verified later when the authorization code is presented 786 in the access token request. 788 5.2.1.1. Example Code Challenge 790 For example, the web server client sends the authorization request by 791 redirecting the browser to the authorization endpoint. That HTTP 792 redirection response looks like the following (with extra line breaks 793 for display purposes only). 795 HTTP/1.1 302 Found 796 Location: https://server.example.com?response_type=code 797 &client_id=example-web-client-id&state=P4FUFqYzs1ij3ffsYCP34d3 798 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 799 &code_challenge=referred_tb&code_challenge_method=referred_tb 800 Include-Referred-Token-Binding-ID: true 802 Figure 16: Redirect the Browser 804 The redirect includes the "Include-Referred-Token-Binding-ID" 805 response header field that signals to the user-agent that it should 806 reveal, to the authorization server, the Token Binding ID used on the 807 connection to the web server client. The resulting HTTP request to 808 the authorization server looks something like the following (with 809 extra line breaks for display purposes only). The base64url-encoded 810 EKM from the TLS connection over which the request was made is 811 "7gOdRzMhPeO-1YwZGmnVHyReN5vd2CxcsRBN69Ue4cI". 813 GET /as/authorization.oauth2?response_type=code 814 &client_id=example-web-client-id&state=dryo8YFpWacbUPjhBf4Nvt51 815 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 816 &code_challenge=referred_tb 817 &code_challenge_method=referred_tb HTTP/1.1 818 Host: server.example.com 819 Sec-Token-Binding: ARIAAgBBQB-XOPf5ePlf7ikATiAFEGOS503lPmRfkyymzdWw 820 HCxl0njjxC3D0E_OVfBNqrIQxzIfkF7tWby2ZfyaE6XpwTsAQBYqhFX78vMOgDX_F 821 d_b2dlHyHlMmkIz8iMVBY_reM98OUaJFz5IB7PG9nZ11j58LoG5QhmQoI9NXYktKZ 822 RXxrYAAAECAEFAdUFTnfQADkn1uDbQnvJEk6oQs38L92gv-KO-qlYadLoDIKe2h53 823 hSiKwIP98iRj_unedkNkAMyg9e2mY4Gp7WwBAeDUOwaSXNz1e6gKohwN4SAZ5eNyx 824 45Mh8VI4woL1BipLoqrJRoK6dxFkWgHRMuBROcLGUj5PiOoxybQH_Tom3gAA 826 Figure 17: Authorization Request 828 5.2.2. Code Verifier 830 The web server client receives the authorization code from the 831 browser and extracts the Provided Token Binding ID from the "Sec- 832 Token-Binding" header of the request. The client sends the 833 base64url-encoded (per Section 5 of [RFC4648] with all trailing 834 padding ('=') characters omitted and without the inclusion of any 835 line breaks or whitespace) Provided Token Binding ID as the value of 836 the "code_verifier" parameter in the access token request to the 837 authorization server's token endpoint. The authorization server 838 compares the value of the "code_verifier" parameter to the Token 839 Binding ID value previously associated with the authorization code. 840 If the values match, the token endpoint continues processing as 841 normal (as defined by OAuth 2.0 [RFC6749]). If the values do not 842 match, an error response indicating "invalid_grant" MUST be returned. 844 5.2.2.1. Example Code Verifier 846 Continuing the example from the previous section, the authorization 847 server sends the code to the web server client by redirecting the 848 browser to the client's "redirect_uri", which results in the browser 849 making a request like the following (with extra line breaks for 850 display purposes only) to the web server client over a TLS channel 851 for which Token Binding has been established. The base64url-encoded 852 EKM from the TLS connection over which the request was made is 853 "EzW60vyINbsb_tajt8ij3tV6cwy2KH-i8BdEMYXcNn0". 855 GET /cb?state=dryo8YFpWacbUPjhBf4Nvt51&code=jwD3oOa5cQvvLc81bwc4CMw 856 Host: client.example.org 857 Sec-Token-Binding: AIkAAgBBQHVBU530AA5J9bg20J7yRJOqELN_C_doL_ijvqpW 858 GnS6AyCntoed4UoisCD_fIkY_7p3nZDZADMoPXtpmOBqe1sAQEwgC9Zpg7QFCDBib 859 6GlZki3MhH32KNfLefLJc1vR1xE8l7OMfPLZHP2Woxh6rEtmgBcAABubEbTz7muNl 860 Ln8uoAAA 862 Figure 18: Authorization Response to Web Server Client 864 The web server client takes the Provided Token Binding ID from the 865 above request from the browser and sends it, base64url encoded, to 866 the authorization server in the "code_verifier" parameter of the 867 authorization code grant type request. Extra line breaks in the 868 example request are for display purposes only. 870 POST /as/token.oauth2 HTTP/1.1 871 Host: server.example.com 872 Content-Type: application/x-www-form-urlencoded 873 Authorization: Basic b3JnLmV4YW1wbGUuY2xpZW50OmlldGY5OGNoaWNhZ28= 875 grant_type=authorization_code&code=jwD3oOa5cQvvLc81bwc4CMw 876 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb 877 &client_id=example-web-client-id 878 &code_verifier=AgBBQHVBU530AA5J9bg20J7yRJOqELN_C_doL_ijv 879 qpWGnS6AyCntoed4UoisCD_fIkY_7p3nZDZADMoPXtpmOBqe1s 881 Figure 19: Exchange Authorization Code 883 6. Token Binding JWT Authorization Grants and Client Authentication 885 The JWT Profile for OAuth 2.0 Client Authentication and Authorization 886 Grants [RFC7523] defines the use of bearer JWTs as a means for 887 requesting an OAuth 2.0 access token as well as for client 888 authentication. This section describes extensions to that 889 specification enabling the application of Token Binding to JWT client 890 authentication and JWT authorization grants. 892 6.1. JWT Format and Processing Requirements 894 In addition the requirements set forth in Section 3 of RFC 7523 895 [RFC7523], the following criteria must also be met for token bound 896 JWTs used as authorization grants or for client authentication. 898 o The JWT MUST contain a "cnf" (confirmation) claim with a "tbh" 899 (token binding hash) member identifying the Token Binding ID of 900 the Provided Token Binding used by the client on the TLS 901 connection to the authorization server. The authorization server 902 MUST reject any JWT that has a token binding hash confirmation 903 that does not match the corresponding hash of the Provided Token 904 Binding ID from the "Sec-Token-Binding" header of the request. 906 6.2. Token Bound JWTs for Client Authentication 908 To use a token bound JWT for client authentication, the client uses 909 the parameter values and encodings from Section 2.2 of RFC 7523 910 [RFC7523] with one exception: the value of the 911 "client_assertion_type" is "urn:ietf:params:oauth:client-assertion- 912 type:jwt-token-bound". 914 The "OAuth Token Endpoint Authentication Methods" registry 915 [IANA.OAuth.Parameters] contains values, each of which specify a 916 method of authenticating a client to the authorization server. The 917 values are used to indicated supported and utilized client 918 authentication methods in authorization server metadata, such as 919 [OpenID.Discovery] and [OAuth.AuthorizationMetadata], and in OAuth 920 2.0 Dynamic Client Registration Protocol [RFC7591]. The values 921 "private_key_jwt" and "client_secret_jwt" are designated by OpenID 922 Connect [OpenID.Core] as authentication method values for bearer JWT 923 client authentication using asymmetric and symmetric JWS [RFC7515] 924 algorithms respectively. For Token Bound JWT for client 925 authentication, this specification defines and registers the 926 following authentication method values. 928 private_key_token_bound_jwt 929 Indicates that client authentication to the authorization server 930 will occur with a Token Bound JWT, which is signed with a client's 931 private key. 933 client_secret_token_bound_jwt 934 Indicates that client authentication to the authorization server 935 will occur with a Token Bound JWT, which is integrity protected 936 with a MAC using the octets of the UTF-8 representation of the 937 client secret as the shared key. 939 Note that just as with the "private_key_jwt" and "client_secret_jwt" 940 authentication methods, the "token_endpoint_auth_signing_alg" client 941 registration parameter may be used to indicate the JWS algorithm used 942 for signing the client authentication JWT for the authentication 943 methods defined above. 945 6.3. Token Bound JWTs for as Authorization Grants 947 To use a token bound JWT for an authorization grant, the client uses 948 the parameter values and encodings from Section 2.1 of RFC 7523 949 [RFC7523] with one exception: the value of the "grant_type" is 950 "urn:ietf:params:oauth:grant-type:jwt-token-bound". 952 7. Security Considerations 954 7.1. Phasing in Token Binding 956 Many OAuth implementations will be deployed in situations in which 957 not all participants support Token Binding. Any of combination of 958 the client, the authorization server, the protected resource, and the 959 user agent may not yet support Token Binding, in which case it will 960 not work end-to-end. 962 It is a context-dependent deployment choice whether to allow 963 interactions to proceed in which Token Binding is not supported or 964 whether to treat the omission of Token Binding at any step as a fatal 965 error. Particularly in dynamic deployment environments in which End 966 Users have choices of clients, authorization servers, protected 967 resources, and/or user agents, it is recommended that, for some 968 reasonable period of time during which Token Binding technology is 969 being adopted, authorizations using one or more components that do 970 not implement Token Binding be allowed to successfully proceed. This 971 enables different components to be upgraded to supporting Token 972 Binding at different times, providing a smooth transition path for 973 phasing in Token Binding. However, when Token Binding has been 974 performed, any Token Binding key mismatches MUST be treated as fatal 975 errors. 977 In more controlled deployment environments where the participants in 978 an authorization interaction are known or expected to support Token 979 Binding and yet one or more of them does not use it, the 980 authorization SHOULD be aborted with an error. For instance, an 981 authorization server should reject a token request that does not 982 include the "Sec-Token-Binding" header, if the request is from a 983 client known to support Token Binding (via configuration or the 984 "client_access_token_token_binding_supported" metadata parameter). 986 7.2. Binding of Refresh Tokens 988 Section 6 of RFC 6749 [RFC6749] requires that a refresh token be 989 bound to the client to which it was issued and that, if the client 990 type is confidential or the client was issued client credentials (or 991 assigned other authentication requirements), the client must 992 authenticate with the authorization server when presenting the 993 refresh token. As a result, for non-public clients, refresh tokens 994 are indirectly bound to the client's credentials and cannot be used 995 without the associated client authentication. Non-public clients 996 then are afforded protections (equivalent to the strength of their 997 authentication credentials) against unauthorized replay of refresh 998 tokens and it is reasonable to not Token Bind refresh tokens for such 999 clients while still Toking Binding the issued access tokens. Refresh 1000 tokens issued to public clients, however, do not have the benefit of 1001 such protections and authorization servers MAY elect to disallow 1002 public clients from registering or establishing configuration that 1003 would allow Token Bound access tokens but unbound refresh tokens. 1005 Some web-based confidential clients implemented as distributed nodes 1006 may be perfectly capable of implementing access token binding (if the 1007 access token remains on the node it was bound to, the token binding 1008 keys would be locally available for that node to prove possession), 1009 but may struggle with refresh token binding due to an inability to 1010 share token binding key material between nodes. As confidential 1011 clients already have credentials which are required to use the 1012 refresh token, and those credentials should only ever be sent over 1013 TLS server-to-server between the client and the Token Endpoint, there 1014 is still value in token binding access tokens without token binding 1015 refresh tokens. Authorization servers SHOULD consider supporting 1016 access token binding without refresh token binding for confidential 1017 web clients as there are still security benefits to do so. 1019 Clients MUST declare through dynamic (Section 4.1) or static 1020 registration information what types of token bound tokens they 1021 support to enable the server to bind tokens accordingly, taking into 1022 account any phase-in policies. Authorization MAY reject requests 1023 from any client who does not support token binding (by returning an 1024 OAuth error response) per their own security policies. 1026 8. IANA Considerations 1028 8.1. OAuth Dynamic Client Registration Metadata Registration 1030 This specification registers the following client metadata 1031 definitions in the IANA "OAuth Dynamic Client Registration Metadata" 1032 registry [IANA.OAuth.Parameters] established by [RFC7591]: 1034 8.1.1. Registry Contents 1036 o Client Metadata Name: 1037 "client_access_token_token_binding_supported" 1038 o Client Metadata Description: Boolean value specifying whether the 1039 client supports Token Binding of access tokens 1040 o Change Controller: IESG 1041 o Specification Document(s): Section 4.1 of [[ this specification ]] 1043 o Client Metadata Name: 1044 "client_refresh_token_token_binding_supported" 1045 o Client Metadata Description: Boolean value specifying whether the 1046 client supports Token Binding of refresh tokens 1047 o Change Controller: IESG 1048 o Specification Document(s): Section 4.1 of [[ this specification ]] 1050 8.2. OAuth Authorization Server Metadata Registration 1052 This specification registers the following metadata definitions in 1053 the IANA "OAuth Authorization Server Metadata" registry established 1054 by [OAuth.AuthorizationMetadata]: 1056 8.2.1. Registry Contents 1058 o Metadata Name: "as_access_token_token_binding_supported" 1059 o Metadata Description: Boolean value specifying whether the 1060 authorization server supports Token Binding of access tokens 1061 o Change Controller: IESG 1062 o Specification Document(s): Section 4.2 of [[ this specification ]] 1064 o Metadata Name: "as_refresh_token_token_binding_supported" 1065 o Metadata Description: Boolean value specifying whether the 1066 authorization server supports Token Binding of refresh tokens 1067 o Change Controller: IESG 1068 o Specification Document(s): Section 4.2 of [[ this specification ]] 1070 8.3. PKCE Code Challenge Method Registration 1072 This specification requests registration of the following Code 1073 Challenge Method Parameter Names in the IANA "PKCE Code Challenge 1074 Methods" registry [IANA.OAuth.Parameters] established by [RFC7636]. 1076 8.3.1. Registry Contents 1078 o Code Challenge Method Parameter Name: TB-S256 1079 o Change controller: IESG 1080 o Specification document(s): Section 5.1.1 of [[ this specification 1081 ]] 1083 o Code Challenge Method Parameter Name: referred_tb 1084 o Change controller: IESG 1085 o Specification document(s): Section 5.2.1 of [[ this specification 1086 ]] 1088 9. Token Endpoint Authentication Method Registration 1090 This specification requests registration of the following values in 1091 the IANA "OAuth Token Endpoint Authentication Methods" registry 1092 [IANA.OAuth.Parameters] established by [RFC7591]. 1094 9.1. Registry Contents 1096 o Token Endpoint Authentication Method Name: 1097 "client_secret_token_bound_jwt" 1098 o Change Controller: IESG 1099 o Specification Document(s): Section 6 of [[ this specification ]] 1101 o Token Endpoint Authentication Method Name: 1102 "private_key_token_bound_jwt" 1103 o Change Controller: IESG 1104 o Specification Document(s): Section 6 of [[ this specification ]] 1106 10. Sub-Namespace Registrations 1108 This specification requests registration of the following values in 1109 the IANA "OAuth URI" registry [IANA.OAuth.Parameters] established in 1110 An IETF URN Sub-Namespace for OAuth [RFC6755]. 1112 10.1. Registry Contents 1114 o URN: urn:ietf:params:oauth:grant-type:jwt-token-bound 1115 o Common Name: Token Bound JWT Grant Type for OAuth 2.0 1116 o Change controller: IESG 1117 o Specification Document: Section 6 of [[ this specification ]] 1119 o URN: urn:ietf:params:oauth:client-assertion-type:jwt-token-bound 1120 o Common Name: Token Bound JWT for OAuth 2.0 Client Authentication 1121 o Change controller: IESG 1122 o Specification Document: Section 6 of [[ this specification ]] 1124 11. References 1126 11.1. Normative References 1128 [I-D.ietf-tokbind-https] 1129 Popov, A., Nystrom, M., Balfanz, D., Langley, A., Harper, 1130 N., and J. Hodges, "Token Binding over HTTP", draft-ietf- 1131 tokbind-https-10 (work in progress), July 2017. 1133 [I-D.ietf-tokbind-negotiation] 1134 Popov, A., Nystrom, M., Balfanz, D., and A. Langley, 1135 "Transport Layer Security (TLS) Extension for Token 1136 Binding Protocol Negotiation", draft-ietf-tokbind- 1137 negotiation-10 (work in progress), October 2017. 1139 [I-D.ietf-tokbind-protocol] 1140 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 1141 Hodges, "The Token Binding Protocol Version 1.0", draft- 1142 ietf-tokbind-protocol-16 (work in progress), October 2017. 1144 [IANA.OAuth.Parameters] 1145 IANA, "OAuth Parameters", 1146 . 1148 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1149 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1150 . 1152 [OAuth.AuthorizationMetadata] 1153 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1154 Authorization Server Metadata", draft-ietf-oauth- 1155 discovery-07 (work in progress), March 2017, 1156 . 1159 [OpenID.TokenBinding] 1160 Jones, M., Bradley, J., and B. Campbell, "OpenID Connect 1161 Token Bound Authentication 1.0", October 2017, 1162 . 1165 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1166 Requirement Levels", BCP 14, RFC 2119, 1167 DOI 10.17487/RFC2119, March 1997, 1168 . 1170 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1171 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1172 . 1174 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1175 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1176 . 1178 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1179 Protocol (HTTP/1.1): Message Syntax and Routing", 1180 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1181 . 1183 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1184 (JWT) Profile for OAuth 2.0 Client Authentication and 1185 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 1186 2015, . 1188 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1189 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1190 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1191 . 1193 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 1194 for Code Exchange by OAuth Public Clients", RFC 7636, 1195 DOI 10.17487/RFC7636, September 2015, 1196 . 1198 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1199 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1200 . 1202 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1203 Possession Key Semantics for JSON Web Tokens (JWTs)", 1204 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1205 . 1207 [SHS] National Institute of Standards and Technology, "Secure 1208 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 1209 . 1212 11.2. Informative References 1214 [BCP212] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 1215 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 1216 . 1218 [OpenID.Core] 1219 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1220 C. Mortimore, "OpenID Connect Core 1.0", August 2015, 1221 . 1223 [OpenID.Discovery] 1224 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 1225 Connect Discovery 1.0", August 2015, 1226 . 1229 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 1230 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 1231 . 1233 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1234 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1235 2015, . 1237 Appendix A. Acknowledgements 1239 The authors would like to thank the following people for their 1240 contributions to the specification: Dirk Balfanz, Andrei Popov, 1241 Justin Richer, and Nat Sakimura. 1243 Appendix B. Document History 1245 [[ to be removed by the RFC Editor before publication as an RFC ]] 1247 -05 1249 o State that authorization servers should not token bind refresh 1250 tokens issued to a client that doesn't support bound refresh 1251 tokens, which can be indicated by the 1252 "client_refresh_token_token_binding_supported" client metadata 1253 parameter. 1255 o Add Token Binding for JWT Authorization Grants and JWT Client 1256 Authentication. 1258 o Adjust the language around aborting authorizations in Phasing in 1259 Token Binding to be somewhat more general and not only about 1260 downgrades. 1262 o Remove reference to, and usage of, 'OAuth 2.0 Protected Resource 1263 Metadata', which is no longer a going concern. 1265 o Moved "Token Binding Metadata" section before "Token Binding for 1266 Authorization Codes" to be closer to the "Token Binding for Access 1267 Tokens" and "Token Binding for Refresh Tokens", to which it is 1268 more closely related. 1270 o Update references for draft-ietf-tokbind- negotiation(-10), 1271 protocol(-16), and https(-10), as well as draft-ietf-oauth- 1272 discovery(-07), and BCP212/RFC8252 OAuth 2.0 for Native Apps. 1274 -04 1276 o Define how to convey token binding information of an access token 1277 via RFC 7662 OAuth 2.0 Token Introspection (note that the 1278 Introspection Response Registration request for cnf/Confirmation 1279 is in https://tools.ietf.org/html/draft-ietf-oauth-mtls- 1280 02#section-4.3 which will likely be published and registered prior 1281 to this document). 1283 o Minor editorial fixes. 1285 o Added an open issue about needing to allow for web server clients 1286 to opt-out of having refresh tokens bound while still allowing for 1287 binding of access tokens (following from mention of the problem on 1288 slide 16 of the presentation from Chicago 1289 https://www.ietf.org/proceedings/98/slides/slides-98-oauth-sessb- 1290 token-binding-00.pdf). 1292 -03 1294 o Fix a few mistakes in and around the examples that were noticed 1295 preparing the slides for IETF 98 Chicago. 1297 -02 1299 o Added a section on Token Binding for authorization codes with one 1300 variation for native clients and one for web server clients. 1302 o Updated language to reflect that the binding is to the token 1303 binding key pair and that proof-of-possession of that key is done 1304 on the TLS connection. 1306 o Added a bunch of examples. 1308 o Added a few Open Issues so they are tracked in the document. 1310 o Updated the Token Binding and OAuth Metadata references. 1312 o Added William Denniss as an author. 1314 -01 1316 o Changed Token Binding for access tokens to use the Referred Token 1317 Binding ID, now that the Implementation Considerations in the 1318 Token Binding HTTPS specification make it clear that 1319 implementations will enable using the Referred Token Binding ID. 1321 o Defined Protected Resource Metadata value. 1323 o Changed to use the more specific term "protected resource" instead 1324 of "resource server". 1326 -00 1328 o Created the initial working group version from draft-jones-oauth- 1329 token-binding-00. 1331 Authors' Addresses 1333 Michael B. Jones 1334 Microsoft 1336 Email: mbj@microsoft.com 1337 URI: http://self-issued.info/ 1339 Brian Campbell 1340 Ping Identity 1342 Email: brian.d.campbell@gmail.com 1344 John Bradley 1345 Yubico 1347 Email: ve7jtb@ve7jtb.com 1348 URI: http://www.thread-safe.com/ 1350 William Denniss 1351 Google 1352 1600 Amphitheatre Pkwy 1353 Mountain View, CA 94043 1354 USA 1356 Email: wdenniss@google.com 1357 URI: http://wdenniss.com/