idnits 2.17.1 draft-broyer-http-cookie-auth-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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 10 characters in excess of 72. ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. 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 -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 4, 2009) is 5591 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) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 2965 (Obsoleted by RFC 6265) Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Broyer 3 Internet-Draft January 4, 2009 4 Intended status: Standards Track 5 Expires: July 8, 2009 7 Cookie-based HTTP Authentication 8 draft-broyer-http-cookie-auth-00 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on July 8, 2009. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. 45 Abstract 47 This document specifies an HTTP authentication scheme for use when 48 credentials are validated by an out-of-band mechanism (not defined 49 here) and later communicated to the server through the use of a 50 cookie. Which out-of-band mechanism should be used, and how, is 51 described by the 401 (Unauthorized) response body. It is common 52 practice that this mechanism is an HTML form, sending the user's 53 credentials with the use of an HTTP POST request to a tier URL which 54 will set a cookie in response; though this document doesn't preclude 55 the use of other mechanisms. 57 Editorial Note (To be removed by RFC Editor before publication) 59 Distribution of this document is unlimited. Please send comments to 60 the ietf-http-auth mailing list at 61 ietf-http-auth@osafoundation.org [1], which may be joined by sending 62 a message with subject "subscribe" to 63 ietf-http-auth-request@osafoundation.org [2]. 65 Discussions of the ietf-http-auth mailing list are archived at 66 . 68 XML versions, latest edits and the issues list for this document are 69 available from . 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 74 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 4 75 3. Cookie Authentication Scheme . . . . . . . . . . . . . . . . . 4 76 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 77 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 78 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 79 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 80 7.1. Normative References . . . . . . . . . . . . . . . . . . . 7 81 7.2. Informative References . . . . . . . . . . . . . . . . . . 8 82 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 8 83 A.1. Simple example (everything goes through TLS) . . . . . . . 8 84 A.2. Mixed HTTP/HTTPS example . . . . . . . . . . . . . . . . . 9 85 A.3. Cross-domain example . . . . . . . . . . . . . . . . . . . 11 86 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 88 1. Introduction 90 Authentication on the web can be done either at the Hypertext 91 Transfer Protocol (HTTP) [RFC2616] level with a 401 (Unauthorized) 92 status code, or using SSL certificates. Among other issues already 93 listed in User Agent Authentication Forms 94 [W3C.NOTE-authentform-19990203], the former suffers from a poor user 95 experience while the latter can quickly become expensive. That's why 96 the most common authentication mechanism is based on HyperText Markup 97 Language (HTML) forms [W3C.REC-html401-19991224] and cookies 98 [RFC2965]. 100 However, form-based authentication is almost always implemented with 101 an HTTP redirect to the login form, making it impossible for non- 102 browser user agents to detect a protected resource (this leads to 103 people downloading and saving login forms instead of the protected 104 resource they wanted, web service clients failing with unrecoverable 105 errors, etc.). 107 User Agent Authentication Forms [W3C.NOTE-authentform-19990203] tried 108 to overcome this with an amendment to HTML forms making them "HTTP- 109 authentication aware". 111 This document solves the problem the other way around, keeping the 112 mechanism backwards compatible with browsers while making it 113 independant of HTML. 115 2. Notational Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL-NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in Appendix of [RFC2119]. 121 The terminology used here follows and extends that in the HTTP 122 specification Appendix of [RFC2616]. 124 3. Cookie Authentication Scheme 126 The "cookie" authentication scheme tries to reconcile the current 127 practice of many web sites and web development frameworks of using 128 HTML forms and cookies to authenticate users, and the Access 129 Authentication Framework described in Section 1.2 of [RFC2617]. The 130 user credentials being passed through cookies, the Authorization and 131 Proxy-Authorization request headers are therefore not used. 133 The "cookie" authentication scheme cannot be used for proxy 134 authentication (within the value of a Proxy-Authenticate response 135 header) because, as defined in Section 3.5 of [RFC2965]: "Proxies 136 MUST NOT introduce Set-Cookie2 (Cookie) headers of their own in proxy 137 responses (requests)." 139 When the origin server sends a 401 (Unauthorized) response containing 140 a WWW-Authenticate header with a "cookie" authentication scheme, the 141 response body gives instructions on how to create the appropriate 142 cookies, generally by issuing another HTTP request (preferably a POST 143 request) to a distinct URL. 145 In most current web sites and web applications, the response body 146 would be an HTML document containing a form; when the form is 147 submitted, the server checks the user-provided form-data and upon 148 validation sends the appropriate Set-Cookie2 response header fields 149 within a 303 (See Other) response redirecting back to the protected 150 resource. 152 The "cookie" authentication scheme is however not limited to such 153 scenarios: the response body could be for example an SVG image with 154 an embedded XForms, or an HTML document with an embedded script that 155 will compute a hash of user-provided data and set the cookie by 156 script before reloading the resource, or some specific entity 157 recognized by the UA, which will authenticate using an out-of-band 158 mechanism and set the appropriate cookie before re-requesting the 159 protected resource. This last scenario might be better solved using 160 another authentication scheme, though this scenario would allow 161 server-side negotiation of the authentication mechanism using content 162 negotiation; instead of the client-side negotiation traditionally 163 used when sending multiple WWW-Authenticate response headers. 165 Syntax (using the augmented Backus-Naur Form (BNF) defined in Section 166 2.1 of [RFC2616]): 168 challenge = "Cookie" cookie-challenge 170 cookie-challenge = 1#( realm | [ form-action ] | cookie-name | 171 [ secure-cookie-name ] | [auth-param] ) 173 form-action = "form-action" "=" <"> URI <"> 174 URI = absolute-URI | ( path-absolute [ "?" query ] ) 175 cookie-name = "cookie-name" "=" token 176 secure-cookie-name = "secure-cookie-name" "=" token 178 path-absolute = 179 quoted-string = 180 query = 181 token = 182 The meanings of the values of the directives used above are as 183 follows: 185 form-action OPTIONAL. The value of the "form-action" attribute is 186 the URI reference of the resource that will set the cookies used 187 for authenticating the user in subsequent requests. The value 188 must resolve to an URI reference where the "scheme" part MUST be 189 "http" or "https", the "authority" part contains no "userinfo", 190 the "host" and "abs_path" parts have the same contraints as the 191 "Domain" and "Path" attributes of a Set-Cookie2 response header 192 respectively. 194 cookie-name REQUIRED. The value of the "cookie-name" attribute is 195 the name of the cookie that is checked by the server to 196 authenticate the user; an UA thus could then inform the user this 197 cookie is necessary to gain access to the protected resource, and 198 eventually use a different, more secure, storage than for other 199 cookies. 201 secure-cookie-name OPTIONAL. In case the application uses a mix of 202 secured and unsecured channels, the value of the "secure-cookie- 203 name" attribute is the name of the cookie that is checked by the 204 server to authenticate the user when the communication uses a 205 secured channel, while the cookie named by the "cookie-name" 206 attribute will be used for unsecured channel. 208 The applicability of the cookie(s) (its Domain, Port and Path 209 attributes) defines the protection space. 211 4. Acknowledgements 213 5. IANA Considerations 215 This memo includes no request to IANA. 217 6. Security Considerations 219 As with any use of cookies, care should be taken by servers to avoid 220 cookie spoofing, and clients to prevent unexpected cookie sharing 221 (see Section 6 and Section 7 of [RFC2965]). 223 However, using cookies for account information requires that some 224 additional measures be taken. Using HTTP Over TLS [RFC2818] or other 225 means of encrypting the conversation is sufficient to mitigate most 226 threats, though it requires that some additional measures be taken, 227 as described in this section. 229 To mitigate replay attacks (re-use of a sniffed cookie), the value of 230 the cookie used for authentication SHOULD NOT contain the users 231 credentials but rather a key associated with the authentication 232 session, and this key SHOULD be renewed (and expired) frequently. 234 Sensitive information (such as the user's IBAN on an online store) 235 and sensitive actions (such as confirming an order) SHOULD only 236 happen on a secure channel such as HTTP Over TLS [RFC2818], and 237 protected with a secure cookie (a cookie with the "Secure" bit set) 238 so that it cannot be stolen on a unsecured channel. 240 This document does not specify how credentials are sent to the "form- 241 action" URL, though care should be taken that those credentials 242 cannot be sniffed. In the case of an HTML form, the "form-action" 243 SHOULD use a secure channel such as HTTP Over TLS [RFC2818]. 245 [[anchor2: TODO: document how secure-cookie-name helps with security 246 by preventing replay-attacks. The cookie must obviously have the 247 Secure attribute set.]] 249 [[anchor3: TODO: add some words about CSRF (and find a normative 250 reference). Mention "logout" as a mean to mitigate CSRF.]] 252 7. References 254 7.1. Normative References 256 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 257 Requirement Levels", BCP 14, RFC 2119, March 1997. 259 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 260 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 261 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 263 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 264 Leach, P., Luotonen, A., and L. Stewart, "HTTP 265 Authentication: Basic and Digest Access Authentication", 266 RFC 2617, June 1999. 268 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 270 [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management 271 Mechanism", RFC 2965, October 2000. 273 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 274 Resource Identifier (URI): Generic Syntax", RFC 3986, 275 January 2005. 277 7.2. Informative References 279 [W3C.NOTE-authentform-19990203] 280 Lawrence, S. and P. Leach, "User Agent Authentication 281 Forms", W3C NOTE NOTE-authentform-19990203, February 1999. 283 [W3C.REC-html401-19991224] 284 Jacobs, I., Hors, A., and D. Raggett, "HTML 4.01 285 Specification", World Wide Web Consortium 286 Recommendation REC-html401-19991224, December 1999, 287 . 289 URIs 291 [1] 293 [2] 296 Appendix A. Examples 298 Most detail of request and response headers has been omitted. Assume 299 that the user agent has no stored cookies. 301 A.1. Simple example (everything goes through TLS) 303 1. User Agent -> Server 305 GET https://www.example.com/acme/ HTTP/1.1 307 2. Server -> User Agent 308 HTTP/1.1 401 Unauthorized 309 WWW-Authenticate: Cookie realm="Acme" 310 form-action="/acme/login" 311 cookie-name=ACME_TICKET 312 Content-Type: text/html 314 Unauthorized 315
316 317

