Security policy implementation

CONTRIBUTORS.txt

@@ -336,3 +336,5 @@ Contributors
 - Colin Dunklau, 2018/09/19
 
 - Alexandre Yukio Harano, 2018/10/05
+
+- Theron Luhn, 2019/02/17

docs/glossary.rst

@@ -306,18 +306,36 @@ Glossary
      a principal, but this is not strictly necessary in custom policies that
      define their principals differently.
 
+   identity
+     An identity is an opaque identifier of the user associated with the
+     current request.
+
+   security policy
+     A security policy in :app:`Pyramid` terms is a bit of code which has an
+     API which identifies the user associated with the current request (perhaps
+     via a cookie or ``Authorization`` header) and determines whether or not
+     that user is permitted to access the requested resource.
+
    authorization policy
      An authorization policy in :app:`Pyramid` terms is a bit of
      code which has an API which determines whether or not the
      principals associated with the request can perform an action
      associated with a permission, based on the information found on the
      :term:`context` resource.
 
+     .. deprecated:: 2.0
+       Authorization policies have been deprecated in favor of a
+       :term:`security policy`.
+
    authentication policy
      An authentication policy in :app:`Pyramid` terms is a bit of
      code which has an API which determines the current
      :term:`principal` (or principals) associated with a request.
 
+     .. deprecated:: 2.0
+       Authentication policies have been deprecated in favor of a
+       :term:`security policy`.
+
    WSGI
      `Web Server Gateway Interface <https://wsgi.readthedocs.io/en/latest/>`_.
      This is a Python standard for connecting web applications to web servers,

src/pyramid/config/__init__.py

