[Security] add description and example for the special ROLE_PREVIOUS_ADMIN role

bicpi · bicpi · commit 42ec5476e7a6 · 2012-11-24T16:41:17.000+01:00
diff --git a/book/security.rst b/book/security.rst
@@ -1644,6 +1644,24 @@ To switch back to the original user, use the special ``_exit`` username:
 
     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 decide
+if a link to exit impersonation needs to be shown:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {% if is_granted('ROLE_PREVIOUS_ADMIN') %}
+            <a href="{{ path('homepage', {_switch_user: '_exit'}) }}">Exit impersonation</a>
+        {% endif %}
+
+    .. code-block:: html+php
+
+        <?php if ($view['security']->isGranted('ROLE_PREVIOUS_ADMIN')): ?>
+            <a href="<?php echo $view['router']->generate('homepage', array('_switch_user' => '_exit') ?>">Exit impersonation</a>
+        <?php endif; ?>
+
 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
