diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/request.rst | 20 | ||||
| -rw-r--r-- | docs/glossary.rst | 5 | ||||
| -rw-r--r-- | docs/narr/security.rst | 100 | ||||
| -rw-r--r-- | docs/whatsnew-2.0.rst | 21 |
4 files changed, 72 insertions, 74 deletions
diff --git a/docs/api/request.rst b/docs/api/request.rst index 8e0f77b87..9e9c70d3a 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -166,27 +166,17 @@ .. attribute:: authenticated_userid - .. deprecated:: 2.0 - - ``authenticated_userid`` has been replaced by - :attr:`authenticated_identity` in the new security system. See - :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 - policy` in effect or there is no currently authenticated user. This - differs from :attr:`~pyramid.request.Request.unauthenticated_userid`, - because the effective authentication policy will have ensured that a - record associated with the :term:`userid` exists in persistent storage; - if it has not, this value will be ``None``. + authenticated user or ``None`` if there is no :term:`security policy` in + effect or there is no currently authenticated user. .. attribute:: unauthenticated_userid .. 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 deprecated in version 2.0. Use + :attr:`authenticated_userid` or :attr:`authenticated_identity` + instead. 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 diff --git a/docs/glossary.rst b/docs/glossary.rst index 81358e688..5a33ff39d 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -303,9 +303,8 @@ Glossary request. Oftentimes this is the ID of the user object in a database. 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`. + An identity is an object identifying the user associated with the current request. + The object can be of any shape, such as a simple ID string or an ORM object. security policy A security policy in :app:`Pyramid` terms is an object implementing the diff --git a/docs/narr/security.rst b/docs/narr/security.rst index f1bb37c69..ac64cba0a 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -32,14 +32,11 @@ how it works at a high level: - A :term:`view callable` is located by :term:`view lookup` using the context as well as other attributes of the request. -- If a :term:`security policy` is in effect, it is passed the request and - returns the :term:`identity` of the current user. - - If a :term:`security 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 policy is passed the - :term:`context`, the current :term:`identity`, and the :term:`permission` - associated with the view; it will allow or deny access. + :term:`permission` associated with it, the policy is passed :term:`request`, + the :term:`context`, and the :term:`permission` associated with the view; it + will allow or deny access. - If the security policy allows access, the view callable is invoked. @@ -62,7 +59,7 @@ Writing a Security Policy accessible by completely anonymous users. In order to begin protecting views from execution based on security settings, you need to write a security policy. -Security policies are simple classes implementing a +Security policies are simple classes implementing :class:`pyramid.interfaces.ISecurityPolicy`. A simple security policy might look like the following: @@ -73,11 +70,22 @@ A simple security policy might look like the following: class SessionSecurityPolicy: def identify(self, request): - """ Return the user ID stored in the session. """ - return request.session.get('userid') + """ Return app-specific user object. """ + userid = request.session.get('userid') + if userid is None: + return None + return load_identity_from_db(request, userid) + + def authenticated_userid(self, request): + """ Return a string ID for the user. """ + identity = self.identify(request) + if identity is None: + return None + return string(identity.id) - 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: @@ -87,7 +95,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 [] @@ -137,11 +145,22 @@ For example, our above security policy can leverage these helpers like so: self.helper = SessionAuthenticationHelper() def identify(self, request): - """ Return the user ID stored in the session. """ - return self.helper.identify(request) + """ Return app-specific user object. """ + userid = self.helper.authenticated_userid(request) + if userid is None: + return None + return load_identity_from_db(request, userid) + + def authenticated_userid(self, request): + """ Return a string ID for the user. """ + identity = self.identify(request) + if identity is None: + return None + return str(identity.id) - 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 +169,14 @@ 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 +Helpers are intended to be used with application-specific code. Notice how the +above code takes the userid from the helper and uses it to load the +:term:`identity` from the database. ``authenticated_userid`` pulls the +:term:`userid` from the :term:`identity` in order to guarantee that the user ID +stored in the session exists in the database ("authenticated"). .. 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: diff --git a/docs/whatsnew-2.0.rst b/docs/whatsnew-2.0.rst index ec506894e..d5f825c43 100644 --- a/docs/whatsnew-2.0.rst +++ b/docs/whatsnew-2.0.rst @@ -40,15 +40,15 @@ The new security policy should implement ``security_policy`` argument of :class:`pyramid.config.Configurator` or :meth:`pyramid.config.Configurator.set_security_policy`. +The policy contains ``authenticated_userid`` and ``remember``, +with the same method signatures as in the legacy authentication policy. It +also contains ``forget``, but now with 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.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`. -(:attr:`pyramid.request.Request.unauthenticated_userid` has been deprecated.) +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; the ``permits`` method is passed an identity object. This change gives much more @@ -94,10 +94,5 @@ normal, as well as all related :class:`pyramid.request.Request` properties. The new :attr:`pyramid.request.Request.authenticated_identity` property will output the same result as :attr:`pyramid.request.Request.authenticated_userid`. -If using a security policy, -:attr:`pyramid.request.Request.unauthenticated_userid` and -:attr:`pyramid.request.Request.authenticated_userid` will both return the -string representation of the :term:`identity`. -:attr:`pyramid.request.Request.effective_principals` will always return a -one-element list containing the :data:`pyramid.security.Everyone` principal, as -there is no equivalent in the new security policy. +If using a security policy, :attr:`pyramid.request.Request.unauthenticated_userid` will return the same value as :attr:`pyramid.request.Request.authenticated_userid`. +:attr:`pyramid.request.Request.effective_principals` will always return a one-element list containing the :data:`pyramid.security.Everyone` principal, as there is no equivalent in the new security policy. |