From 0e2b406ed1b3b32e8d7fa2158f5aa0b48d3c5eb4 Mon Sep 17 00:00:00 2001 From: Wouter de Jong Date: Mon, 24 Feb 2020 20:09:52 +0100 Subject: [PATCH] Documented new security attributes --- components/security/authorization.rst | 20 ++++++++++++++++---- security.rst | 17 ++++++++++++++++- security/impersonating_user.rst | 13 +++++++++---- security/remember_me.rst | 12 +++++++++++- 4 files changed, 52 insertions(+), 10 deletions(-) diff --git a/components/security/authorization.rst b/components/security/authorization.rst index 4918953bc26..253bbd45f06 100644 --- 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 index ec7c17dcb29..0d6a3e61d45 100644 --- 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 `, (i.e. a + remember-me cookie). + +* ``IS_IMPERSONATOR``: When the current user is + :doc:`impersonating ` 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 index d9d1deba976..580e9e3149b 100644 --- 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') %} Exit impersonation {% 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 index 7df40a41fb3..a001e0367ef 100644 --- 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