From 1025eb090fb902568f546527856c22e3356bd526 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 23 Jun 2010 14:55:33 +0000 Subject: - 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. --- docs/tutorials/bfgwiki/authorization.rst | 28 +++++----- docs/tutorials/bfgwiki2/authorization.rst | 60 ++++++++++++++++------ docs/tutorials/bfgwiki2/basiclayout.rst | 2 +- docs/tutorials/bfgwiki2/definingmodels.rst | 2 +- docs/tutorials/bfgwiki2/definingviews.rst | 2 +- docs/tutorials/bfgwiki2/index.rst | 2 +- .../src/authorization/tutorial/configure.zcml | 1 + .../bfgwiki2/src/authorization/tutorial/models.py | 3 +- .../src/authorization/tutorial/security.py | 2 +- 9 files changed, 67 insertions(+), 35 deletions(-) (limited to 'docs') 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 -`_. +`_. 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 `_. +`docs.repoze.org `_. ``__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 `_. +`docs.repoze.org `_. 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 `_. +`docs.repoze.org `_. 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 -`_. +`_. .. 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 @@ 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: -- cgit v1.2.3