From 8b8e10932274f5ee9a9668671d828cab20096a94 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 21 Jul 2008 04:33:08 +0000 Subject: ACL stuff. --- docs/narr/security.rst | 101 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 96 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 3869d6e7a..5566d7c28 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -12,7 +12,7 @@ Jargon Permission A string or unicode object that represents an action being taken - against a context. For example, 'read', or 'view_blog_entries'. + against a context. For example, ``read``, or ``view_blog_entries``. ACE @@ -21,8 +21,8 @@ ACE describes three things: an *action* (one of either ``Allow`` or ``Deny``), a *principal* (a string describing a user or group), and a *permission*. For example the ACE, ``(Allow, 'bob', 'read')`` is - a member of an ACL that indicates that the principal 'bob' is - allowed the permission 'read' against the context the ACL is + a member of an ACL that indicates that the principal ``bob`` is + allowed the permission ``read`` against the context the ACL is attached to. ACL @@ -92,5 +92,96 @@ data when attempting to call some *view*. The policy either allows the view that the permission was declared for to be called, or returns a ``401 Unathorized`` response code to the upstream WSGI server. - - +Protecting Views with Permissions +--------------------------------- + +You declaratively protected a particular view with a permisson via the +``configure.zcml`` application registry. For example, the following +declaration protects the view named "add_entry.html" when invoked +against an IBlog context with the ``add`` permission:: + + + +If a security policy is in place when this view is found during normal +application operations, the user will need to possess the ``add`` +permission against the context to be able to invoke the +``blog_entry_add_view`` view. + +Permission names are just strings. They hold no special significance +to the system. You can name permissions whatever you like. + +Assigning ACLs to your Model Objects +------------------------------------ + +When ``repoze.bfg`` determines whether a user possesses a particular +permission in a context, it examines the ACL associated with the +context. An ACL is associated with a context by virtue of the +``__acl__`` attribute of the model object representing the context. +This attribute can be defined on the model *instance* (if you need +instance-level security), or it can be defined on the model *class* +(if you just need type-level security). + +For example, an ACL might be attached to model for a blog via its +class:: + + from repoze.bfg.security import Everyone + from repoze.bfg.security import Allow + from zope.location.interfaces import ILocation + from zope.location.location import Location + + class IBlog(Interface): + pass + + class Blog(dict, Location): + __acl__ = [ + (Allow, Everyone, 'view'), + (Allow, 'group:editors', 'add'), + (Allow, 'group:editors', 'edit'), + ] + implements(IBlog, ILocation) + +The above ACL indicates that the Everyone principal (a system-defined +principal) is allowed to view the blog, the ``group:editors`` +principal is allowed to add to and edit the blog. + +ACL Inheritance +--------------- + +While the security policy is in place, if a model object does not have +an ACL when it is the context, its *parent* is consulted for an ACL. +If that object does not have an ACL, *its* parent is consulted for an +ACL, ad infinitum, until we've reached the root and there are no more +parents left. + +The *first* ACL found by the security policy will be used as the +effective ACL. No combination of ACLs found during traversal or +backtracking is done. + +Location-Awareness +------------------ + +In order to allow the security machinery to perform ACL inheritance, +model objects should provide *location-awareness*. + +Objects have parents when they define an ``__parent__`` attribute +which points at their parent object. The root object's ``__parent__`` +is ``None``. An object with a ``__parent__`` attribute and a +``__name__`` attribute is said to be *location-aware*. + +If the root object in a ``repoze.bfg`` application declares that it +implements the ``ILocation`` interface, it is assumed that the objects +in the rest of the model are location-aware. Even if they are not +explictly, if the root object is marked as ``ILocation``, the bfg +framework will wrap each object during traversal in a *location +proxy*, which will wrap each object found during traversal in a proxy +object that has both the ``__name__`` and ``__parent__`` attributes, +but otherwise acts the same as your model object. + +You can of course supply ``__name__`` and ``__parent__`` attributes +explicitly on all of your model objects, and no location proxying will +be performed. -- cgit v1.2.3