diff options
| -rw-r--r-- | docs/glossary.rst | 12 | ||||
| -rw-r--r-- | docs/whatsnew-2.0.rst | 15 | ||||
| -rw-r--r-- | src/pyramid/interfaces.py | 4 | ||||
| -rw-r--r-- | src/pyramid/security.py | 52 |
4 files changed, 41 insertions, 42 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index 5d374e0ec..b850f6e3e 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -298,18 +298,14 @@ Glossary foo` and `group bar`. userid - A *userid* is a string used to identify and authenticate - a real-world user or client. A userid is supplied to an - :term:`authentication policy` in order to discover the user's - :term:`principals <principal>`. In the authentication policies which - :app:`Pyramid` provides, the default behavior returns the user's userid as - a principal, but this is not strictly necessary in custom policies that - define their principals differently. + A *userid* is the string representation of an :term:`identity`. Just like + the identity, it should identify the user associated with the current + request. Oftentimes this is the ID of the user object in a database. identity An identity is an object identify the user associated with the current request. The identity can be any object, but should implement a - ``__str__`` method for logging and debugging purposes. + ``__str__`` method that outputs a corresponding :term:`userid`. security policy A security policy in :app:`Pyramid` terms is a bit of code which has an diff --git a/docs/whatsnew-2.0.rst b/docs/whatsnew-2.0.rst index 49400a937..446fcda21 100644 --- a/docs/whatsnew-2.0.rst +++ b/docs/whatsnew-2.0.rst @@ -40,12 +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 new security policy merges ``unauthenticated_userid`` and -``authenticated_userid`` into an :term:`identity` object. This object can be -of any shape, such as a simple ID string or an ORM object, but should have a -string representation (i.e. a ``__str__`` method) useful for debugging. -The identity can be accessed via -:attr:`pyramid.request.Request.authenticated_identity`. +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 outputs 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 concept of :term:`principals <principal>` has been removed; the ``permits`` method is passed an identity object. This change gives much more diff --git a/src/pyramid/interfaces.py b/src/pyramid/interfaces.py index 06ab1c32e..d97c3811b 100644 --- a/src/pyramid/interfaces.py +++ b/src/pyramid/interfaces.py @@ -485,8 +485,8 @@ class IViewMapperFactory(Interface): 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 for - logging and debugging purposes. + object may be anything, but should implement a ``__str__`` method that + outputs a corresponding :term:`userid`. """ diff --git a/src/pyramid/security.py b/src/pyramid/security.py index 64e840801..08c36b457 100644 --- a/src/pyramid/security.py +++ b/src/pyramid/security.py @@ -306,6 +306,28 @@ class SecurityAPIMixin(object): return None return policy.identify(self) + @property + def authenticated_userid(self): + """ + Return the :term:`userid` of the currently authenticated user or + ``None`` if there is no :term:`security policy` in effect or there is + no currently authenticated user. + + .. versionchanged:: 2.0 + + When using the new security system, this property outputs the + string representation of the :term:`identity`. + + """ + authn = _get_authentication_policy(self) + security = _get_security_policy(self) + if authn is not None: + return authn.authenticated_userid(self) + elif security is not None: + return str(security.identify(self)) + else: + return None + def has_permission(self, permission, context=None): """ Given a permission and an optional context, returns an instance of :data:`pyramid.security.Allowed` if the permission is granted to this @@ -337,36 +359,14 @@ class SecurityAPIMixin(object): class AuthenticationAPIMixin(object): @property - def authenticated_userid(self): - """ - .. deprecated:: 2.0 - - ``authenticated_userid`` has been replaced by - :attr:`authenticated_identity` in the new security system. See - :ref:`upgrading_auth` for more information. - - Return the userid of the currently authenticated user or - ``None`` if there is no :term:`authentication policy` in effect or - there is no currently authenticated user. - - """ - authn = _get_authentication_policy(self) - security = _get_security_policy(self) - if authn is not None: - return authn.authenticated_userid(self) - elif security is not None: - return str(security.identify(self)) - else: - return None - - @property def unauthenticated_userid(self): """ .. 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`` does not have an equivalent in the new + security system. Use :attr:`.authenticated_userid` or + :attr:`.identity` instead. See :ref:`upgrading_auth` for more + information. Return an object which represents the *claimed* (not verified) user id of the credentials present in the request. ``None`` if there is no |