From 3e1edff0a9ff0181333a14b281970f9eb1b2a707 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 19 Jul 2017 10:28:11 +0200 Subject: [PATCH 1/4] Reworded the article about form login redirects --- security/form_login.rst | 222 ++++++++++++++++++++++++---------------- 1 file changed, 132 insertions(+), 90 deletions(-) diff --git a/security/form_login.rst b/security/form_login.rst index 7d87b96d712..3aac25aafd3 100644 --- a/security/form_login.rst +++ b/security/form_login.rst @@ -1,50 +1,42 @@ .. index:: - single: Security; Customizing form login + single: Security; Customizing form login redirect -How to Customize your Form Login -================================ +How to Customize Redirect After Form Login +========================================== -Using a :doc:`form login ` for authentication -is a common, and flexible, method for handling authentication in Symfony. -Pretty much every aspect of the form login can be customized. The full, default -configuration is shown in the next section. - -Form Login Configuration Reference ----------------------------------- - -To see the full form login configuration reference, see -:doc:`/reference/configuration/security`. Some of the more interesting options -are explained below. +Using a :doc:`form login ` for authentication is a +common, and flexible, method for handling authentication in Symfony. This +article explains how to customize the URL which the user is redirected to after +a successful or failure login. Check out the full +:doc:`form login configuration reference ` to +learn about the rest of possible customizations. Redirecting after Success ------------------------- -You can change where the login form redirects after a successful login using -the various config options. By default the form will redirect to the URL the -user requested (i.e. the URL which triggered the login form being shown). -For example, if the user requested ``http://www.example.com/admin/post/18/edit``, -then after they successfully log in, they will eventually be sent back to -``http://www.example.com/admin/post/18/edit``. -This is done by storing the requested URL in the session. -If no URL is present in the session (perhaps the user went -directly to the login page), then the user is redirected to the default page, -which is ``/`` (i.e. the homepage) by default. You can change this behavior -in several ways. +By default, the form will redirect to the URL the user requested (i.e. the URL +which triggered the login form being shown). For example, if the user requested +``http://www.example.com/admin/post/18/edit``, then after they successfully log +in, they will be sent back to ``http://www.example.com/admin/post/18/edit``. + +This is done by storing the requested URL in the session. If no URL is present +in the session (perhaps the user went directly to the login page), then the user +is redirected to ``/`` (i.e. the homepage). You can change this behavior in +several ways. .. note:: - As mentioned, by default the user is redirected back to the page originally - requested. Sometimes, this can cause problems, like if a background Ajax - request "appears" to be the last visited URL, causing the user to be - redirected there. For information on controlling this behavior, see - :doc:`/security/target_path`. + Sometimes, redirecting to the originally requested page can cause problems, + like if a background Ajax request "appears" to be the last visited URL, + causing the user to be redirected there. For information on controlling this + behavior, see :doc:`/security/target_path`. Changing the default Page ~~~~~~~~~~~~~~~~~~~~~~~~~ -First, the default page can be set (i.e. the page the user is redirected to -if no previous page was stored in the session). To set it to the -``default_security_target`` route use the following config: +Define the ``default_security_target`` option to change the page where the user +is redirected to if no previous page was stored in the session. The value can be + relative/absolute URL or a Symfony route name: .. configuration-block:: @@ -58,7 +50,7 @@ if no previous page was stored in the session). To set it to the main: form_login: # ... - default_target_path: default_security_target + default_target_path: after_login_route_name .. code-block:: xml @@ -74,7 +66,7 @@ if no previous page was stored in the session). To set it to the - + @@ -91,21 +83,17 @@ if no previous page was stored in the session). To set it to the 'form_login' => array( // ... - 'default_target_path' => 'default_security_target', + 'default_target_path' => 'after_login_route_name', ), ), ), )); -Now, when no URL is set in the session, users will be sent to the -``default_security_target`` route. - Always Redirect to the default Page ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can make it so that users are always redirected to the default page regardless -of what URL they had requested previously by setting the -``always_use_default_target_path`` option to true: +Define the ``always_use_default_target_path`` boolean option to ignore the +previously requested URL and always redirect to the default page: .. configuration-block:: @@ -159,12 +147,52 @@ of what URL they had requested previously by setting the ), )); +.. _control-the-redirect-url-from-inside-the-form: + +Control the Redirect Using Request Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The URL to redirect after the login can be defined using the ``_target_path`` +parameter of GET and POST requests. Its value must be a relative or absolute +URL, not a Symfony route name. + +Defining the redirect URL via GET using a query string parameter: + +.. code-block:: text + + http://example.com/some/path?_target_path=/dashboard + +Defining the redirect URL via POST using a hidden form field: + +.. configuration-block:: + + .. code-block:: html+twig + + {# src/AppBundle/Resources/views/Security/login.html.twig #} +
+ {# ... #} + + + +
+ + .. code-block:: html+php + + +
+ // ... + + + +
+ Using the Referring URL ~~~~~~~~~~~~~~~~~~~~~~~ -In case no previous URL was stored in the session, you may wish to try using -the ``HTTP_REFERER`` instead, as this will often be the same. You can do -this by setting ``use_referer`` to true (it defaults to false): +In case no previous URL was stored in the session and no ``_target_path`` +parameter is included in the request, you may wish to try using the value of the +``HTTP_REFERER`` header instead, as this will often be the same. Define the +``use_referer`` boolean option to enable this behavior: .. configuration-block:: @@ -218,12 +246,14 @@ this by setting ``use_referer`` to true (it defaults to false): ), )); -Redirecting on Login Failure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _redirecting-on-login-failure: + +Redirecting after Failure +------------------------- After a failed login (e.g. an invalid username or password was submitted), the user is redirected back to the login form itself. Use the ``failure_path`` -option to define the route or URL the user is redirected to: +option to define a new target via a relative/absolute URL or a Symfony route name: .. configuration-block:: @@ -238,7 +268,7 @@ option to define the route or URL the user is redirected to: # ... form_login: # ... - failure_path: login_failure + failure_path: login_failure_route_name .. code-block:: xml @@ -255,7 +285,7 @@ option to define the route or URL the user is redirected to: - + @@ -271,65 +301,46 @@ option to define the route or URL the user is redirected to: // ... 'form_login' => array( // ... - 'failure_path' => 'login_failure', + 'failure_path' => 'login_failure_route_name', ), ), ), )); -Control the Redirect URL from inside the Form -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This option can also be set via the ``_failure_path`` request parameter: + +.. code-block:: text -You can also override where the user is redirected to via the form itself by -including a hidden field with the name ``_target_path`` for successful logins -and ``_failure_path`` for login errors: + http://example.com/some/path?_failure_path=/forgot-password .. configuration-block:: .. code-block:: html+twig {# src/AppBundle/Resources/views/Security/login.html.twig #} - {% if error %} -
{{ error.message }}
- {% endif %} -
- - - - - - - - + {# ... #} +
.. code-block:: html+php - -
getMessage() ?>
- -
- - - - - - - - + // ... +
-Now, the user will be redirected to the value of the hidden form field. The -value attribute can be a relative path, absolute URL, or a route name. -The name of the hidden fields in the login form is also configurable using the -``target_path_parameter`` and ``failure_path_parameter`` options of the firewall. +Customizing the Target and Failure Request Parameters +----------------------------------------------------- + +The name of the request attributes used to define the success and failure login +redirects can be customized using the ``target_path_parameter`` and +``failure_path_parameter`` options of the firewall that defines the login form. .. configuration-block:: @@ -343,8 +354,8 @@ The name of the hidden fields in the login form is also configurable using the main: # ... form_login: - target_path_parameter: login_success - failure_path_parameter: login_fail + target_path_parameter: go_to + failure_path_parameter: back_to .. code-block:: xml @@ -361,8 +372,8 @@ The name of the hidden fields in the login form is also configurable using the - - + + @@ -377,9 +388,40 @@ The name of the hidden fields in the login form is also configurable using the 'main' => array( // ... 'form_login' => array( - 'target_path_parameter' => 'login_success', - 'failure_path_parameter' => 'login_fail', + 'target_path_parameter' => 'go_to', + 'failure_path_parameter' => 'back_to', ), ), ), )); + +Using the above configuration, the query string parameters and hidden form fields +are now fully customized: + +.. code-block:: text + + http://example.com/some/path?go_to=/dashboard&back_to=/forgot-password + +.. configuration-block:: + + .. code-block:: html+twig + + {# src/AppBundle/Resources/views/Security/login.html.twig #} +
+ {# ... #} + + + + +
+ + .. code-block:: html+php + + +
+ // ... + + + + +
From e4ee5186d7eb46906631504484e29544ec4c8e41 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 20 Jul 2017 08:38:26 +0200 Subject: [PATCH 2/4] Added some help notes --- security/form_login.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/security/form_login.rst b/security/form_login.rst index 3aac25aafd3..4852be12f22 100644 --- a/security/form_login.rst +++ b/security/form_login.rst @@ -190,7 +190,7 @@ Using the Referring URL ~~~~~~~~~~~~~~~~~~~~~~~ In case no previous URL was stored in the session and no ``_target_path`` -parameter is included in the request, you may wish to try using the value of the +parameter is included in the request, you may use the value of the ``HTTP_REFERER`` header instead, as this will often be the same. Define the ``use_referer`` boolean option to enable this behavior: @@ -246,6 +246,16 @@ parameter is included in the request, you may wish to try using the value of the ), )); +.. note:: + + For historical reasons, and to match the misspelling of the HTTP standard, + the option is called ``use_referer`` instead of ``use_referrer``. + +.. note:: + + The referrer URL is only used when is different from the URL generated by + the ``login_path`` route, to avoid a redirection loop. + .. _redirecting-on-login-failure: Redirecting after Failure From 5652ab0d00954645be13baa5c0b6ed0ebd69c048 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 20 Jul 2017 09:50:36 +0200 Subject: [PATCH 3/4] Removed a note that has been moved to the security config reference --- security/form_login.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/security/form_login.rst b/security/form_login.rst index 4852be12f22..de35bca7146 100644 --- a/security/form_login.rst +++ b/security/form_login.rst @@ -246,11 +246,6 @@ parameter is included in the request, you may use the value of the ), )); -.. note:: - - For historical reasons, and to match the misspelling of the HTTP standard, - the option is called ``use_referer`` instead of ``use_referrer``. - .. note:: The referrer URL is only used when is different from the URL generated by From 5d75e8bc6d01dde1bda67f110c4ff5849ab050db Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 21 Jul 2017 17:20:48 +0200 Subject: [PATCH 4/4] Fixed lots of issues --- security/form_login.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/security/form_login.rst b/security/form_login.rst index de35bca7146..3eaca7ca413 100644 --- a/security/form_login.rst +++ b/security/form_login.rst @@ -7,17 +7,17 @@ How to Customize Redirect After Form Login Using a :doc:`form login ` for authentication is a common, and flexible, method for handling authentication in Symfony. This article explains how to customize the URL which the user is redirected to after -a successful or failure login. Check out the full +a successful or failed login. Check out the full :doc:`form login configuration reference ` to -learn about the rest of possible customizations. +learn of the possible customization options. Redirecting after Success ------------------------- By default, the form will redirect to the URL the user requested (i.e. the URL which triggered the login form being shown). For example, if the user requested -``http://www.example.com/admin/post/18/edit``, then after they successfully log -in, they will be sent back to ``http://www.example.com/admin/post/18/edit``. +``http://www.example.com/admin/post/18/edit``, then after they have successfully +logged in, they will be sent back to ``http://www.example.com/admin/post/18/edit``. This is done by storing the requested URL in the session. If no URL is present in the session (perhaps the user went directly to the login page), then the user @@ -36,7 +36,7 @@ Changing the default Page Define the ``default_security_target`` option to change the page where the user is redirected to if no previous page was stored in the session. The value can be - relative/absolute URL or a Symfony route name: +a relative/absolute URL or a Symfony route name: .. configuration-block:: @@ -168,7 +168,7 @@ Defining the redirect URL via POST using a hidden form field: .. code-block:: html+twig - {# src/AppBundle/Resources/views/Security/login.html.twig #} + {# app/Resources/views/security/login.html.twig #}
{# ... #} @@ -178,7 +178,7 @@ Defining the redirect URL via POST using a hidden form field: .. code-block:: html+php - + // ... @@ -248,8 +248,8 @@ parameter is included in the request, you may use the value of the .. note:: - The referrer URL is only used when is different from the URL generated by - the ``login_path`` route, to avoid a redirection loop. + The referrer URL is only used when it is different from the URL generated by + the ``login_path`` route to avoid a redirection loop. .. _redirecting-on-login-failure: @@ -322,21 +322,21 @@ This option can also be set via the ``_failure_path`` request parameter: .. code-block:: html+twig - {# src/AppBundle/Resources/views/Security/login.html.twig #} + {# app/Resources/views/security/login.html.twig #} {# ... #} - +
.. code-block:: html+php - +
- // ... + - +
@@ -411,22 +411,22 @@ are now fully customized: .. code-block:: html+twig - {# src/AppBundle/Resources/views/Security/login.html.twig #} + {# app/Resources/views/security/login.html.twig #}
{# ... #} - +
.. code-block:: html+php - +
- // ... + - +