Cookie-based HTTP Authentication

t.broyer@ltgt.net

Applications Hypertext Transfer Protocol (HTTP) authentication is in little use in the public web, where most web sites and applications use an HyperText Markup Language (HTML) form for the user to provide his credentials, and cookies to maintain the "authenticated" session. Most of the time, the HTML form is sent back with a 200 (OK) status or as the target of a redirect. This is a problem for non-interactive user agents (web crawlers, download tools, etc.) that will treat the response as a success. It can even become a problem for interactive user agents (browsers) in some situations (asynchronous AJAX requests, "save link target as..." feature, etc.). The HTTP way of communicating a lack of authorization for a protected resource is through a 401 (Unauthorized) status. However, this requires sending a WWW-Authenticate header in the response. This document tries to reconcile the current practice of using HTML forms and cookies to authenticate users, and the 401 (Unauthorized) status requirement, by specifying the "Cookie" HTTP authentication scheme. It also goes beyond using HTML forms by allowing any content type to be returned in the 401 (Unauthorized) response body, provided that a cookie is used to authorize access to the protected resource. Finally, a new HTTP status code, 308 (Unauthorized, See Other), is also introduced for those cases where a redirection is deemed necessary, or at least better than a 401 (Unauthorized). Distribution of this document is unlimited. Please send comments to the ietf-http-auth mailing list at ietf-http-auth@osafoundation.org, which may be joined by sending a message with subject "subscribe" to ietf-http-auth-request@osafoundation.org. Discussions of the ietf-http-auth mailing list are archived at . XML versions, latest edits and the issues list for this document are available from .

Hypertext Transfer Protocol (HTTP) authentication is in little use in the public web, where most web sites and applications use an HyperText Markup Language (HTML) form for the user to provide his credentials, and cookies to maintain the "authenticated" session. Most of the time, the HTML form is sent back with a 200 (OK) status or as the target of a redirect. This is a problem for non-interactive user agents (web crawlers, download tools, etc.) that will treat the response as a success. It can even become a problem for interactive user agents (browsers) in some situations (asynchronous AJAX requests, "save link target as..." feature, etc.). The HTTP way of communicating a lack of authorization for a protected resource is through a 401 (Unauthorized) status. However, this requires sending a WWW-Authenticate header in the response. This document tries to reconcile the current practice of using HTML forms and cookies to authenticate users, and the 401 (Unauthorized) status requirement, by specifying the "Cookie" HTTP authentication scheme. It also goes beyond using HTML forms by allowing any content type to be returned in the 401 (Unauthorized) response body, provided that a cookie is used to authorize access to the protected resource. Finally, a new HTTP status code, 308 (Unauthorized, See Other), is also introduced for those cases where a redirection is deemed necessary, or at least better than a 401 (Unauthorized).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL-NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . The terminology used here follows and extends that in the HTTP specification .

TODO: backwards compat with current UAs, easy migration path for web sites (almost no-op).

Following paragraphs to be re-ordered and probably re-worded too The user credentials being passed through cookies, the Authorization and Proxy-Authorization request headers are therefore not used. The "cookie" authentication scheme cannot be used for proxy authentication (within the value of a Proxy-Authenticate response header) because, as defined in : Proxies &MUST-NOT; introduce Set-Cookie2 (Cookie) headers of their own in proxy responses (requests). When the origin server sends a 401 (Unauthorized) response containing a WWW-Authenticate header with a "cookie" authentication scheme, the response body gives instructions on how to create the appropriate cookies. In most current web sites and web applications, the response body would be an HTML document containing a form; when the form is submitted, the server checks the user-provided form-data and upon validation sends the appropriate Set-Cookie2 response header fields within a 303 (See Other) response redirecting back to the protected resource. The "cookie" authentication scheme is however not limited to such scenarios: the response body could be for example an SVG image with an embedded XForms, or an HTML document with an embedded script that will compute a hash of user-provided data and set the cookie by script before reloading the resource, or some specific entity recognized by the UA, which will authenticate using an out-of-band mechanism and set the appropriate cookie before re-requesting the protected resource. This last scenario might be better solved using another authentication scheme, though this scenario would allow server-side negotiation of the authentication mechanism using content negotiation; instead of the client-side negotiation traditionally used when sending multiple WWW-Authenticate response headers.

