diff options
| -rw-r--r-- | CHANGES.rst | 59 | ||||
| -rw-r--r-- | docs/api/authorization.rst | 43 | ||||
| -rw-r--r-- | docs/api/security.rst | 46 |
3 files changed, 141 insertions, 7 deletions
diff --git a/CHANGES.rst b/CHANGES.rst index 8159cea36..f1ccdf8e6 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -7,6 +7,19 @@ Features - Add support for Python 3.8. See https://github.com/Pylons/pyramid/pull/3547 +- New security APIs have been added to support a massive overhaul of the + authentication and authorization system. Read + "Upgrading Authentication/Authorization" in the "What's New in Pyramid 2.0" + document for information about using this new system. + + - ``pyramid.config.Configurator.set_security_policy``. + - ``pyramid.interfaces.ISecurityPolicy`` + - ``pyramid.request.Request.authenticated_identity``. + - ``pyramid.authentication.SessionAuthenticationHelper`` + - ``pyramid.authorization.ACLHelper`` + + See https://github.com/Pylons/pyramid/pull/3465 + - Changed the default ``serializer`` on ``pyramid.session.SignedCookieSessionFactory`` to use ``pyramid.session.JSONSerializer`` instead of @@ -94,9 +107,55 @@ Features and then we want to cache the data for the duration of the request. See https://github.com/Pylons/pyramid/pull/3561 +- Exposed ``pyramid.authorization.ALL_PERMISSIONS`` and + ``pyramid.authorization.DENY_ALL`` such that all of the ACL-related constants + are now importable from the ``pyramid.authorization`` namespace. + See https://github.com/Pylons/pyramid/pull/3563 + Deprecations ------------ +- Deprecated the authentication and authorization interfaces and + principal-based support. See "Upgrading Authentication/Authorization" in + the "What's New in Pyramid 2.0" document for information on equivalent APIs + and notes on upgrading. The following APIs are deprecated as a result of + this change: + + - ``pyramid.config.Configurator.set_authentication_policy`` + - ``pyramid.config.Configurator.set_authorization_policy`` + - ``pyramid.interfaces.IAuthenticationPolicy`` + - ``pyramid.interfaces.IAuthorizationPolicy`` + - ``pyramid.request.Request.effective_principals`` + - ``pyramid.request.Request.unauthenticated_userid`` + - ``pyramid.authentication.AuthTktAuthenticationPolicy`` + - ``pyramid.authentication.RemoteUserAuthenticationPolicy`` + - ``pyramid.authentication.RepozeWho1AuthenticationPolicy`` + - ``pyramid.authentication.SessionAuthenticationPolicy`` + - ``pyramid.authentication.BasicAuthAuthenticationPolicy`` + - ``pyramid.authorization.ACLAuthorizationPolicy`` + - The ``effective_principals`` view and route predicates. + + See https://github.com/Pylons/pyramid/pull/3465 + +- Deprecated ``pyramid.security.principals_allowed_by_permission``. This + method continues to work with the deprecated + ``pyramid.interfaces.IAuthorizationPolicy`` interface but will not work with + the new ``pyramid.interfaces.ISecurityPolicy``. + See https://github.com/Pylons/pyramid/pull/3465 + +- Deprecated several ACL-related aspects of ``pyramid.security``. Equivalent + objects should now be imported from the ``pyramid.authorization`` namespace. + This includes: + + - ``pyramid.security.Everyone`` + - ``pyramid.security.Authenticated`` + - ``pyramid.security.ALL_PERMISSIONS`` + - ``pyramid.security.DENY_ALL`` + - ``pyramid.security.ACLAllowed`` + - ``pyramid.security.ACLDenied`` + + See https://github.com/Pylons/pyramid/pull/3563 + - Deprecated ``pyramid.session.PickleSerializer``. See https://github.com/pylons/pyramid/issues/2709 and https://github.com/pylons/pyramid/pull/3353 diff --git a/docs/api/authorization.rst b/docs/api/authorization.rst index c6b3d090e..fac47490a 100644 --- a/docs/api/authorization.rst +++ b/docs/api/authorization.rst @@ -10,3 +10,46 @@ .. autoclass:: ACLAuthorizationPolicy +Constants +--------- + +.. attribute:: Everyone + + The special principal id named 'Everyone'. This principal id is + granted to all requests. Its actual value is the string + 'system.Everyone'. + +.. attribute:: Authenticated + + The special principal id named 'Authenticated'. This principal id + is granted to all requests which contain any other non-Everyone + principal id (according to the :term:`authentication policy`). + Its actual value is the string 'system.Authenticated'. + +.. attribute:: ALL_PERMISSIONS + + An object that can be used as the ``permission`` member of an ACE + which matches all permissions unconditionally. For example, an + ACE that uses ``ALL_PERMISSIONS`` might be composed like so: + ``('Deny', 'system.Everyone', ALL_PERMISSIONS)``. + +.. attribute:: DENY_ALL + + A convenience shorthand ACE that defines ``('Deny', + 'system.Everyone', ALL_PERMISSIONS)``. This is often used as the + last ACE in an ACL in systems that use an "inheriting" security + policy, representing the concept "don't inherit any other ACEs". + +Return Values +------------- + +.. autoclass:: ACLDenied + :members: msg + + .. automethod:: __new__ + +.. autoclass:: ACLAllowed + :members: msg + + .. automethod:: __new__ + diff --git a/docs/api/security.rst b/docs/api/security.rst index edb66472e..3350f8207 100644 --- a/docs/api/security.rst +++ b/docs/api/security.rst @@ -10,7 +10,7 @@ Authentication API Functions .. autofunction:: forget -.. autofunction:: remember(request, userid, **kwargs) +.. autofunction:: remember Authorization API Functions --------------------------- @@ -22,12 +22,24 @@ Authorization API Functions Constants --------- +.. attribute:: NO_PERMISSION_REQUIRED + + A special permission which indicates that the view should always + be executable by entirely anonymous users, regardless of the + default permission, bypassing any :term:`authorization policy` + that may be in effect. Its actual value is the string + '__no_permission_required__'. + .. attribute:: Everyone The special principal id named 'Everyone'. This principal id is granted to all requests. Its actual value is the string 'system.Everyone'. + .. deprecated:: 2.0 + + Moved to :data:`pyramid.authorization.Everyone`. + .. attribute:: Authenticated The special principal id named 'Authenticated'. This principal id @@ -35,6 +47,10 @@ Constants principal id (according to the :term:`authentication policy`). Its actual value is the string 'system.Authenticated'. + .. deprecated:: 2.0 + + Moved to :data:`pyramid.authorization.Authenticated`. + .. attribute:: ALL_PERMISSIONS An object that can be used as the ``permission`` member of an ACE @@ -42,6 +58,10 @@ Constants ACE that uses ``ALL_PERMISSIONS`` might be composed like so: ``('Deny', 'system.Everyone', ALL_PERMISSIONS)``. + .. deprecated:: 2.0 + + Moved to :data:`pyramid.authorization.ALL_PERMISSIONS`. + .. attribute:: DENY_ALL A convenience shorthand ACE that defines ``('Deny', @@ -49,13 +69,9 @@ Constants last ACE in an ACL in systems that use an "inheriting" security policy, representing the concept "don't inherit any other ACEs". -.. attribute:: NO_PERMISSION_REQUIRED + .. deprecated:: 2.0 - A special permission which indicates that the view should always - be executable by entirely anonymous users, regardless of the - default permission, bypassing any :term:`authorization policy` - that may be in effect. Its actual value is the string - '__no_permission_required__'. + Moved to :data:`pyramid.authorization.DENY_ALL`. Return Values ------------- @@ -66,12 +82,20 @@ Return Values 'read')`` that means allow access. A sequence of ACEs makes up an ACL. It is a string, and its actual value is "Allow". + .. deprecated:: 2.0 + + Moved to :data:`pyramid.authorization.Allow`. + .. attribute:: Deny The ACE "action" (the first element in an ACE e.g. ``(Deny, 'george', 'read')`` that means deny access. A sequence of ACEs makes up an ACL. It is a string, and its actual value is "Deny". + .. deprecated:: 2.0 + + Moved to :data:`pyramid.authorization.Deny`. + .. autoclass:: Denied :members: msg @@ -85,10 +109,18 @@ Return Values .. autoclass:: ACLDenied :members: msg + .. deprecated:: 2.0 + + Moved to :data:`pyramid.authorization.ACLDenied`. + .. automethod:: __new__ .. autoclass:: ACLAllowed :members: msg + .. deprecated:: 2.0 + + Moved to :data:`pyramid.authorization.ACLAllowed`. + .. automethod:: __new__ |