8000 Reworded the article about form login redirects · symfony/symfony-docs@5015723 · GitHub
[go: up one dir, main page]
Skip to content

Commit 5015723

< 8000 span data-component="leadingVisual" class="prc-Button-Visual-2epfX prc-Button-VisualWrap-Db-eB">Browse files
javiereguiluzxabbuh
javiereguiluz
authored and
xabbuh
committed
Reworded the article about form login redirects
1 parent 7a58612 commit 5015723

File tree

1 file changed

+139
-92
lines changed

1 file changed

+139
-92
lines changed

‎security/form_login.rst

Lines changed: 139 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,42 @@
11
.. index::
2-
single: Security; Customizing form login
2+
single: Security; Customizing form login redirect
33

4-
How to Customize your Form Login
5-
================================
4+
How to Customize Redirect After Form Login
5+
==========================================
66

7-
Using a :doc:`form login </security/form_login_setup>` for authentication
8-
is a common, and flexible, method for handling authentication in Symfony.
9-
Pretty much every aspect of the form login can be customized. The full, default
10-
configuration is shown in the next section.
11-
12-
Form Login Configuration Reference
13-
----------------------------------
14-
15-
To see the full form login configuration reference, see
16-
:doc:`/reference/configuration/security`. Some of the more interesting options
17-
are explained below.
7+
Using a :doc:`form login </security/form_login_setup>` for authentication is a
8+
common, and flexible, method for handling authentication in Symfony. This
9+
article explains how to customize the URL which the user is redirected to after
10+
a successful or failed login. Check out the full
11+
:doc:`form login configuration reference </reference/configuration/security>` to
12+
learn of the possible customization options.
1813

1914
Redirecting after Success
2015
-------------------------
2116

22-
You can change where the login form redirects after a successful login using
23-
the various config options. By default the form will redirect to the URL the
24-
user requested (i.e. the URL which triggered the login form being shown).
25-
For example, if the user requested ``http://www.example.com/admin/post/18/edit``,
26-
then after they successfully log in, they will eventually be sent back to
27-
``http://www.example.com/admin/post/18/edit``.
28-
This is done by storing the requested URL in the session.
29-
If no URL is present in the session (perhaps the user went
30-
directly to the login page), then the user is redirected to the default page,
31-
which is ``/`` (i.e. the homepage) by default. You can change this behavior
32-
in several ways.
17+
By default, the form will redirect to the URL the user requested (i.e. the URL
18+
which triggered the login form being shown). For example, if the user requested
19+
``http://www.example.com/admin/post/18/edit``, then after they have successfully
20+
logged in, they will be sent back to ``http://www.example.com/admin/post/18/edit``.
21+
22+
This is done by storing the requested URL in the session. If no URL is present
23+
in the session (perhaps the user went directly to the login page), then the user
24+
is redirected to ``/`` (i.e. the homepage). You can change this behavior in
25+
several ways.
3326

3427
.. note::
3528

36-
As mentioned, by default the user is redirected back to the page originally
37-
requested. Sometimes, this can cause problems, like if a background Ajax
38-
request "appears" to be the last visited URL, causing the user to be
39-
redirected there. For information on controlling this behavior, see
40-
:doc:`/security/target_path`.
29+
Sometimes, redirecting to the originally requested page can cause problems,
30+
like if a background Ajax request "appears" to be the last visited URL,
31+
causing the user to be redirected there. For information on controlling this
32+
behavior, see :doc:`/security/target_path`.
4133

4234
Changing the default Page
4335
~~~~~~~~~~~~~~~~~~~~~~~~~
4436

45-
First, the default page can be set (i.e. the page the user is redirected to
46-
if no previous page was stored in the session). To set it to the
47-
``default_security_target`` route use the following config:
37+
Define the ``default_security_target`` option to change the page where the user
38+
is redirected to if no previous page was stored in the session. The value can be
39+
a relative/absolute URL or a Symfony route name:
4840

4941
.. configuration-block::
5042

@@ -58,7 +50,7 @@ if no previous page was stored in the session). To set it to the
5850
main:
5951
form_login:
6052
# ...
61-
default_target_path: default_security_target
53+
default_target_path: after_login_route_name
6254
6355
.. code-block:: xml
6456
@@ -74,7 +66,7 @@ if no previous page was stored in the session). To set it to the
7466
<!-- ... -->
7567
7668
<firewall name="main">
77-
<form-login default-target-path="default_security_target" />
69+
<form-login default-target-path="after_login_route_name" />
7870
</firewall>
7971
</config>
8072
</srv:container>
@@ -91,21 +83,17 @@ if no previous page was stored in the session). To set it to the
9183
9284
'form_login' => array(
9385
// ...
94-
'default_target_path' => 'default_security_target',
86+
'default_target_path' => 'after_login_route_name',
9587
),
9688
),
9789
),
9890
));
9991
100-
Now, when no URL is set in the session, users will be sent to the
101-
``default_security_target`` route.
102-
10392
Always Redirect to the default Page
10493
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10594

