8000 minor #8192 Reworded the article about form login redirects (javiereg… · symfony/symfony-docs@bd74006 · GitHub
[go: up one dir, main page]
Skip to content

Commit bd74006

Browse files
xabbuhxabbuh
committed
minor #8192 Reworded the article about form login redirects (javiereguiluz)
This PR was squashed before being merged into the 2.7 branch (closes #8192). Discussion ---------- Reworded the article about form login redirects Now that form login redirects have been fully fixed (see symfony/symfony#23580) I thought about updating this article, specially its structure. All changes are simple rewordings, except this one: previously, the article said that you can use a Symfony route name as the value of the `_target_path` parameter in the query string or the hidden form field. But if you check the code of this feature, it looks like you can't because we use the value of that parameter "as is" to redirect, so it must be a relative/absolute URL, right? ```php protected function determineTargetUrl(Request $request) { if ($this->options['always_use_default_target_path']) { return $this->options['default_target_path']; } // We redirect directly to the value of the parameter, so it can't be a route name, right ???? if ($targetUrl = $request->get($this->options['target_path_parameter'], null, true)) { return $targetUrl; } // ... } ``` Commits ------- 5015723 Reworded the article about form login redirects
2 parents 096046c + 5015723 commit bd74006

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
68FA
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="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