Features

  - The ``BFG_DEBUG_AUTHORIZATION`` envvar and the
    ``debug_authorization`` config file value now only imply debugging
    of view-invoked security checks.  Previously, information was
    printed for every call to ``has_permission`` as well, which made
    output confusing.  To debug ``has_permission`` checks and other
    manual permission checks, use the debugger and print statements in
    your own code.

  - Authorization debugging info is now only present in the HTTP
    response body oif ``debug_authorization`` is true.

  - The format of authorization debug messages was improved.

  - A new ``BFG_DEBUG_NOTFOUND`` envvar was added and a symmetric
    ``debug_notfound`` config file value was added.  When either is
    true, and a NotFound response is returned by the BFG router
    (because a view could not be found), debugging information is
    printed to stderr.  When this value is set true, the body of
    HTTPNotFound responses will also contain the same debugging
    information.

  - ``Allowed`` and ``Denied`` responses from the security machinery
    are now specialized into two types: ACL types, and non-ACL types.
    The ACL-related responses are instances of
    ``repoze.bfg.security.ACLAllowed`` and
    ``repoze.bfg.security.ACLDenied``.  The non-ACL-related responses
    are ``repoze.bfg.security.Allowed`` and
    ``repoze.bfg.security.Denied``.  The allowed-type responses
    continue to evaluate equal to things that themselves evaluate
    equal to the ``True`` boolean, while the denied-type responses
    continue to evaluate equal to things that themselves evaluate
    equal to the ``False`` boolean.  The only difference between the
    two types is the information attached to them for debugging
    purposes.

  - Added a new ``BFG_DEBUG_ALL`` envvar and a symmetric ``debug_all``
    config file value.  When either is true, all other debug-related
    flags are set true unconditionally (e.g. ``debug_notfound`` and
    ``debug_authorization``).

  Documentation

  - Added info about debug flag changes.

  - Added a section to the security chapter named "Debugging
    Imperative Authorization Failures" (for e.g. ``has_permssion``).

1 files changed, 25 insertions, 7 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index b57ad2958..041fff89d 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -166,19 +166,20 @@ location-awareness.
 
 .. _debug_authorization_section:
 
-Debugging Authorization Failures
---------------------------------
+Debugging View Authorization Failures
+-------------------------------------
 
-If your application in your judgment is allowing or denying access
-inappropriately, start your application under a shell using the
+If your application in your judgment is allowing or denying view
+access inappropriately, start your application under a shell using the
 ``BFG_DEBUG_AUTHORIZATION`` environment variable set to ``1``.  For
 example::
 
   $ BFG_DEBUG_AUTHORIZATION=1 bin/paster serve myproject.ini
 
-When any authorization takes place, a message will be logged to the
-console (to stderr) about what ACE in which ACL permitted or denied
-the authorization based on authentication information.
+When any authorization takes place during a top-level view rendering,
+a message will be logged to the console (to stderr) about what ACE in
+which ACL permitted or denied the authorization based on
+authentication information.
 
 This behavior can also be turned on in the application ``.ini`` file
 by setting the ``debug_authorization`` key to ``true`` within the
@@ -188,3 +189,20 @@ application's configuration section, e.g.::
   use = egg:MyProject#app
   debug_authorization = true
 
+With this debug flag turned on, the response sent to the browser will
+also contain security debugging information in its body.
+
+Debugging Imperative Authorization Failures
+-------------------------------------------
+
+The ``has_permission`` API (see :ref:`security_module`) is used to
+check security within view functions imperatively.  It returns
+instances of objects that are effectively booleans.  But these objects
+are not raw ``True`` or ``False`` objects, and have information
+attached to them about why the permission was allowed or denied.  The
+object will be one of ``ACLAllowed``, ``ACLDenied``, ``Allowed``, and
+``Denied``, documented in :ref:`security_module`.  At very minimum
+these objects will have a ``msg`` attribute, which is a string
+indicating why permission was denied or allowed.  Introspecting this
+information in the debugger or via print statements when a
+``has_permission`` fails is often useful.