From f54cae02910f27e2ef7df224aa8fb7b9e1df5f99 Mon Sep 17 00:00:00 2001 From: Theron Luhn Date: Sun, 23 Jun 2019 11:27:27 -0700 Subject: Add a whatsnew-2.0 doc. --- docs/whatsnew-2.0.rst | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/whatsnew-2.0.rst (limited to 'docs/whatsnew-2.0.rst') diff --git a/docs/whatsnew-2.0.rst b/docs/whatsnew-2.0.rst new file mode 100644 index 000000000..c33f40206 --- /dev/null +++ b/docs/whatsnew-2.0.rst @@ -0,0 +1,95 @@ +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. + +Feature Additions +----------------- + +The feature additions in Pyramid 2.0 are as follows: + +- The authentication and authorization policies of Pyramid 1.x have been merged + into a single :term:`security policy` in Pyramid 2.0. For details on how to + migrate to the new security policy, see :ref:`upgrading_auth`. + Authentication and authorization policies can still be used and will continue + to function normally for the time being. + +Deprecations +------------ + +- Authentication and authorization policies have been deprecated in favor of + the new :term:`security policy`. + +.. _upgrading_auth: + +Upgrading Authentication/Authorization +-------------------------------------- + +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 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 The +identity can be accessed via +:attr:`pyramid.request.Request.authenticated_identity`. + +The concept of :term:`principals ` has been removed; the +``permits`` method is passed an identity object. 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:`pyraid.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 easily implement your own security policy. +The functionality of the legacy authencation policies roughly correspond to the +following helpers + +* :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. + +For further documentation on implementing security policies, see +:ref:`writing_security_policy`. + +.. _behavior_of_legacy_auth: + +Behavior of the Legacy System +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Legacy authentication and authorization policies will continue to function as +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. -- cgit v1.2.3 From f2315b9cd94fd403f1030c3199bfc76c5982d55b Mon Sep 17 00:00:00 2001 From: Theron Luhn Date: Sun, 23 Jun 2019 11:36:52 -0700 Subject: Use a table for policy => helper list. --- docs/whatsnew-2.0.rst | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'docs/whatsnew-2.0.rst') diff --git a/docs/whatsnew-2.0.rst b/docs/whatsnew-2.0.rst index c33f40206..a32801058 100644 --- a/docs/whatsnew-2.0.rst +++ b/docs/whatsnew-2.0.rst @@ -59,19 +59,23 @@ 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 easily implement your own security policy. The functionality of the legacy authencation policies roughly correspond to the -following helpers - -* :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. +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. | ++----------------------------------------------------------------+-------------------------------------------------------------------+ For further documentation on implementing security policies, see :ref:`writing_security_policy`. -- cgit v1.2.3 From 5384cc6929e8abb37b49a9447bb4b9f6c85c5e49 Mon Sep 17 00:00:00 2001 From: Theron Luhn Date: Sun, 23 Jun 2019 11:43:18 -0700 Subject: Act on @stevepiercy's suggestions --- docs/whatsnew-2.0.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/whatsnew-2.0.rst') diff --git a/docs/whatsnew-2.0.rst b/docs/whatsnew-2.0.rst index a32801058..49400a937 100644 --- a/docs/whatsnew-2.0.rst +++ b/docs/whatsnew-2.0.rst @@ -42,8 +42,9 @@ The new security policy should implement 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 The -identity can be accessed via +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 concept of :term:`principals ` has been removed; the @@ -57,8 +58,8 @@ 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 easily implement your own security policy. -The functionality of the legacy authencation policies roughly correspond to the +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: +----------------------------------------------------------------+-------------------------------------------------------------------+ -- cgit v1.2.3 From d2d20b92158088e7d646393733092e67120058f0 Mon Sep 17 00:00:00 2001 From: Theron Luhn Date: Sun, 21 Jul 2019 09:20:44 -0700 Subject: Un-deprecate authenticated_userid. --- docs/whatsnew-2.0.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'docs/whatsnew-2.0.rst') 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 ` has been removed; the ``permits`` method is passed an identity object. This change gives much more -- cgit v1.2.3