Skip to content
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

csrf_token_generator and csrf_token_id documentation #6152

Merged
merged 4 commits into from
Jan 16, 2016
+32 −15
Merged

csrf_token_generator and csrf_token_id documentation #6152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0044aa2
Updated csrf_in_login_form.rst to include csrf_token_id and csrf_toke…
Raistlfiren Dec 1, 2015
91b5e2e
Updated documentation as requested by @stof and @xabbuh
Dec 2, 2015
3ceb61c
Improper markdown for versionadded.
Dec 2, 2015
304d7a5
finish csrf_token_generator and csrf_token_id docs
xabbuh Jan 15, 2016
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
10 changes: 7 additions & 3 deletions book/forms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1809,7 +1809,7 @@ The CSRF token can be customized on a form-by-form basis. For example::
'csrf_protection' => true,
'csrf_field_name' => '_token',
// a unique key to help generate the secret token
'intention' => 'task_item',
'csrf_token_id' => 'task_item',
));
}

Expand All @@ -1825,8 +1825,12 @@ section.

.. note::

The ``intention`` option is optional but greatly enhances the security of
the generated token by making it different for each form.
The ``csrf_token_id`` option is optional but greatly enhances the security
of the generated token by making it different for each form.

.. versionadded:: 2.4
The ``csrf_token_id`` option was introduced in Symfony 2.4. Prior, you
had to use the ``intention`` option.

.. caution::

Expand Down
22 changes: 15 additions & 7 deletions cookbook/security/csrf_in_login_form.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ provider available in the Security component:
# ...
form_login:
# ...
csrf_provider: security.csrf.token_manager
csrf_token_generator: security.csrf.token_manager

.. code-block:: xml

Expand All @@ -50,7 +50,7 @@ provider available in the Security component:

<firewall name="secured_area">
<!-- ... -->
<form-login csrf-provider="security.csrf.token_manager" />
<form-login csrf-token-generator="security.csrf.token_manager" />
</firewall>
</config>
</srv:container>
Expand All @@ -66,12 +66,16 @@ provider available in the Security component:
// ...
'form_login' => array(
// ...
'csrf_provider' => 'security.csrf.token_manager',
'csrf_token_generator' => 'security.csrf.token_manager',
),
),
),
));

.. versionadded:: 2.4
The ``csrf_token_generator`` option was introduced in Symfony 2.4. Prior,
you had to use the ``csrf_provider`` option.

The Security component can be configured further, but this is all information
it needs to be able to use CSRF in the login form.

Expand Down Expand Up @@ -122,7 +126,7 @@ After this, you have protected your login form against CSRF attacks.
.. tip::

You can change the name of the field by setting ``csrf_parameter`` and change
the token ID by setting ``intention`` in your configuration:
the token ID by setting ``csrf_token_id`` in your configuration:

.. configuration-block::

Expand All @@ -138,7 +142,7 @@ After this, you have protected your login form against CSRF attacks.
form_login:
# ...
csrf_parameter: _csrf_security_token
intention: a_private_string
csrf_token_id: a_private_string

.. code-block:: xml

Expand All @@ -156,7 +160,7 @@ After this, you have protected your login form against CSRF attacks.
<firewall name="secured_area">
<!-- ... -->
<form-login csrf-parameter="_csrf_security_token"
intention="a_private_string"
csrf-token-id="a_private_string"
/>
</firewall>
</config>
Expand All @@ -174,11 +178,15 @@ After this, you have protected your login form against CSRF attacks.
'form_login' => array(
// ...
'csrf_parameter' => '_csrf_security_token',
'intention' => 'a_private_string',
'csrf_token_id' => 'a_private_string'
),
),
),
));

.. versionadded:: 2.4
The ``csrf_token_id`` option was introduced in Symfony 2.4. Prior, you
had to use the ``intention`` option.

.. _`Cross-site request forgery`: https://en.wikipedia.org/wiki/Cross-site_request_forgery
.. _`Forging Login Requests`: https://en.wikipedia.org/wiki/Cross-site_request_forgery#Forging_login_requests
15 changes: 10 additions & 5 deletions reference/configuration/security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,11 @@ Each part will be explained in the next section.
Support for restricting security firewalls to specific http methods was introduced in
Symfony 2.5.

.. versionadded:: 2.4
The ``csrf_token_generator`` and ``csrf_token_id`` were introduced in
Symfony 2.4. Prior, you had to use the ``csrf_provider`` and ``intention``
options.

.. configuration-block::

.. code-block:: yaml
Expand Down Expand Up @@ -165,9 +170,9 @@ Each part will be explained in the next section.
password_parameter: _password

# csrf token options
csrf_parameter: _csrf_token
intention: authenticate
csrf_provider: my.csrf_provider.id
csrf_parameter: _csrf_token
csrf_token_id: authenticate
csrf_token_generator: my.csrf_token_generator.id

# by default, the login form *must* be a POST, not a GET
post_only: true
Expand Down Expand Up @@ -213,8 +218,8 @@ Each part will be explained in the next section.
context: ~
logout:
csrf_parameter: _csrf_token
csrf_provider: ~
intention: logout
csrf_token_generator: ~
csrf_token_id: logout
path: /logout
target: /
success_handler: ~
Expand Down