@@ -139,13 +139,17 @@ class Configurator(
     :term:`dotted Python name` to the same.  If it is ``None``, a default
     root factory will be used.
 
+    If ``security_policy`` is passed, it should be an instance of a
+    :term:`security policy` or a :term:`dotted Python name` to the same.
+
     If ``authentication_policy`` is passed, it should be an instance
     of an :term:`authentication policy` or a :term:`dotted Python
-    name` to the same.
+    name` to the same.  (Deprecated as of Pyramid 2.0 in favor of
+    ``security_policy``.)
 
     If ``authorization_policy`` is passed, it should be an instance of
     an :term:`authorization policy` or a :term:`dotted Python name` to
-    the same.
+    the same.  (Deprecated as of Pyramid 2.0 in favor of ``security_policy``.)
 
     .. note:: A ``ConfigurationError`` will be raised when an
        authorization policy is supplied without also supplying an
@@ -278,6 +282,7 @@ def __init__(
         package=None,
         settings=None,
         root_factory=None,
+        security_policy=None,
         authentication_policy=None,
         authorization_policy=None,
         renderers=None,
@@ -315,6 +320,7 @@ def __init__(
                 root_factory=root_factory,
                 authentication_policy=authentication_policy,
                 authorization_policy=authorization_policy,
+                security_policy=security_policy,
                 renderers=renderers,
                 debug_logger=debug_logger,
                 locale_negotiator=locale_negotiator,
@@ -330,6 +336,7 @@ def setup_registry(
         self,
         settings=None,
         root_factory=None,
+        security_policy=None,
         authentication_policy=None,
         authorization_policy=None,
         renderers=None,
@@ -415,6 +422,9 @@ def setup_registry(
         if authentication_policy:
             self.set_authentication_policy(authentication_policy)
 
+        if security_policy:
+            self.set_security_policy(security_policy)
+
         if default_view_mapper is not None:
             self.set_view_mapper(default_view_mapper)
 

src/pyramid/config/security.py

@@ -6,13 +6,15 @@
     ICSRFStoragePolicy,
     IDefaultCSRFOptions,
     IDefaultPermission,
+    ISecurityPolicy,
     PHASE1_CONFIG,
     PHASE2_CONFIG,
 )
 
 from pyramid.csrf import LegacySessionCSRFStoragePolicy
 from pyramid.exceptions import ConfigurationError
 from pyramid.util import as_sorted_tuple
+from pyramid.security import LegacySecurityPolicy
 
 from pyramid.config.actions import action_method
 
@@ -21,6 +23,38 @@ class SecurityConfiguratorMixin(object):
     def add_default_security(self):
         self.set_csrf_storage_policy(LegacySessionCSRFStoragePolicy())
 
+    @action_method
+    def set_security_policy(self, policy):
+        """ Override the :app:`Pyramid` :term:`security policy` in the current
+        configuration.  The ``policy`` argument must be an instance
+        of a security policy or a :term:`dotted Python name`
+        that points at an instance of a security policy.
+
+        .. note::
+
+           Using the ``security_policy`` argument to the
+           :class:`pyramid.config.Configurator` constructor can be used to
+           achieve the same purpose.
+
+        """
+
+        def register():
+            self._set_security_policy(policy)
+
+        intr = self.introspectable(
+            'security policy',
+            None,
+            self.object_description(policy),
+            'security policy',
+        )
+        intr['policy'] = policy
+        # authentication policy used by view config (phase 3)
+        self.action(ISecurityPolicy, register, introspectables=(intr,))
+
+    def _set_security_policy(self, policy):
+        policy = self.maybe_dotted(policy)
+        self.registry.registerUtility(policy, ISecurityPolicy)
+
     @action_method
     def set_authentication_policy(self, policy):
         """ Override the :app:`Pyramid` :term:`authentication policy` in the
@@ -44,6 +78,7 @@ def register():
                     'also configuring an authorization policy '
                     '(use the set_authorization_policy method)'
                 )
+            self._set_legacy_policy()
 
         intr = self.introspectable(
             'authentication policy',
@@ -64,6 +99,15 @@ def _set_authentication_policy(self, policy):
         policy = self.maybe_dotted(policy)
         self.registry.registerUtility(policy, IAuthenticationPolicy)
 
+    def _set_legacy_policy(self):
+        if self.registry.queryUtility(ISecurityPolicy) is not None:
+            raise ConfigurationError(
+                'Cannot configure an authentication and authorization policy '
+                'with a configured security policy.'
+            )
+        policy = LegacySecurityPolicy()
+        self.registry.registerUtility(policy, ISecurityPolicy)
+
     @action_method
     def set_authorization_policy(self, policy):
         """ Override the :app:`Pyramid` :term:`authorization policy` in the

src/pyramid/config/testing.py

@@ -1,11 +1,6 @@
 from zope.interface import Interface
 
-from pyramid.interfaces import (
-    ITraverser,
-    IAuthorizationPolicy,
-    IAuthenticationPolicy,
-    IRendererFactory,
-)
+from pyramid.interfaces import ITraverser, ISecurityPolicy, IRendererFactory
 
 from pyramid.renderers import RendererHelper
 
@@ -18,8 +13,7 @@ class TestingConfiguratorMixin(object):
     # testing API
     def testing_securitypolicy(
         self,
-        userid=None,
-        groupids=(),
+        identity=None,
         permissive=True,
         remember_result=None,
         forget_result=None,
@@ -69,10 +63,9 @@ def testing_securitypolicy(
         from pyramid.testing import DummySecurityPolicy
 
         policy = DummySecurityPolicy(
-            userid, groupids, permissive, remember_result, forget_result
+            identity, permissive, remember_result, forget_result
         )
-        self.registry.registerUtility(policy, IAuthorizationPolicy)
-        self.registry.registerUtility(policy, IAuthenticationPolicy)
+        self.registry.registerUtility(policy, ISecurityPolicy)
         return policy
 
     def testing_resources(self, resources):

src/pyramid/interfaces.py

@@ -482,8 +482,40 @@ def __call__(self, **kw):
         """
 
 
+class ISecurityPolicy(Interface):
+    def identify(request):
+        """ Return an object identifying a trusted and verified user. """
+
+    def permits(request, context, identity, permission):
+        """ Return an instance of :class:`pyramid.security.Allowed` if a user
+        of the given identity is allowed the ``permission`` in the current
+        ``context``, else return an instance of
+        :class:`pyramid.security.Denied`.
+        """
+
+    def remember(request, userid, **kw):
+        """ Return a set of headers suitable for 'remembering' the
+        :term:`userid` named ``userid`` when set in a response.  An
+        individual authentication policy and its consumers can
+        decide on the composition and meaning of ``**kw``.
+
+        """
+
+    def forget(request):
+        """ Return a set of headers suitable for 'forgetting' the
+        current user on subsequent requests.
+
+        """
+
+
 class IAuthenticationPolicy(Interface):
-    """ An object representing a Pyramid authentication policy. """
+    """ An object representing a Pyramid authentication policy.
+
+    .. deprecated:: 2.0
+
+        Use :class:`ISecurityPolicy`.
+
+    """
 
     def authenticated_userid(request):
         """ Return the authenticated :term:`userid` or ``None`` if
@@ -536,7 +568,13 @@ def forget(request):
 
 
 class IAuthorizationPolicy(Interface):
-    """ An object representing a Pyramid authorization policy. """
+    """ An object representing a Pyramid authorization policy.
+
+    .. deprecated:: 2.0
+
+        Use :class:`ISecurityPolicy`.
+
+    """
 
     def permits(context, principals, permission):
         """ Return an instance of :class:`pyramid.security.Allowed` if any

src/pyramid/predicates.py

@@ -291,6 +291,13 @@ def __call__(self, context, request):
 
 
 class EffectivePrincipalsPredicate(object):
+    """
+    .. deprecated:: 2.0
+
+        No longer applicable with the new :term:`security policy`.
+
+    """
+
     def __init__(self, val, config):
         if is_nonstr_iter(val):
             self.val = set(val)

src/pyramid/request.py

@@ -15,7 +15,7 @@
 from pyramid.decorator import reify
 from pyramid.i18n import LocalizerRequestMixin
 from pyramid.response import Response, _get_response_factory
-from pyramid.security import AuthenticationAPIMixin, AuthorizationAPIMixin
+from pyramid.security import SecurityAPIMixin, AuthenticationAPIMixin
 from pyramid.url import URLMethodsMixin
 from pyramid.util import (
     InstancePropertyHelper,
@@ -147,8 +147,8 @@ class Request(
     CallbackMethodsMixin,
     InstancePropertyMixin,
     LocalizerRequestMixin,
+    SecurityAPIMixin,
     AuthenticationAPIMixin,
-    AuthorizationAPIMixin,
     ViewMethodsMixin,
 ):
     """