pyramid.security

Authentication API Functions

authenticated_userid(request)

A function that returns the value of the property pyramid.request.Request.authenticated_userid.

Deprecated since version 1.5: Use pyramid.request.Request.authenticated_userid instead.

unauthenticated_userid(request)

A function that returns the value of the property pyramid.request.Request.unauthenticated_userid.

Deprecated since version 1.5: Use pyramid.request.Request.unauthenticated_userid instead.

effective_principals(request)

A function that returns the value of the property pyramid.request.Request.effective_principals.

Deprecated since version 1.5: Use pyramid.request.Request.effective_principals instead.

forget(request)

Return a sequence of header tuples (e.g. [('Set-Cookie', 'foo=abc')]) suitable for 'forgetting' the set of credentials possessed by the currently authenticated user. A common usage might look like so within the body of a view function (response is assumed to be an WebOb -style response object computed previously by the view code):

from pyramid.security import forget
headers = forget(request)
response.headerlist.extend(headers)
return response

If no authentication policy is in use, this function will always return an empty sequence.

remember(request, userid, **kwargs)

Returns a sequence of header tuples (e.g. [('Set-Cookie', 'foo=abc')]) on this request's response. These headers are suitable for 'remembering' a set of credentials implied by the data passed as userid and *kw using the current authentication policy. Common usage might look like so within the body of a view function (response is assumed to be a WebOb -style response object computed previously by the view code):

from pyramid.security import remember
headers = remember(request, 'chrism', password='123', max_age='86400')
response = request.response
response.headerlist.extend(headers)
return response

If no authentication policy is in use, this function will always return an empty sequence. If used, the composition and meaning of **kw must be agreed upon by the calling code and the effective authentication policy.

Changed in version 1.6: Deprecated the principal argument in favor of userid to clarify its relationship to the authentication policy.

Changed in version 1.10: Removed the deprecated principal argument.

Authorization API Functions

has_permission(permission, context, request)

A function that calls pyramid.request.Request.has_permission() and returns its result.

Deprecated since version 1.5: Use pyramid.request.Request.has_permission() instead.

Changed in version 1.5a3: If context is None, then attempt to use the context attribute of self; if not set, then the AttributeError is propagated.

principals_allowed_by_permission(context, permission)

Provided a context (a resource object), and a permission (a string or unicode object), if an authorization policy is in effect, return a sequence of principal ids that possess the permission in the context. If no authorization policy is in effect, this will return a sequence with the single value pyramid.security.Everyone (the special principal identifier representing all principals).

Note

Even if an authorization policy is in effect, some (exotic) authorization policies may not implement the required machinery for this function; those will cause a NotImplementedError exception to be raised when this function is invoked.

view_execution_permitted(context, request, name='')

If the view specified by context and name is protected by a permission, check the permission associated with the view using the effective authentication/authorization policies and the request. Return a boolean result. If no authorization policy is in effect, or if the view is not protected by a permission, return True. If no view can view found, an exception will be raised.

Changed in version 1.4a4: An exception is raised if no view is found.

Constants

Everyone

The special principal id named 'Everyone'. This principal id is granted to all requests. Its actual value is the string 'system.Everyone'.

Authenticated

The special principal id named 'Authenticated'. This principal id is granted to all requests which contain any other non-Everyone principal id (according to the authentication policy). Its actual value is the string 'system.Authenticated'.

ALL_PERMISSIONS

An object that can be used as the permission member of an ACE which matches all permissions unconditionally. For example, an ACE that uses ALL_PERMISSIONS might be composed like so: ('Deny', 'system.Everyone', ALL_PERMISSIONS).

DENY_ALL

A convenience shorthand ACE that defines ('Deny', 'system.Everyone', ALL_PERMISSIONS). This is often used as the last ACE in an ACL in systems that use an "inheriting" security policy, representing the concept "don't inherit any other ACEs".

NO_PERMISSION_REQUIRED

A special permission which indicates that the view should always be executable by entirely anonymous users, regardless of the default permission, bypassing any authorization policy that may be in effect. Its actual value is the string '__no_permission_required__'.

Return Values

Allow

The ACE "action" (the first element in an ACE e.g. (Allow, Everyone, 'read') that means allow access. A sequence of ACEs makes up an ACL. It is a string, and its actual value is "Allow".

Deny

The ACE "action" (the first element in an ACE e.g. (Deny, 'george', 'read') that means deny access. A sequence of ACEs makes up an ACL. It is a string, and its actual value is "Deny".

class Denied(s, *args)

An instance of Denied is returned when a security-related API or other Pyramid code denies an action unrelated to an ACL check. It evaluates equal to all boolean false types. It has an attribute named msg describing the circumstances for the deny.

static __new__(cls, s, *args)

Create a new instance.

Parameters:

• fmt -- A format string explaining the reason for denial.

• args -- Arguments are stored and used with the format string to generate the msg.

property msg

A string indicating why the result was generated.

class Allowed(s, *args)

An instance of Allowed is returned when a security-related API or other Pyramid code allows an action unrelated to an ACL check. It evaluates equal to all boolean true types. It has an attribute named msg describing the circumstances for the allow.

static __new__(cls, s, *args)

Create a new instance.

Parameters:

• fmt -- A format string explaining the reason for denial.

• args -- Arguments are stored and used with the format string to generate the msg.

property msg

A string indicating why the result was generated.

class ACLDenied(ace, acl, permission, principals, context)

An instance of ACLDenied is a specialization of pyramid.security.Denied that represents that a security check made explicitly against ACL was denied. It evaluates equal to all boolean false types. It also has the following attributes: acl, ace, permission, principals, and context. These attributes indicate the security values involved in the request. Its __str__ method prints a summary of these attributes for debugging purposes. The same summary is available as the msg attribute.

static __new__(cls, ace, acl, permission, principals, context)

Create a new instance.

Parameters:

• ace -- The ACE that matched, triggering the result.

• acl -- The ACL containing ace.

• permission -- The required permission.

• principals -- The list of principals provided.

• context -- The context providing the lineage searched.

property msg

A string indicating why the result was generated.

class ACLAllowed(ace, acl, permission, principals, context)

An instance of ACLAllowed is a specialization of pyramid.security.Allowed that represents that a security check made explicitly against ACL was allowed. It evaluates equal to all boolean true types. It also has the following attributes: acl, ace, permission, principals, and context. These attributes indicate the security values involved in the request. Its __str__ method prints a summary of these attributes for debugging purposes. The same summary is available as the msg attribute.

static __new__(cls, ace, acl, permission, principals, context)

Create a new instance.

Parameters:

• ace -- The ACE that matched, triggering the result.

• acl -- The ACL containing ace.

• permission -- The required permission.

• principals -- The list of principals provided.

• context -- The context providing the lineage searched.

property msg

A string indicating why the result was generated.