|
1 | 1 | How to Implement CSRF Protection |
2 | 2 | ================================ |
3 | 3 |
|
4 | | -CSRF -or `Cross-site request forgery`_ -is amethod by whicha malicious |
5 | | -userattempts to make your legitimate users unknowingly submit data that |
6 | | -they don't intend to submit. |
| 4 | +CSRF,or `Cross-site request forgery`_,is atype of attack wherea malicious actor |
| 5 | +tricks auserinto performing actions on a web application without their knowledge |
| 6 | +or consent. |
7 | 7 |
|
8 | | -CSRF protection works by adding a hidden field to your form that contains a |
9 | | -value that only you and your user know. This ensures that the user - not some |
10 | | -other entity - is submittingthegiven data. |
| 8 | +The attack is based on the trust that a web application has in a user's browser |
| 9 | +(e.g. on session cookies). Here's a real example of a CSRF attack: a malicious |
| 10 | +actor could createthefollowing website: |
11 | 11 |
|
12 | | -Before using the CSRF protection, install it in your project: |
| 12 | +..code-block::html |
| 13 | + |
| 14 | + <html> |
| 15 | + <body> |
| 16 | + <formaction="https://example.com/settings/update-email"method="POST"> |
| 17 | + <inputtype="hidden"name="email"value="malicious-actor-address@some-domain.com"/> |
| 18 | + </form> |
| 19 | + <script> |
| 20 | +document.forms[0].submit(); |
| 21 | +</script> |
| 22 | + |
| 23 | +<!-- some content here to distract the user--> |
| 24 | + </body> |
| 25 | + </html> |
| 26 | + |
| 27 | +If you visit this website (e.g. by clicking on some email link or some social |
| 28 | +network post) and you were already logged in on the ``https://example.com`` site, |
| 29 | +the malicious actor could change the email address associated to your account |
| 30 | +(effectively taking over your account) without you even being aware of it. |
| 31 | + |
| 32 | +An effective way of preventing CSRF attacks is to use anti-CSRF tokens. These are |
| 33 | +unique tokens added to forms as hidden fields. The legit server validates them to |
| 34 | +ensure that the request originated from the expected source and not some other |
| 35 | +malicious website. |
| 36 | + |
| 37 | +Installation |
| 38 | +------------ |
| 39 | + |
| 40 | +Symfony provides all the needed features to generate and validate the anti-CSRF |
| 41 | +tokens. Before using them, install this package in your project: |
13 | 42 |
|
14 | 43 | ..code-block::terminal |
15 | 44 |
|
@@ -75,9 +104,9 @@ protected forms. As an alternative, you can: |
75 | 104 | CSRF Protection in Symfony Forms |
76 | 105 | -------------------------------- |
77 | 106 |
|
78 | | -Forms created with theSymfonyForm component include CSRF tokens by default |
79 | | -and Symfonychecks them automatically, so you don't have to do anything to be |
80 | | -protected against CSRF attacks. |
| 107 | +:doc:`SymfonyForms</forms>` include CSRF tokens by default and Symfony also |
| 108 | +checks them automatically for you. So, when using Symfony Forms, you don't have |
| 109 | +o do anything to beprotected against CSRF attacks. |
81 | 110 |
|
82 | 111 | .. _form-csrf-customization: |
83 | 112 |
|
@@ -117,12 +146,15 @@ You can also customize the rendering of the CSRF form field creating a custom |
117 | 146 | the field (e.g. define ``{% block csrf_token_widget %} ... {% endblock %}`` to |
118 | 147 | customize the entire form field contents). |
119 | 148 |
|
120 | | -CSRF Protection in Login Forms |
121 | | ------------------------------- |
| 149 | +.. _csrf-protection-in-login-forms: |
| 150 | + |
| 151 | +CSRF Protection in Login Form and Logout Action |
| 152 | +----------------------------------------------- |
| 153 | + |
| 154 | +Read the following: |
122 | 155 |
|
123 | | -See:ref:`form_login-csrf` for a login form that is protected from CSRF |
124 | | -attacks. You can also configure the |
125 | | -:ref:`CSRF protection for the logout action<reference-security-logout-csrf>`. |
| 156 | +*:ref:`CSRF Protection in Login Forms<form_login-csrf>`; |
| 157 | +*:ref:`CSRF protection for the logout action<reference-security-logout-csrf>`. |
126 | 158 |
|
127 | 159 | .. _csrf-protection-in-html-forms: |
128 | 160 |
|
|