106-
You can make it so that users are always redirected to the default page regardless
107-
of what URL they had requested previously by setting the
108-
``always_use_default_target_path`` option to true:
95+
Define the ``always_use_default_target_path`` boolean option to ignore the
96+
previously requested URL and always redirect to the default page:
10997

11098
.. configuration-block::
11199

@@ -159,12 +147,52 @@ of what URL they had requested previously by setting the
159147
),
160148
));
161149
150+
.. _control-the-redirect-url-from-inside-the-form:
151+
152+
Control the Redirect Using Request Parameters
153+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
154+
155+
The URL to redirect after the login can be defined using the ``_target_path``
156+
parameter of GET and POST requests. Its value must be a relative or absolute
157+
URL, not a Symfony route name.
158+
159+
Defining the redirect URL via GET using a query string parameter:
160+
161+
.. code-block:: text
162+
163+
http://example.com/some/path?_target_path=/dashboard
164+
165+
Defining the redirect URL via POST using a hidden form field:
166+
167+
.. configuration-block::
168+
169+
.. code-block:: html+twig
170+
171+
{# app/Resources/views/security/login.html.twig #}
172+
<form action="{{ path('login') }}" method="post">
173+
{# ... #}
174+
175+
<input type="hidden" name="_target_path" value="{{ path('account') }}" />
176+
<input type="submit" name="login" />
177+
</form>
178+
179+
.. code-block:: html+php
180+
181+
<!-- app/Resources/views/security/login.html.php -->
182+
<form action="<?php echo $view['router']->generate('login') ?>" method="post">
183+
// ...
184+
185+
<input type="hidden" name="_target_path" value="<?php echo $view['router']->generate('account') ?>" />
186+
<input type="submit" name=&qu 10000 ot;login" />
187+
</form>
188+
162189
Using the Referring URL
163190
~~~~~~~~~~~~~~~~~~~~~~~
164191

165-
In case no previous URL was stored in the session, you may wish to try using
166-
the ``HTTP_REFERER`` instead, as this will often be the same. You can do
167-
this by setting ``use_referer`` to true (it defaults to false):
192+
In case no previous URL was stored in the session and no ``_target_path``
193+
parameter is included in the request, you may use the value of the
194+
``HTTP_REFERER`` header instead, as this will often be the same. Define the
195+
``use_referer`` boolean option to enable this behavior:
168196

169197
.. configuration-block::
170198

@@ -218,12 +246,19 @@ this by setting ``use_referer`` to true (it defaults to false):
218246
),
219247
));
220248
221-
Redirecting on Login Failure
222-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
249+
.. note::
250+
251+
The referrer URL is only used when it is different from the URL generated by
252+
the ``login_path`` route to avoid a redirection loop.
253+
254+
.. _redirecting-on-login-failure:
255+
256+
Redirecting after Failure
257+
-------------------------
223258

224259
After a failed login (e.g. an invalid username or password was submitted), the
225260
user is redirected back to the login form itself. Use the ``failure_path``
226-
option to define the route or URL the user is redirected to:
261+
option to define a new target via a relative/absolute URL or a Symfony route name:
227262

228263
.. configuration-block::
229264

@@ -238,7 +273,7 @@ option to define the route or URL the user is redirected to:
238273
# ...
239274
form_login:
240275
# ...
241-
failure_path: login_failure
276+
failure_path: login_failure_route_name
242277
243278
.. code-block:: xml
244279
@@ -255,7 +290,7 @@ option to define the route or URL the user is redirected to:
255290
256291
<firewall name="main">
257292
<!-- ... -->
258-
<form-login failure-path="login_failure" />
293+
<form-login failure-path="login_failure_route_name" />
259294
</firewall>
260295
</config>
261296
</srv:container>
@@ -271,65 +306,46 @@ option to define the route or URL the user is redirected to:
271306
// ...
272307
'form_login' => array(
273308
// ...
274-
'failure_path' => 'login_failure',
309+
'failure_path' => 'login_failure_route_name',
275310
),
276311
),
277312
),
278313
));
279314
280-
Control the Redirect URL from inside the Form
281-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
315+
This option can also be set via the ``_failure_path`` request parameter:
282316

283-
You can also override where the user is redirected to via the form itself by
284-
including a hidden field with the name ``_target_path`` for successful logins
285-
and ``_failure_path`` for login errors:
317+
.. code-block:: text
318+
319+
http://example.com/some/path?_failure_path=/forgot-password
286320
287321
.. configuration-block::
288322

289323
.. code-block:: html+twig
290324

