`.
Don't let this controller confuse you. As you'll see in a moment, when the
user submits the form, the security system automatically handles the form
submission for you. If the user submits an invalid username or password,
this controller reads the form submission error from the security system,
so that it can be displayed back to the user.
In other words, your job is to *display* the login form and any login errors
that may have occurred, but the security system itself takes care of checking
the submitted username and password and authenticating the user.
Finally, create the template:
.. code-block:: html+twig
{# templates/security/login.html.twig #}
{# ... you will probably extend your base template, like base.html.twig #}
{% if error %}
{{ error.messageKey|trans(error.messageData, 'security') }}
{% endif %}
.. tip::
The ``error`` variable passed into the template is an instance of
:class:`Symfony\\Component\\Security\\Core\\Exception\\AuthenticationException`.
It may contain more information - or even sensitive information - about
the authentication failure, so use it wisely!
The form can look like anything, but it usually follows some conventions:
* The ``
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 ``csrf_token_id`` in your configuration:
.. configuration-block::
.. code-block:: yaml
# config/packages/security.yaml
security:
# ...
firewalls:
secured_area:
# ...
form_login:
# ...
csrf_parameter: _csrf_security_token
csrf_token_id: a_private_string
.. code-block:: xml
.. code-block:: php
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'secured_area' => [
// ...
'form_login' => [
// ...
'csrf_parameter' => '_csrf_security_token',
'csrf_token_id' => 'a_private_string',
],
],
],
]);
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 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
is redirected to ``/`` (i.e. the homepage). You can change this behavior in
several ways.
Changing the default Page
~~~~~~~~~~~~~~~~~~~~~~~~~
Define the ``default_target_path`` option to change the page where the user
is redirected to if no previous page was stored in the session. The value can be
a relative/absolute URL or a Symfony route name:
.. configuration-block::
.. code-block:: yaml
# config/packages/security.yaml
security:
# ...
firewalls:
main:
form_login:
# ...
default_target_path: after_login_route_name
.. code-block:: xml
.. code-block:: php
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'main' => [
// ...
'form_login' => [
// ...
'default_target_path' => 'after_login_route_name',
],
],
],
]);
Always Redirect to the default Page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Define the ``always_use_default_target_path`` boolean option to ignore the
previously requested URL and always redirect to the default page:
.. configuration-block::
.. code-block:: yaml
# config/packages/security.yaml
security:
# ...
firewalls:
main:
form_login:
# ...
always_use_default_target_path: true
.. code-block:: xml
.. code-block:: php
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'main' => [
// ...
'form_login' => [
// ...
'always_use_default_target_path' => true,
],
],
],
]);
.. _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:
.. code-block:: html+twig
{# templates/security/login.html.twig #}
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 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:
.. configuration-block::
.. code-block:: yaml
# config/packages/security.yaml
security:
# ...
firewalls:
main:
# ...
form_login:
# ...
use_referer: true
.. code-block:: xml
.. code-block:: php
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'main' => [
// ...
'form_login' => [
// ...
'use_referer' => true,
],
],
],
]);
.. note::
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:
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 a new target via a relative/absolute URL or a Symfony route name:
.. configuration-block::
.. code-block:: yaml
# config/packages/security.yaml
security:
# ...
firewalls:
main:
# ...
form_login:
# ...
failure_path: login_failure_route_name
.. code-block:: xml
.. code-block:: php
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'main' => [
// ...
'form_login' => [
// ...
'failure_path' => 'login_failure_route_name',
],
],
],
]);
This option can also be set via the ``_failure_path`` request parameter:
.. code-block:: text
http://example.com/some/path?_failure_path=/forgot-password
.. code-block:: html+twig
{# templates/security/login.html.twig #}
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::
.. code-block:: yaml
# config/packages/security.yaml
security:
# ...
firewalls:
main:
# ...
form_login:
target_path_parameter: go_to
failure_path_parameter: back_to
.. code-block:: xml
.. code-block:: php
// config/packages/security.php
$container->loadFromExtension('security', [
// ...
'firewalls' => [
'main' => [
// ...
'form_login' => [
'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
.. code-block:: html+twig
{# templates/security/login.html.twig #}
.. _`Login CSRF attacks`: https://en.wikipedia.org/wiki/Cross-site_request_forgery#Forging_login_requests