Skip to content

Added docs for cookie_samesite option #10258

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 5, 2018
Merged

Added docs for cookie_samesite option #10258

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions reference/configuration/framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ Configuration
* `cookie_httponly`_
* `cookie_lifetime`_
* `cookie_path`_
* `cookie_samesite`_
* `cookie_secure`_
* `gc_divisor`_
* `gc_maxlifetime`_
Expand Down Expand Up @@ -814,6 +815,40 @@ This determines the domain to set in the session cookie. By default it's
blank, meaning the host name of the server which generated the cookie according
to the cookie specification.

cookie_samesite
...............

**type**: ``string`` or ``null`` **default**: ``'lax'``

. versionadded:: 4.2
The ``cookie_samesite`` option was introduced in Symfony 4.2.

It controls they way cookies are sent when the HTTP request was not originated
from the same domain the cookies are associated to. Setting this option is
recommended to mitigate `CSRF security attacks`_.

By default, browsers send all cookies related to the domain of the HTTP request.
This may be a problem for example when you visit a forum and some malicious
comment includes a link like ``https://some-bank.com/?send_money_to=attacker&amount=1000``.
If you were previously logged into your bank website, the browser will send all
those cookies when making that HTTP request.

The possible values for this option are:

* ``null``, use it to disable this protection. Same behavior as in older Symfony
versions.
* ``'strict'`` (or the ``Cookie::SAMESITE_STRICT`` constant), use it to never
send any cookie when the HTTP request is not originated from the same domain.
* ``'lax'`` (or the ``Cookie::SAMESITE_LAX`` constant), use it to allow sending
cookies when the request originated from a different domain, but only when the
user consciously made the request (by clicking a link or submitting a form
with the ``GET`` method).

.. note::

This option is available starting from PHP 7.3, but Symfony has a polyfill
so you can use it with any older PHP version as well.

cookie_secure
.............

Expand Down Expand Up @@ -2023,3 +2058,4 @@ available, or to ``flock`` otherwise. Store's DSN are also allowed.
.. _`gulp-rev`: https://www.npmjs.com/package/gulp-rev
.. _`webpack-manifest-plugin`: https://www.npmjs.com/package/webpack-manifest-plugin
.. _`error_reporting PHP option`: https://secure.php.net/manual/en/errorfunc.configuration.php#ini.error-reporting
.. _`CSRF security attacks`: https://en.wikipedia.org/wiki/Cross-site_request_forgery