/authorization.rst

https://bitbucket.org/blaflamme/pylonswiking · ReStructuredText · 280 lines · 215 code · 65 blank · 0 comment · 0 complexity · 703019131ff19d9e3037bd7322dc9168 MD5 · raw file

  1. .. _wiki2_adding_authorization:
  2. ====================
  3. Adding Authorization
  4. ====================
  5. Our application currently allows anyone with access to the server to
  6. view, edit, and add pages to our wiki. For purposes of demonstration
  7. we'll change our application to allow only people whom possess a
  8. specific username (`editor`) to add and edit wiki pages but we'll
  9. continue allowing anyone with access to the server to view pages.
  10. :mod:`repoze.bfg` provides facilities for *authorization* and
  11. *authentication*. We'll make use of both features to provide security
  12. to our application.
  13. The source code for this tutorial stage can be browsed at
  14. `docs.repoze.org
  15. <http://docs.repoze.org/bfgwiki2-1.3/authorization>`_.
  16. Adding A Root Factory
  17. ---------------------
  18. We're going to start to use a custom :term:`root factory` within our
  19. ``run.py`` file. The objects generated by the root factory will be
  20. used as the :term:`context` of each request to our application. In
  21. order for :mod:`repoze.bfg` declarative security to work properly, the
  22. context object generated during a request must be decorated with
  23. security declarations; when we begin to use a custom root factory to
  24. generate our contexts, we can begin to make use of the declarative
  25. security features of :mod:`repoze.bfg`.
  26. Let's modify our ``run.py``, passing in a :term:`root factory` to our
  27. :term:`Configurator` constructor. We'll point it at a new class we
  28. create inside our ``models.py`` file. Add the following statements to
  29. your ``models.py`` file:
  30. .. code-block:: python
  31. from repoze.bfg.security import Allow
  32. from repoze.bfg.security import Everyone
  33. class RootFactory(object):
  34. __acl__ = [ (Allow, Everyone, 'view'),
  35. (Allow, 'group:editors', 'edit') ]
  36. def __init__(self, request):
  37. self.__dict__.update(request.matchdict)
  38. The ``RootFactory`` class we've just added will be used by
  39. :mod:`repoze.bfg` to construct a ``context`` object. The context is
  40. attached to the request object passed to our view callables as the
  41. ``context`` attribute.
  42. All of our context objects will possess an ``__acl__`` attribute that
  43. allows :data:`repoze.bfg.security.Everyone` (a special principal) to
  44. view all pages, while allowing only a :term:`principal` named
  45. ``group:editors`` to edit and add pages. The ``__acl__`` attribute
  46. attached to a context is interpreted specially by :mod:`repoze.bfg` as
  47. an access control list during view callable execution. See
  48. :ref:`assigning_acls` for more information about what an :term:`ACL`
  49. represents.
  50. .. note: Although we don't use the functionality here, the ``factory``
  51. used to create route contexts may differ per-route as opposed to
  52. globally. See the ``factory`` attribute in
  53. :ref:`route_zcml_directive` for more info.
  54. We'll pass the ``RootFactory`` we created in the step above in as the
  55. ``root_factory`` argument to a :term:`Configurator`. When we're done,
  56. your application's ``run.py`` will look like this.
  57. .. literalinclude:: src/authorization/tutorial/run.py
  58. :linenos:
  59. :language: python
  60. Configuring a ``repoze.bfg`` Authorization Policy
  61. -------------------------------------------------
  62. For any :mod:`repoze.bfg` application to perform authorization, we
  63. need to add a ``security.py`` module and we'll need to change our
  64. ``configure.zcml`` file to add an :term:`authentication policy` and an
  65. :term:`authorization policy`.
  66. Changing ``configure.zcml``
  67. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  68. We'll change our ``configure.zcml`` file to enable an
  69. ``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to
  70. enable declarative security checking. We'll also change
  71. ``configure.zcml`` to add a view stanza which points at our ``login``
  72. :term:`view callable`, also known as a :term:`forbidden view`. This
  73. configures our newly created login view to show up when
  74. :mod:`repoze.bfg` detects that a view invocation can not be
  75. authorized. Also, we'll add ``view_permission`` attributes with the
  76. value ``edit`` to the ``edit_page`` and ``add_page`` route
  77. declarations. This indicates that the view callables which these
  78. routes reference cannot be invoked without the authenticated user
  79. possessing the ``edit`` permission with respect to the current
  80. context.
  81. This makes the assertion that only users who possess the effective
  82. ``edit`` permission at the time of the request may invoke those two
  83. views. We've granted the ``group:editors`` principal the ``edit``
  84. permission at the root model via its ACL, so only the a user whom is a
  85. member of the group named ``group:editors`` will able to invoke the
  86. views associated with the ``add_page`` or ``edit_page`` routes.
  87. When you're done, your ``configure.zcml`` will look like so
  88. .. literalinclude:: src/authorization/tutorial/configure.zcml
  89. :linenos:
  90. :language: xml
  91. Note that the ``authtktauthenticationpolicy`` tag has two attributes:
  92. ``secret`` and ``callback``. ``secret`` is a string representing an
  93. encryption key used by the "authentication ticket" machinery
  94. represented by this policy: it is required. The ``callback`` is a
  95. string, representing a :term:`dotted Python name`, which points at the
  96. ``groupfinder`` function in the current directory's ``security.py``
  97. file. We haven't added that module yet, but we're about to.
  98. Adding ``security.py``
  99. ~~~~~~~~~~~~~~~~~~~~~~
  100. Add a ``security.py`` module within your package (in the same
  101. directory as "run.py", "views.py", etc) with the following content:
  102. .. literalinclude:: src/authorization/tutorial/security.py
  103. :linenos:
  104. :language: python
  105. The groupfinder defined here is an :term:`authentication policy`
  106. "callback"; it is a callable that accepts a userid and a request. If
  107. the userid exists in the system, the callback will return a sequence
  108. of group identifiers (or an empty sequence if the user isn't a member
  109. of any groups). If the userid *does not* exist in the system, the
  110. callback will return ``None``. In a production system, user and group
  111. data will most often come from a database, but here we use "dummy"
  112. data to represent user and groups sources. Note that the ``editor``
  113. user is a member of the ``group:editors`` group in our dummy group
  114. data (the ``GROUPS`` data structure).
  115. We've given the ``editor`` user membership to the ``group:editors`` by
  116. mapping him to this group in the ``GROUPS`` data structure (``GROUPS =
  117. {'editor':['group:editors']}``). Since the ``groupfinder`` function
  118. consults the ``GROUPS`` data structure, this will mean that, as a
  119. result of the ACL attached to the root returned by the root factory,
  120. and the permission associated with the ``add_page`` and ``edit_page``
  121. views, the ``editor`` user should be able to add and edit pages.
  122. Adding Login and Logout Views
  123. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  124. We'll add a ``login`` view callable which renders a login form and
  125. processes the post from the login form, checking credentials.
  126. We'll also add a ``logout`` view callable to our application and
  127. provide a link to it. This view will clear the credentials of the
  128. logged in user and redirect back to the front page.
  129. We'll add a different file (for presentation convenience) to add login
  130. and logout view callables. Add a file named ``login.py`` to your
  131. application (in the same directory as ``views.py``) with the following
  132. content:
  133. .. literalinclude:: src/authorization/tutorial/login.py
  134. :linenos:
  135. :language: python
  136. Changing Existing Views
  137. ~~~~~~~~~~~~~~~~~~~~~~~
  138. Then we need to change each of our ``view_page``, ``edit_page`` and
  139. ``add_page`` views in ``views.py`` to pass a "logged in" parameter to
  140. its template. We'll add something like this to each view body:
  141. .. ignore-next-block
  142. .. code-block:: python
  143. :linenos:
  144. from repoze.bfg.security import authenticated_userid
  145. logged_in = authenticated_userid(request)
  146. We'll then change the return value of these views to pass the
  147. `resulting `logged_in`` value to the template, e.g.:
  148. .. ignore-next-block
  149. .. code-block:: python
  150. :linenos:
  151. return dict(page = context,
  152. content = content,
  153. logged_in = logged_in,
  154. edit_url = edit_url)
  155. Adding the ``login.pt`` Template
  156. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  157. Add a ``login.pt`` template to your templates directory. It's
  158. referred to within the login view we just added to ``login.py``.
  159. .. literalinclude:: src/authorization/tutorial/templates/login.pt
  160. :linenos:
  161. :language: xml
  162. Change ``view.pt`` and ``edit.pt``
  163. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  164. We'll also need to change our ``edit.pt`` and ``view.pt`` templates to
  165. display a "Logout" link if someone is logged in. This link will
  166. invoke the logout view.
  167. To do so we'll add this to both templates within the ``<div
  168. class="main_content">`` div:
  169. .. code-block:: xml
  170. :linenos:
  171. <span tal:condition="logged_in">
  172. <a href="${request.application_url}/logout">Logout</a>
  173. </span>
  174. Viewing the Application in a Browser
  175. ------------------------------------
  176. We can finally examine our application in a browser. The views we'll
  177. try are as follows:
  178. - Visiting ``http://localhost:6543/`` in a browser invokes the
  179. ``view_wiki`` view. This always redirects to the ``view_page`` view
  180. of the FrontPage page object. It is executable by any user.
  181. - Visiting ``http://localhost:6543/FrontPage`` in a browser invokes
  182. the ``view_page`` view of the FrontPage page object.
  183. - Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
  184. invokes the edit view for the FrontPage object. It is executable by
  185. only the ``editor`` user. If a different user (or the anonymous
  186. user) invokes it, a login form will be displayed. Supplying the
  187. credentials with the username ``editor``, password ``editor`` will
  188. display the edit page form.
  189. - Visiting ``http://localhost:6543/add_page/SomePageName`` in a
  190. browser invokes the add view for a page. It is executable by only
  191. the ``editor`` user. If a different user (or the anonymous user)
  192. invokes it, a login form will be displayed. Supplying the
  193. credentials with the username ``editor``, password ``editor`` will
  194. display the edit page form.
  195. Seeing Our Changes To ``views.py`` and our Templates
  196. ----------------------------------------------------
  197. Our ``views.py`` module will look something like this when we're done:
  198. .. literalinclude:: src/authorization/tutorial/views.py
  199. :linenos:
  200. :language: python
  201. Our ``edit.pt`` template will look something like this when we're done:
  202. .. literalinclude:: src/authorization/tutorial/templates/edit.pt
  203. :linenos:
  204. :language: xml
  205. Our ``view.pt`` template will look something like this when we're done:
  206. .. literalinclude:: src/authorization/tutorial/templates/view.pt
  207. :linenos:
  208. :language: xml
  209. Revisiting the Application
  210. ---------------------------
  211. When we revisit the application in a browser, and log in (as a result
  212. of hitting an edit or add page and submitting the login form with the
  213. ``editor`` credentials), we'll see a Logout link in the upper right
  214. hand corner. When we click it, we're logged out, and redirected back
  215. to the front page.