diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/security.rst | 4 | ||||
| -rw-r--r-- | docs/upgrading-2.0.rst | 94 |
2 files changed, 65 insertions, 33 deletions
diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 656ac9ca6..a92942a25 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -300,8 +300,8 @@ When a default permission is registered: .. _assigning_acls: -Implement ACL Authorization ---------------------------- +Implementing ACL Authorization +------------------------------ A common way to implement authorization is using an :term:`ACL`. An ACL is a :term:`context`-specific list of access control entries, which allow or deny diff --git a/docs/upgrading-2.0.rst b/docs/upgrading-2.0.rst index e896633e5..506d9cf3c 100644 --- a/docs/upgrading-2.0.rst +++ b/docs/upgrading-2.0.rst @@ -1,42 +1,74 @@ Upgrading to Pyramid 2.0 ======================== -Pyramid 2.0 was built to be backwards compatible with the 1.x series, so no -changes to your application should be necessary. However, some functionality -has been deprecated and it is recommended to upgrade from the legacy systems. +Pyramid 2.0 is largely backwards compatible with the 1.x series, so minimal +changes should be necessary. However, some 1.x functionality has been +deprecated and it is recommended to upgrade from the legacy systems. -.. _upgrade_auth: +.. _upgrading_auth: -Upgrading to a Security Policy ------------------------------- +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 will continue to function normally, however they have -been deprecated and may be removed in upcoming versions. - -A security policy should implement -:interface:`pyramid.interfaces.ISecurityPolicy`. You can set the security -policy for your application via the ``security_policy`` parameter in -:class:`pyramid.config.Configurator` or by calling -:meth:`pyramid.config.Configurator.set_security_policy`. If you set a security -policy, you cannot set a authentication or authorization policy. - -``unauthenticated_userid`` and ``authenticated_userid`` have been replaced with -the ``identify`` method. This method should return an :term:`identity`, which -can be an object of any shape, such as a dictionary or an ORM object. (It can -also be a simple user ID, as in the legacy authentication policy.) The +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 +:interface:`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 -:meth:`pyramid.request.Request.authenticated_identity`. If you're -using a legacy authentication policy, -:meth:`pyramid.request.Request.authenticated_identity` will return the result -of ``authenticated_userid``. +:prop:`pyramid.request.Request.authenticated_identity`. + +The concept of :term:`principals <principal>` 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 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 :prop:`pyramid.request.Request.authenticated_identity` property will +output the same result as :prop:`pyramid.request.Request.authenticated_userid`. +If using a security policy, :prop:`pyramid.request.Request.unauthenticated_userid` and -:prop:`pyramid.request.Request.authenticated_userid` are deprecated but will -continue to work as normal with legacy policies. If using a new security -policy, both properties will return the string representation of the -:term:`identity`. :prop:`pyramid.request.Request.effective_principals` is -also deprecated and will work with legacy policies, but always return a -one-element list containing the :data:`pyramid.security.Everyone` principal -when using a security policy, as there is no equivalent in the new +:prop:`pyramid.request.Request.authenticated_userid` will both return the +string representation of the :term:`identity`. +:prop:`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. |