Fixed #16010 -- Added Origin header checking to CSRF middleware.

Thanks David Benjamin for the original patch, and Florian
Apolloner, Chris Jerdonek, and Adam Johnson for reviews.

docs/ref/csrf.txt

@@ -263,10 +263,15 @@ The CSRF protection is based on the following things:
 
    This check is done by ``CsrfViewMiddleware``.
 
-#. In addition, for HTTPS requests, strict referer checking is done by
-   ``CsrfViewMiddleware``. This means that even if a subdomain can set or
-   modify cookies on your domain, it can't force a user to post to your
-   application since that request won't come from your own exact domain.
+#. ``CsrfViewMiddleware`` verifies the `Origin header`_, if provided by the
+   browser, against the current host and the :setting:`CSRF_TRUSTED_ORIGINS`
+   setting. This provides protection against cross-subdomain attacks.
+
+#. In addition, for HTTPS requests, if the ``Origin`` header isn't provided,
+   ``CsrfViewMiddleware`` performs strict referer checking. This means that
+   even if a subdomain can set or modify cookies on your domain, it can't force
+   a user to post to your application since that request won't come from your
+   own exact domain.
 
    This also addresses a man-in-the-middle attack that's possible under HTTPS
    when using a session independent secret, due to the fact that HTTP
@@ -284,6 +289,10 @@ The CSRF protection is based on the following things:
    Expanding the accepted referers beyond the current host or cookie domain can
    be done with the :setting:`CSRF_TRUSTED_ORIGINS` setting.
 
+.. versionadded:: 4.0
+
+    ``Origin`` checking was added, as described above.
+
 This ensures that only forms that have originated from trusted domains can be
 used to POST data back.
 
@@ -314,6 +323,7 @@ vulnerability allows and much worse).
     sites.
 
 .. _BREACH: http://breachattack.com/
+.. _Origin header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin
 .. _disable the referer: https://www.w3.org/TR/referrer-policy/#referrer-policy-delivery
 
 Caching

docs/ref/settings.txt

@@ -459,13 +459,18 @@ Default: ``[]`` (Empty list)
 
 A list of trusted origins for unsafe requests (e.g. ``POST``).
 
+For requests that include the ``Origin`` header, Django's CSRF protection
+requires that header match the origin present in the ``Host`` header.
+
 For a :meth:`secure <django.http.HttpRequest.is_secure>` unsafe
-request, Django's CSRF protection requires that the request have a ``Referer``
-header that matches the origin present in the ``Host`` header. This prevents,
-for example, a ``POST`` request from ``subdomain.example.com`` from succeeding
-against ``api.example.com``. If you need cross-origin unsafe requests over
-HTTPS, continuing the example, add ``'https://subdomain.example.com'`` to this
-list (and/or ``http://...`` if requests originate from an insecure page).
+request that doesn't include the ``Origin`` header, the request must have a
+``Referer`` header that matches the origin present in the ``Host`` header.
+
+These checks prevent, for example, a ``POST`` request from
+``subdomain.example.com`` from succeeding against ``api.example.com``. If you
+need cross-origin unsafe requests, continuing the example, add
+``'https://subdomain.example.com'`` to this list (and/or ``http://...`` if
+requests originate from an insecure page).
 
 The setting also supports subdomains, so you could add
 ``'https://*.example.com'``, for example, to allow access from all subdomains
@@ -476,6 +481,8 @@ of ``example.com``.
     The values in older versions must only include the hostname (possibly with
     a leading dot) and not the scheme or an asterisk.
 
+    Also, ``Origin`` header checking isn't performed in older versions.
+
 .. setting:: DATABASES
 
 ``DATABASES``

docs/releases/4.0.txt

@@ -149,7 +149,9 @@ Cache
 CSRF
 ~~~~
 
-* ...
+* CSRF protection now consults the ``Origin`` header, if present. To facilitate
+  this, :ref:`some changes <csrf-trusted-origins-changes-4.0>` to the
+  :setting:`CSRF_TRUSTED_ORIGINS` setting are required.
 
 Decorators
 ~~~~~~~~~~
@@ -323,6 +325,15 @@ the dot. For example, change ``'.example.com'`` to ``'https://*.example.com'``.
 
 A system check detects any required changes.
 
+Configuring it may now be required
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As CSRF protection now consults the ``Origin`` header, you may need to set
+:setting:`CSRF_TRUSTED_ORIGINS`, particularly if you allow requests from
+subdomains by setting :setting:`CSRF_COOKIE_DOMAIN` (or
+:setting:`SESSION_COOKIE_DOMAIN` if :setting:`CSRF_USE_SESSIONS` is enabled) to
+a value starting with a dot.
+
 Miscellaneous
 -------------