Documented new security attributes

symfony · wouterj · Feb 28, 2020 · Feb 24, 2020 · Feb 28, 2020 · 0e2b406ed1b3b32e8d7fa2158f5aa0b48d3c5eb4
commit 0e2b406ed1b3b32e8d7fa2158f5aa0b48d3c5eb4
diff --git a/components/security/authorization.rst b/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;


diff --git a/security.rst b/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

diff --git a/security/impersonating_user.rst b/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
 -------------------------


diff --git a/security/remember_me.rst b/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