291-
{# src/AppBundle/Resources/views/Security/login.html.twig #}
292-
{% if error %}
293-
<div>{{ error.message }}</div>
294-
{% endif %}
295-
325+
{# app/Resources/views/security/login.html.twig #}
296326
<form action="{{ path('login') }}" method="post">
297-
<label for="username">Username:</label>
298-
<input type="text" id="username" name="_username" value="{{ last_username }}" />
299-
300-
<label for="password">Password:</label>
301-
<input type="password" id="password" name="_password" />
302-
303-
<input type="hidden" name="_target_path" value="account" />
304-
<input type="hidden" name="_failure_path" value="login" />
327+
{# ... #}
305328

329+
<input type="hidden" name="_failure_path" value="{{ path('forgot_password') }}" />
306330
<input type="submit" name="login" />
307331
</form>
308332

309333
.. code-block:: html+php
310334

311-
<!-- src/AppBundle/Resources/views/Security/login.html.php -->
312-
<?php if ($error): ?>
313-
<div><?php echo $error->getMessage() ?></div>
314-
<?php endif ?>
315-
335+
<!-- app/Resources/views/security/login.html.php -->
316336
<form action="<?php echo $view['router']->generate('login') ?>" method="post">
317-
<label for="username">Username:</label>
318-
<input type="text" id="username" name="_username" value="<?php echo $last_username ?>" />
319-
320-
<label for="password">Password:</label>
321-
<input type="password" id="password" name="_password" />
322-
323-
<input type="hidden" name="_target_path" value="account" />
324-
<input type="hidden" name="_failure_path" value="login" />
337+
<!-- ... -->
325338

339+
<input type="hidden" name="_failure_path" value="<?php echo $view['router']->generate('forgot_password') ?>" />
326340
<input type="submit" name="login" />
327341
</form>
328342

329-
Now, the user will be redirected to the value of the hidden form field. The
330-
value attribute can be a relative path, absolute URL, or a route name.
331-
The name of the hidden fields in the login form is also configurable using the
332-
``target_path_parameter`` and ``failure_path_parameter`` options of the firewall.
343+
Customizing the Target and Failure Request Parameters
344+
-----------------------------------------------------
345+
346+
The name of the request attributes used to define the success and failure login
347+
redirects can be customized using the ``target_path_parameter`` and
348+
``failure_path_parameter`` options of the firewall that defines the login form.
333349

334350
.. configuration-block::
335351

@@ -343,8 +359,8 @@ The name of the hidden fields in the login form is also configurable using the
343359
main:
344360
# ...
345361
form_login:
346-
target_path_parameter: login_success
347-
failure_path_parameter: login_fail
362+
target_path_parameter: go_to
363+
failure_path_parameter: back_to
348364
349365
.. code-block:: xml
350366
@@ -361,8 +377,8 @@ The name of the hidden fields in the login form is also configurable using the
361377
362378
<firewall name="main">
363379
<!-- ... -->
364-
<form-login target-path-parameter="login_success" />
365-
<form-login failure-path-parameter="login_fail" />
380+
<form-login target-path-parameter="go_to" />
381+
<form-login failure-path-parameter="back_to" />
366382
</firewall>
367383
</config>
368384
</srv:container>
@@ -377,9 +393,40 @@ The name of the hidden fields in the login form is also configurable using the
377393
'main' => array(
378394
// ...
379395
'form_login' => array(
380-
'target_path_parameter' => 'login_success',
381-
'failure_path_parameter' => 'login_fail',
396+
'target_path_parameter' => 'go_to',
397+
'failure_path_parameter' => 'back_to',
382398
),
383399
),
384400
),
385401
));
402+
403+
Using the above configuration, the query string parameters and hidden form fields
404+
are now fully customized:
405+
406+
.. code-block:: text
407+
408+
http://example.com/some/path?go_to=/dashboard&back_to=/forgot-password
409+
410+
.. configuration-block::
411+
412+
.. code-block:: html+twig
413+
414+
{# app/Resources/views/security/login.html.twig #}
415+
<form action="{{ path('login') }}" method="post">
416+
{# ... #}
417+
418+
<input type="hidden" name="go_to" value="{{ path('dashboard') }}" />
419+
<input type="hidden" name="back_to" value="{{ path('forgot_password') }}" />
420+
<input type="submit" name="login" />
421+
</form>
422+
423+
.. code-block:: html+php
424+
425+
<!-- app/Resources/views/security/login.html.php -->
426+
<form action="<?php echo $view['router']->generate('login') ?>" method="post">
427+
<!-- ... -->
428+
429+
<input type="hidden" name="go_to" value="<?php echo $view['router']->generate('dashboard') ?>" />
430+
<input type="hidden" name="back_to" value="<?php echo $view['router']->generate('forgot_password') ?>" />
431+
<input type="submit" name="login" />
432+
</form>

0 commit comments

Comments
 (0)
0