Features

--------

- It is now possible to write a custom security policy that returns a
  customized ``Forbidden`` WSGI application when BFG cannot authorize
  an invocation of a view.  To this end, ISecurityPolicy objects must
  now have a ``forbidden`` method.  This method should return a WSGI
  application.  The returned WSGI application should generate a
  response which is appropriate when access to a view resource was
  forbidden by the security policy (e.g. perhaps a login page).
  ``repoze.bfg`` is willing to operate with a custom security policy
  that does not have a ``forbidden`` method, but it will issue a
  warning; eventually security policies without a ``forbidden`` method
  will cease to work under ``repoze.bfg``.

  Note that the ``forbidden`` WSGI application returned by the
  security policy is not used if a developer has registered an
  IForbiddenAppFactory (see the "Hooks" narrative chapter); the
  explicitly registered IForbiddenAppFactory will be preferred over
  the (more general) security policy forbidden app factory.

- All default security policies now have a ``forbidden`` callable
  attached to them.  This particular callable returns a WSGI
  application which generates a ``401 Unauthorized`` response for
  backwards compatibility (had backwards compatibility not been an
  issue, this callable would have returned a WSGI app that generated a
  ``403 Forbidden`` response).

Backwards Incompatibilities
---------------------------

- Custom NotFound and Forbidden (nee' Unauthorized) WSGI applications
  (registered a a utility for INotFoundAppFactory and
  IUnauthorizedAppFactory) could rely on an environment key named
  ``message`` describing the circumstance of the response.  This key
  has been renamed to ``repoze.bfg.message`` (as per the WSGI spec,
  which requires environment extensions to contain dots).

Deprecations
------------

- The ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` interface has
  been renamed to ``repoze.bfg.interfaces.IForbiddenAppFactory``.

1 files changed, 18 insertions, 1 deletions

diff --git a/repoze/bfg/interfaces.py b/repoze/bfg/interfaces.py
index cecc3a397..034e0ac1c 100644
--- a/repoze/bfg/interfaces.py
+++ b/repoze/bfg/interfaces.py
@@ -131,6 +131,17 @@ class ISecurityPolicy(Interface):
         implementation, in which case, it should raise a
         ``NotImplementedError`` exception."""
 
+    def forbidden():
+        """ This method should return a WSGI application (a callable
+        accepting ``environ`` and ``start_response``).  This WSGI
+        application will be called by ``repoze.bfg`` when view
+        invocation is denied due to a security policy deny.  The WSGI
+        application should return a response appropriate when access
+        to a view resource was forbidden by the security policy.  Note
+        that the ``repoze.bfg.message`` key in the environ passed to
+        the WSGI app will contain the 'raw' reason that view
+        invocation was denied by repoze.bfg."""
+
 class IViewPermission(Interface):
     def __call__(security_policy):
         """ Return True if the permission allows, return False if it denies. """
@@ -197,7 +208,7 @@ class INotFoundAppFactory(Interface):
         a``message`` key in the WSGI environ provides information
         pertaining to the reason for the notfound."""
 
-class IUnauthorizedAppFactory(Interface):
+class IForbiddenAppFactory(Interface):
     """ A utility which returns an Unauthorized WSGI application
     factory"""
     def __call__():
@@ -206,6 +217,12 @@ class IUnauthorizedAppFactory(Interface):
         ``message`` key in the WSGI environ provides information
         pertaining to the reason for the unauthorized."""
 
+IUnauthorizedAppFactory = IForbiddenAppFactory
+deprecated('IUnauthorizedAppFactory',
+           '(repoze.bfg.interfaces.IUnauthorizedAppFactory should now be '
+           'imported as repoze.bfg.interfaces.IForbiddenAppFactory)',
+           )
+
 class IContextURL(Interface):
     """ An adapter which deals with URLs related to a context.
     """