318

319

320

Register for an account 321

323 3. User Agent -> Server 325 POST https://www.example.com/acme/login HTTP/1.1 326 Content-Type: application/x-www-form-urlencoded 328 referer=%2Facme%2F&user=Aladdin&password=open%20sesame 330 4. Server -> User Agent 332 HTTP/1.1 303 See Other 333 Location: https://www.example.com/acme/ 334 Set-Cookie2: ACME_TICKET="sdf354s5c1s8e1s"; Version="1"; 335 Path="/acme"; Secure 337 5. User Agent -> Server 339 GET https://www.example.com/acme/ HTTP/1.1 340 Cookie: $Version="1"; ACME_TICKET="sdf354s5c1s8e1s"; $Path="/acme" 342 6. Server -> User Agent 344 HTTP/1.1 200 OK 346 A.2. Mixed HTTP/HTTPS example 348 1. User Agent -> Server 350 GET http://www.example.com/acme/ HTTP/1.1 352 2. Server -> User Agent 353 HTTP/1.1 401 Unauthorized 354 WWW-Authenticate: Cookie realm="Acme" 355 form-action="https://secure.example.com/acme/login" 356 cookie-name=ACME_TICKET 357 secure-cookie-name=ACME_SECURE_TICKET 358 Content-Type: text/html 360 Unauthorized 361
362 364

