Файл: pyramid.pdf

27.2. PROTECTING VIEWS WITH PERMISSIONS

While it is possible to mix and match different authentication and authorization policies, it is an error to configure a Pyramid application with an authentication policy but without the authorization policy or vice versa. If you do this, you’ll receive an error at application startup time.

See also the pyramid.authorization and pyramid.authentication modules for alternate implementations of authorization and authentication policies.

27.2 Protecting Views with Permissions

To protect a view callable from invocation based on a user’s security settings when a particular type of resource becomes the context, you must pass a permission to view configuration. Permissions are usually just strings, and they have no required composition: you can name permissions whatever you like.

For example, the following view declaration protects the view named add_entry.html when the context resource is of type Blog with the add permission using the pyramid.config.Configurator.add_view() API:

The equivalent view registration including the add permission name may be performed via the

@view_config decorator:

1 from pyramid.view import view_config

2 from resources import Blog

3

4 @view_config(context=Blog, name=’add_entry.html’, permission=’add’) 5 def blog_entry_add_view(request):

6""" Add blog entry code goes here """

7pass

As a result of any of these various view configuration statements, if an authorization policy is in place when the view callable is found during normal application operations, the requesting user will need to possess the add permission against the context resource in order to be able to invoke the blog_entry_add_view view. If he does not, the Forbidden view will be invoked.

295

27. SECURITY

27.2.1 Setting a Default Permission

If a permission is not supplied to a view configuration, the registered view will always be executable by entirely anonymous users: any authorization policy in effect is ignored.

In support of making it easier to configure applications which are “secure by default”, Pyramid allows you to configure a default permission. If supplied, the default permission is used as the permission string to all view registrations which don’t otherwise name a permission argument.

The pyramid.config.Configurator.set_default_permission() method supports configuring a default permission for an application.

When a default permission is registered:

•If a view configuration names an explicit permission, the default permission is ignored for that view registration, and the view-configuration-named permission is used.

•If a view configuration names the permission pyramid.security.NO_PERMISSION_REQUIRED, the default permission is ignored, and the view is registered without a permission (making it available to all callers regardless of their credentials).

27.3 Assigning ACLs to your Resource Objects

When the default Pyramid authorization policy determines whether a user possesses a particular permission with respect to a resource, it examines the ACL associated with the resource. An ACL is associated with a resource by adding an __acl__ attribute to the resource object. This attribute can be defined on the resource instance if you need instance-level security, or it can be defined on the resource class if you just need type-level security.

For example, an ACL might be attached to the resource for a blog via its class:

296

27.4. ELEMENTS OF AN ACL

1 from pyramid.security import Everyone

2 from pyramid.security import Allow

3

4 class Blog(object):

5__acl__ = [

6(Allow, Everyone, ’view’),

7(Allow, ’group:editors’, ’add’),

8(Allow, ’group:editors’, ’edit’),

9]

Or, if your resources are persistent, an ACL might be specified via the __acl__ attribute of an instance of a resource:

1 from pyramid.security import Everyone

2 from pyramid.security import Allow

3

4 class Blog(object):

5pass

6

7 blog = Blog()

8

9 blog.__acl__ = [

10(Allow, Everyone, ’view’),

11(Allow, ’group:editors’, ’add’),

12(Allow, ’group:editors’, ’edit’),

13]

Whether an ACL is attached to a resource’s class or an instance of the resource itself, the effect is the same. It is useful to decorate individual resource instances with an ACL (as opposed to just decorating their class) in applications such as “CMS” systems where fine-grained access is required on an object-by- object basis.

27.4 Elements of an ACL

Here’s an example ACL:

297

27. SECURITY

The example ACL indicates that the pyramid.security.Everyone principal – a special systemdefined principal indicating, literally, everyone – is allowed to view the blog, the group:editors principal is allowed to add to and edit the blog.

Each element of an ACL is an ACE or access control entry. For example, in the above code block, there are three ACEs: (Allow, Everyone, ’view’), (Allow, ’group:editors’, ’add’), and (Allow, ’group:editors’, ’edit’).

The first element of any ACE is either pyramid.security.Allow, or pyramid.security.Deny, representing the action to take when the ACE matches. The second element is a principal. The third argument is a permission or sequence of permission names.

