Security

repoze.bfg provides an optional declarative authorization system that prevents a view from being invoked when the user represented by credentials in the request does not have an appropriate level of access with respect to a specific context.

Authorization is enabled by modifying your application registry (aka configure.zcml).

Enabling an Authorization Policy

By default, repoze.bfg enables no authorization policy. All views are accessible by completely anonymous users.

However, if you modify the application registry file in your application’s package (usually named configure.zcml), you can enable an authorization policy.

You must also enable a a authentication policy in order to enable the an authorization policy (this is because authorization, in general, depends upon authentication).

For example, to enable a policy which compares the value of an “auth ticket” cookie passed in the request’s environment which contains a reference to a single principal against the principals present in any ACL found in model data when attempting to call some view, modify your configure.zcml to look something like this:

<configure xmlns="http://namespaces.repoze.org/bfg">

  <!-- views and other directives before this... -->

  <authtktauthenticationpolicy
       secret="iamsosecret"/>

  <aclauthorizationpolicy/>

 </configure>

“Under the hood”, these statements cause an instance of the class repoze.bfg.authentication.AuthTktAuthenticationPolicy to be injected as the authentication policy used by this application and an instance of the class repoze.bfg.authorization.ACLAuthorizationPolicy to be injected as the authorization policy used by this application.

repoze.bfg ships with a few pre-chewed authentication and authorization policies that should prove useful. See Built-In Authentication Policy Directives and Built-In Authorization Policy Directives for more information.

It is also possible to construct your own custom authentication policy or authorization policy: see Creating Your Own Authentication Policy and Creating Your Own Authorization Policy.

Protecting Views with Permissions

You declaratively protect a particular view using a permission name via the configure.zcml application registry. For example, the following declaration protects the view named add_entry.html when invoked against a Blog context with the add permission:

<view
    for=".models.Blog"
    view=".views.blog_entry_add_view"
    name="add_entry.html"
    permission="add"
    />

The equivalent view registration including the ‘add’ permission name may be performed via the bfg_view decorator within the “views” module of your project’s package

from repoze.bfg.view import bfg_view
from models import Blog

@bfg_view(for_=Blog, name='add_entry.html', permission='add')
def blog_entry_add_view(context, request):
    """ Add blog entry code goes here """
    pass

If an authorization 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 usually 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

class Blog(object):
    __acl__ = [
        (Allow, Everyone, 'view'),
        (Allow, 'group:editors', 'add'),
        (Allow, 'group:editors', 'edit'),
        ]

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

from repoze.bfg.security import Everyone
from repoze.bfg.security import Allow

class Blog(object):
    pass

blog = Blog()

blog.__acl__ = [
        (Allow, Everyone, 'view'),
        (Allow, 'group:editors', 'add'),
        (Allow, 'group:editors', 'edit'),
        ]

Whether an ACL is attached to a model’s class or an instance of the model itself, the effect is the same. It is useful to decorate individual model 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.

Elements of an ACL

Here’s an example ACL:

from repoze.bfg.security import Everyone
from repoze.bfg.security import Allow

__acl__ = [
        (Allow, Everyone, 'view'),
        (Allow, 'group:editors', 'add'),
        (Allow, 'group:editors', 'edit'),
        ]

The example ACL indicates that the Everyone principal (a special system-defined principal indicating, literally, everyone) is allowed to view the blog, the group:editors principal is allowed to add to and edit the blog.

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.

from repoze.bfg.security import Everyone
from repoze.bfg.security import Allow

__acl__ = [
    (Allow, Everyone, 'view'),
    (Allow, 'group:editors', ('add', 'edit')),
    ]

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 RepozeWho1AuthenicationPolicy enabled by the repozewho1authenticationpolicy ZCML directive respects group information if you configure it with a callback. See Built-In Authentication Policy Directives for more information about the callback attribute.

Each tuple within an ACL structure is known as a ACE, which stands for “access control entry”. For example, in the above ACL, (Allow, Everyone, 'view') is an ACE. 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:

from repoze.bfg.security import Everyone
from repoze.bfg.security import Allow
from repoze.bfg.security import Deny

__acl__ = [
    (Allow, Everyone, 'view'),
    (Deny, Everyone, 'view'),
    ]

