:app:`Pyramid` provides an optional declarative authorization system that prevents a :term:`view` from being invoked when the user represented by credentials in the :term:`request` does not have an appropriate level of access within a particular :term:`context`. Here's how it works at a high level:
- A :term:`request` is generated when a user visits our application.
- Based on the request, a :term:`context` is located through :term:`context finding`. A context is located differently depending on whether the application uses :term:`traversal` or :term:`URL dispatch`, but a context is ultimately found in either case. See :ref:`contextfinding_chapter` for more information about context finding.
- A :term:`view callable` is located by :term:`view lookup` using the context as well as other attributes of the request.
- If an :term:`authentication policy` is in effect, it is passed the request; it returns some number of :term:`principal` identifiers.
- If an :term:`authorization policy` is in effect and the :term:`view configuration` associated with the view callable that was found has a :term:`permission` associated with it, the authorization policy is passed the :term:`context`, some number of :term:`principal` identifiers returned by the authentication policy, and the :term:`permission` 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 :term:`forbidden view` is invoked.
Authorization is enabled by modifying your application to include an :term:`authentication policy` and :term:`authorization policy`. :app:`Pyramid` comes with a variety of implementations of these policies. To provide maximal flexibility, :app:`Pyramid` also allows you to create custom authentication policies and authorization policies.
Enabling an Authorization Policy
By default, :app:`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.
Enabling an Authorization Policy Imperatively
authorization_policy argument to the constructor of the
:class:`pyramid.config.Configurator` class enables an
You must also enable an :term:`authentication policy` in order to
enable the authorization policy. This is because authorization, in
general, depends upon authentication. Use the
authentication_policy argument to the
:class:`pyramid.config.Configurator` class during
application setup to specify an authentication policy.
arguments may also be passed to the Configurator as :ref:`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 :term:`principal` against the principals present in any :term:`ACL` found in model data when attempting to call some :term:`view`.
While it is possible to mix and match different authentication and authorization policies, it is an error to pass an authentication policy without the authorization policy or vice versa to a :term:`Configurator` constructor.
You can also enable a security policy declaratively via ZCML. See :ref:`zcml_authorization_policy`.
Protecting Views with Permissions
To protect a :term:`view callable` from invocation based on a user's security settings in a :term:`context`, you must pass a :term:`permission` to :term:`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 invoked against a
Blog context with the
permission using the :meth:`pyramid.config.Configurator.add_view` API:
The equivalent view registration including the
add permission name
may be performed via the
Or the same thing can be done using the
permission attribute of the ZCML
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 :term:`context` to be able to invoke the
blog_entry_add_view view. If he does not, the :term:`Forbidden view`
will be invoked.
Setting a Default Permission
If a permission is not supplied to a view configuration, the registered view 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", :app:`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
These APIs are in support of configuring a default permission for an application:
default_permissionconstructor argument to the :mod:`pyramid.config.Configurator` constructor.
- The :meth:`pyramid.config.Configurator.set_default_permission` method.
- The :ref:`default_permission_directive` ZCML directive.
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 an explicit permission as the string
__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).
Assigning ACLs to your Model Objects
When the default :app:`Pyramid` :term:`authorization policy`
determines whether a user possesses a particular permission in a
:term:`context`, it examines the :term:`ACL` associated with the
context. An ACL is associated with a context by virtue of the
__acl__ attribute of the model object representing the
:term:`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 the model for a blog via its class:
Or, if your models are persistent, an ACL might be specified via the
__acl__ attribute of an instance of a model:
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:
The example ACL indicates that the
:data:`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 :term:`ACE` or access control entry.
For example, in the above code block, there are three ACEs:
(Allow, 'group:editors', 'add'), and
(Allow, 'group:editors', 'edit').
The first element of any ACE is either :data:`pyramid.security.Allow`, or :data:`pyramid.security.Deny`, representing the action to take when the ACE matches. The second element is a :term:`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
:term:`authentication policy` policy is written to respect group information.
For example, the
:class:`pyramid.authentication.RepozeWho1AuthenicationPolicy` respects group
information if you configure it with a
:ref:`authentication_policies_directives_section` for more information about
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:
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
group:editors group, we can collapse this into a single
ACE, as below.
Special Principal Names
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.
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" (
Special permission names exist in the :mod:`pyramid.security` module. These can be imported for use in ACLs.
An object representing, literally, all permissions. Useful in an ACL like so:
(Allow, 'fred', ALL_PERMISSIONS). The
ALL_PERMISSIONSobject 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.
A convenience :term:`ACE` is defined representing a deny to everyone
of all permissions in :data:`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 in a particular
traversal context despite what inherited ACLs may say when the default
authorization policy is in effect might look like so:
"Under the hood", the :data:`pyramid.security.DENY_ALL` ACE equals the following:
ACL Inheritance and Location-Awareness
While the default :term:`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.
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
An object with a
__parent__ attribute and a
is said to be location-aware. Location-aware objects define an
__parent__ attribute which points at their parent object. The
Changing the Forbidden View
When :app:`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
:ref:`changing_the_forbidden_view` within :ref:`hooks_chapter` 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
$ 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
by setting the
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.
Debugging Imperative Authorization Failures
The :func:`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
False objects, and have information attached to them
about why the permission was allowed or denied. The object will be
one of :data:`pyramid.security.ACLAllowed`,
:data:`pyramid.security.Denied`, as documented in
:ref:`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
:func:`pyramid.security.has_permission` fails is often useful.
Creating Your Own Authentication Policy
:app:`Pyramid` ships with a number of useful out-of-the-box security policies (see :mod:`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:
After you do so, you can pass an instance of such a class into the
:class:`pyramid.config.Configurator` class at configuration
authentication_policy to use it.
Creating Your Own Authorization Policy
An authorization policy is a policy that allows or denies access after a user has been authenticated. By default, :app:`Pyramid` will use the :class:`pyramid.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 authorization policy than the default :class:`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 :term:`ACL` objects.
:app:`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:
After you do so, you can pass an instance of such a class into the
:class:`pyramid.config.Configurator` class at configuration
authorization_policy to use it.