Documentation for settings.CSRF_COOKIE_DOMAIN confusing

[Anthony]

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

[Carlton Gibson]

Yes, thanks — I think you're right. Set-Cookie doesn't need the leading dot, but the CSRF check does.

I think a small regression in afd375fc343baa46e61036087bc43b3d096bb0ca for #28741

​PR

[Carlton Gibson <carlton@…>]

In 3d4ffd1f:

Fixed #32065 -- Restored leading dot to CSRF_COOKIE_DOMAIN examples.

Partially reverts afd375fc343baa46e61036087bc43b3d096bb0ca.

Thanks to Tim Graham for review.

[Carlton Gibson <carlton.gibson@…>]

In 1f8dbc8f:

[3.1.x] Fixed #32065 -- Restored leading dot to CSRF_COOKIE_DOMAIN examples.

Partially reverts afd375fc343baa46e61036087bc43b3d096bb0ca.

Thanks to Tim Graham for review.

Backport of 3d4ffd1ff0eb9343ee41de77caf6ae427b6e873c from master

[Mariusz Felisiak <felisiak.mariusz@…>]

In 2e7ba605:

Refs #28741 -- Doc'd SESSION_COOKIE_DOMAIN requirement with CSRF_USE_SESSIONS.

Similar considerations as refs #32065, again adding some nuance to
afd375fc343baa46e61036087bc43b3d096bb0ca.

[Mariusz Felisiak <felisiak.mariusz@…>]

In f4db2d1:

[3.1.x] Refs #28741 -- Doc'd SESSION_COOKIE_DOMAIN requirement with CSRF_USE_SESSIONS.

Similar considerations as refs #32065, again adding some nuance to
afd375fc343baa46e61036087bc43b3d096bb0ca.

Backport of 2e7ba6057cfc82a15a22b6021cd60cf307152e2d from master