From 753ce0f9cad9188a7965e39e3a7b991c2fdebe7c Mon Sep 17 00:00:00 2001 From: Romaric Drigon Date: Sat, 14 Dec 2013 14:51:41 +0100 Subject: [PATCH 1/3] Moved "Impersonating a User" to a cookbook entry --- book/security.rst | 120 +--------------------- cookbook/map.rst.inc | 1 + cookbook/security/impersonating_user.rst | 122 +++++++++++++++++++++++ cookbook/security/index.rst | 1 + 4 files changed, 125 insertions(+), 119 deletions(-) create mode 100644 cookbook/security/impersonating_user.rst 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..95818855156 --- /dev/null +++ b/cookbook/security/impersonating_user.rst @@ -0,0 +1,122 @@ +.. 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 From 7d75fad99a9bac3f4474788a7b37a4b5cca3255f Mon Sep 17 00:00:00 2001 From: Romaric Drigon Date: Tue, 17 Dec 2013 09:46:06 +0100 Subject: [PATCH 2/3] CaseFix --- cookbook/security/impersonating_user.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst index 95818855156..a18097d06e8 100644 --- a/cookbook/security/impersonating_user.rst +++ b/cookbook/security/impersonating_user.rst @@ -1,7 +1,7 @@ .. index:: single: Security; Impersonating User -How to impersonate a User +How to Impersonate a User ========================= Sometimes, it's useful to be able to switch from one user to another without From 4cfa0dfa523ee0fbd5a1e6251973a46ecde10f9c Mon Sep 17 00:00:00 2001 From: Romaric Drigon Date: Tue, 17 Dec 2013 09:46:33 +0100 Subject: [PATCH 3/3] Expanded XML examples --- cookbook/security/impersonating_user.rst | 38 ++++++++++++++++-------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst index a18097d06e8..c3bd0b708c6 100644 --- a/cookbook/security/impersonating_user.rst +++ b/cookbook/security/impersonating_user.rst @@ -23,12 +23,19 @@ done by activating the ``switch_user`` firewall listener: .. code-block:: xml - - - - - - + + + + + + + + + .. code-block:: php @@ -99,12 +106,19 @@ setting: .. code-block:: xml - - - - - - + + + + + + + + + .. code-block:: php