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.

5 files changed, 104 insertions, 1 deletions

diff --git a/docs/api/configuration.rst b/docs/api/configuration.rst
index 36e4c5186..1fb232275 100644
--- a/docs/api/configuration.rst
+++ b/docs/api/configuration.rst
@@ -5,7 +5,7 @@
 
 .. automodule:: repoze.bfg.configuration
 
-  .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None)
+  .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None, default_permission=None)
 
      .. attribute:: registry
 
@@ -60,6 +60,8 @@
 
      .. automethod:: set_locale_negotiator
 
+     .. automethod:: set_default_permission
+
      .. automethod:: set_request_factory
 
      .. automethod:: set_renderer_globals_factory
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 81f5cb797..4c1c0ebab 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -10,6 +10,10 @@ Glossary
      A ``WebOb`` request object.  See :ref:`webob_chapter` for
      information about request objects.
 
+   request factory
+     An object which, provided a WSGI environment as a single
+     positional argument, returns a ``WebOb`` compatible request.
+
    response
      An object that has three attributes: ``app_iter`` (representing an
      iterable body), ``headerlist`` (representing the http headers sent
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
diff --git a/docs/zcml.rst b/docs/zcml.rst
index e1bfc4f4b..9a41b8bcc 100644
--- a/docs/zcml.rst
+++ b/docs/zcml.rst
@@ -14,6 +14,7 @@ directive documentation is organized alphabetically by directive name.
    zcml/adapter
    zcml/authtktauthenticationpolicy
    zcml/configure
+   zcml/default_permission
    zcml/forbidden
    zcml/include
    zcml/localenegotiator
diff --git a/docs/zcml/default_permission.rst b/docs/zcml/default_permission.rst
new file mode 100644
index 000000000..39edbacd4
--- /dev/null
+++ b/docs/zcml/default_permission.rst
@@ -0,0 +1,61 @@
+.. _default_permission_directive:
+
+``default_permission``
+-------------------------------
+
+Set the default permission to be used by all :term:`view
+configuration` registrations.
+
+This directive accepts a single attribute ,``name``, which should be
+used as the default permission string.  An example of a permission
+string:``view``.  Adding a default permission makes it unnecessary to
+protect each view configuration with an explicit permission, unless
+your application policy requires some exception for a particular view.
+
+If a default permission is *not* set, views represented by view
+configuration registrations which do not explicitly declare a
+permission will be executable by entirely anonymous users (any
+authorization policy is ignored).
+
+There can be only one default permission active at a time within an
+application, thus the default permission directive can only be used
+once in any particular set of ZCML.
+
+.. note:  This API is new as of :mod:`repoze.bfg` version 1.3.
+
+Attributes
+~~~~~~~~~~
+
+``name`` must be a string representing a :term:`permission`,
+    e.g. ``view``.
+
+
+    The ``secret`` is a string that will be used to encrypt the data
+    stored by the cookie.  It is required and has no default.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <default_permission
+    name="view"
+    />
+
+Alternatives
+~~~~~~~~~~~~
+
+Using the ``default_permission`` argument to the
+:class:`repoze.bfg.configuration.Configurator` constructor can be used
+to achieve the same purpose.
+
+Using the
+:meth:`repoze.bfg.configuration.Configurator.set_default_permission`
+method can be used to achieve the same purpose when using imperative
+configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:``setting_a_default_permission``.