diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/configuration.rst | 4 | ||||
| -rw-r--r-- | docs/glossary.rst | 4 | ||||
| -rw-r--r-- | docs/narr/security.rst | 35 | ||||
| -rw-r--r-- | docs/zcml.rst | 1 | ||||
| -rw-r--r-- | docs/zcml/default_permission.rst | 61 |
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``. |