feature symfony#11487 [Security] Documented new IS_IMPERSONATOR, IS_ANONYMOUS and IS_REMEMBERED attributes (wouterj)

This PR was merged into the master branch.

Discussion
----------

[Security] Documented new IS_IMPERSONATOR, IS_ANONYMOUS and IS_REMEMBERED attributes

Changes the documentation to no longer use security attributes/functions that will be deprecated in symfony/symfony#31189 . It's funny to see how the docs were also confusing about the old attributes, as wrong attributes were used.

While doing these changes, I've also rewritten some parts to no longer talk about attributes as something the users have (like roles), but instead as something the user is matched against.

Commits
-------

0e2b406 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.
+
+::
 
     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