Skip to content

Latest commit

 

History

History
378 lines (285 loc) · 21.5 KB

whatsnew-2.0.rst

File metadata and controls

378 lines (285 loc) · 21.5 KB
Raw

What's New in Pyramid 2.0

This article explains the new features in :app:`Pyramid` version 2.0 as compared to its predecessor, :app:`Pyramid` 1.10. It also documents backwards incompatibilities between the two versions and deprecations added to :app:`Pyramid` 2.0, as well as software dependency changes and notable documentation additions.

Note

This is the first release of :app:`Pyramid` that does not support Python 2, which is now End-of-Life and no longer receiving critical security updates by the PSF.

Feature Additions

The feature additions in Pyramid 2.0 are as follows:

Deprecations

Upgrading Authentication/Authorization

Note

It's important to note that the principal and ACL features within :app:`Pyramid` are not going away, nor deprecated, nor removed. Most ACL features are deprecated in their current locations and moved into the :mod:`pyramid.authorization` module. The main change is that they are now more optional than before and modifications were made to make the top-level APIs less opinionated as well as simpler.

:app:`Pyramid` provides a simple set of APIs for plugging in allowed/denied semantics in your application.

The authentication and authorization policies of Pyramid 1.x have been merged into a single :term:`security policy` in Pyramid 2.0. Authentication and authorization policies can still be used and will continue to function normally, however they have been deprecated and support may be removed in upcoming versions.

The new security policy should implement :class:`pyramid.interfaces.ISecurityPolicy` and can be set via the security_policy argument of :class:`pyramid.config.Configurator` or :meth:`pyramid.config.Configurator.set_security_policy`.

The policy contains :meth:`pyramid.interfaces.ISecurityPolicy.authenticated_userid` and :meth:`pyramid.interfaces.ISecurityPolicy.remember`, with the same method signatures as in the legacy authentication policy. It also contains :meth:`pyramid.interfaces.ISecurityPolicy.forget`, but now accepting keyword arguments in the method signature.

The new security policy adds the concept of an :term:`identity`, which is an object representing the user associated with the current request. The identity can be accessed via :attr:`pyramid.request.Request.identity`. The object can be of any shape, such as a simple ID string or an ORM object.

The concept of :term:`principals <principal>` has been removed from the request object, security policy, and view/route predicates. Principals are replaced by identity. The :meth:`pyramid.interfaces.ISecurityPolicy.permits` method is provided the request, context, and permissions and may now use the identity object, or derive principals, in any way it deems necessary for the application without being restricted to a list of principals represented by strings. This change gives much more flexibility in authorization implementations, especially those that do not match the ACL pattern. If you were previously using :class:`pyramid.authorization.ACLAuthorizationPolicy`, you can achieve the same results by writing your own permits method using :class:`pyramid.authorization.ACLHelper`. For more details on implementing an ACL, see :ref:`assigning_acls`.

Pyramid does not provide any built-in security policies. Similiar functionality of the authentication and authorization policies is now provided by helpers, which can be utilized to implement your own security policy. The functionality of the legacy authentication policies roughly correspond to the following helpers:

Authentication Policy Security Policy Helper
:class:`pyramid.authentication.SessionAuthenticationPolicy` :class:`pyramid.authentication.SessionAuthenticationHelper`
:class:`pyramid.authentication.AuthTktAuthenticationPolicy` :class:`pyramid.authentication.AuthTktCookieHelper`
:class:`pyramid.authentication.BasicAuthAuthenticationPolicy` Use :func:`pyramid.authentication.extract_http_basic_credentials` to retrieve credentials.
:class:`pyramid.authentication.RemoteUserAuthenticationPolicy` REMOTE_USER can be accessed with request.environ.get('REMOTE_USER').
:class:`pyramid.authentication.RepozeWho1AuthenticationPolicy` No equivalent.

Upgrading from Built-in Policies

Let's assume your application is using the built-in authentication and authorization policies, like :class:`pyramid.authentication.AuthTktAuthenticationPolicy`. For example:

def groupfinder(userid, request):
    # do some db lookups to verify userid, then return
    # None if not recognized, or a list of principals
    if userid == 'editor':
        return ['group:editor']

authn_policy = AuthTktAuthenticationPolicy('seekrit', callback=groupfinder)
authz_policy = ACLAuthorizationPolicy()
config.set_authentication_policy(authn_policy)
config.set_authorization_policy(authz_policy)

We can easily write our own :class:`pyramid.interfaces.ISecurityPolicy` implementation:

from pyramid.authentication import AuthTktCookieHelper
from pyramid.authorization import ACLHelper, Authenticated, Everyone

