- The authorization chapter of the SQLAlchemy Wiki Tutorial

  (docs/tutorials/bfgwiki2) was changed to demonstrate authorization
  via a group rather than via a direct username.

9 files changed, 67 insertions, 35 deletions

diff --git a/docs/tutorials/bfgwiki/authorization.rst b/docs/tutorials/bfgwiki/authorization.rst
index 8ae3c079d..91224c23e 100644
--- a/docs/tutorials/bfgwiki/authorization.rst
+++ b/docs/tutorials/bfgwiki/authorization.rst
@@ -206,28 +206,28 @@ pass a ``permission`` argument to each of our
 
 - We add ``permission='edit'`` to the decorator attached to the
   ``add_page`` view function.  This makes the assertion that only
-  users who possess the effective ``view`` permission at the time of
+  users who possess the effective ``edit`` permission at the time of
   the request may invoke this view.  We've granted the
-  ``group:editors`` principal the view permission at the root model
-  via its ACL, so only the a user whom is a member of the group named
-  ``group:editors`` will able to invoke the ``add_page`` view.  We've
-  likewise given the ``editor`` user membership to this group via thes
-  ``security.py`` file by mapping him to the ``group:editors`` group
-  in the ``GROUPS`` data structure (``GROUPS =
+  ``group:editors`` principal the ``edit`` permission at the root
+  model via its ACL, so only the a user whom is a member of the group
+  named ``group:editors`` will able to invoke the ``add_page`` view.
+  We've likewise given the ``editor`` user membership to this group
+  via thes ``security.py`` file by mapping him to the
+  ``group:editors`` group in the ``GROUPS`` data structure (``GROUPS =
   {'editor':['group:editors']}``); the ``groupfinder`` function
   consults the ``GROUPS`` data structure.  This means that the
   ``editor`` user can add pages.
 
 - We add ``permission='edit'`` to the ``bfg_view`` decorator attached
   to the ``edit_page`` view function.  This makes the assertion that
-  only users who possess the effective ``view`` permission at the time
+  only users who possess the effective ``edit`` permission at the time
   of the request may invoke this view.  We've granted the
-  ``group:editors`` principal the view permission at the root model
-  via its ACL, so only the a user whom is a member of the group named
-  ``group:editors`` will able to invoke the ``edit_page`` view.  We've
-  likewise given the ``editor`` user membership to this group via thes
-  ``security.py`` file by mapping him to the ``group:editors`` group
-  in the ``GROUPS`` data structure (``GROUPS =
+  ``group:editors`` principal the ``edit`` permission at the root
+  model via its ACL, so only the a user whom is a member of the group
+  named ``group:editors`` will able to invoke the ``edit_page`` view.
+  We've likewise given the ``editor`` user membership to this group
+  via thes ``security.py`` file by mapping him to the
+  ``group:editors`` group in the ``GROUPS`` data structure (``GROUPS =
   {'editor':['group:editors']}``); the ``groupfinder`` function
   consults the ``GROUPS`` data structure.  This means that the
   ``editor`` user can edit pages.
diff --git a/docs/tutorials/bfgwiki2/authorization.rst b/docs/tutorials/bfgwiki2/authorization.rst
index 2f1a9e082..58b08cad0 100644
--- a/docs/tutorials/bfgwiki2/authorization.rst
+++ b/docs/tutorials/bfgwiki2/authorization.rst
@@ -15,7 +15,7 @@ to our application.
 
 The source code for this tutorial stage can be browsed at
 `docs.repoze.org
-<http://docs.repoze.org/bfgwiki2-1.2/authorization>`_.
+<http://docs.repoze.org/bfgwiki2-1.3/authorization>`_.
 
 Adding A Root Factory
 ---------------------
@@ -40,7 +40,8 @@ your ``models.py`` file:
    from repoze.bfg.security import Everyone
 
    class RootFactory(object):
-       __acl__ = [ (Allow, Everyone, 'view'), (Allow, 'editor', 'edit') ]
+       __acl__ = [ (Allow, Everyone, 'view'), 
+                   (Allow, 'group:editors', 'edit') ]
        def __init__(self, request):
            self.__dict__.update(request.matchdict)
 
@@ -51,11 +52,12 @@ attached to the request object passed to our view callables as the
 
 All of our context objects will possess an ``__acl__`` attribute that
 allows :data:`repoze.bfg.security.Everyone` (a special principal) to
-view all pages, while allowing only a user named ``editor`` to edit
-and add pages.  The ``__acl__`` attribute attached to a context is
-interpreted specially by :mod:`repoze.bfg` as an access control list
-during view callable execution.  See :ref:`assigning_acls` for more
-information about what an :term:`ACL` represents.
+view all pages, while allowing only a :term:`principal` named
+``group:editors`` to edit and add pages.  The ``__acl__`` attribute
+attached to a context is interpreted specially by :mod:`repoze.bfg` as
+an access control list during view callable execution.  See
+:ref:`assigning_acls` for more information about what an :term:`ACL`
+represents.
 
 .. note: Although we don't use the functionality here, the ``factory``
    used to create route contexts may differ per-route as opposed to
@@ -93,29 +95,57 @@ value ``edit`` to the ``edit_page`` and ``add_page`` route
 declarations.  This indicates that the view callables which these
 routes reference cannot be invoked without the authenticated user
 possessing the ``edit`` permission with respect to the current
-context.  When you're done, your ``configure.zcml`` will look like so
+context.
+
+This makes the assertion that only users who possess the effective
+``edit`` permission at the time of the request may invoke those two
+views.  We've granted the ``group:editors`` principal the ``edit``
+permission at the root model via its ACL, so only the a user whom is a
+member of the group named ``group:editors`` will able to invoke the
+views associated with the ``add_page`` or ``edit_page`` routes.  
+
+When you're done, your ``configure.zcml`` will look like so
 
 .. literalinclude:: src/authorization/tutorial/configure.zcml
    :linenos:
    :language: xml
 
+Note that the ``authtktauthenticationpolicy`` tag has two attributes:
+``secret`` and ``callback``.  ``secret`` is a string representing an
+encryption key used by the "authentication ticket" machinery
+represented by this policy: it is required.  The ``callback`` is a
+string, representing a :term:`Python dotted name`, which points at the
+``groupfinder`` function in the current directory's ``security.py``
+file.  We haven't added that module yet, but we're about to.
+
 Adding ``security.py``
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Add a ``security.py`` module within your package (in the same
 directory as "run.py", "views.py", etc) with the following content:
+
+.. literalinclude:: src/authorization/tutorial/security.py
+   :linenos:
+   :language: python
+
 The groupfinder defined here is an :term:`authentication policy`
 "callback"; it is a callable that accepts a userid and a request.  If
 the userid exists in the system, the callback will return a sequence
 of group identifiers (or an empty sequence if the user isn't a member
 of any groups).  If the userid *does not* exist in the system, the
-callback will return ``None``.  We'll use "dummy" data to represent
-user and groups sources.  When we're done, your application's
-``security.py`` will look like this.
-
-.. literalinclude:: src/authorization/tutorial/security.py
-   :linenos:
-   :language: python
+callback will return ``None``.  In a production system, user and group
+data will most often come from a database, but here we use "dummy"
+data to represent user and groups sources. Note that the ``editor``
+user is a member of the ``group:editors`` group in our dummy group
+data (the ``GROUPS`` data structure).
+
+We've given the ``editor`` user membership to the ``group:editors`` by
+mapping him to this group in the ``GROUPS`` data structure (``GROUPS =
+{'editor':['group:editors']}``).  Since the ``groupfinder`` function
+consults the ``GROUPS`` data structure, this will mean that, as a
+result of the ACL attached to the root returned by the root factory,
+and the permission associated with the ``add_page`` and ``edit_page``
+views, the ``editor`` user should be able to add and edit pages.
 
 Adding Login and Logout Views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/tutorials/bfgwiki2/basiclayout.rst b/docs/tutorials/bfgwiki2/basiclayout.rst
index 6df33e9fa..a284b2eb4 100644
--- a/docs/tutorials/bfgwiki2/basiclayout.rst
+++ b/docs/tutorials/bfgwiki2/basiclayout.rst
@@ -7,7 +7,7 @@ basic, but they provide a good orientation for the high-level patterns
 common to most :term:`url dispatch` -based :mod:`repoze.bfg` projects.
 
 The source code for this tutorial stage can be browsed at
-`docs.repoze.org <http://docs.repoze.org/bfgwiki2-1.2/basiclayout>`_.
+`docs.repoze.org <http://docs.repoze.org/bfgwiki2-1.3/basiclayout>`_.
 
 ``__init__.py``
 ---------------
diff --git a/docs/tutorials/bfgwiki2/definingmodels.rst b/docs/tutorials/bfgwiki2/definingmodels.rst
index d2db4955e..03c97259f 100644
--- a/docs/tutorials/bfgwiki2/definingmodels.rst
+++ b/docs/tutorials/bfgwiki2/definingmodels.rst
@@ -7,7 +7,7 @@ will be to define a :term:`model` constructor representing a wiki
 page.  We'll do this inside our ``models.py`` file.
 
 The source code for this tutorial stage can be browsed at
-`docs.repoze.org <http://docs.repoze.org/bfgwiki2-1.2/models>`_.
+`docs.repoze.org <http://docs.repoze.org/bfgwiki2-1.3/models>`_.
 
 Making Edits to ``models.py``
 -----------------------------
diff --git a/docs/tutorials/bfgwiki2/definingviews.rst b/docs/tutorials/bfgwiki2/definingviews.rst
index 1d40d0051..775334b51 100644
--- a/docs/tutorials/bfgwiki2/definingviews.rst
+++ b/docs/tutorials/bfgwiki2/definingviews.rst
@@ -30,7 +30,7 @@ request passed to the view would have a ``one`` key with the value
 ``foo`` and a ``two`` key with the value ``bar``.
 
 The source code for this tutorial stage can be browsed at
-`docs.repoze.org <http://docs.repoze.org/bfgwiki2-1.2/views>`_.
+`docs.repoze.org <http://docs.repoze.org/bfgwiki2-1.3/views>`_.
 
 Declaring Dependencies in Our ``setup.py`` File
 ===============================================
diff --git a/docs/tutorials/bfgwiki2/index.rst b/docs/tutorials/bfgwiki2/index.rst
index 42189f3e6..34b56ff82 100644
--- a/docs/tutorials/bfgwiki2/index.rst
+++ b/docs/tutorials/bfgwiki2/index.rst
@@ -10,7 +10,7 @@ created a basic Wiki application with authentication.
 
 For cut and paste purposes, the source code for all stages of this
 tutorial can be browsed at `docs.repoze.org
-<http://docs.repoze.org/bfgwiki2-1.2>`_.
+<http://docs.repoze.org/bfgwiki2-1.3>`_.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/tutorials/bfgwiki2/src/authorization/tutorial/configure.zcml b/docs/tutorials/bfgwiki2/src/authorization/tutorial/configure.zcml
index b87ca6398..e51a67d70 100644
--- a/docs/tutorials/bfgwiki2/src/authorization/tutorial/configure.zcml
+++ b/docs/tutorials/bfgwiki2/src/authorization/tutorial/configure.zcml
@@ -57,6 +57,7 @@
 
   <authtktauthenticationpolicy
     secret="sosecret"
+    callback=".security.groupfinder"
     />
 
   <aclauthorizationpolicy/>
diff --git a/docs/tutorials/bfgwiki2/src/authorization/tutorial/models.py b/docs/tutorials/bfgwiki2/src/authorization/tutorial/models.py
index db2095ad1..607aa6fde 100644
--- a/docs/tutorials/bfgwiki2/src/authorization/tutorial/models.py
+++ b/docs/tutorials/bfgwiki2/src/authorization/tutorial/models.py
@@ -32,7 +32,8 @@ class Page(Base):
        self.data = data
 
 class RootFactory(object):
-    __acl__ = [ (Allow, Everyone, 'view'), (Allow, 'editor', 'edit') ]
+    __acl__ = [ (Allow, Everyone, 'view'),
+                (Allow, 'group:editors', 'edit') ]
     def __init__(self, request):
         self.__dict__.update(request.matchdict)
 
diff --git a/docs/tutorials/bfgwiki2/src/authorization/tutorial/security.py b/docs/tutorials/bfgwiki2/src/authorization/tutorial/security.py
index 791367183..cfd13071e 100644
--- a/docs/tutorials/bfgwiki2/src/authorization/tutorial/security.py
+++ b/docs/tutorials/bfgwiki2/src/authorization/tutorial/security.py
@@ -1,6 +1,6 @@
 USERS = {'editor':'editor',
           'viewer':'viewer'}
-GROUPS = {'editor':['group.editors']}
+GROUPS = {'editor':['group:editors']}
 
 def groupfinder(userid, request):
     if userid in USERS: