Security policy documentation.

2 files changed, 31 insertions, 14 deletions

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
 ----------------------------------