365

366

367

Register for an account 368

370 3. User Agent -> Server 372 POST https://secure.example.com/acme/login HTTP/1.1 373 Content-Type: application/x-www-form-urlencoded 375 referer=http%3A%2F%2Fwww.example.com%2Facme%2F&user=Aladdin&password=open%20sesame 377 4. Server -> User Agent 379 HTTP/1.1 303 See Other 380 Location: http://www.example.com/acme/ 381 Set-Cookie2: ACME_TICKET="sdf354s5c1s8e1s"; Version="1"; 382 Path="/acme"; Domain=".example.com" 383 Set-Cookie2: ACME_SECURE_TICKET="drg53d51fd535rg"; Version="1"; 384 Path="/acme"; Domain=".example.com"; Secure 386 5. User Agent -> Server 388 GET http://www.example.com/acme/ HTTP/1.1 389 Cookie: $Version="1"; ACME_TICKET="sdf354s5c1s8e1s"; 390 $Path="/acme"; $Domain=".example.com" 392 6. Server -> User Agent 394 HTTP/1.1 200 OK 396 7. User Agent -> Server 398 GET https://secure.example.com/acme/ HTTP/1.1 399 Cookie: $Version="1"; ACME_SECURE_TICKET="drg53d51fd535rg"; 400 $Path="/acme"; $Domain=".example.com" 402 8. Server -> User Agent 404 HTTP/1.1 200 OK 406 A.3. Cross-domain example 408 [[anchor9: TODO: using CSRF and server-to-server communication to 409 achieve cross-domain single sign-on between sso.some-co.com and 410 www.some-tm.net.]] 412 At some-tm.net, the 401 response body loads a javascript from 413 sso.some-co.com that sets a "temporary" cookie if already 414 authenticated or redirects to sso.some-co.com otherwise. In the 415 former case, the server validates the "temporary" cookie by calling 416 sso.some-co.com and then sets the appropriate cookie to authenticate 417 the user at some-tm.net. On the latter case, the server then 418 redirects the browser back to some-tm.net with some token in the URL; 419 this token is validated the same way as with the "temporary" cookie 420 and the browser is then redirected back to the protected resource. 422 Fallback in case javascript is not available is a (in 423 a