class MySecurityPolicy:
    def __init__(self, secret):
        self.helper = AuthTktCookieHelper(secret)

    def identity(self, request):
        # define our simple identity as None or a dict with userid and principals keys
        identity = self.helper.identify(request)
        if identity is None:
            return None
        userid = identity['userid']  # identical to the deprecated request.unauthenticated_userid

        # verify the userid, just like we did before with groupfinder
        principals = groupfinder(userid, request)

        # assuming the userid is valid, return a map with userid and principals
        if principals is not None:
            return {
                'userid': userid,
                'principals': principals,
            }

    def authenticated_userid(self, request):
        # defer to the identity logic to determine if the user id logged in
        # and return None if they are not
        identity = request.identity
        if identity is not None:
            return identity['userid']

    def permits(self, request, context, permission):
        # use the identity to build a list of principals, and pass them
        # to the ACLHelper to determine allowed/denied
        identity = request.identity
        principals = set([Everyone])
        if identity is not None:
            principals.add(Authenticated)
            principals.add(identity['userid'])
            principals.update(identity['principals'])
        return ACLHelper().permits(context, principals, permission)

    def remember(self, request, userid, **kw):
        return self.helper.remember(request, userid, **kw)

    def forget(self, request, **kw):
        return self.helper.forget(request, **kw)

config.set_security_policy(MySecurityPolicy('seekrit'))

This is a little bit more verbose than before, but it is easy to write, and is significantly more extensible for more advanced applications.

For further documentation on implementing security policies, see :ref:`writing_security_policy`.

Upgrading from Third-Party Policies

A generic :term:`security policy` can be written to work with legacy authentication and authorization policies. Note that some new features like the identity may not be as extensible and nice to use when taking this approach but it can be done to ease the transition:

class ShimSecurityPolicy:
    def __init__(self, authn_policy, authz_policy):
        self.authn_policy = authn_policy
        self.authz_policy = authz_policy

    def authenticated_userid(self, request):
        return self.authn_policy.authenticated_userid(request)

    def permits(self, request, context, permission):
        principals = self.authn_policy.effective_principals(request)
        return self.authz_policy.permits(context, principals, permission)

    def remember(self, request, userid, **kw):
        return self.authn_policy.remember(request, userid, **kw)

    def forget(self, request, **kw):
        return self.authz_policy.forget(request, **kw)

Compatibility with Legacy Authentication/Authorization Policies and APIs

If you are upgrading from an application that is using the legacy authentication and authorization policies and APIs, things will continue to function normally. The new system is backward-compatible and the APIs still exist. It is highly encouraged to upgrade in order to embrace the new features. The legacy APIs are deprecated and may be removed in the future.

The new :attr:`pyramid.request.Request.identity` property will output the same result as :attr:`pyramid.request.Request.authenticated_userid`.

If you try to use the new APIs with an application that is using the legacy authentication and authorization policies, then there are some issues to be aware of:

.. index::
    triple: pickle deprecation; JSON-serializable; ISession interface

Upgrading Session Serialization

In :app:`Pyramid` 2.0 the :class:`pyramid.interfaces.ISession` interface was changed to require that session implementations only need to support JSON-serializable data types. This is a stricter contract than the previous requirement that all objects be pickleable and it is being done for security purposes. This is a backward-incompatible change. Previously, if a client-side session implementation was compromised, it left the application vulnerable to remote code execution attacks using specially-crafted sessions that execute code when deserialized.

Please reference the following tickets if detailed information on these changes is needed:

For users with compatibility concerns, it's possible to craft a serializer that can handle both formats until you are satisfied that clients have had time to reasonably upgrade. Remember that sessions should be short-lived and thus the number of clients affected should be small (no longer than an auth token, at a maximum). An example serializer:

import pickle
from pyramid.session import JSONSerializer
from pyramid.session import SignedCookieSessionFactory


class JSONSerializerWithPickleFallback(object):
    def __init__(self):
        self.json = JSONSerializer()

    def dumps(self, appstruct):
        """
        Accept a Python object and return bytes.

        During a migration, you may want to catch serialization errors here,
        and keep using pickle while finding spots in your app that are not
        storing JSON-serializable objects. You may also want to integrate
        a fall-back to pickle serialization here as well.
        """
        return self.json.dumps(appstruct)

    def loads(self, bstruct):
        """Accept bytes and return a Python object."""
        try:
            return self.json.loads(bstruct)
        except ValueError:
            try:
                return pickle.loads(bstruct)
            except Exception:
                # this block should catch at least:
                # ValueError, AttributeError, ImportError; but more to be safe
                raise ValueError

# somewhere in your configuration code
serializer = JSONSerializerWithPickleFallback()
session_factory = SignedCookieSessionFactory(..., serializer=serializer)
config.set_session_factory(session_factory)