symfony · weaverryan · Oct 29, 2017 · Oct 4, 2017 · Oct 8, 2017 · Oct 29, 2017
diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst
@@ -30,8 +30,10 @@ Each part will be explained in the next section.
                 strategy:             affirmative # One of affirmative, consensus, unanimous
                 allow_if_all_abstain:  false
                 allow_if_equal_granted_denied:  true
-            acl:
 
+            # ACL support was deprecated in Symfony 3.4 and removed in Symfony 4.0
+            # Use https://github.com/symfony/acl-bundle instead
+            acl:
                 # any name configured in doctrine.dbal section
                 connection:           ~
                 cache:

diff --git a/security.rst b/security.rst
@@ -637,10 +637,9 @@ The process of authorization has two different sides:
 .. tip::
 
     In addition to roles (e.g. ``ROLE_ADMIN``), you can protect a resource
-    using other attributes/strings (e.g. ``EDIT``) and use voters or Symfony's
-    ACL system to give these meaning. This might come in handy if you need
-    to check if user A can "EDIT" some object B (e.g. a Product with id 5).
-    See :ref:`security-secure-objects`.
+    using other attributes/strings (e.g. ``EDIT``) and use voters to give these
+    meaning. This might come in handy if you need to check if user A can "EDIT"
+    some object B (e.g. a Product with id 5). See :ref:`security-secure-objects`.
 
 Roles
 ~~~~~
@@ -970,6 +969,10 @@ For more details on expressions and security, see :ref:`expressions-security`.
 Access Control Lists (ACLs): Securing individual Database Objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 3.4
+    ACL support was deprecated in Symfony 3.4 and will be removed in 4.0. Install
+    the `Symfony ACL bundle`_ if you want to keep using ACL.
+
 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 yourself want to be able to edit
@@ -1322,3 +1325,4 @@ Other Security Related Topics
 
 .. _`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
diff --git a/security/acl.rst b/security/acl.rst
@@ -4,6 +4,10 @@
 How to Use Access Control Lists (ACLs)
 ======================================
 
+.. versionadded:: 3.4
+    ACL support was deprecated in Symfony 3.4 and will be removed in 4.0. Install
+    the `Symfony ACL bundle`_ if you wan to keep using ACL.
+
 In complex applications, you will often face the problem that access decisions
 cannot only be based on the person (``Token``) who is requesting access, but
 also involve a domain object that access is being requested for. This is where
@@ -246,4 +250,5 @@ added above:
 
 The user is now allowed to view, edit, delete, and un-delete objects.
 
+.. _`Symfony ACL bundle`: https://github.com/symfony/acl-bundle
 .. _`MongoDBAclBundle`: https://github.com/IamPersistent/MongoDBAclBundle
diff --git a/security/acl_advanced.rst b/security/acl_advanced.rst
@@ -4,6 +4,10 @@
 How to Use advanced ACL Concepts
 ================================
 
+.. versionadded:: 3.4
+    ACL support was deprecated in Symfony 3.4 and will be removed in 4.0. Install
+    the `Symfony ACL bundle`_ if you wan to keep using ACL.
+
 The aim of this article is to give a more in-depth view of the ACL system, and
 also explain some of the design decisions behind it.
 
@@ -195,4 +199,5 @@ is applicable, the class-scope ACEs will be checked. If none is applicable,
 then the process will be repeated with the ACEs of the parent ACL. If no
 parent ACL exists, an exception will be thrown.
 
+.. _`Symfony ACL bundle`: https://github.com/symfony/acl-bundle
 .. _JMSSecurityExtraBundle: https://github.com/schmittjoh/JMSSecurityExtraBundle
diff --git a/security/voters.rst b/security/voters.rst
@@ -4,10 +4,8 @@
 How to Use Voters to Check User Permissions
 ===========================================
 
-In Symfony, you can check the permission to access data by using the
-:doc:`ACL module </security/acl>`, which is a bit overwhelming
-for many applications. A much easier solution is to work with custom voters,
-which are like simple conditional statements.
+Security voters are the most granular way of checking permissions (e.g. "can this
+specific user edit the given item?"). This article explains voters in detail.
 
 .. tip::