diff --git a/docs/source/secure_controller.rst b/docs/source/secure_controller.rst index d0d7fd0..aebebbd 100644 --- a/docs/source/secure_controller.rst +++ b/docs/source/secure_controller.rst @@ -8,15 +8,15 @@ necessary tools to handle authentication and authorization as you see fit. In Pecan, you can wrap entire controller subtrees *or* individual method calls with function calls to determine access and secure portions of your application. -Pecan's ``secure`` method secures a method or class depending on invocation. +Pecan's ``secure`` decorator secures a method or class depending on invocation. To decorate a method, use one argument:: - @secure('') + secure('') To secure a class, invoke with two arguments:: - secure(, '') + secure(object_instance, '') :: @@ -97,6 +97,12 @@ or ``False`` value (depending on whether or not the user has permissions to the highly_classified = HighlyClassifiedController() unclassified = unlocked(UnclassifiedController()) + + +Also note the use of the ``@unlocked`` decorator in the above example, which can be used similarly +to explicitly unlock a controller for public access without any security checks. + + Writing Authentication/Authorization Methods ---------------- The ``check_permissions`` method should be used to determine user authentication and authorization. The @@ -186,6 +192,7 @@ You can also use the ``secure`` method to change the behavior of a SecureControl In the example above, pecan will *only* call ``admin_user`` when a request is made for ``/api/``. + Multiple Secure Controllers --------------------------- Pecan allows you to have nested secure controllers. In the example below, when a request is made for ``/admin/index/``, Pecan first calls ``check_permissions`` on the RootController and then calls ``check_permissions`` on the AdminController. The ability to nest ``SsecureController`` instances allows you to protect controllers with an increasing level of protection. ::