From 041897caf1f765d0edffcc3a1af2787714f308ca Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Jan 2009 21:13:35 +0000 Subject: Security policy documentation. --- docs/narr/security.rst | 22 ++++++++++++++++------ docs/narr/views.rst | 23 +++++++++++++++-------- 2 files changed, 31 insertions(+), 14 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index f511f402d..4afb04258 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -31,12 +31,22 @@ However, if you add the following bit of code to your application's The above inscrutable stanza enables the ``RemoteUserACLSecurityPolicy`` to be in effect for every request to your application. The ``RemoteUserACLSecurityPolicy`` is a policy -which compares the ``REMOTE_USER`` variable passed in the reqest's -environment (as the sole :term:`principal`) against any *ACL* found in -model data when attempting to call some :term:`view`. The policy -either allows the view that the permission was declared for to be -called, or returns a ``401 Unathorized`` response code to the upstream -WSGI server. +which compares the ``REMOTE_USER`` variable passed in the request's +environment (as the sole :term:`principal`) against the principals +present in any :term:`ACL` found in model data when attempting to call +some :term:`view`. The policy either allows the view that the +permission was declared for to be called, or returns a ``401 +Unathorized`` response code to the upstream WSGI server. + +.. note:: Another security policy also exists: + ``RepozeWhoIdentityACLSecurityPolicy``. This policy uses principal + information found in the ``repoze.who.identity`` value set into the + WSGI environment by the :term:`repoze.who` middleware rather than + ``REMOTE_USER`` information. This policy only works when + :term:`repoze.who` middleware is present in the WSGI pipeline. + +.. note:: See :ref:`security_policies_api_section` for more + information about the features of the default security policies. Protecting Views with Permissions --------------------------------- diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 5fa601a59..b23529f8f 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -266,10 +266,10 @@ Using Model Interfaces ---------------------- Instead of registering your views ``for`` a Python *class*, you can -instead register a view for an :term:`interface`. Since an interface -can be attached arbitrarily to any instance (as opposed to its -identity being implied by only its class), associating a view with an -interface can provide more flexibility for sharing a single view +optionally register a view for an :term:`interface`. Since an +interface can be attached arbitrarily to any instance (as opposed to +its identity being implied by only its class), associating a view with +an interface can provide more flexibility for sharing a single view between two or more different implementations of a model type. For example, if two model object instances of different Python class types share the same interface, you can use the same view against each of @@ -471,16 +471,23 @@ declaration: /> When a security policy is enabled, this view will be protected with -the ``add`` permission. The view will not be called if the user does -not possess the ``add`` permission relative to the current -:term:`context`. Instead an HTTP ``Unauthorized`` status will be -returned to the client. +the ``add`` permission. The view will *not be called* if the user +does not possess the ``add`` permission relative to the current +:term:`context` and a security policy is enabled. Instead an HTTP +``Unauthorized`` status will be returned to the client. .. note:: See the :ref:`security_chapter` chapter to find out how to turn on a security policy. +.. note:: + + Packages such as :term:`repoze.who` are capable of intercepting an + ``Unauthorized`` response and displaying a form that asks a user to + authenticate. Use this kind of package to ask the user for + authentication credentials. + Using a View to Do A HTTP Redirect ---------------------------------- -- cgit v1.2.3