A principal is usually a user id, however it also may be a group id if your authentication system provides group information and the effective authentication policy policy is written to respect group information. For example, the pyramid.authentication.RepozeWho1AuthenicationPolicy respects group information if you configure it with a callback.

Each ACE in an ACL is processed by an authorization policy in the order dictated by the ACL. So if you have an ACL like this:

The default authorization policy will allow everyone the view permission, even though later in the ACL you have an ACE that denies everyone the view permission. On the other hand, if you have an ACL like this:

4

298

27.5. SPECIAL PRINCIPAL NAMES

The authorization policy will deny everyone the view permission, even though later in the ACL is an ACE that allows everyone.

The third argument in an ACE can also be a sequence of permission names instead of a single permission name. So instead of creating multiple ACEs representing a number of different permission grants to a single group:editors group, we can collapse this into a single ACE, as below.

1 from pyramid.security import Everyone

2 from pyramid.security import Allow

3

4 __acl__ = [

5(Allow, Everyone, ’view’),

6(Allow, ’group:editors’, (’add’, ’edit’)),

7]

27.5 Special Principal Names

Special principal names exist in the pyramid.security module. They can be imported for use in your own code to populate ACLs, e.g. pyramid.security.Everyone.

pyramid.security.Everyone

Literally, everyone, no matter what. This object is actually a string “under the hood” (system.Everyone). Every user “is” the principal named Everyone during every request, even if a security policy is not in use.

pyramid.security.Authenticated

Any user with credentials as determined by the current security policy. You might think of it as any user that is “logged in”. This object is actually a string “under the hood” (system.Authenticated).

299

27. SECURITY

27.6 Special Permissions

Special permission names exist in the pyramid.security module. These can be imported for use in ACLs. pyramid.security.ALL_PERMISSIONS

An object representing, literally, all permissions. Useful in an ACL like so: (Allow, ’fred’, ALL_PERMISSIONS). The ALL_PERMISSIONS object is actually a stand-in object that has a __contains__ method that always returns True, which, for all known authorization policies, has the effect of indicating that a given principal “has” any permission asked for by the system.

27.7 Special ACEs

A convenience ACE is defined representing a deny to everyone of all permissions in pyramid.security.DENY_ALL. This ACE is often used as the last ACE of an ACL to explicitly cause inheriting authorization policies to “stop looking up the traversal tree” (effectively breaking any inheritance). For example, an ACL which allows only fred the view permission for a particular resource despite what inherited ACLs may say when the default authorization policy is in effect might look like so:

“Under the hood”, the pyramid.security.DENY_ALL ACE equals the following:

27.8 ACL Inheritance and Location-Awareness

While the default authorization policy is in place, if a resource 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.

In order to allow the security machinery to perform ACL inheritance, resource objects must provide location-awareness. Providing location-awareness means two things: the root object in the resource tree must have a __name__ attribute and a __parent__ attribute.

300

27.9. CHANGING THE FORBIDDEN VIEW

1 class Blog(object):

2__name__ = ’’

3__parent__ = None

An object with a __parent__ attribute and a __name__ attribute is said to be location-aware. Location-aware objects define an __parent__ attribute which points at their parent object. The root object’s __parent__ is None.

See pyramid.location for documentations of functions which use location-awareness. See also LocationAware Resources.

27.9 Changing the Forbidden View

When Pyramid denies a view invocation due to an authorization denial, the special forbidden view is invoked. “Out of the box”, this forbidden view is very plain. See Changing the Forbidden View within Using Hooks for instructions on how to create a custom forbidden view and arrange for it to be called when view authorization is denied.

27.10 Debugging View Authorization Failures

If your application in your judgment is allowing or denying view access inappropriately, start your application under a shell using the PYRAMID_DEBUG_AUTHORIZATION environment variable set to 1. For example:

$ PYRAMID_DEBUG_AUTHORIZATION=1 bin/pserve myproject.ini

When any authorization takes place during a top-level view rendering, a message will be logged to the console (to stderr) about what ACE in which ACL permitted or denied the authorization based on authentication information.

This behavior can also be turned on in the application .ini file by setting the pyramid.debug_authorization key to true within the application’s configuration section, e.g.:

With this debug flag turned on, the response sent to the browser will also contain security debugging information in its body.

301