minor #13522 [Security] Describe voters more prominently in the Security guide (wouterj)

wouterj · wouterj · commit 2209ca25fd64 · 2020-04-16T11:32:07.000+02:00
This PR was merged into the 4.4 branch. Discussion ---------- [Security] Describe voters more prominently in the Security guide Fixes #11505, Fixes #13406 * I've removed the ACL bundle reference, imho it no longer makes sense to talk about it * I've also changed the title from "Access Control Lists (ACLs): Securing individual Database Objects" to "Securing Individual Objects"; it's no longer about ACL * I've updated the content to talk about the function of voters and not talk about why we replaced ACL with voters (that was useful in Symfony 3, but I think it no longer makes sense - everyone has made the change already) * I've moved the chapter slightly up, the TOC now is: ``` 4) Denying Access, Roles and other Authorization Roles Add Code to Deny Access Securing URL patterns (access_control) Securing Controllers and other Code Access Control in Templates Securing other Services Securing Individual Objects Checking to see if a User is Logged In (IS_AUTHENTICATED_FULLY) ``` Commits ------- b610beb Describe voters a bit more prominent in the Security guide
diff --git a/security.rst b/security.rst
@@ -391,20 +391,24 @@ generated earlier, the roles are an array that's stored in the database, and
 every user is *always* given at least one role: ``ROLE_USER``::
 
     // src/Entity/User.php
-    // ...
-
-    /**
-     * @ORM\Column(type="json")
-     */
-    private $roles = [];
 
-    public function getRoles(): array
+    // ...
+    class User
     {
-        $roles = $this->roles;
-        // guarantee every user at least has ROLE_USER
-        $roles[] = 'ROLE_USER';
+        /**
+         * @ORM\Column(type="json")
+         */
+        private $roles = [];
 
-        return array_unique($roles);
+        // ...
+        public function getRoles(): array
+        {
+            $roles = $this->roles;
+            // guarantee every user at least has ROLE_USER
+            $roles[] = 'ROLE_USER';
+
+            return array_unique($roles);
+        }
     }
 
 This is a nice default, but you can do *whatever* you want to determine which roles
@@ -659,6 +663,16 @@ Securing other Services
 
 See :doc:`/security/securing_services`.
 
+Securing Individual Objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most applications require more specific access rules. For instance, a user
+should be able to only edit their own comments on a blog. Voters allow you
+to write *whatever* business logic you need to determine access. Using
+these voters is similar to the role-based access checks implemented in the
+previous chapters. Read :doc:`/security/voters` to learn how to implement
+your own voter.
+
 Checking to see if a User is Logged In (IS_AUTHENTICATED_FULLY)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -696,22 +710,6 @@ like this:
   this - this is useful when *whitelisting* URLs to guarantee access - some
   details are in :doc:`/security/access_control`.
 
-.. _security-secure-objects:
-
-Access Control Lists (ACLs): Securing individual Database Objects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Imagine you are designing a blog where users can comment on your posts. You
-also want a user to be able to edit their own comments, but not those of
-other users. Also, as the admin user, you want to be able to edit *all* comments.
-
-:doc:`Voters </security/voters>` allow you to write *whatever* business logic you
-need (e.g. the user can edit this post because they are the creator) to determine
-access. That's why voters are officially recommended by Symfony to create ACL-like
-security systems.
-
-If you still prefer to use traditional ACLs, refer to the `Symfony ACL bundle`_.
-
 .. _retrieving-the-user-object:
 
 5a) Fetching the User Object
@@ -1047,6 +1045,5 @@ Authorization (Denying Access)
 
 .. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`HWIOAuthBundle`: https://github.com/hwi/HWIOAuthBundle
-.. _`Symfony ACL bundle`: https://github.com/symfony/acl-bundle
 .. _`Symfony Security screencast series`: https://symfonycasts.com/screencast/symfony-security
 .. _`MakerBundle`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html
