Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#32065 closed Bug (fixed)

Documentation for settings.CSRF_COOKIE_DOMAIN confusing

Reported by: Anthony Owned by: Carlton Gibson
Component: Documentation Version: 3.1
Severity: Normal Keywords: cookie, domain, csrf
Cc: Anthony Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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

Change History (7)

comment:1 by Anthony, 4 years ago

Cc: Anthony added

comment:2 by Carlton Gibson, 4 years ago

Owner: changed from nobody to Carlton Gibson
Status: newassigned
Triage Stage: UnreviewedAccepted

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

comment:3 by Mariusz Felisiak, 4 years ago

Has patch: set
Triage Stage: AcceptedReady for checkin

comment:4 by Carlton Gibson <carlton@…>, 4 years ago

Resolution: fixed
Status: assignedclosed

In 3d4ffd1f:

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

Partially reverts afd375fc343baa46e61036087bc43b3d096bb0ca.

Thanks to Tim Graham for review.

comment:5 by Carlton Gibson <carlton.gibson@…>, 4 years ago

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

comment:6 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

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.

comment:7 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

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

Note: See TracTickets for help on using tickets.
Back to Top