idnits 2.17.1 draft-ietf-oauth-token-binding-00.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 (September 7, 2016) is 2789 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-06 == Outdated reference: A later version (-19) exists of draft-ietf-tokbind-protocol-10 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Bradley 5 Expires: March 11, 2017 B. Campbell 6 Ping Identity 7 September 7, 2016 9 OAuth 2.0 Token Binding 10 draft-ietf-oauth-token-binding-00 12 Abstract 14 This specification enables OAuth 2.0 implementations to apply Token 15 Binding to Access Tokens and Refresh Tokens. This cryptographically 16 binds these tokens to the TLS connections over which they are 17 intended to be used. This use of Token Binding protects these tokens 18 from man-in-the-middle and token export and replay attacks. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on March 11, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Token Binding for Refresh Tokens . . . . . . . . . . . . . . 3 58 3. Token Binding for Access Tokens . . . . . . . . . . . . . . . 4 59 3.1. Initial Access Tokens . . . . . . . . . . . . . . . . . . 5 60 3.2. Refreshed Access Tokens . . . . . . . . . . . . . . . . . 5 61 3.3. Resource Server Token Binding Validation . . . . . . . . 5 62 3.4. Representing Token Binding in JWT Access Tokens . . . . . 5 63 4. Phasing in Token Binding and Preventing Downgrade Attacks . . 6 64 5. Token Binding Metadata . . . . . . . . . . . . . . . . . . . 7 65 5.1. Token Binding Client Metadata . . . . . . . . . . . . . . 7 66 5.2. Token Binding Authorization Server Metadata . . . . . . . 7 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 69 7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 8 70 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 71 7.2. OAuth Dynamic Client Registration Metadata Registration . 8 72 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 73 7.3. OAuth Authorization Server Discovery Metadata 74 Registration . . . . . . . . . . . . . . . . . . . . . . 8 75 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 9 76 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 78 8.2. Informative References . . . . . . . . . . . . . . . . . 10 79 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 80 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 11 81 Appendix C. Document History . . . . . . . . . . . . . . . . . . 11 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 84 1. Introduction 86 This specification enables OAuth 2.0 [RFC6749] implementations to 87 apply Token Binding The Token Binding Protocol Version 1.0 88 [I-D.ietf-tokbind-protocol] Token Binding over HTTP 89 [I-D.ietf-tokbind-https] to Access Tokens and Refresh Tokens. This 90 cryptographically binds these tokens to the TLS connections over 91 which they are intended to be used. This use of Token Binding 92 protects these tokens from man-in-the-middle and token export and 93 replay attacks. 95 1.1. Requirements Notation and Conventions 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 99 "OPTIONAL" in this document are to be interpreted as described in RFC 100 2119 [RFC2119]. 102 1.2. Terminology 104 This specification uses the terms "Access Token", "Authorization 105 Code", "Authorization Endpoint", "Authorization Grant", 106 "Authorization Server", "Client", "Client Authentication", "Client 107 Identifier", "Client Secret", "Grant Type", "Protected Resource", 108 "Redirection URI", "Refresh Token", "Resource Owner", "Resource 109 Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0 110 [RFC6749], the terms "Claim", "Claim Name", "Claim Value", and "JSON 111 Web Token (JWT)" defined by JSON Web Token (JWT) [JWT], the term 112 "User Agent" defined by RFC 7230 [RFC7230], and the terms "Provided", 113 "Referred", "Token Binding" and "Token Binding ID" defined by Token 114 Binding over HTTP [I-D.ietf-tokbind-https]. 116 2. Token Binding for Refresh Tokens 118 Token Binding of refresh tokens is a straightforward first-party 119 scenario, applying term "first-party" as used in Token Binding over 120 HTTP [I-D.ietf-tokbind-https]. It cryptographically binds the 121 refresh token to the TLS connection between the client and the token 122 endpoint. This case is straightforward because the refresh token is 123 both retrieved by the client from the token endpoint and sent by the 124 client to the token endpoint. Unlike the federated scenarios 125 described in Section 3 (Federation Use Cases) of Token Binding over 126 HTTP [I-D.ietf-tokbind-https] and the access token case described in 127 the next section, only a single TLS connection is involved in the 128 refresh token case. 130 Token Binding a refresh token requires that the authorization server 131 do two things. First, when refresh token is sent to the client, the 132 authorization server needs to remember the Provided Token Binding ID 133 and remember its association with the issued refresh token. Second, 134 when a token request containing a refresh token is received at the 135 token endpoint, the authorization server needs to verify that the 136 Provided Token Binding ID for the request matches the remembered 137 Token Binding ID associated with the refresh token. If the Token 138 Binding IDs do not match, the authorization server should return an 139 error in response to the request. 141 The means by which the authorization server remembers the association 142 between the refresh token and the Token Binding ID is an 143 implementation detail that beyond the scope of this specification. 144 Some authorization servers will choose to store the Token Binding ID 145 (or a cryptographic hash of it, such a SHA-256 hash [SHS]) in the 146 refresh token itself, thus reducing the amount of state to be kept by 147 the server. Other authorization servers will add the Token Binding 148 ID value (or a hash of it) to an internal data structure also 149 containing other information about the refresh token, such as grant 150 type information. These choices make no difference to the client, 151 since the refresh token is opaque to it. 153 3. Token Binding for Access Tokens 155 Token Binding for access tokens cryptographically binds the access 156 token to the TLS connection between the client and the resource 157 server. Token Binding is applied to access tokens in a similar 158 manner to that described in Section 3 (Federation Use Cases) of Token 159 Binding over HTTP [I-D.ietf-tokbind-https]. It is also builds upon 160 the mechanisms for Token Binding of ID Tokens defined in OpenID 161 Connect Token Bound Authentication 1.0 [OpenID.TokenBinding]. 163 In the OpenID Connect [OpenID.Core] use case, HTTP redirects are used 164 to pass information between the identity provider and the relying 165 party; this HTTP redirect makes the Token Binding ID of the relying 166 party available to the identity provider as the Referred Token 167 Binding ID, information about which is then added to the ID Token. 168 No such redirect occurs between the authorization server and the 169 resource server in the access token case; therefore, information 170 about the Token Binding ID for the TLS connection between the client 171 and the resource server needs to be explicitly communicated by the 172 client to the authorization server to achieve Token Binding of the 173 access token. This information is passed to the authorization server 174 using this request parameter: 176 resource_tbh 177 Base64url encoding of the SHA-256 hash [SHS] of the Token Binding 178 ID for the TLS connection between the client and the resource 179 server. 181 Note that to obtain this Token Binding ID, the client needs to 182 establish a TLS connection between itself and the resource server 183 prior to making the authorization request so that the Provided Token 184 Binding ID for the TLS connection to the resource server can be 185 obtained. The means by which the client retrieves this Token Binding 186 ID from the underlying Token Binding API is implementation and 187 operating system specific. An alternative, if supported, is for the 188 client to generate a Token Binding key to use for the resource 189 server, use the Token Binding ID for that key, and then later use 190 that key when the TLS connection to the resource server is 191 established. 193 The authorization server MUST ignore the "resource_tbh" parameter if 194 it does not support Token Binding for the access token. 196 3.1. Initial Access Tokens 198 Upon receiving the hash of the Token Binding ID in an authorization 199 request containing the "resource_tbh" (resource token binding hash) 200 authorization request parameter, the authorization server then 201 records it in the issued access token. Alternatively, in some 202 implementations, the resource's Token Binding ID hash might be 203 communicated to the resource server by other means, such as by 204 introspecting [RFC7662] the access token. 206 3.2. Refreshed Access Tokens 208 Access tokens obtained from refresh requests can also be token bound. 209 In this case, the hash of the Token Binding ID of the TLS connection 210 between the client and the resource server is sent to the 211 authorization server at the token endpoint using the "resource_tbh" 212 (resource token binding hash) token request parameter; its syntax is 213 exactly the same as the corresponding authorization request 214 parameter. The authorization server then records it in the issued 215 access token or communicates it to the resource server by other 216 means, just as in the previous case. 218 3.3. Resource Server Token Binding Validation 220 Upon receiving a token bound access token, the resource server 221 validates the binding by computing a SHA-256 hash of the Provided 222 Token Binding ID and comparing it to the token binding hash value for 223 the access token. If these values do not match, the resource access 224 attempt MUST be rejected with an error. 226 3.4. Representing Token Binding in JWT Access Tokens 228 If the access token is represented as a JWT, the token binding 229 information SHOULD be represented in the same way that it is in token 230 bound OpenID Connect ID Tokens [OpenID.TokenBinding]. That 231 specification defines the new JWT Confirmation Method RFC 7800 232 [RFC7800] member "tbh" (token binding hash) to represent the SHA-256 233 hash of a Token Binding ID in an ID Token. The value of the "tbh" 234 member is the base64url encoding of the SHA-256 hash of the Token 235 Binding ID. 237 The following example demonstrates the JWT Claims Set of an access 238 token containing the base64url encoding of the SHA-256 hash of a 239 Token Binding ID as the value of the "tbh" (token binding hash) 240 element in the "cnf" (confirmation) claim: 242 { 243 "iss": "https://server.example.com", 244 "aud": "https://resource.example.com", 245 "iat": 1467324320, 246 "exp": 1467324920, 247 "cnf":{ 248 "tbh": "n0jI3trBK6_Gp2qiLOf48ZEZTjpBnhm-QOyzJxhBeAk" 249 } 250 } 252 4. Phasing in Token Binding and Preventing Downgrade Attacks 254 Many OAuth implementations will be deployed in situations in which 255 not all participants support Token Binding. Any of combination of 256 the client, the authorization server, the resource server, and the 257 User Agent may not yet support Token Binding, in which case it will 258 not work end-to-end. 260 It is a context-dependent deployment choice whether to allow 261 interactions to proceed in which Token Binding is not supported or 262 whether to treat Token Binding failures at any step as fatal errors. 263 Particularly in dynamic deployment environments in which End Users 264 have choices of clients, authorization servers, resource servers, 265 and/or User Agents, it is RECOMMENDED that authorizations using one 266 or more components that do not implement Token Binding be allowed to 267 successfully proceed. This enables different components to be 268 upgraded to supporting Token Binding at different times, providing a 269 smooth transition path for phasing in Token Binding. However, when 270 Token Binding has been performed, any Token Binding key mismatches 271 MUST be treated as fatal errors. 273 If all the participants in an authorization interaction support Token 274 Binding and yet one or more of them does not use it, this is likely 275 evidence of a downgrade attack. In this case, the authorization 276 SHOULD be aborted with an error. For instance, if the resource 277 server knows that the authorization server and the User Agent both 278 support Token Binding and yet the access token received does not 279 contain Token Binding information, this is almost certainly a sign of 280 an attack. 282 The authorization server and client can determine whether the other 283 supports Token Binding using the metadata values defined in the next 284 section. They can determine whether the User Agent supports Token 285 Binding by whether it negotiated Token Binding for the TLS 286 connection. At present, there is no defined mechanism for 287 determining whether the resource server supports Token Binding or 288 not. However, it always safe to proceed as if it does; at worst, the 289 resource server simply won't verify the Token Binding. 291 5. Token Binding Metadata 293 5.1. Token Binding Client Metadata 295 Clients supporting Token Binding that also support the OAuth 2.0 296 Dynamic Client Registration Protocol [RFC7591] use these metadata 297 values to register their support for Token Binding of Access Tokens 298 and Refresh Tokens: 300 client_access_token_token_binding_supported 301 OPTIONAL. Boolean value specifying whether the Client supports 302 Token Binding of Access Tokens. If omitted, the default value is 303 "false". 305 client_refresh_token_token_binding_supported 306 OPTIONAL. Boolean value specifying whether the Client supports 307 Token Binding of Refresh Tokens. If omitted, the default value is 308 "false". 310 5.2. Token Binding Authorization Server Metadata 312 Authorization Servers supporting Token Binding that also support 313 OAuth 2.0 Authorization Server Metadata [OAuth.AuthorizationMetadata] 314 use these metadata values to register their support for Token Binding 315 of Access Tokens and Refresh Tokens: 317 as_access_token_token_binding_supported 318 OPTIONAL. Boolean value specifying whether the Authorization 319 Server supports Token Binding of Access Tokens. If omitted, the 320 default value is "false". 322 as_refresh_token_token_binding_supported 323 OPTIONAL. Boolean value specifying whether the Authorization 324 Server supports Token Binding of Refresh Tokens. If omitted, the 325 default value is "false". 327 6. Security Considerations 329 If a refresh request is received by the authorization server 330 containing a "resource_tbh" (resource token binding hash) value 331 requesting a token bound access token and the refresh token in the 332 request is not itself token bound, then it is not clear that token 333 binding the access token adds significant value. This situation 334 should be considered an open issue for discussion by the working 335 group. 337 7. IANA Considerations 339 7.1. OAuth Parameters Registration 341 This specification registers the following parameter in the IANA 342 "OAuth Parameters" registry [IANA.OAuth.Parameters] established by 343 RFC 6749 [RFC6749]: 345 7.1.1. Registry Contents 347 o Parameter name: "resource_tbh" 348 o Parameter usage location: Authorization Request, Token Request 349 o Change controller: IESG 350 o Specification document(s): Section 3 of this document 351 o Related information: None 353 7.2. OAuth Dynamic Client Registration Metadata Registration 355 This specification registers the following client metadata 356 definitions in the IANA "OAuth Dynamic Client Registration Metadata" 357 registry [IANA.OAuth.Parameters] established by [RFC7591]: 359 7.2.1. Registry Contents 361 o Client Metadata Name: 362 "client_access_token_token_binding_supported" 363 o Client Metadata Description: Boolean value specifying whether the 364 Client supports Token Binding of Access Tokens 365 o Change Controller: IESG 366 o Specification Document(s): Section 5.1 of [[ this specification ]] 368 o Client Metadata Name: 369 "client_refresh_token_token_binding_supported" 370 o Client Metadata Description: Boolean value specifying whether the 371 Client supports Token Binding of Refresh Tokens 372 o Change Controller: IESG 373 o Specification Document(s): Section 5.1 of [[ this specification ]] 375 7.3. OAuth Authorization Server Discovery Metadata Registration 377 This specification registers the following discovery metadata 378 definitions in the IANA "OAuth Authorization Server Discovery 379 Metadata" registry established by [OAuth.AuthorizationMetadata]: 381 7.3.1. Registry Contents 383 o Discovery Metadata Name: "as_access_token_token_binding_supported" 384 o Discovery Metadata Description: Boolean value specifying whether 385 the Authorization Server supports Token Binding of Access Tokens 386 o Change Controller: IESG 387 o Specification Document(s): Section 5.2 of [[ this specification ]] 389 o Discovery Metadata Name: 390 "as_refresh_token_token_binding_supported" 391 o Discovery Metadata Description: Boolean value specifying whether 392 the Authorization Server supports Token Binding of Refresh Tokens 393 o Change Controller: IESG 394 o Specification Document(s): Section 5.2 of [[ this specification ]] 396 8. References 398 8.1. Normative References 400 [I-D.ietf-tokbind-https] 401 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 402 Hodges, "Token Binding over HTTP", draft-ietf-tokbind- 403 https-06 (work in progress), August 2016. 405 [I-D.ietf-tokbind-protocol] 406 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 407 Hodges, "The Token Binding Protocol Version 1.0", draft- 408 ietf-tokbind-protocol-10 (work in progress), September 409 2016. 411 [IANA.OAuth.Parameters] 412 IANA, "OAuth Parameters", 413 . 415 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 416 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 417 . 419 [OpenID.TokenBinding] 420 Jones, M., Bradley, J., and B. Campbell, "OpenID Connect 421 Token Bound Authentication 1.0", July 2016, 422 . 425 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 426 Requirement Levels", BCP 14, RFC 2119, 427 DOI 10.17487/RFC2119, March 1997, 428 . 430 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 431 RFC 6749, DOI 10.17487/RFC6749, October 2012, 432 . 434 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 435 Protocol (HTTP/1.1): Message Syntax and Routing", 436 RFC 7230, DOI 10.17487/RFC7230, June 2014, 437 . 439 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 440 RFC 7662, DOI 10.17487/RFC7662, October 2015, 441 . 443 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 444 Possession Key Semantics for JSON Web Tokens (JWTs)", 445 RFC 7800, DOI 10.17487/RFC7800, April 2016, 446 . 448 [SHS] National Institute of Standards and Technology, "Secure 449 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 450 . 453 8.2. Informative References 455 [OAuth.AuthorizationMetadata] 456 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 457 Authorization Server Metadata", draft-ietf-oauth- 458 discovery-02 (work in progress), August 2016, 459 . 462 [OpenID.Core] 463 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 464 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 465 . 467 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 468 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 469 RFC 7591, DOI 10.17487/RFC7591, July 2015, 470 . 472 Appendix A. Acknowledgements 474 The authors would like to thank the following people for their 475 contributions to the specification: Dirk Balfanz, William Denniss, 476 Andrei Popov, and Nat Sakimura. 478 Appendix B. Open Issues 480 o Some token binding implementations apparently provide APIs that 481 enable native applications to provide Referred Token Bindings, 482 just as the federation support in the HTTPS Token Binding spec 483 does. Can we count on these APIs being supported on all 484 platforms, and if so, does this enable us to somehow do without 485 the "resource_tbh" parameter by mandating that the client send 486 both a Provided and a Referred Token Binding to the authorization 487 server? If this isn't the case, is "resource_tbh" actually secure 488 or does this open a cross-channel validation hole? This area 489 probably needs more attention from both the Token Binding and 490 OAuth working groups. 491 o How should we support crypto agility for the hash function? 493 Appendix C. Document History 495 [[ to be removed by the RFC Editor before publication as an RFC ]] 497 -00 499 o Created the initial working group version from draft-jones-oauth- 500 token-binding-00. 502 Authors' Addresses 504 Michael B. Jones 505 Microsoft 507 Email: mbj@microsoft.com 508 URI: http://self-issued.info/ 510 John Bradley 511 Ping Identity 513 Email: ve7jtb@ve7jtb.com 514 URI: http://www.thread-safe.com/ 516 Brian Campbell 517 Ping Identity 519 Email: brian.d.campbell@gmail.com 520 URI: https://twitter.com/__b_c