From 08ead74d05e25f58c83712f6f8651484ddc983d0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 26 May 2009 00:44:17 +0000 Subject: Revert all work towards creating a "forbidden" API on the security policy; I'll do this work on the authchanges branch first. --- docs/narr/hooks.rst | 72 ++++++++++++++++++++++++++--------------------------- 1 file changed, 35 insertions(+), 37 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 6428408e8..21906e466 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -88,7 +88,7 @@ an object that implements any particular interface; it simply needs have a ``status`` attribute, a ``headerlist`` attribute, and and ``app_iter`` attribute. -Changing the NotFound Application +Changing the NotFound application --------------------------------- When :mod:`repoze.bfg` can't map a URL to code, it creates and invokes @@ -119,56 +119,54 @@ sample code that implements a minimal NotFound application factory: .. note:: When a NotFound application factory is invoked, it is passed the WSGI environ and the WSGI ``start_response`` handler by :mod:`repoze.bfg`. Within the WSGI environ will be a key named - ``repoze.bfg.message`` that has a value explaining why the not - found error was raised. This error will be different when the - ``debug_notfound`` environment setting is true than it is when it - is false. + ``message`` that has a value explaining why the not found error was + raised. This error will be different when the ``debug_notfound`` + environment setting is true than it is when it is false. -Changing the Forbidden Response -------------------------------- +Changing the Unauthorized application +------------------------------------- When :mod:`repoze.bfg` can't authorize execution of a view based on -the security policy in use, it invokes a "forbidden response factory". -Usually this forbidden response factory is serviced by the currently -active :term:`security policy`, but it can be overridden as necessary -by placing something like the following ZCML in your -``configure.zcml`` file. +the security policy in use, it creates and invokes an Unauthorized +WSGI application. The application it invokes can be customized by +placing something like the following ZCML in your ``configure.zcml`` +file. .. code-block:: xml :linenos: - + -Replace ``helloworld.factories.forbidden_app_factory`` with the Python -dotted name to the forbidden response factory you want to use. The -response factory must accept two parameters: ``context`` and -``request``. The ``context`` is the context found by the router when -the view invocation was denied. The ``request`` is the current -:term:`request` representing the denied action. Here's some sample -code that implements a minimal forbidden response factory: +Replace ``helloworld.factories.unauthorized_app_factory`` with the +Python dotted name to the request factory you want to use. Here's +some sample code that implements a minimal Unauthorized application +factory: .. code-block:: python - from repoze.bfg.chameleon_zpt import render_template_to_response + from webob.exc import HTTPUnauthorized - def forbidden_response_factory(context, request): - return render_template_to_response('templates/login_form.pt') + class MyUnauthorized(HTTPUnauthorized): + pass -.. note:: When an forbidden response factory is invoked, it is passed - the request as the second argument. An attribute of the request is - ``environ``, which is the WSGI environment. Within the WSGI - environ will be a key named ``repoze.bfg.message`` that has a value - explaining why the current view invocation was forbidden. This - error will be different when the ``debug_authorization`` - environment setting is true than it is when it is false. + def notfound_app_factory(): + return MyUnauthorized -.. warning:: the default forbidden application factory sends a - response with a ``401 Unauthorized`` status code for backwards - compatibility reasons. You can influence the status code of - Forbidden responses by using an alterate forbidden application - factory. For example, it would make sense to return an forbidden - application with a ``403 Forbidden`` status code. +.. note:: When an Unauthorized application factory is invoked, it is + passed the WSGI environ and the WSGI ``start_response`` handler by + :mod:`repoze.bfg`. Within the WSGI environ will be a key named + ``message`` that has a value explaining why the action was not + authorized. This error will be different when the + ``debug_authorization`` environment setting is true than it is when + it is false. + +.. note:: You can influence the status code of Unauthorized responses + by using an alterate unauthorized application factory. For + example, you may return an unauthorized application with a ``403 + Forbidden`` status code, rather than use the default unauthorized + application factory, which sends a response with a ``401 + Unauthorized`` status code. Changing the Default Routes Context Factory ------------------------------------------- -- cgit v1.2.3