Documented new security attributes

Author: wouterj

components/security/authorization.rst

@@ -105,10 +105,22 @@ AuthenticatedVoter
 ~~~~~~~~~~~~~~~~~~
 
 The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\AuthenticatedVoter`
-voter supports the attributes ``IS_AUTHENTICATED_FULLY``, ``IS_AUTHENTICATED_REMEMBERED``,
-and ``IS_AUTHENTICATED_ANONYMOUSLY`` and grants access based on the current
-level of authentication, i.e. is the user fully authenticated, or only based
-on a "remember-me" cookie, or even authenticated anonymously?::
+voter supports the attributes ``IS_AUTHENTICATED_FULLY``,
+``IS_AUTHENTICATED_REMEMBERED``, ``IS_AUTHENTICATED_ANONYMOUSLY``,
+to grant access based on the current level of authentication, i.e. is the
+user fully authenticated, or only based on a "remember-me" cookie, or even
+authenticated anonymously?
+
+It also supports the attributes ``IS_ANONYMOUS``, ``IS_REMEMBERED``,
+``IS_IMPERSONATED`` to grant access based on a specific state of
+authentication.
+
+.. versionadded:: 5.1
+
+    The ``IS_ANONYMOUS``, ``IS_REMEMBERED`` and ``IS_IMPERSONATED``
+    attributes were introduced in Symfony 5.1.
+
+.. code-block:: php
 
     use Symfony\Component\Security\Core\Authentication\AuthenticationTrustResolver;
 

security.rst

@@ -663,7 +663,7 @@ You can use ``IS_AUTHENTICATED_FULLY`` anywhere roles are used: like
 ``access_control`` or in Twig.
 
 ``IS_AUTHENTICATED_FULLY`` isn't a role, but it kind of acts like one, and every
-user that has logged in will have this. Actually, there are 3 special attributes
+user that has logged in will have this. Actually, there are some special attributes
 like this:
 
 * ``IS_AUTHENTICATED_REMEMBERED``: *All* logged in users have this, even
@@ -679,6 +679,21 @@ like this:
   this - this is useful when *whitelisting* URLs to guarantee access - some
   details are in :doc:`/security/access_control`.
 
+* ``IS_ANONYMOUS``: *Only* anonymous users are matched by this attribute.
+
+* ``IS_REMEMBERED``: *Only* users authenticated using the 
+  :doc:`remember me functionality </security/remember_me>`, (i.e. a
+  remember-me cookie).
+
+* ``IS_IMPERSONATOR``: When the current user is
+  :doc:`impersonating </security/impersonating_user>` another user in this
+  session, this attribute will match.
+
+.. versionadded:: 5.1
+
+    The ``IS_ANONYMOUS``, ``IS_REMEMBERED`` and ``IS_IMPERSONATOR``
+    attributes were introduced in Symfony 5.1.
+
 .. _security-secure-objects:
 
 Access Control Lists (ACLs): Securing individual Database Objects

security/impersonating_user.rst

@@ -85,16 +85,21 @@ role to the users that need it.
 Knowing When Impersonation Is Active
 ------------------------------------
 
-When a user is being impersonated, Symfony grants them a special role called
-``ROLE_PREVIOUS_ADMIN`` (in addition to the roles the user may have). Use this
-special role, for instance, to show a link to exit impersonation in a template:
+You can use the special attribute ``IS_IMPERSONATOR`` to check if the
+impersonation is active in this session. Use this special role, for
+instance, to show a link to exit impersonation in a template:
 
 .. code-block:: html+twig
 
-    {% if is_granted('ROLE_PREVIOUS_ADMIN') %}
+    {% if is_granted('IS_IMPERSONATOR') %}
         <a href="{{ path('homepage', {'_switch_user': '_exit'}) }}">Exit impersonation</a>
     {% endif %}
 
+.. versionadded:: 5.1
+
+    The ``IS_IMPERSONATOR`` was introduced in Symfony 5.1. Use
+    ``ROLE_PREVIOUS_ADMIN`` prior to Symfony 5.1.
+
 Finding the Original User
 -------------------------
 

security/remember_me.rst

@@ -176,7 +176,8 @@ visiting the site.
 
 In some cases, however, you may want to force the user to actually re-authenticate
 before accessing certain resources. For example, you might not allow "remember me"
-users to change their password. You can do this by leveraging a few special "roles"::
+users to change their password. You can do this by leveraging a few special
+"attributes"::
 
     // src/Controller/AccountController.php
     // ...
@@ -200,6 +201,15 @@ users to change their password. You can do this by leveraging a few special "rol
         // ...
     }
 
+.. tip::
+
+    There is also a ``IS_REMEMBERED`` attribute that grants *only* when the
+    user is authenticated via the remember me mechanism.
+
+.. versionadded:: 5.1
+
+    The ``IS_REMEMBERED`` attribute was introduced in Symfony 5.1.
+
 .. _remember-me-token-in-database:
 
 Storing Remember Me Tokens in the Database