start reworking security policy

.flake8

@@ -9,7 +9,6 @@ ignore =
     # W504: line break after binary operator (flake8 is not PEP8 compliant)
     W504
 exclude =
-    src/pyramid/compat.py
     tests/fixtures
     tests/pkgs
     tests/test_config/pkgs

TODO.txt

@@ -116,10 +116,6 @@ Probably Bad Ideas
 
 - Add functionality that mocks the behavior of ``repoze.browserid``.
 
-- Consider implementing the API outlined in
-  http://plope.com/pyramid_auth_design_api_postmortem, phasing out the
-  current auth-n-auth abstractions in a backwards compatible way.
-
 - Maybe add ``add_renderer_globals`` method to Configurator.
 
 - Supply ``X-Vhm-Host`` support (probably better to do what paste#prefix

docs/api/request.rst

@@ -166,11 +166,11 @@
 
    .. attribute:: authenticated_userid
 
-      .. deprecated:: 2.0
+      .. versionchanged:: 2.0
 
-          ``authenticated_userid`` has been replaced by
-          :attr:`authenticated_identity` in the new security system.  See
-          :ref:`upgrading_auth` for more information.
+         ``authenticated_userid`` uses security policy or authn pol
+         see also :attr:`authenticated_identity` and
+         :ref:`upgrading_auth` for more information.
 
       A property which returns the :term:`userid` of the currently
       authenticated user or ``None`` if there is no :term:`authentication
@@ -184,9 +184,9 @@
 
       .. deprecated:: 2.0
 
-          ``unauthenticated_userid`` has been replaced by
-          :attr:`authenticated_identity` in the new security system.  See
-          :ref:`upgrading_auth` for more information.
+         ``unauthenticated_userid`` has been replaced by
+         :attr:`authenticated_identity` in the new security system.  See
+         :ref:`upgrading_auth` for more information.
 
       A property which returns a value which represents the *claimed* (not
       verified) :term:`userid` of the credentials present in the
@@ -203,8 +203,8 @@
 
       .. deprecated:: 2.0
 
-          The new security policy has removed the concept of principals.  See
-          :ref:`upgrading_auth` for more information.
+         The new security policy has removed the concept of principals.  See
+         :ref:`upgrading_auth` for more information.
 
       A property which returns the list of 'effective' :term:`principal`
       identifiers for this request.  This list typically includes the

docs/glossary.rst

@@ -304,8 +304,8 @@ Glossary
 
    identity
      An identity is an object identifying the user associated with the
-     current request.  The identity can be any object, but should implement a
-     ``__str__`` method that outputs a corresponding :term:`userid`.
+     current request.  The identity can be any object, but security policies
+     should ensure that it represents a valid user (not deleted or deactivated).
 
    security policy
      A security policy in :app:`Pyramid` terms is an object implementing the

docs/narr/security.rst

@@ -72,12 +72,19 @@ A simple security policy might look like the following:
     from pyramid.security import Allowed, Denied
 
     class SessionSecurityPolicy:
-        def identify(self, request):
+        def authenticated_userid(self, request):
             """ Return the user ID stored in the session. """
             return request.session.get('userid')
 
-        def permits(self, request, context, identity, permission):
+        def identify(self, request):
+            """ Return app-specific user object. """
+            userid = self.authenticated_userid(request)
+            if userid is not None:
+                return models.Users.get(id=userid)
+
+        def permits(self, request, context, permission):
             """ Allow access to everything if signed in. """
+            identity = self.identify(request)
             if identity is not None:
                 return Allowed('User is signed in.')
             else:
@@ -87,7 +94,7 @@ A simple security policy might look like the following:
             request.session['userid'] = userid
             return []
 
-        def forget(request):
+        def forget(request, **kw):
             del request.session['userid']
             return []
 
@@ -136,12 +143,16 @@ For example, our above security policy can leverage these helpers like so:
         def __init__(self):
             self.helper = SessionAuthenticationHelper()
 
+        def authenticated_userid(self, request):
+            # XXX add code
+            ...
+
         def identify(self, request):
-            """ Return the user ID stored in the session. """
             return self.helper.identify(request)
 
-        def permits(self, request, context, identity, permission):
+        def permits(self, request, context, permission):
             """ Allow access to everything if signed in. """
+            identity = self.identify(request)
             if identity is not None:
                 return Allowed('User is signed in.')
             else:
@@ -150,22 +161,22 @@ For example, our above security policy can leverage these helpers like so:
         def remember(request, userid, **kw):
             return self.helper.remember(request, userid, **kw)
 
-        def forget(request):
-            return self.helper.forget(request)
+        def forget(request, **kw):
+            return self.helper.forget(request, **kw)
 
 Helpers are intended to be used with application-specific code, so perhaps your
 authentication also queries the database to ensure the identity is valid.
 
 .. code-block:: python
     :linenos:
 
-        def identify(self, request):
-            """ Return the user ID stored in the session. """
-            user_id = self.helper.identify(request)
-            if validate_user_id(user_id):
-                return user_id
-            else:
-                return None
+    def identify(self, request):
+        # XXX review: use authenticated_userid below or identify?
+        user_id = self.helper.identify(request)
+        if validate_user_id(user_id):
+            return user_id
+        else:
+            return None
 
 .. index::
    single: permissions
@@ -237,7 +248,9 @@ might look like so:
     from pyramid.security import Allowed, Denied
 
     class SecurityPolicy:
-        def permits(self, request, context, identity, permission):
+        def permits(self, request, context, permission):
+            identity = self.identify(request)
+
             if identity is None:
                 return Denied('User is not signed in.')
             if identity.role == 'admin':
@@ -246,6 +259,7 @@ might look like so:
                 allowed = ['read', 'write']
             else:
                 allowed = ['read']
+
             if permission in allowed:
                 return Allowed(
                     'Access granted for user %s with role %s.',
@@ -326,7 +340,7 @@ object.  An implementation might look like this:
     from pyramid.authorization import ACLHelper
 
     class SecurityPolicy:
-        def permits(self, request, context, identity, permission):
+        def permits(self, request, context, permission):
             principals = [Everyone]
             if identity is not None:
                 principals.append(Authenticated)
@@ -352,7 +366,7 @@ For example, an ACL might be attached to the resource for a blog via its class:
             (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:
@@ -369,10 +383,10 @@ Or, if your resources are persistent, an ACL might be specified via the
     blog = Blog()
 
     blog.__acl__ = [
-            (Allow, Everyone, 'view'),
-            (Allow, 'group:editors', 'add'),
-            (Allow, 'group:editors', 'edit'),
-            ]
+        (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
@@ -425,10 +439,10 @@ Here's an example ACL:
     from pyramid.security import Everyone
 
     __acl__ = [
-            (Allow, Everyone, 'view'),
-            (Allow, 'group:editors', 'add'),
-            (Allow, 'group:editors', 'edit'),
-            ]
+        (Allow, Everyone, 'view'),
+        (Allow, 'group:editors', 'add'),
+        (Allow, 'group:editors', 'edit'),
+    ]
 
 The example ACL indicates that the :data:`pyramid.security.Everyone`
 principal—a special system-defined principal indicating, literally, everyone—is
@@ -460,7 +474,7 @@ dictated by the ACL*.  So if you have an ACL like this:
     __acl__ = [
         (Allow, Everyone, 'view'),
         (Deny, Everyone, 'view'),
-        ]
+    ]
 
 The ACL helper 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
@@ -476,7 +490,7 @@ hand, if you have an ACL like this:
     __acl__ = [
         (Deny, Everyone, 'view'),
         (Allow, Everyone, 'view'),
-        ]
+    ]
 
 The ACL helper will deny everyone the view permission, even though
 later in the ACL, there is an ACE that allows everyone.
@@ -495,7 +509,7 @@ can collapse this into a single ACE, as below.
     __acl__ = [
         (Allow, Everyone, 'view'),
         (Allow, 'group:editors', ('add', 'edit')),
-        ]
+    ]
 
 .. _special_principals:
 

docs/quick_tutorial/authentication.rst

@@ -104,6 +104,8 @@ Steps
 Analysis
 ========
 
+# TODO update
+
 Unlike many web frameworks, Pyramid includes a built-in but optional security
 model for authentication and authorization. This security system is intended to
 be flexible and support many needs. In this security model, authentication (who

docs/whatsnew-2.0.rst

@@ -44,10 +44,12 @@ 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.authenticated_identity`.
 The object can be of any shape, such as a simple ID string or an ORM object,
-but should implement a ``__str__`` method that returns a string identifying the
-current user, e.g. the ID of the user object in a database.  The string
-representation is return as
-:attr:`pyramid.request.Request.authenticated_userid`.
+and should represent an active user.
+
+As in previous version, the property :attr:`pyramid.request.Request.authenticated_userid`
+can be used to get a string identifying the current user, for example
+the ID of the user object in a database.  The value is obtained from the
+security policy.
 (:attr:`pyramid.request.Request.unauthenticated_userid` has been deprecated.)
 
 The concept of :term:`principals <principal>` has been removed; the

src/pyramid/authentication.py

@@ -1110,7 +1110,7 @@ def forget(self, request):
         return self.helper.forget(request)
 
     def unauthenticated_userid(self, request):
-        return self.helper.identify(request)
+        return self.helper.authenticated_userid(request)
 
 
 class SessionAuthenticationHelper:
@@ -1134,13 +1134,13 @@ def remember(self, request, userid, **kw):
         request.session[self.userid_key] = userid
         return []
 
-    def forget(self, request):
+    def forget(self, request, **kw):
         """ Remove the stored userid from the session."""
         if self.userid_key in request.session:
             del request.session[self.userid_key]
         return []
 
-    def identify(self, request):
+    def authenticated_userid(self, request):
         """ Return the stored userid."""
         return request.session.get(self.userid_key)
 

src/pyramid/config/testing.py

@@ -13,6 +13,7 @@ class TestingConfiguratorMixin(object):
     # testing API
     def testing_securitypolicy(
         self,
+        userid=None,
         identity=None,
         permissive=True,
         remember_result=None,
@@ -39,6 +40,7 @@ def testing_securitypolicy(
         not provided (or it is provided, and is ``None``), the default value
         ``[]`` (the empty list) will be returned by ``forget``.
 
+        XXX rewrite
         The behavior of the registered :term:`authentication policy`
         depends on the values provided for the ``userid`` and
         ``groupids`` argument.  The authentication policy will return
@@ -51,19 +53,21 @@ def testing_securitypolicy(
         This function is most useful when testing code that uses
         the APIs named :meth:`pyramid.request.Request.has_permission`,
         :attr:`pyramid.request.Request.authenticated_userid`,
-        :attr:`pyramid.request.Request.effective_principals`, and
         :func:`pyramid.security.principals_allowed_by_permission`.
 
         .. versionadded:: 1.4
            The ``remember_result`` argument.
 
         .. versionadded:: 1.4
            The ``forget_result`` argument.
+
+        .. versionchanged:: 2.0
+           Removed ``groupids`` argument and doc about effective principals.
         """
         from pyramid.testing import DummySecurityPolicy
 
         policy = DummySecurityPolicy(
-            identity, permissive, remember_result, forget_result
+            userid, identity, permissive, remember_result, forget_result
         )
         self.registry.registerUtility(policy, ISecurityPolicy)
         return policy

src/pyramid/interfaces.py

@@ -484,32 +484,33 @@ def __call__(self, **kw):
 
 class ISecurityPolicy(Interface):
     def identify(request):
-        """ Return an object identifying a trusted and verified user.  This
-        object may be anything, but should implement a ``__str__`` method that
-        outputs a corresponding :term:`userid`.
+        """ Return an object identifying a trusted and verified user.
 
+        The object may be anything.
         """
 
-    def permits(request, context, identity, permission):
+    def authenticated_userid(request, identity):
+        """ Return a :term:`userid` string identifying the trusted and
+        verified user, or ``None`` if unauthenticated.
+        """
+
+    def permits(request, context, 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):
+    def forget(request, **kw):
         """ Return a set of headers suitable for 'forgetting' the
         current user on subsequent requests.
-
         """