The 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:

from repoze.bfg.security import Everyone
from repoze.bfg.security import Allow
from repoze.bfg.security import Deny

__acl__ = [
    (Deny, Everyone, 'view'),
    (Allow, Everyone, 'view'),
    ]

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

Special Principal Names

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

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.

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).

Special Permissions

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

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.

Special ACEs

A convenience ACE is defined within the repoze.bfg.security module named DENY_ALL. It equals the following:

(Deny, Everyone, ALL_PERMISSIONS)

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 in a particular traversal context despite what inherited ACLs may say when the default authorization policy is in effect might look like so:

from repoze.bfg.security import Allow
from repoze.bfg.security import DENY_ALL

__acl__ = [ (Allow, 'fred', 'view'), DENY_ALL ]

ACL Inheritance

While the default authorization 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.

Location-Awareness

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

class Blog(object):
    __name__ = ''
    __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 repoze.bfg.location for documentations of functions which use location-awareness. See also Location-Aware Model Instances.

Changing the Forbidden View

When repoze.bfg 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 ZCML Hooks for instructions on how to create a custom forbidden view and arrange for it to be called when view authorization is denied.

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 BFG_DEBUG_AUTHORIZATION environment variable set to 1. For example:

$ BFG_DEBUG_AUTHORIZATION=1 bin/paster serve 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 debug_authorization key to true within the application’s configuration section, e.g.:

[app:main]
use = egg:MyProject#app
debug_authorization = true

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

Debugging Imperative Authorization Failures

The has_permission API (see repoze.bfg.security) is used to check security within view functions imperatively. It returns instances of objects that are effectively booleans. But these objects are not raw True or False objects, and have information attached to them about why the permission was allowed or denied. The object will be one of ACLAllowed, ACLDenied, Allowed, and Denied, documented in repoze.bfg.security. At very minimum these objects will have a msg attribute, which is a string indicating why permission was denied or allowed. Introspecting this information in the debugger or via print statements when a has_permission fails is often useful.

Built-In Authentication Policy Directives

repoze.who ships with a few “pre-chewed” authentication policy implementations that you can make use of within your application.

repozewho1authenticationpolicy

When this directive is used, authentication information is obtained from a repoze.who.identity key in the WSGI environment, assumed to be set by repoze.who middleware.

An example of its usage, with all attributes fully expanded:

<repozewho1authenticationpolicy
 identifier_name="auth_tkt"
 callback=".somemodule.somefunc"
 />

The identifier_name controls the name used to look up the repoze.who “identifier” plugin within environ['repoze.who.plugins'] which is used by this policy to “remember” and “forget” credentials. It defaults to auth_tkt.

The callback is a Python dotted name to a function passed the repoze.who identity and the request as positional arguments. The callback is expected to return None if the user represented by the identity doesn’t exist or a sequence of group identifiers (possibly empty) if the user does exist. If callback is None, the userid will be assumed to exist with no groups. It defaults to None.

remoteuserauthenticationpolicy

When this directive is used, authentication information is obtained from a REMOTE_USER key in the WSGI environment, assumed to be set by a WSGI server or an upstream middleware component.

An example of its usage, with all attributes fully expanded:

<remoteuserauthenticationpolicy
 environ_key="REMOTE_USER"
 callback=".somemodule.somefunc"
 />

The environ_key is the name that will be used to obtain the remote user value from the WSGI environment. It defaults to REMOTE_USER.

The callback is a Python dotted name to a function passed the string representing the remote user and the request as positional arguments. The callback is expected to return None if the user represented by the string doesn’t exist or a sequence of group identifiers (possibly empty) if the user does exist. If callback is None, the userid will be assumed to exist with no groups. It defaults to None.

authtktauthenticationpolicy

When this directive is used, authentication information is obtained from an “auth ticket” cookie value, assumed to be set by a custom login form.

An example of its usage, with all attributes fully expanded:

<authtktauthenticationpolicy
 secret="goshiamsosecret"
 callback=".somemodule.somefunc"
 cookie_name="mycookiename"
 secure="false"
 include_ip="false"
 timeout="86400"
 reissue_time="600"
 />

The secret is a string that will be used to encrypt the data stored by the cookie. It is required and has no default.

