diff --git a/book/security.rst b/book/security.rst
index 9977e7754cc..81975235691 100644
--- a/book/security.rst
+++ b/book/security.rst
@@ -1873,125 +1873,6 @@ method of the security context::
A firewall must be active or an exception will be thrown when the ``isGranted``
method is called. See the note above about templates for more details.
-Impersonating a User
---------------------
-
-Sometimes, it's useful to be able to switch from one user to another without
-having to log out and log in again (for instance when you are debugging or trying
-to understand a bug a user sees that you can't reproduce). This can be easily
-done by activating the ``switch_user`` firewall listener:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/security.yml
- security:
- firewalls:
- main:
- # ...
- switch_user: true
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/security.php
- $container->loadFromExtension('security', array(
- 'firewalls' => array(
- 'main'=> array(
- // ...
- 'switch_user' => true
- ),
- ),
- ));
-
-To switch to another user, just add a query string with the ``_switch_user``
-parameter and the username as the value to the current URL:
-
-.. code-block:: text
-
- http://example.com/somewhere?_switch_user=thomas
-
-To switch back to the original user, use the special ``_exit`` username:
-
-.. code-block:: text
-
- http://example.com/somewhere?_switch_user=_exit
-
-During impersonation, the user is provided with a special role called
-``ROLE_PREVIOUS_ADMIN``. In a template, for instance, this role can be used
-to show a link to exit impersonation:
-
-.. configuration-block::
-
- .. code-block:: html+jinja
-
- {% if is_granted('ROLE_PREVIOUS_ADMIN') %}
- Exit impersonation
- {% endif %}
-
- .. code-block:: html+php
-
- isGranted('ROLE_PREVIOUS_ADMIN')): ?>
-
- Exit impersonation
-
-
-
-Of course, this feature needs to be made available to a small group of users.
-By default, access is restricted to users having the ``ROLE_ALLOWED_TO_SWITCH``
-role. The name of this role can be modified via the ``role`` setting. For
-extra security, you can also change the query parameter name via the ``parameter``
-setting:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/security.yml
- security:
- firewalls:
- main:
- # ...
- switch_user: { role: ROLE_ADMIN, parameter: _want_to_be_this_user }
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/security.php
- $container->loadFromExtension('security', array(
- 'firewalls' => array(
- 'main'=> array(
- // ...
- 'switch_user' => array(
- 'role' => 'ROLE_ADMIN',
- 'parameter' => '_want_to_be_this_user',
- ),
- ),
- ),
- ));
Stateless Authentication
------------------------
@@ -2116,6 +1997,7 @@ Learn more from the Cookbook
----------------------------
* :doc:`Forcing HTTP/HTTPS `
+* :doc:`Impersonating a User `
* :doc:`Blacklist users by IP address with a custom voter `
* :doc:`Access Control Lists (ACLs) `
* :doc:`/cookbook/security/remember_me`
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
index 9c8260fd929..9a1ea8bc75d 100644
--- a/cookbook/map.rst.inc
+++ b/cookbook/map.rst.inc
@@ -124,6 +124,7 @@
* :doc:`/cookbook/security/entity_provider`
* :doc:`/cookbook/security/remember_me`
+ * :doc:`/cookbook/security/impersonating_user`
* :doc:`/cookbook/security/voters`
* :doc:`/cookbook/security/acl`
* :doc:`/cookbook/security/acl_advanced`
diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst
new file mode 100644
index 00000000000..c3bd0b708c6
--- /dev/null
+++ b/cookbook/security/impersonating_user.rst
@@ -0,0 +1,136 @@
+.. index::
+ single: Security; Impersonating User
+
+How to Impersonate a User
+=========================
+
+Sometimes, it's useful to be able to switch from one user to another without
+having to log out and log in again (for instance when you are debugging or trying
+to understand a bug a user sees that you can't reproduce). This can be easily
+done by activating the ``switch_user`` firewall listener:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/security.yml
+ security:
+ firewalls:
+ main:
+ # ...
+ switch_user: true
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/security.php
+ $container->loadFromExtension('security', array(
+ 'firewalls' => array(
+ 'main'=> array(
+ // ...
+ 'switch_user' => true
+ ),
+ ),
+ ));
+
+To switch to another user, just add a query string with the ``_switch_user``
+parameter and the username as the value to the current URL:
+
+.. code-block:: text
+
+ http://example.com/somewhere?_switch_user=thomas
+
+To switch back to the original user, use the special ``_exit`` username:
+
+.. code-block:: text
+
+ http://example.com/somewhere?_switch_user=_exit
+
+During impersonation, the user is provided with a special role called
+``ROLE_PREVIOUS_ADMIN``. In a template, for instance, this role can be used
+to show a link to exit impersonation:
+
+.. configuration-block::
+
+ .. code-block:: html+jinja
+
+ {% if is_granted('ROLE_PREVIOUS_ADMIN') %}
+ Exit impersonation
+ {% endif %}
+
+ .. code-block:: html+php
+
+ isGranted('ROLE_PREVIOUS_ADMIN')): ?>
+
+ Exit impersonation
+
+
+
+Of course, this feature needs to be made available to a small group of users.
+By default, access is restricted to users having the ``ROLE_ALLOWED_TO_SWITCH``
+role. The name of this role can be modified via the ``role`` setting. For
+extra security, you can also change the query parameter name via the ``parameter``
+setting:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/security.yml
+ security:
+ firewalls:
+ main:
+ # ...
+ switch_user: { role: ROLE_ADMIN, parameter: _want_to_be_this_user }
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/security.php
+ $container->loadFromExtension('security', array(
+ 'firewalls' => array(
+ 'main'=> array(
+ // ...
+ 'switch_user' => array(
+ 'role' => 'ROLE_ADMIN',
+ 'parameter' => '_want_to_be_this_user',
+ ),
+ ),
+ ),
+ ));
diff --git a/cookbook/security/index.rst b/cookbook/security/index.rst
index a8edbdc4317..e99d1312c7e 100644
--- a/cookbook/security/index.rst
+++ b/cookbook/security/index.rst
@@ -6,6 +6,7 @@ Security
entity_provider
remember_me
+ impersonating_user
voters
acl
acl_advanced