diff --git a/docs/guide/security.rst b/docs/guide/security.rst index 4d658790a3..0bd75871e4 100644 --- a/docs/guide/security.rst +++ b/docs/guide/security.rst @@ -338,6 +338,13 @@ for authentication, provides protection against XSRF attacks that is equivalent to Tornado's ``xsrf_cookies`` feature, so that feature is now deprecated. +You may wish to continue using ``xsrf_cookies`` in some situations: + +* If your application may perform side effects in response to HTTP GET + requests, but cannot use ``samesite="strict"``. +* If your authentication is based on something other than cookies, such + as TLS certificates or network addresses. + If you have an application that uses Tornado's ``xsrf_cookies`` feature and you want to migrate to the ``samesite`` cookie attribute, follow these steps: diff --git a/tornado/web.py b/tornado/web.py index 50d8c191e7..329c5068ac 100644 --- a/tornado/web.py +++ b/tornado/web.py @@ -745,6 +745,16 @@ def set_signed_cookie( Similar to `set_cookie`, the effect of this method will not be seen until the following request. + Consider setting additional attributes whenever you set a signed + cookie: + + * Use the ``samesite="lax"`` (or ``"strict"``) attribute on any + cookie used for authentication to protect against XSRF attacks. + * Use the ``secure=True`` attribute if your application is + only available over HTTPS. + * Use the ``httponly=True`` attribute unless you need this cookie + to be readable from javascript. + .. versionchanged:: 3.2.1 Added the ``version`` argument. Introduced cookie version 2