Syntax (using the augmented Backus-Naur Form (BNF) defined in ): challenge = "Cookie" cookie-challenge cookie-challenge = 1#( realm | [ form-action ] | cookie-name | [ secure-cookie-name ] | [ form-username-field-name ] | [ form-password-field-name ] | [ auth-param ] ) form-action = "form-action" "=" <"> URI <"> URI = absolute-URI | ( path-absolute [ "?" query ] ) cookie-name = "cookie-name" "=" token secure-cookie-name = "secure-cookie-name" "=" token form-username-field-name = "form-username-field-name" "=" token form-password-field-name = "form-password-field-name" "=" token auth-param = <defined in > path-absolute = <defined in > quoted-string = <defined in > query = <defined in > token = <defined in > The meanings of the values of the directives used above are as follows: &OPTIONAL;. The value of the "form-action" attribute is the URI reference of the resource that will set the cookies used for authenticating the user in subsequent requests. The value must resolve to an URI reference where the "scheme" part &MUST; be "http" or "https", the "authority" part contains no "userinfo", the "host" and "abs_path" parts have the same contraints as the "Domain" and "Path" attributes of a Set-Cookie2 response header respectively. &REQUIRED;. The value of the "cookie-name" attribute is the name of the cookie that is checked by the server to authenticate the user; an UA thus could then inform the user this cookie is necessary to gain access to the protected resource, and eventually use a different, more secure, storage than for other cookies. &OPTIONAL;. In case the application uses a mix of secured and unsecured channels, the value of the "secure-cookie-name" attribute is the name of the cookie that is checked by the server to authenticate the user when the communication uses a secured channel, while the cookie named by the "cookie-name" attribute will be used for unsecured channel. &OPTIONAL;. To be completed. &OPTIONAL;. To be completed. This directive allows for future extensions. Any unrecognized directive MUST be ignored. The applicability of the cookie(s) (its Domain, Port and Path attributes) defines the protection space.

TODO

Allow a 401 without WWW-Authenticate. Problem: it doesn't communicate the fact that cookies are used for authentication (vs. some other header, or as part of the request payload (as generally done with SOAP Web Services). User Agent Authentication Forms

Thanks to those who raised the issue to the WHAT Working Group and the World Wide Web Consortium's HTML Working Group; to Ian Hickson for his summary of the issue and a similar proposal (tied to HTML, though). Many thanks to Julian Reschke for his encouragements and help with xml2rfc.

This memo includes no request to IANA.

As with any use of cookies, care should be taken by servers to avoid cookie spoofing, and clients to prevent unexpected cookie sharing (see and ). However, using cookies for account information requires that some additional measures be taken. Using HTTP Over TLS or other means of encrypting the conversation is sufficient to mitigate most threats, though it requires that some additional measures be taken, as described in this section. To mitigate replay attacks (re-use of a sniffed cookie), the value of the cookie used for authentication &SHOULD-NOT; contain the users credentials but rather a key associated with the authentication session, and this key &SHOULD; be renewed (and expired) frequently. Sensitive information (such as the user's IBAN on an online store) and sensitive actions (such as confirming an order) &SHOULD; only happen on a secure channel such as HTTP Over TLS, and protected with a secure cookie (a cookie with the "Secure" bit set) so that it cannot be stolen on a unsecured channel. This document does not specify how credentials are sent to the "form-action" URL, though care should be taken that those credentials cannot be sniffed. In the case of an HTML form, the "form-action" &SHOULD; use a secure channel such as HTTP Over TLS. TODO: document how secure-cookie-name helps with security by preventing replay-attacks. The cookie must obviously have the Secure attribute set. TODO: add some words about CSRF (and find a normative reference). Mention "logout" as a mean to mitigate CSRF.

Key words for use in RFCs to Indicate Requirement Levels Harvard University

sob@harvard.edu

Hypertext Transfer Protocol -- HTTP/1.1 University of California, Irvine

fielding@ics.uci.edu

W3C

jg@w3.org

Compaq Computer Corporation

mogul@wrl.dec.com

MIT Laboratory for Computer Science

frystyk@w3.org

Xerox Corporation

masinter@parc.xerox.com

Microsoft Corporation

paulle@microsoft.com

W3C

timbl@w3.org

HTTP Authentication: Basic and Digest Access Authentication Northwestern University, Department of Mathematics

Northwestern University Evanston IL 60208-2730 USA john@math.nwu.edu

Verisign Inc.

301 Edgewater Place Suite 210 Wakefield MA 01880 USA pbaker@verisign.com

AbiSource, Inc.

6 Dunlap Court Savoy IL 61874 USA jeff@AbiSource.com

Agranat Systems, Inc.

5 Clocktower Place Suite 400 Maynard MA 01754 USA lawrence@agranat.com

Microsoft Corporation

1 Microsoft Way Redmond WA 98052 USA paulle@microsoft.com

Netscape Communications Corporation

501 East Middlefield Road Mountain View CA 94043 USA

Open Market, Inc.

215 First Street Cambridge MA 02142 USA stewart@OpenMarket.com

"HTTP/1.0", includes the specification for a Basic Access Authentication scheme. This scheme is not considered to be a secure method of user authentication (unless used in conjunction with some external secure system such as SSL ), as the user name and password are passed over the network as cleartext. This document also provides the specification for HTTP's authentication framework, the original Basic authentication scheme and a scheme based on cryptographic hashes, referred to as "Digest Access Authentication". It is therefore also intended to serve as a replacement for RFC 2069 . Some optional elements specified by RFC 2069 have been removed from this specification due to problems found since its publication; other new elements have been added for compatibility, those new elements have been made optional, but are strongly recommended. Like Basic, Digest access authentication verifies that both parties to a communication know a shared secret (a password); unlike Basic, this verification can be done without sending the password in the clear, which is Basic's biggest weakness. As with most other authentication protocols, the greatest sources of risks are usually found not in the core protocol itself but in policies and procedures surrounding its use. HTTP Over TLS This memo describes how to use Transport Layer Security (TLS) to secure Hypertext Transfer Protocol (HTTP) connections over the Internet. This memo provides information for the Internet community. HTTP State Management Mechanism Bell Laboratories, Lucent Technologies

600 Mountain Ave. Room 2A-333 Murray Hill NJ 07974 (908) 582-2250 (908) 582-1239 dmk@bell-labs.com

Epinions.com, Inc.

2037 Landings Dr. Mountain View CA 94301 lou@montulli.org

This document specifies a way to create a stateful session with Hypertext Transfer Protocol (HTTP) requests and responses. It describes three new headers, Cookie, Cookie2, and Set-Cookie2, which carry state information between participating origin servers and user agents. The method described here differs from Netscape's Cookie proposal , but it can interoperate with HTTP/1.0 user agents that use Netscape's method. (See the HISTORICAL section.) This document reflects implementation experience with RFC 2109 and obsoletes it. Uniform Resource Identifier (URI): Generic Syntax World Wide Web Consortium

Massachusetts Institute of Technology 77 Massachusetts Avenue Cambridge MA 02139 USA +1-617-253-5702 +1-617-258-5999 timbl@w3.org http://www.w3.org/People/Berners-Lee/

Day Software

5251 California Ave., Suite 110 Irvine CA 92617 USA +1-949-679-2960 +1-949-679-2972 fielding@gbiv.com http://roy.gbiv.com/

Adobe Systems Incorporated

345 Park Ave San Jose CA 95110 USA +1-408-536-3024 LMM@acm.org http://larry.masinter.net/

HTML 4.01 Specification User Agent Authentication Forms

Most detail of request and response headers has been omitted. Assume that the user agent has no stored cookies.

User Agent -> Server

GET https://www.example.com/acme/ HTTP/1.1 Server -> User Agent

HTTP/1.1 401 Unauthorized WWW-Authenticate: Cookie realm="Acme" form-action="/acme/login" cookie-name=ACME_TICKET Content-Type: text/html Unauthorized ]]> User Agent -> Server

