From ee50aec09576620537ff68895cfb81fd4663a45f Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Fri, 31 Dec 2010 18:24:18 -0700 Subject: Remove resource location chapter and move intro parts to url dispatch. The new much ado about traversal chapter takes care of selling traversal now --- docs/narr/security.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index c5262faa2..62a4727bc 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -18,8 +18,7 @@ works at a high level: :term:`resource location`. A context is located differently depending on whether the application uses :term:`traversal` or :term:`URL dispatch`, but a context is ultimately found in either case. See - :ref:`resourcelocation_chapter` for more information about resource - location. + the :ref:`urldispatch_chapter` chapter for more information. - A :term:`view callable` is located by :term:`view lookup` using the context as well as other attributes of the request. -- cgit v1.2.3 From 82e0452f9c71ddd71489cca74f6070dada94e5dd Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Sat, 15 Jan 2011 21:54:58 -0700 Subject: our => the --- docs/narr/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 62a4727bc..43b5aaa19 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -12,7 +12,7 @@ credentials in the :term:`request` does not have an appropriate level of access when a particular resource is the :term:`context`. Here's how it works at a high level: -- A :term:`request` is generated when a user visits our application. +- A :term:`request` is generated when a user visits the application. - Based on the request, a :term:`context` resource is located through :term:`resource location`. A context is located differently depending on -- cgit v1.2.3 From 93d5dbd2bc8890a771425a8cd7f6dcd5aad66d58 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Sat, 15 Jan 2011 22:07:07 -0700 Subject: reword security intro paragraph --- docs/narr/security.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 43b5aaa19..814f232d7 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -6,11 +6,12 @@ Security ======== -:app:`Pyramid` provides an optional declarative authorization system that -prevents a :term:`view` from being invoked when the user represented by -credentials in the :term:`request` does not have an appropriate level of -access when a particular resource is the :term:`context`. Here's how it -works at a high level: +:app:`Pyramid` provides an optional declarative authorization system +that prevents a :term:`view` from being invoked based on an +:term:`authorization policy`. Before a view is invoked, the +authorization system can use the credentials in the :term:`request` +along with the :term:`context` resource to determine if access will be +allowed. Here's how it works at a high level: - A :term:`request` is generated when a user visits the application. -- cgit v1.2.3 From c90930a41c7ccac634d96536a4c65bce57f5fb8b Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Sat, 15 Jan 2011 22:08:21 -0700 Subject: slight clarification --- docs/narr/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 814f232d7..6ea48794c 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -7,7 +7,7 @@ Security ======== :app:`Pyramid` provides an optional declarative authorization system -that prevents a :term:`view` from being invoked based on an +that can prevent a :term:`view` from being invoked based on an :term:`authorization policy`. Before a view is invoked, the authorization system can use the credentials in the :term:`request` along with the :term:`context` resource to determine if access will be -- cgit v1.2.3 From 3dc9116f868c40aed42904b95b0ca703b2f73aa3 Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Sat, 15 Jan 2011 22:20:52 -0700 Subject: XXX explain the authentication/authorization separate in pyramid. Confirm this is correct XXX --- docs/narr/security.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 6ea48794c..f20c9f63e 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -41,6 +41,15 @@ allowed. Here's how it works at a high level: - If the authorization policy denies access, the view callable is not invoked; instead the :term:`forbidden view` is invoked. +Security in :app:`Pyramid`, unlike many systems, cleanly and explicitly +separates authentication and authorization. Authentication is merely the +mechanism by which credentials provided in the :term:`request` are +resolved to one or more :term:`principal` identifiers. These identifiers +represent the users and groups in effect during the request. +Authorization then determines access based on the :term:`principal` +identifiers, the :term:`view callable` being invoked, and the +:term:`context` resource. + Authorization is enabled by modifying your application to include an :term:`authentication policy` and :term:`authorization policy`. :app:`Pyramid` comes with a variety of implementations of these -- cgit v1.2.3 From cb0f3c4f0f06ba9e052d6c3ea248045965ebbc0c Mon Sep 17 00:00:00 2001 From: Casey Duncan Date: Sat, 15 Jan 2011 22:24:45 -0700 Subject: add missing word --- docs/narr/security.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index f20c9f63e..babf66ecd 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -179,8 +179,8 @@ to invoke the ``blog_entry_add_view`` view. If he does not, the Setting a Default Permission ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If a permission is not supplied to a view configuration, the -registered view always be executable by entirely anonymous users: any +If a permission is not supplied to a view configuration, the registered +view will always be executable by entirely anonymous users: any authorization policy in effect is ignored. In support of making it easier to configure applications which are -- cgit v1.2.3 From c9c3c487bcaedeca97bb6463a00188b0dc01203a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 18 Jan 2011 12:25:56 -0500 Subject: - Most references to ZCML in narrative chapters have been removed or redirected to ``pyramid_zcml`` locations. --- docs/narr/security.rst | 8 -------- 1 file changed, 8 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 62a4727bc..ebaeb1526 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -106,9 +106,6 @@ See also the :mod:`pyramid.authorization` and :mod:`pyramid.authentication` modules for alternate implementations of authorization and authentication policies. -You can also enable a security policy declaratively via ZCML. See -:ref:`zcml_authorization_policy`. - .. index:: single: permissions single: protecting views @@ -154,9 +151,6 @@ may be performed via the ``@view_config`` decorator: """ Add blog entry code goes here """ pass -Or the same thing can be done using the ``permission`` attribute of the ZCML -:ref:`view_directive` directive. - As a result of any of these various view configuration statements, if an authorization policy is in place when the view callable is found during normal application operations, the requesting user will need to possess the @@ -189,8 +183,6 @@ application: :meth:`pyramid.config.Configurator.set_default_permission` method. -- The :ref:`default_permission_directive` ZCML directive. - When a default permission is registered: - if a view configuration names an explicit ``permission``, the default -- cgit v1.2.3 From 57cc8680abf2c2bce3a8bc405277677043ffe007 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 21 Jan 2011 12:26:17 -0500 Subject: - Slightly improved interface docs for ``IAuthorizationPolicy``. --- docs/narr/security.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index e395b15f1..783810734 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -566,10 +566,12 @@ that implements the following interface: authenticated userid can be found. """ def effective_principals(self, request): + """ Return a sequence representing the effective principals including the userid and any groups belonged to by the current - user, including 'system' groups such as Everyone and - Authenticated. """ + user, including 'system' groups such as + ``pyramid.security.Everyone`` and + ``pyramid.security.Authenticated``. """ def remember(self, request, principal, **kw): """ Return a set of headers suitable for 'remembering' the @@ -618,12 +620,18 @@ following interface: class IAuthorizationPolicy(object): """ An object representing a Pyramid authorization policy. """ def permits(self, context, principals, permission): - """ Return True if any of the principals is allowed the - permission in the current context, else return False """ + """ Return ``True`` if any of the ``principals`` is allowed the + ``permission`` in the current ``context``, else return ``False`` + """ def principals_allowed_by_permission(self, context, permission): - """ Return a set of principal identifiers allowed by the - permission """ + """ Return a set of principal identifiers allowed by the + ``permission`` in ``context``. This behavior is optional; if you + choose to not implement it you should define this method as + something which raises a ``NotImplementedError``. This method + will only be called when the + ``pyramid.security.principals_allowed_by_permission`` API is + used.""" After you do so, you can pass an instance of such a class into the :class:`pyramid.config.Configurator` class at configuration -- cgit v1.2.3 From 2021a002c125f24995c78602e2f4b68df46b71f8 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Jan 2011 17:59:07 -0500 Subject: - Beef up documentation related to ``set_default_permission``: explicitly mention that default permissions also protect exception views. --- docs/narr/security.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 783810734..8b3427675 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -204,6 +204,13 @@ When a default permission is registered: and the view is registered *without* a permission (making it available to all callers regardless of their credentials). +.. warning:: + + When you register a default permission, *all* views (even :term:`exception + view` views) are protected by a permission. For all views which are truly + meant to be anonymously accessible, you will need to associate the view's + configuration with the ``__no_permission_required__`` permission. + .. index:: single: ACL single: access control list -- cgit v1.2.3 From a47e1921af0f49454c084d2480949b53fd1f3717 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Jan 2011 22:02:43 -0500 Subject: fix dangling references --- docs/narr/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 8b3427675..61948650e 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -97,7 +97,7 @@ For example: authorization_policy=authorization_policy) .. note:: the ``authentication_policy`` and ``authorization_policy`` - arguments may also be passed to the Configurator as :ref:`dotted + arguments may also be passed to the Configurator as :term:`dotted Python name` values, each representing the dotted name path to a suitable implementation global defined at Python module scope. -- cgit v1.2.3 From 70acd25f40f32fc6cbb3b5d38a695b8982b52a31 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 27 Jan 2011 23:06:55 -0500 Subject: module name contractions --- docs/narr/security.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 61948650e..72e4e3a6f 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -72,14 +72,14 @@ Enabling an Authorization Policy Imperatively ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Passing an ``authorization_policy`` argument to the constructor of the -:class:`pyramid.config.Configurator` class enables an +:class:`~pyramid.config.Configurator` class enables an authorization policy. You must also enable an :term:`authentication policy` in order to enable the authorization policy. This is because authorization, in general, depends upon authentication. Use the ``authentication_policy`` argument to the -:class:`pyramid.config.Configurator` class during +:class:`~pyramid.config.Configurator` class during application setup to specify an authentication policy. For example: @@ -187,11 +187,9 @@ These APIs are in support of configuring a default permission for an application: - The ``default_permission`` constructor argument to the - :mod:`pyramid.config.Configurator` constructor. + :mod:`~pyramid.config.Configurator` constructor. -- The - :meth:`pyramid.config.Configurator.set_default_permission` - method. +- The :meth:`pyramid.config.Configurator.set_default_permission` method. When a default permission is registered: @@ -546,7 +544,7 @@ one of :data:`pyramid.security.ACLAllowed`, ``msg`` attribute, which is a string indicating why the permission was denied or allowed. Introspecting this information in the debugger or via print statements when a call to -:func:`pyramid.security.has_permission` fails is often useful. +:func:`~pyramid.security.has_permission` fails is often useful. .. index:: single: authentication policy (creating) @@ -591,7 +589,7 @@ that implements the following interface: current user on subsequent requests. """ After you do so, you can pass an instance of such a class into the -:class:`pyramid.config.Configurator` class at configuration +:class:`~pyramid.config.Configurator` class at configuration time as ``authentication_policy`` to use it. .. index:: @@ -610,7 +608,7 @@ otherwise specified. In some cases, it's useful to be able to use a different authorization policy than the default -:class:`pyramid.authorization.ACLAuthorizationPolicy`. For +:class:`~pyramid.authorization.ACLAuthorizationPolicy`. For example, it might be desirable to construct an alternate authorization policy which allows the application to use an authorization mechanism that does not involve :term:`ACL` objects. @@ -641,5 +639,5 @@ following interface: used.""" After you do so, you can pass an instance of such a class into the -:class:`pyramid.config.Configurator` class at configuration +:class:`~pyramid.config.Configurator` class at configuration time as ``authorization_policy`` to use it. -- cgit v1.2.3 From e47c780e3a45e256dd1b4f98c92c9b75c26ca665 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 30 Jan 2011 13:17:02 -0500 Subject: remove reference to ZCML directives; doesnt work in printed book --- docs/narr/security.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 72e4e3a6f..6414c7143 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -311,9 +311,7 @@ authentication system provides group information and the effective :term:`authentication policy` policy is written to respect group information. For example, the :class:`pyramid.authentication.RepozeWho1AuthenicationPolicy` respects group -information if you configure it with a ``callback``. See -:ref:`authentication_policies_directives_section` for more information about -the ``callback`` attribute. +information if you configure it with a ``callback``. Each ACE in an ACL is processed by an authorization policy *in the order dictated by the ACL*. So if you have an ACL like this: -- cgit v1.2.3 From 5a3520f197aadba1740ded566fb5c4956cae0bc3 Mon Sep 17 00:00:00 2001 From: Chris Beelby Date: Wed, 2 Feb 2011 21:16:35 -0500 Subject: Capitalization fix --- docs/narr/security.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 783810734..d4957b491 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -195,11 +195,11 @@ application: When a default permission is registered: -- if a view configuration names an explicit ``permission``, the default +- If a view configuration names an explicit ``permission``, the default permission is ignored for that view registration, and the view-configuration-named permission is used. -- if a view configuration names an explicit permission as the string +- If a view configuration names an explicit permission as the string ``__no_permission_required__``, the default permission is ignored, and the view is registered *without* a permission (making it available to all callers regardless of their credentials). -- cgit v1.2.3 From 9b514e5df0caba9a02bb6d2915d5eb3f13e7a897 Mon Sep 17 00:00:00 2001 From: Chris Beelby Date: Wed, 2 Feb 2011 21:27:29 -0500 Subject: Wrong name for variable --- docs/narr/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index d4957b491..10a6c3db3 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -457,7 +457,7 @@ parents left. In order to allow the security machinery to perform ACL inheritance, resource objects must provide *location-awareness*. Providing *location-awareness* means two things: the root object in the resource tree must have a -``_name__`` attribute and a ``__parent__`` attribute. +``__name__`` attribute and a ``__parent__`` attribute. .. code-block:: python :linenos: -- cgit v1.2.3 From 80b4af9533c54fd02636e997bfe620fcb7b491e0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 28 Feb 2011 10:38:06 -0500 Subject: Fix authentication policy example. Closes #137 --- docs/narr/security.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'docs/narr/security.rst') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 6e07c9338..c7a07b857 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -564,12 +564,23 @@ that implements the following interface: class AuthenticationPolicy(object): """ An object representing a Pyramid authentication policy. """ + def authenticated_userid(self, request): """ Return the authenticated userid or ``None`` if no - authenticated userid can be found. """ + authenticated userid can be found. This method of the policy + should ensure that a record exists in whatever persistent store is + used related to the user (the user should not have been deleted); + if a record associated with the current id does not exist in a + persistent store, it should return ``None``.""" + + def unauthenticated_userid(self, request): + """ Return the *unauthenticated* userid. This method performs the + same duty as ``authenticated_userid`` but is permitted to return the + userid based only on data present in the request; it needn't (and + shouldn't) check any persistent store to ensure that the user record + related to the request userid exists.""" def effective_principals(self, request): - """ Return a sequence representing the effective principals including the userid and any groups belonged to by the current user, including 'system' groups such as -- cgit v1.2.3