Security policy documentation.

5 files changed, 68 insertions, 32 deletions

diff --git a/docs/api/security.rst b/docs/api/security.rst
index c7088656e..accc46205 100644
--- a/docs/api/security.rst
+++ b/docs/api/security.rst
@@ -5,47 +5,65 @@
 
 .. automodule:: repoze.bfg.security
 
-  .. autofunction:: authenticated_userid
+API Functions
+~~~~~~~~~~~~~
 
-  .. autofunction:: effective_principals
+.. autofunction:: authenticated_userid
 
-  .. autofunction:: has_permission
+.. autofunction:: effective_principals
 
-  .. autofunction:: principals_allowed_by_permission
+.. autofunction:: has_permission
 
-  .. attribute:: Everyone
+.. autofunction:: principals_allowed_by_permission
+
+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
+.. 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 security policy).  Its actual value
     is the string 'system.Authenticated'.
 
-  .. attribute:: Allow
+Return Values
+~~~~~~~~~~~~~
+
+.. attribute:: Allow
 
     The ACE "action" (the first element in an ACE e.g. ``(Allow, Everyone,
     'read')`` that means allow access.  A sequence of ACEs makes up an
     ACL.  It is a string, and it's actual value is "Allow".
 
-  .. attribute:: Deny
+.. 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 it's actual value is "Deny".
 
-  .. autoclass:: ACLDenied
-     :members:
+.. autoclass:: ACLDenied
+   :members:
+
+.. autoclass:: ACLAllowed
+   :members:
+
+.. autoclass:: Denied
+   :members:
+
+.. autoclass:: Allowed
+   :members:
+
+.. _security_policies_api_section:
 
-  .. autoclass:: ACLAllowed
-     :members:
+Security Policies
+~~~~~~~~~~~~~~~~~
 
-  .. autoclass:: Denied
-     :members:
+.. autofunction:: RepozeWhoIdentityACLSecurityPolicy
 
-  .. autoclass:: Allowed
-     :members:
+.. autofunction:: RemoteUserACLSecurityPolicy
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
 ----------------------------------
 
diff --git a/docs/notes.txt b/docs/notes.txt
index c060e0cb5..d303042de 100644
--- a/docs/notes.txt
+++ b/docs/notes.txt
@@ -8,5 +8,3 @@
 
 - Describe better that render_template_to_response is a shortcut.
 
-- Show usage of, e.g. HTTPFound(location=url).
-
diff --git a/docs/tutorials/cmf/actions.rst b/docs/tutorials/cmf/actions.rst
index 3703db770..e16e70c52 100644
--- a/docs/tutorials/cmf/actions.rst
+++ b/docs/tutorials/cmf/actions.rst
@@ -24,3 +24,6 @@ individual views (tabs) within the group which cannot be displayed to
 the user due to the user's lack of permissions will be omitted from
 the rendered output.
 
+The :term:`repoze.lemonade` package provides "list item" support that
+may be used to construct action lists.
+