The callback is a Python dotted name to a function passed the string representing the userid stored in the cookie and the request as positional arguments. The callback is expected to return None if the user represented by the string doesn’t exist or a sequence of group identifiers (possibly empty) if the user does exist. If callback is None, the userid will be assumed to exist with no groups. It defaults to None.

The cookie_name is the name used for the cookie that contains the user information. It defaults to repoze.bfg.auth_tkt.

secure is a boolean value. If it’s set to “true”, the cookie will only be sent back by the browser over a secure (HTTPS) connection. It defaults to “false”.

include_ip is a boolean value. If it’s set to true, the requesting IP address is made part of the authentication data in the cookie; if the IP encoded in the cookie differs from the IP of the requesting user agent, the cookie is considered invalid. It defaults to “false”.

timeout is an integer value. It represents the maximum age in seconds allowed for a cookie to live. If timeout is specified, you must also set reissue_time to a lower value. It defaults to None, meaning that the cookie will only live for the duration of the user’s browser session.

reissue_time is an integer value. If reissue_time is specified, when we encounter a cookie that is older than the reissue time (in seconds), but younger that the timeout, a new cookie will be issued. It defaults to None, meaning that authentication cookies are never reissued.

Built-In Authorization Policy Directives

aclauthorizationpolicy

When this directive is used, authorization information is obtained from ACL objects attached to model instances.

An example of its usage, with all attributes fully expanded:

<aclauthorizationpolicy/>

In other words, it has no configuration attributes; its existence in a configure.zcml file enables it.

Creating Your Own Authentication Policy

repoze.bfg ships with a number of useful out-of-the-box security policies (see Built-In Authentication Policy Directives). However, creating your own authentication policy is often necessary when you want to control the “horizontal and vertical” of how your users authenticate. Doing so is matter of creating an instance of something that implements the following interface:

class AuthenticationPolicy(object):
    """ An object representing a BFG authentication policy. """
    def authenticated_userid(self, request):
        """ Return the authenticated userid or ``None`` if no
        authenticated userid can be found. """

    def effective_principals(self, request):
        """ Return a sequence representing the effective principals
        including the userid and any groups belonged to by the current
        user, including 'system' groups such as Everyone and
        Authenticated. """

    def remember(self, request, principal, **kw):
        """ Return a set of headers suitable for 'remembering' the
        principal named ``principal`` when set in a response.  An
        individual authentication policy and its consumers can decide
        on the composition and meaning of **kw. """

    def forget(self, request):
        """ Return a set of headers suitable for 'forgetting' the
        current user on subsequent requests. """

You will then need to create a ZCML directive which allows you to use the authentication policy within a ZCML file. See the repoze.bfg.zcml module in the repoze.bfg source code for examples of how to create a directive. Authorization policy ZCML directives should use the ZCML discriminator value “authentication_policy” in their actions to allow for conflict detection.

Creating Your Own Authorization Policy

An authentication policy the policy that allows or denies access after a user has been authenticated. By default, repoze.bfg will use the repoze.bfg.authorization.ACLAuthorizationPolicy if an authentication policy is activated and an authorization policy isn’t otherwise specified. In some cases, it’s useful to be able to use a different authentication policy than the repoze.bfg.authorization.ACLAuthorizationPolicy. For example, it might be desirable to construct an alternate authorization policy which allows the application to use an authorization mechanism that does not involve ACL objects.

repoze.bfg ships with only its single default ACLAuthorizationPolicy, so you’ll need to create your own if you’d like to use a different one. Creating and using your own authorization policy is a matter of creating an instance of an object that implements the following interface:

class IAuthorizationPolicy(object):
    """ A adapter on context """
    def permits(self, context, principals, permission):
        """ Return True if any of the principals is allowed the
        permission in the current context, else return False """

    def principals_allowed_by_permission(self, context, permission):
        """ Return a set of principal identifiers allowed by the
            permission """

You will then need to create a ZCML directive which allows you to use the authorization policy within a ZCML file. See the repoze.bfg.zcml module in the repoze.bfg source for examples of how to create a directive. Authorization policy ZCML directives should use the ZCML discriminator value “authorization_policy” in their actions to allow for conflict detection.