single: security
Pyramid
provides an optional declarative authorization system that can prevent a view
from being invoked based on an authorization policy
. Before a view is invoked, the authorization system can use the credentials in the request
along with the context
resource to determine if access will be allowed. Here's how it works at a high level:
- A
request
is generated when a user visits the application. - Based on the request, a
context
resource is located throughresource location
. A context is located differently depending on whether the application usestraversal
orURL dispatch
, but a context is ultimately found in either case. See theurldispatch_chapter
chapter for more information. - A
view callable
is located byview lookup
using the context as well as other attributes of the request. - If an
authentication policy
is in effect, it is passed the request; it returns some number ofprincipal
identifiers. - If an
authorization policy
is in effect and theview configuration
associated with the view callable that was found has apermission
associated with it, the authorization policy is passed thecontext
, some number ofprincipal
identifiers returned by the authentication policy, and thepermission
associated with the view; it will allow or deny access. - If the authorization policy allows access, the view callable is invoked.
- If the authorization policy denies access, the view callable is not invoked; instead the
forbidden view
is invoked.
Security in Pyramid
, unlike many systems, cleanly and explicitly separates authentication and authorization. Authentication is merely the mechanism by which credentials provided in the request
are resolved to one or more principal
identifiers. These identifiers represent the users and groups in effect during the request. Authorization then determines access based on the principal
identifiers, the view callable
being invoked, and the context
resource.
Authorization is enabled by modifying your application to include an authentication policy
and authorization policy
. Pyramid
comes with a variety of implementations of these policies. To provide maximal flexibility, Pyramid
also allows you to create custom authentication policies and authorization policies.
single: authorization policy
By default, Pyramid
enables no authorization policy. All views are accessible by completely anonymous users. In order to begin protecting views from execution based on security settings, you need to enable an authorization policy.
Use the ~pyramid.config.Configurator.set_authorization_policy
method of the ~pyramid.config.Configurator
to enable an authorization policy.
You must also enable an authentication policy
in order to enable the authorization policy. This is because authorization, in general, depends upon authentication. Use the ~pyramid.config.Configurator.set_authentication_policy
and method during application setup to specify the authentication policy.
For example:
from pyramid.config import Configurator
from pyramid.authentication import AuthTktAuthenticationPolicy
from pyramid.authorization import ACLAuthorizationPolicy
authentication_policy = AuthTktAuthenticationPolicy('seekrit')
authorization_policy = ACLAuthorizationPolicy()
config = Configurator()
config.set_authentication_policy(authentication_policy)
config.set_authorization_policy(authorization_policy)
Note
the authentication_policy
and authorization_policy
arguments may also be passed to their respective methods mentioned above as dotted Python name
values, each representing the dotted name path to a suitable implementation global defined at Python module scope.
The above configuration enables 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 the resource tree when attempting to call some view
.
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.
single: permissions single: protecting views
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:
# config is an instance of pyramid.config.Configurator
config.add_view('mypackage.views.blog_entry_add_view',
name='add_entry.html',
context='mypackage.resources.Blog',
permission='add')
The equivalent view registration including the add
permission name may be performed via the @view_config
decorator:
from pyramid.view import view_config
from resources import Blog
@view_config(context=Blog, name='add_entry.html', permission='add')
def blog_entry_add_view(request):
""" Add blog entry code goes here """
pass
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.
pair: permission; default
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).
Warning
When you register a default permission, all views (even exception
view
views) are protected by a permission. For all views which are truly meant to be anonymously accessible, you will need to associate the view's configuration with the pyramid.security.NO_PERMISSION_REQUIRED
permission.
single: ACL single: access control list pair: resource; ACL
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:
from pyramid.security import Everyone
from pyramid.security import Allow
class Blog(object):
__acl__ = [
(Allow, Everyone, 'view'),
(Allow, 'group:editors', 'add'),
(Allow, 'group:editors', 'edit'),
]
Or, if your resources are persistent, an ACL might be specified via the __acl__
attribute of an instance of a resource:
from pyramid.security import Everyone
from pyramid.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 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.
single: ACE single: access control entry
Here's an example ACL:
from pyramid.security import Everyone
from pyramid.security import Allow
__acl__ = [
(Allow, Everyone, 'view'),
(Allow, 'group:editors', 'add'),
(Allow, 'group:editors', 'edit'),
]
The example ACL indicates that the pyramid.security.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.
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:
from pyramid.security import Everyone
from pyramid.security import Allow
from pyramid.security import Deny
__acl__ = [
(Allow, Everyone, 'view'),
(Deny, Everyone, 'view'),
]
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:
from pyramid.security import Everyone
from pyramid.security import Allow
from pyramid.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.
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 pyramid.security import Everyone
from pyramid.security import Allow
__acl__ = [
(Allow, Everyone, 'view'),
(Allow, 'group:editors', ('add', 'edit')),
]
single: principal single: 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
).
single: permission names single: special permission names
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)
. TheALL_PERMISSIONS
object is actually a stand-in object that has a__contains__
method that always returnsTrue
, which, for all known authorization policies, has the effect of indicating that a given principal "has" any permission asked for by the system.
single: special ACE single: ACE (special)
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:
from pyramid.security import Allow
from pyramid.security import DENY_ALL
__acl__ = [ (Allow, 'fred', 'view'), DENY_ALL ]
"Under the hood", the pyramid.security.DENY_ALL
ACE equals the following:
from pyramid.security import ALL_PERMISSIONS
__acl__ = [ (Deny, Everyone, ALL_PERMISSIONS) ]
single: ACL inheritance pair: location-aware; security
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.
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 location_module
for documentations of functions which use location-awareness. See also location_aware
.
single: 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 hooks_chapter
for instructions on how to create a custom forbidden view and arrange for it to be called when view authorization is denied.
single: debugging 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.:
[app:main]
use = egg:MyProject
pyramid.debug_authorization = true
With this debug flag turned on, the response sent to the browser will also contain security debugging information in its body.
The pyramid.security.has_permission
API 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 pyramid.security.ACLAllowed
, pyramid.security.ACLDenied
, pyramid.security.Allowed
, or pyramid.security.Denied
, as documented in security_module
. At the very minimum these objects will have a msg
attribute, which is a string indicating why the permission was denied or allowed. Introspecting this information in the debugger or via print statements when a call to ~pyramid.security.has_permission
fails is often useful.
single: authentication policy (creating)
Pyramid
ships with a number of useful out-of-the-box security policies (see pyramid.authentication
). 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 a matter of creating an instance of something that implements the following interface:
class IAuthenticationPolicy(object):
""" An object representing a Pyramid authentication policy. """
def authenticated_userid(self, request):
""" Return the authenticated userid or ``None`` if no
authenticated userid can be found. This method of the policy
should ensure that a record exists in whatever persistent store is
used related to the user (the user should not have been deleted);
if a record associated with the current id does not exist in a
persistent store, it should return ``None``."""
def unauthenticated_userid(self, request):
""" Return the *unauthenticated* userid. This method performs the
same duty as ``authenticated_userid`` but is permitted to return the
userid based only on data present in the request; it needn't (and
shouldn't) check any persistent store to ensure that the user record
related to the request userid exists."""
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
``pyramid.security.Everyone`` and
``pyramid.security.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. """
After you do so, you can pass an instance of such a class into the ~pyramid.config.Configurator.set_authentication_policy
method configuration time to use it.
single: authorization policy (creating)
An authorization policy is a policy that allows or denies access after a user has been authenticated. Most Pyramid
applications will use the default pyramid.authorization.ACLAuthorizationPolicy
.
However, in some cases, it's useful to be able to use a different authorization policy than the default ~pyramid.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.
Pyramid
ships with only a single default authorization policy, 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):
""" An object representing a Pyramid authorization policy. """
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`` in ``context``. This behavior is optional; if you
choose to not implement it you should define this method as
something which raises a ``NotImplementedError``. This method
will only be called when the
``pyramid.security.principals_allowed_by_permission`` API is
used."""
After you do so, you can pass an instance of such a class into the ~pyramid.config.Configurator.set_authorization_policy
method at configuration time to use it.