idnits 2.17.00 (12 Aug 2021) /tmp/idnits26876/draft-tschofenig-oauth-hotk-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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 9, 2012) is 3603 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: draft-ietf-oauth-v2 has been published as RFC 6749 == Outdated reference: draft-ietf-jose-json-web-key has been published as RFC 7517 == Outdated reference: draft-ietf-tls-oob-pubkey has been published as RFC 7250 == Outdated reference: draft-ietf-oauth-json-web-token has been published as RFC 7519 ** Obsolete normative reference: RFC 5246 (ref. '6') (Obsoleted by RFC 8446) == Outdated reference: draft-ietf-oauth-v2-bearer has been published as RFC 6750 == Outdated reference: A later version (-05) exists of draft-ietf-oauth-v2-http-mac-01 -- Obsolete informational reference (is this intentional?): RFC 5849 (ref. '10') (Obsoleted by RFC 6749) == Outdated reference: draft-ietf-oauth-assertions has been published as RFC 7521 Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group H. Tschofenig 3 Internet-Draft Nokia Siemens Networks 4 Intended status: Standards Track July 9, 2012 5 Expires: January 10, 2013 7 The OAuth 2.0 Authorization Framework: Holder-of-the-Key Token Usage 8 draft-tschofenig-oauth-hotk-00.txt 10 Abstract 12 OAuth 2.0 deployments currently rely on bearer tokens for securing 13 access to protected resources. Bearer tokens require Transport Layer 14 Security to be used between an OAuth client and the resource server 15 when presenting the access token in order to get access. The 16 security model is based on proof-of-possession of the access token: 17 access token storage and transfer has to be done with care to prevent 18 leakage. 20 There are, however, use cases that require a more active involvement 21 of the OAuth client to offer increased security, particularly against 22 token leakage. This document specifies an OAuth security framework 23 using ephemeral asymmetric credentials that are bound to the access 24 token. A client can create these key pairs dynamically and use them, 25 after they are bound to an access token by the authorization server, 26 in communication interactions with resource servers. 28 This document is discussed at 29 https://www.ietf.org/mailman/listinfo/oauth. This initial version of 30 the specification shall serve as a discussion starter. 32 Status of this Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on January 10, 2013. 49 Copyright Notice 51 Copyright (c) 2012 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 3. Protocol Specification . . . . . . . . . . . . . . . . . . . . 5 69 3.1. Binding a Public Key to an Access Token . . . . . . . . . 5 70 3.2. Accessing a Protected Resource . . . . . . . . . . . . . . 8 71 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 72 4.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 9 73 4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 9 74 4.3. Summary of Recommendations . . . . . . . . . . . . . . . . 10 75 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 76 5.1. OAuth Parameters Registration . . . . . . . . . . . . . . 11 77 5.2. The 'hotk' JSON Web Token Claims . . . . . . . . . . . . . 11 78 5.3. The 'hotk' OAuth Access Token Type . . . . . . . . . . . . 11 79 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 81 7.1. Normative References . . . . . . . . . . . . . . . . . . . 13 82 7.2. Informative References . . . . . . . . . . . . . . . . . . 13 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 85 1. Introduction 87 At the time of writing the OAuth 2.0 [1] and accompanying protocols 88 offer one main security mechanism to access protected resources, 89 namely the bearer token. In [8] a bearer token is defined as 91 A security token with the property that any party in possession of 92 the token (a "bearer") can use the token in any way that any other 93 party in possession of it can. Using a bearer token does not 94 require a bearer to prove possession of cryptographic key material 95 (proof-of-possession). 97 The bearer token provides sufficient security properties for a number 98 of use cases OAuth had been designed for, if certain conditions are 99 met (which are documented in [8]). Some usage scenarios, however, 100 require stronger security guarantees and ask for active participation 101 of the client software in form of cryptographic computations when 102 presenting an access token. 104 In addition to the bearer token a MAC token has been specified, see 105 [9]. The design of the MAC token was inspired by features in the 106 OAuth 1.0 [10]. Unfortunately, the MAC token has not received a lot 107 of deployment attention. 109 This specification defines a new security mechanism for usage with 110 OAuth that combines various existing specifications to offer enhanced 111 security properties for OAuth. The incredients for this security 112 solution are: 114 1. A mechanism for on-the-fly provisioning of ephemeral asymmetric 115 credentials using the JSON Web Key (JWK) format [2]. 117 2. The ability to access a protected resource using this ephemeral 118 asymmetric credentials for client authentication using a 119 transport layer extension that allows out-of-band key validation 120 [3]. 122 3. A data structure to bind the emphemeral asymmetric credential to 123 an access token. The structure uses the JSON Web Token (JWT) 124 [4]. 126 The rest of the document describes how these different components 127 work together. 129 2. Terminology 131 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 132 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 133 specification are to be interpreted as described in [5]. 135 3. Protocol Specification 137 To describe the architecture of the proposed security mechanism it is 138 best to start by looking at the main OAuth 2.0 protocol exchange 139 sequence. Figure 1 shows the abstract OAuth 2.0 protocol exchanges 140 graphically. The exchange in this document will focus on two 141 interactions, namely 143 1. to allow the client to obtain the ephemeral asymmetric 144 credentails in step (D) 146 2. to use the obtained asymmetric credentials for the interaction 147 with the resource server in step (E) 149 +--------+ +---------------+ 150 | |--(A)- Authorization Request ->| Resource | 151 | | | Owner | 152 | |<-(B)-- Authorization Grant ---| | 153 | | +---------------+ 154 | | 155 | | +---------------+ 156 | |--(C)-- Authorization Grant -->| Authorization | 157 | Client | | Server | 158 | |<-(D)----- Access Token -------| | 159 | | +---------------+ 160 | | 161 | | +---------------+ 162 | |--(E)----- Access Token ------>| Resource | 163 | | | Server | 164 | |<-(F)--- Protected Resource ---| | 165 +--------+ +---------------+ 167 Figure 1: Abstract OAuth 2.0 Protocol Flow 169 3.1. Binding a Public Key to an Access Token 171 OAuth 2.0 offers different ways to obtain an access token, namely 172 using authorization grants and using a refresh token. The core OAuth 173 specification defines four authorization grants, see Section 1.3 of 174 [1], and [11] adds an assertion-based authorization grant to that 175 list. 177 This document extends the communication with the token endpoint. The 178 token endpoint, which is described in Section 3.2 of [1], is used 179 with every authorization grant except for the implicit grant type 180 since an access token is issued directly. The request contains 181 information about the public key the client would like to bind to the 182 access token in the JSON Web Key format. This parameter also 183 provides an indication to the authorization servers about the support 184 by the client for this specification. Since the client makes a 185 request to the token endpoint by adding a new of parameters using the 186 "application/x-www-form-urlencoded" format in the HTTP request 187 entity-body the public key information must be encoded into a new 188 parameter, called 'pk-info'. A new token type, called 'hotk', is 189 also defined by this specification. 191 For example, the client makes the following HTTP request using TLS 192 (extra line breaks are for display purposes only): 194 POST /token HTTP/1.1 195 Host: server.example.com 196 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 197 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 199 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 200 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 201 &pk-info=eZQQYbYS6WxS...lxlOB 203 whereby the content of the pk-info field represents the following 204 structure: 206 {"keys": 207 [ 208 {"alg":"RSA", 209 "mod": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx 210 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs 211 tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 212 QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI 213 SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb 214 w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 215 "exp":"AQAB", 216 "kid":"2011-04-29"} 217 ] 218 } 220 Example Request to the Authorization Server 222 If the access token request is valid and authorized, the 223 authorization server issues an access token and optionally a refresh 224 token. If the request client authentication failed or is invalid, 225 the authorization server returns an error response as described in 226 Section 5.2 of [1]. 228 The authorization server also places information about the public key 229 used by the client into the access token to create the binding 230 between the two. 232 An example successful response: 234 HTTP/1.1 200 OK 235 Content-Type: application/json;charset=UTF-8 236 Cache-Control: no-store 237 Pragma: no-cache 239 { 240 "access_token":"2YotnFZFE....jr1zCsicMWpAA", 241 "token_type":"hotk", 242 "expires_in":3600, 243 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" 244 } 246 whereby the content of the 'access_token' field, for example, 247 contains an encoded JWT with the following raw structure: 249 {"typ":"JWT", 250 "alg":"HS256"} 251 . 252 {"iss":"authorization-server-id", 253 "exp":1300819380, 254 "hotk": {"keys": 255 [ 256 {"alg":"RSA", 257 "mod": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx 258 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs 259 tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 260 QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI 261 SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb 262 w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", 263 "exp":"AQAB", 264 "kid":"2011-04-29"} 265 ] 266 } 267 } 268 . 269 bbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZC 271 Example Response from the Authorization Server 273 3.2. Accessing a Protected Resource 275 The client accesses protected resources by presenting the access 276 token to the resource server. It does so via a Transport Layer 277 Security (TLS) secured channel. Since the client had previously 278 bound a public key to an access token it selects this key for usage 279 with TLS as described in [3]. 281 The resource server validates the access token and ensure it has not 282 expired and that its scope covers the requested resource. 283 Additionally, the resource server verifies that the public key 284 presented during the TLS handshake corresponds to the public key that 285 is contained in the access token. 287 Note that this step confirms that the client is in possession of the 288 private key corresponding to the public key previously bound to the 289 access token. Information about the client authentication may be 290 contained in the token in case the authorization server added this 291 information when it authenticated the client. 293 4. Security Considerations 295 4.1. Security Threats 297 The following list presents several common threats against protocols 298 utilizing some form of tokens. This list of threats is based on NIST 299 Special Publication 800-63 [12]. We exclude a discussion of threats 300 related to any form of registration and authentication. 302 Token manufacture/modification: An attacker may craft a fake token 303 or modify the token content (such as the authentication or 304 attribute statements), causing a resource server to grant 305 inappropriate access to the attacker. For example, an attacker 306 may modify the token to extend the validity period or the scope to 307 have extended access to information. 309 Token disclosure: Tokens may contain authentication and attribute 310 statements that include sensitive information. 312 Token redirect: An attacker uses a token generated for consumption 313 by one resource server to gain access to a different resource 314 server that mistakenly believes the token to be for it. 316 Token reuse: An attacker attempts to use a token that has already 317 been used with that resource server in the past. 319 4.2. Threat Mitigation 321 A large range of threats can be mitigated by protecting the contents 322 of the access token by using a digital signature or a Message 323 Authentication Code (MAC). Consequently, the token integrity 324 protection MUST be sufficient to prevent the token from being 325 modified. 327 To deal with token redirect, it is important for the authorization 328 server to include the identity of the intended recipients (the 329 audience), typically a single resource server (or a list of resource 330 servers), in the token. Restricting the use of the token to a 331 specific scope is also RECOMMENDED. 333 The authorization server MUST implement TLS. Which version(s) ought 334 to be implemented will vary over time, and depend on the widespread 335 deployment and known security vulnerabilities at the time of 336 implementation. At the time of this writing, TLS version 1.2 [6] is 337 the most recent version. The client MUST validate the TLS 338 certificate chain when making requests to protected resources, 339 including checking the Certificate Revocation List (CRL) [7]. In 340 addition, this specificatio requires a TLS extension for usage with 341 out-of-band validation [3] to be used that allows clients to present 342 raw public keys. 344 With the usage of the holder-of-the-key concept it is not possible 345 for any party other than the legitimate client to use a token and to 346 re-use it without knowing the corresponding asymmetric key pair. 347 This mechanism prevents against token disclosure. In some 348 deployments, including those utilizing load balancers, the TLS 349 connection to the resource server terminates prior to the actual 350 server that provides the resource. This could leave the token 351 unprotected between the front end server where the TLS connection 352 terminates and the back end server that provides the resource. Even 353 in such deployments, token leakage is not a problem. 355 Client implementations must be carefully implemented to avoid leaking 356 the ephemeral asymmetric key pair. 358 Token replay is also not possible since an eavesdropper will also 359 have to obtain the corresponding asymmetric key pair that corresponds 360 to the access token. Nevertheless, it is good practice to limit the 361 lifetime of the and therefore the lifetime of the ephemeral 362 asymmetric key associated with it. 364 4.3. Summary of Recommendations 366 The following three items represent the main recommendations: 368 Safeguard the private key: Client implementations MUST ensure that 369 the ephemeral private key is not leaked to third parties, since 370 those will be able to use the access together with the key pair to 371 gain access to protected resources. 373 Switch keying material regularly: Clients can at any time create a 374 new ephemeral key pair and request the public key to be associated 375 with the access token. For example, a client presents a new 376 public key when requesting an access token with the help of a 377 refresh token. Nevertheless, the lifetime of these access token 378 may be longer than the lifetime of bearer tokens. 380 Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens 381 that contain an audience restriction, scoping their use to the 382 intended relying party or set of relying parties. 384 5. IANA Considerations 386 This document requires IANA to take the following actions. 388 5.1. OAuth Parameters Registration 390 This specification registers the 'pk-info' parameter in the OAuth 391 Parameters Registry established by [1]. 393 Parameter name: pk-info 395 Parameter usage location: token request 397 Change controller: IETF 399 Specification document(s): [[ this document ]] 401 Related information: None 403 5.2. The 'hotk' JSON Web Token Claims 405 [4] established the IANA JSON Web Token Claims registry for reserved 406 JWT Claim Names and this document adds the 'hotk' name to that 407 registry. 409 5.3. The 'hotk' OAuth Access Token Type 411 Section 11.1 of [1] defines the OAuth Access Token Type Registry and 412 this document adds another token type to this registry. 414 Type name: hotk 416 Additional Token Endpoint Response Parameters: (none) 418 HTTP Authentication Scheme(s): Holder of the key confirmation using 419 TLS 421 Change controller: IETF 423 Specification document(s): [[ this document ]] 425 6. Acknowledgements 427 The author would like to thank the OAuth working group and 428 participants of the Internet Identity Workshop for their discussion 429 input that lead to this document. 431 7. References 433 7.1. Normative References 435 [1] Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 2.0 436 Authorization Framework", draft-ietf-oauth-v2-28 (work in 437 progress), June 2012. 439 [2] Jones, M., "JSON Web Key (JWK)", 440 draft-ietf-jose-json-web-key-03 (work in progress), July 2012. 442 [3] Wouters, P., Gilmore, J., Weiler, S., Kivinen, T., and H. 443 Tschofenig, "TLS Out-of-Band Public Key Validation", 444 draft-ietf-tls-oob-pubkey-03 (work in progress), April 2012. 446 [4] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 447 (JWT)", draft-ietf-oauth-json-web-token-01 (work in progress), 448 July 2012. 450 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 451 Levels", BCP 14, RFC 2119, March 1997. 453 [6] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) 454 Protocol Version 1.2", RFC 5246, August 2008. 456 [7] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, 457 R., and W. Polk, "Internet X.509 Public Key Infrastructure 458 Certificate and Certificate Revocation List (CRL) Profile", 459 RFC 5280, May 2008. 461 7.2. Informative References 463 [8] Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 464 Authorization Framework: Bearer Token Usage", 465 draft-ietf-oauth-v2-bearer-21 (work in progress), June 2012. 467 [9] Hammer-Lahav, E., "HTTP Authentication: MAC Access 468 Authentication", draft-ietf-oauth-v2-http-mac-01 (work in 469 progress), February 2012. 471 [10] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 472 April 2010. 474 [11] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 475 "Assertion Framework for OAuth 2.0", 476 draft-ietf-oauth-assertions-04 (work in progress), July 2012. 478 [12] Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., and E. 480 Nabbus, "NIST Special Publication 800-63-1, INFORMATION 481 SECURITY", December 2008. 483 Author's Address 485 Hannes Tschofenig 486 Nokia Siemens Networks 487 Linnoitustie 6 488 Espoo 02600 489 Finland 491 Phone: +358 (50) 4871445 492 Email: Hannes.Tschofenig@gmx.net 493 URI: http://www.tschofenig.priv.at