id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
32065	Documentation for settings.CSRF_COOKIE_DOMAIN confusing	Anthony	Carlton Gibson	"The current documentation for settings.CSRF_COOKIE_DOMAIN states:
> ... easily allowing cross-subdomain requests to be excluded from the normal cross site request forgery protection.
Then goes on to say:
> It should be set to a string such as ""example.com"" to allow a POST request from a form on one subdomain to be accepted by a view served from another subdomain.

I don't believe this is correct as according to the CSRF protection documentation (and my own experience):
> If the CSRF_COOKIE_DOMAIN setting is set, the referer is compared against it. This setting supports subdomains. For example, CSRF_COOKIE_DOMAIN = '.example.com' will allow POST requests from www.example.com and api.example.com. If the setting is not set, then the referer must match the HTTP Host header.

I believe it should either state that:
- setting it to ""example.com"" **restricts** POST requests to form submissions with an HTTP Referer header exactly matching ""example.com"" only
or
- setting it to **"".example.com""** to allow a POST request from a form on any subdomain of ""example.com"" (including ""example.com"" with no subdomain)

It should probably also state that (at least according to the above CSRF protection documentation) a default CSRF_COOKIE_DOMAIN value of None is equal to the HTTP Host header.

I found that the documentation for SESSION_COOKIE_DOMAIN and LANGUAGE_COOKIE_DOMAIN compounded my confusion by both stating:
> Set this to a string such as ""example.com"" for cross-domain cookies
which does not hold true for CSRF_COOKIE_DOMAIN

When looking at the 'Domain' part of https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie it specifies that leading dots are ignored but subdomains are always included. It may be worth highlighting that the leading dot is significant in Django (at least for CSRF_COOKIE_DOMAIN), even if it is not in setting cookies any more.

----

Perhaps it would be better to separate the actual cookie domain specification from the behaviour of the HTTP Referer check so that the all _COOKIE_DOMAIN functionality and documentation can remain consistent and the HTTP Referer subdomain check can be configured separately in a more clear fashion?

PS: Love the project, keep up the fantastic work"	Bug	closed	Documentation	3.1	Normal	fixed	cookie, domain, csrf	Anthony	Ready for checkin	1	0	0	0	0	0