POST https://www.example.com/acme/login HTTP/1.1 Content-Type: application/x-www-form-urlencoded referer=%2Facme%2F&user=Aladdin&password=open%20sesame Server -> User Agent

HTTP/1.1 303 See Other Location: https://www.example.com/acme/ Set-Cookie2: ACME_TICKET="sdf354s5c1s8e1s"; Version="1"; Path="/acme"; Secure User Agent -> Server

GET https://www.example.com/acme/ HTTP/1.1 Cookie: $Version="1"; ACME_TICKET="sdf354s5c1s8e1s"; $Path="/acme" Server -> User Agent

HTTP/1.1 200 OK

User Agent -> Server

GET http://www.example.com/acme/ HTTP/1.1 Server -> User Agent

HTTP/1.1 401 Unauthorized WWW-Authenticate: Cookie realm="Acme" form-action="https://secure.example.com/acme/login" cookie-name=ACME_TICKET secure-cookie-name=ACME_SECURE_TICKET Content-Type: text/html Unauthorized ]]> User Agent -> Server

POST https://secure.example.com/acme/login HTTP/1.1 Content-Type: application/x-www-form-urlencoded referer=http%3A%2F%2Fwww.example.com%2Facme%2F&user=Aladdin&password=open%20sesame Server -> User Agent

HTTP/1.1 303 See Other Location: http://www.example.com/acme/ Set-Cookie2: ACME_TICKET="sdf354s5c1s8e1s"; Version="1"; Path="/acme"; Domain=".example.com" Set-Cookie2: ACME_SECURE_TICKET="drg53d51fd535rg"; Version="1"; Path="/acme"; Domain=".example.com"; Secure User Agent -> Server

GET http://www.example.com/acme/ HTTP/1.1 Cookie: $Version="1"; ACME_TICKET="sdf354s5c1s8e1s"; $Path="/acme"; $Domain=".example.com" Server -> User Agent

HTTP/1.1 200 OK User Agent -> Server

GET https://secure.example.com/acme/ HTTP/1.1 Cookie: $Version="1"; ACME_SECURE_TICKET="drg53d51fd535rg"; $Path="/acme"; $Domain=".example.com" Server -> User Agent

HTTP/1.1 200 OK

TODO: using CSRF and server-to-server communication to achieve cross-domain single sign-on between sso.some-co.com and www.some-tm.net. At some-tm.net, the 401 response body loads a javascript from sso.some-co.com that sets a "temporary" cookie if already authenticated or redirects to sso.some-co.com otherwise. In the former case, the server validates the "temporary" cookie by calling sso.some-co.com and then sets the appropriate cookie to authenticate the user at some-tm.net. On the latter case, the server then redirects the browser back to some-tm.net with some token in the URL; this token is validated the same way as with the "temporary" cookie and the browser is then redirected back to the protected resource. Fallback in case javascript is not available is a <meta refresh> (in a <noscript>) to redirect the browser to sso.some-co.com. The process is then similar to JA-SIG Central Authentication Service (CAS). Or maybe these should be two distinct examples? And do not forget the "single-logout" issue.