diff options
Diffstat (limited to 'docs/source/secure_controller.rst')
| -rw-r--r-- | docs/source/secure_controller.rst | 81 |
1 files changed, 48 insertions, 33 deletions
diff --git a/docs/source/secure_controller.rst b/docs/source/secure_controller.rst index 65709b5..090b512 100644 --- a/docs/source/secure_controller.rst +++ b/docs/source/secure_controller.rst @@ -2,23 +2,24 @@ Security and Authentication =========================== -Pecan provides no out-of-the-box support for authentication, but it does give -you the 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 provides no out-of-the-box support for authentication, but it +does give you the necessary tools to handle authentication and +authorization as you see fit. -Pecan's ``secure`` decorator secures a method or class depending on invocation. +``secure`` Decorator Basics +--------------------------- + +You can wrap entire controller subtrees *or* individual method calls +with access controls using the :func:`secure` decorator. To decorate a method, use one argument:: - secure('<check_permissions_method>') + secure('<check_permissions_method_name>') To secure a class, invoke with two arguments:: - secure(object_instance, '<check_permissions_method>') + secure(object_instance, '<check_permissions_method_name>') :: @@ -59,11 +60,17 @@ To secure a class, invoke with two arguments:: highly_classified = secure(HighlyClassifiedController(), 'check_permissions') unclassified = UnclassifiedController() -Alternatively, the same functionality can also be accomplished by subclassing -Pecan's ``SecureController`` class. Implementations of ``SecureController`` -should extend the ``check_permissions`` classmethod to return a ``True`` -or ``False`` value (depending on whether or not the user has permissions to -the controller branch):: + +``SecureController`` +------------------- + +Alternatively, the same functionality can also be accomplished by +subclassing Pecan's :class:`SecureController`. Implementations of +:class:`SecureController` should extend the :func:`check_permissions` +class method to return ``True`` if the user has permissions to the +controller branch and ``False`` if they do not. + +:: from pecan import expose from pecan.secure import SecureController, unlocked @@ -103,14 +110,15 @@ the controller branch):: unclassified = unlocked(UnclassifiedController()) -Also note the use of the ``@unlocked`` decorator in the above example, which +Also note the use of the :func:`@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 + +The :func:`check_permissions` method should be used to determine user authentication and authorization. The code you implement here could range from simple session assertions (the existing user is authenticated as an administrator) to connecting to an LDAP service. @@ -118,14 +126,17 @@ administrator) to connecting to an LDAP service. More on ``secure`` ------------------ -The ``secure`` method has several advanced uses that allow you to create + +The :func:`secure` method has several advanced uses that allow you to create robust security policies for your application. -First, you can pass via a string the name of either a classmethod or an -instance method of the controller to use as the ``check_permission`` method. +First, you can pass via a string the name of either a class method or an +instance method of the controller to use as the :func:`check_permission` method. Instance methods are particularly useful if you wish to authorize access to -attributes of a particular model instance. Consider the following example -of a basic virtual filesystem:: +attributes of a model instance. Consider the following example +of a basic virtual filesystem. + +:: from pecan import expose from pecan.secure import secure @@ -159,10 +170,12 @@ of a basic virtual filesystem:: return FileController(name), remainder -The ``secure`` method also accepts a function instead of a string. When +The :func:`secure` method also accepts a function argument. When passing a function, make sure that the function is imported from another -file or defined in the same file before the class definition -- otherwise -you will likely get error during module import. :: +file or defined in the same file before the class definition, otherwise +you will likely get error during module import. + +:: from pecan import expose from pecan.secure import secure @@ -176,8 +189,8 @@ you will likely get error during module import. :: return 'Logged in' -You can also use the ``secure`` method to change the behavior of a -``SecureController``. Decorating a method or wrapping a subcontroller tells +You can also use the :func:`secure` method to change the behavior of a +:class:`SecureController`. Decorating a method or wrapping a subcontroller tells Pecan to use another security function other than the default controller method. This is useful for situations where you want a different level or type of security. @@ -207,18 +220,20 @@ type of security. api = secure(ApiController(), 'check_api_permissions') -In the example above, pecan will *only* call ``admin_user`` when a request is +In the example above, pecan will *only* call :func:`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 -``SecureController`` instances allows you to protect controllers with an -increasing level of protection. :: + +Secure controllers can be nested to provide increasing levels of +security on subcontrollers. In the example below, when a request is +made for ``/admin/index/``, Pecan first calls +:func:`check_permissions` on the :class:`RootController` and then +calls :func:`check_permissions` on the :class:`AdminController`. + +:: from pecan import expose from pecan.secure import SecureController |