Features

--------

- In support of making it easier to configure applications which are
  "secure by default", a default permission feature was added.  If
  supplied, the default permission is used as the permission string to
  all view registrations which don't otherwise name a permission.
  These APIs are in support of that:

  - A new constructor argument was added to the Configurator:
    ``default_permission``.

  - A new method was added to the Configurator:
    ``set_default_permission``.

  - A new ZCML directive was added: ``default_permission``.

Documentation
-------------

- Added documentation for the ``default_permission`` ZCML directive.

- Added documentation for the ``default_permission`` constructor value
  and the ``set_default_permission`` method in the Configurator API
  documentation.

- Added a new section to the "security" chapter named "Setting a
  Default Permission".

- Document ``renderer_globals_factory`` and ``request_factory``
  arguments to Configurator constructor.

1 files changed, 35 insertions, 0 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 3b1de27ad..85ab9ef58 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -232,6 +232,41 @@ possess the ``add`` permission against the :term:`context` to be able
 to invoke the ``blog_entry_add_view`` view.  If he does not, the
 :term:`Forbidden view` will be invoked.
 
+.. _setting_a_default_permission:
+
+Setting a Default Permission
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a permission is not supplied to a view configuration, the
+registered view always be executable by entirely anonymous users: any
+authorization policy in effect is ignored.
+
+In support of making it easier to configure applications which are
+"secure by default", :mod:`repoze.bfg` allows you to configure a
+*default* permission.  If supplied, the default permission is used as
+the permission string to all view registrations which don't otherwise
+name a ``permission`` argument.
+
+These APIs are in support of configuring a default permission for an
+application:
+
+- The ``default_permission`` constructor argument to the
+  :mod:`repoze.bfg.configuration.Configurator` constructor.
+
+- The
+  :meth:`repoze.bfg.configuration.Configurator.set_default_permission`
+  method.
+
+- The :ref:`default_permission_directive` ZCML directive.
+
+When a default permission is registered, if a view configuration
+*does* name its own permission, the default permission is ignored for
+that view registration, and the view-configuration-named permission is
+used.
+
+.. note:: All APIs and ZCML directives related to default permissions
+   are new in :mod:`repoze.bfg` 1.3.
+
 .. index::
    single: ACL
    single: access control list