update authorization docs with new security policy

1 files changed, 18 insertions, 37 deletions

diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 234f40e3b..e8f95f8cf 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -12,10 +12,8 @@ the constraints from the view function itself.
 
 We will implement access control with the following steps:
 
-* Update the :term:`authentication policy` to break down the :term:`userid`
-  into a list of :term:`principals <principal>` (``security.py``).
-* Define an :term:`authorization policy` for mapping users, resources and
-  permissions (``security.py``).
+* Update the :term:`security policy` to break down the :term:`identity` into a list of :term:`principals <principal>` (``security.py``).
+* Utilize the :class:`pyramid.authorization.ACLHelper` to support a per-context mapping of principals to permissions (``security.py``).
 * Add new :term:`resource` definitions that will be used as the :term:`context`
   for the wiki pages (``routes.py``).
 * Add an :term:`ACL` to each resource (``routes.py``).
@@ -23,8 +21,8 @@ We will implement access control with the following steps:
   (``views/default.py``).
 
 
-Add user principals
--------------------
+Add ACL support
+---------------
 
 A :term:`principal` is a level of abstraction on top of the raw :term:`userid`
 that describes the user in terms of its capabilities, roles, or other
@@ -42,7 +40,7 @@ Open the file ``tutorial/security.py`` and edit it as follows:
 
 .. literalinclude:: src/authorization/tutorial/security.py
    :linenos:
-   :emphasize-lines: 3-6,17-24
+   :emphasize-lines: 2,4-7,15,37-48
    :language: python
 
 Only the highlighted lines need to be added.
@@ -51,33 +49,16 @@ Note that the role comes from the ``User`` object. We also add the ``user.id``
 as a principal for when we want to allow that exact user to edit pages which
 they have created.
 
+We're using the :class:`pyramid.authorization.ACLHelper`, which will suffice for most applications.
+It uses the :term:`context` to define the mapping between a :term:`principal` and :term:`permission` for the current request via the ``__acl__`` method or attribute.
 
-Add the authorization policy
-----------------------------
-
-We already added the :term:`authorization policy` in the previous chapter
-because :app:`Pyramid` requires one when adding an
-:term:`authentication policy`. However, it was not used anywhere, so we'll
-mention it now.
-
-In the file ``tutorial/security.py``, notice the following lines:
-
-.. literalinclude:: src/authorization/tutorial/security.py
-   :lines: 38-40
-   :lineno-match:
-   :emphasize-lines: 2
-   :language: python
-
-We're using the :class:`pyramid.authorization.ACLAuthorizationPolicy`, which
-will suffice for most applications. It uses the :term:`context` to define the
-mapping between a :term:`principal` and :term:`permission` for the current
-request via the ``__acl__``.
+The ``permits`` method completes our implementation of the :class:`pyramid.interfaces.ISecurityPolicy` interface and enables our application to use :attr:`pyramid.request.Request.has_permission` and the ``permission=`` constraint on views.
 
 
 Add resources and ACLs
 ----------------------
 
-Resources are the hidden gem of :app:`Pyramid`. You've made it!
+Resources and context are the hidden gems of :app:`Pyramid`. You've made it!
 
 Every URL in a web application represents a :term:`resource` (the "R" in
 Uniform Resource Locator). Often the resource is something in your data model,
@@ -108,7 +89,7 @@ Open the file ``tutorial/routes.py`` and edit the following lines:
 
 .. literalinclude:: src/authorization/tutorial/routes.py
    :linenos:
-   :emphasize-lines: 1-11,17-
+   :emphasize-lines: 1-11,18-
    :language: python
 
 The highlighted lines need to be edited or added.
@@ -120,7 +101,7 @@ the principals of either ``role:editor`` or ``role:basic`` to have the
 ``create`` permission:
 
 .. literalinclude:: src/authorization/tutorial/routes.py
-   :lines: 30-38
+   :lines: 31-39
    :lineno-match:
    :emphasize-lines: 5-9
    :language: python
@@ -129,7 +110,7 @@ The ``NewPage`` is loaded as the :term:`context` of the ``add_page`` route by
 declaring a ``factory`` on the route:
 
 .. literalinclude:: src/authorization/tutorial/routes.py
-   :lines: 18-19
+   :lines: 19-20
    :lineno-match:
    :emphasize-lines: 1-2
    :language: python
@@ -138,7 +119,7 @@ The ``PageResource`` class defines the :term:`ACL` for a ``Page``. It uses an
 actual ``Page`` object to determine *who* can do *what* to the page.
 
 .. literalinclude:: src/authorization/tutorial/routes.py
-   :lines: 47-
+   :lines: 48-
    :lineno-match:
    :emphasize-lines: 5-10
    :language: python
@@ -147,7 +128,7 @@ The ``PageResource`` is loaded as the :term:`context` of the ``view_page`` and
 ``edit_page`` routes by declaring a ``factory`` on the routes:
 
 .. literalinclude:: src/authorization/tutorial/routes.py
-   :lines: 17-21
+   :lines: 18-22
    :lineno-match:
    :emphasize-lines: 1,4-5
    :language: python
@@ -167,7 +148,7 @@ Open the file ``tutorial/views/default.py``.
 First, you can drop a few imports that are no longer necessary:
 
 .. literalinclude:: src/authorization/tutorial/views/default.py
-   :lines: 5-7
+   :lines: 3-5
    :lineno-match:
    :emphasize-lines: 1
    :language: python
@@ -207,7 +188,7 @@ Note the ``pagename`` here is pulled off of the context instead of
 ``request.matchdict``. The factory has done a lot of work for us to hide the
 actual route pattern.
 
-The ACLs defined on each :term:`resource` are used by the :term:`authorization
+The ACLs defined on each :term:`resource` are used by the :term:`security
 policy` to determine if any :term:`principal` is allowed to have some
 :term:`permission`. If this check fails (for example, the user is not logged
 in) then an ``HTTPForbidden`` exception will be raised automatically. Thus
@@ -238,14 +219,14 @@ following URLs, checking that the result is as expected:
 
 - http://localhost:6543/FrontPage/edit_page invokes the ``edit_page`` view for
   the ``FrontPage`` page object.  It is executable by only the ``editor`` user.
-  If a different user (or the anonymous user) invokes it, then a login form
+  If an anonymous user invokes it, then a login form
   will be displayed. Supplying the credentials with the username ``editor`` and
   password ``editor`` will display the edit page form.
 
 - http://localhost:6543/add_page/SomePageName invokes the ``add_page`` view for
   a page. If the page already exists, then it redirects the user to the
   ``edit_page`` view for the page object. It is executable by either the
-  ``editor`` or ``basic`` user.  If a different user (or the anonymous user)
+  ``editor`` or ``basic`` user.  If an anonymous user
   invokes it, then a login form will be displayed. Supplying the credentials
   with either the username ``editor`` and password ``editor``, or username
   ``basic`` and password ``basic``, will display the edit page form.