From 3324e5534289b530a571698519dfe20738cc5610 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Tue, 13 Mar 2012 12:41:50 -0700 Subject: Improved the Authorization chapter - Added a summary of the steps - Fixed a couple of typos --- docs/tutorials/wiki2/authorization.rst | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 5c60640b7..fb80c3536 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -12,14 +12,19 @@ application to allow only people whom possess a specific username (`editor`) to add and edit wiki pages but we'll continue allowing anyone with access to the server to view pages. -To do so, we'll add an :term:`authentication policy` and an -:term:`authorization policy`. We'll also add a ``security.py`` module, -create a :term:`root factory` with an :term:`ACL`, and add :term:`permission` -declarations to the ``edit_page`` and ``add_page`` views. Then we'll add -``login`` and ``logout`` views, and modify the existing views to make them -return a ``logged_in`` flag to the renderer. Finally, we will add a -``login.pt`` template and change the existing ``view.pt`` and ``edit.pt`` to -show a "Logout" link when not logged in. +We will do the following steps: + +* Add a :term:`root factory` with an :term:`ACL` (``models.py``). +* Add an :term:`authentication policy` and an :term:`authorization policy` + (``__init__.py``). +* Add an authentication policy callback (new ``security.py`` module). +* Add :term:`permission` declarations to the ``edit_page`` and ``add_page`` + views (``views.py``). +* Add ``login`` and ``logout`` views (``views.py``). +* Make the existing views return a ``logged_in`` flag to the renderer (``views.py``). +* Add a login template (new ``login.pt``). +* Add a "Logout" link to be shown when logged in and viewing or editing a page + (``view.pt``, ``edit.pt``). The source code for this tutorial stage can be browsed at `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/ @@ -98,7 +103,7 @@ Then, we'll add those policies to the configuration: :linenos: :language: python -Note that that the +Note that the :class:`pyramid.authentication.AuthTktAuthenticationPolicy` constructor accepts two arguments: ``secret`` and ``callback``. ``secret`` is a string representing an encryption key used by the "authentication ticket" machinery @@ -248,7 +253,7 @@ Adding the ``login.pt`` Template -------------------------------- Add a ``login.pt`` template to your templates directory. It's -referred to within the login view we just added to ``login.py``. +referred to within the login view we just added to ``views.py``. .. literalinclude:: src/authorization/tutorial/templates/login.pt :language: xml -- cgit v1.2.3 From cd475e28d716ad4621b832cf1dc888cfcc4bedce Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Tue, 13 Mar 2012 14:17:23 -0700 Subject: Sync section titles with the summary --- docs/tutorials/wiki2/authorization.rst | 69 ++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index fb80c3536..aadd5097f 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -18,9 +18,9 @@ We will do the following steps: * Add an :term:`authentication policy` and an :term:`authorization policy` (``__init__.py``). * Add an authentication policy callback (new ``security.py`` module). +* Add ``login`` and ``logout`` views (``views.py``). * Add :term:`permission` declarations to the ``edit_page`` and ``add_page`` views (``views.py``). -* Add ``login`` and ``logout`` views (``views.py``). * Make the existing views return a ``logged_in`` flag to the renderer (``views.py``). * Add a login template (new ``login.pt``). * Add a "Logout" link to be shown when logged in and viewing or editing a page @@ -30,15 +30,16 @@ The source code for this tutorial stage can be browsed at `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/ `_. -Changing ``__init__.py`` For Authorization -------------------------------------------- - -We're going to be making several changes to our ``__init__.py`` file which -will help us configure an authorization policy. - Adding A Root Factory ~~~~~~~~~~~~~~~~~~~~~ +Open ``models.py`` and add the following statements: + +.. literalinclude:: src/authorization/tutorial/models.py + :lines: 1-4,35-39 + :linenos: + :language: python + We're going to start to use a custom :term:`root factory` within our ``__init__.py`` file. The objects generated by the root factory will be used as the :term:`context` of each request to our application. We do this to @@ -49,14 +50,8 @@ our contexts, we can begin to make use of the declarative security features of :app:`Pyramid`. We'll modify our ``__init__.py``, passing in a :term:`root factory` to our -:term:`Configurator` constructor. We'll point it at a new class we create -inside our ``models.py`` file. Add the following statements to your -``models.py`` file: - -.. literalinclude:: src/authorization/tutorial/models.py - :lines: 1-4,35-39 - :linenos: - :language: python +:term:`Configurator` constructor. We'll point it at the new class we created +inside our ``models.py`` file. The ``RootFactory`` class we've just added will be used by :app:`Pyramid` to construct a ``context`` object. The context is attached to the request @@ -78,8 +73,11 @@ information about what an :term:`ACL` represents. We'll pass the ``RootFactory`` we created in the step above in as the ``root_factory`` argument to a :term:`Configurator`. -Configuring an Authorization Policy -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Add an Authorization Policy and an Authentication Policy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We're going to be making several changes to our ``__init__.py`` file which +will help us configure an authorization policy. For any :app:`Pyramid` application to perform authorization, we need to add a ``security.py`` module (we'll do that shortly) and we'll need to change our @@ -87,16 +85,16 @@ For any :app:`Pyramid` application to perform authorization, we need to add a :term:`authorization policy` which uses the ``security.py`` file for a *callback*. -We'll change our ``__init__.py`` file to enable an -``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to enable -declarative security checking. We need to import the new policies: +We'll enable an ``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` +to implement declarative security checking. Open ``tutorial/__init__.py`` and +add these import statements: .. literalinclude:: src/authorization/tutorial/__init__.py :lines: 2-3,7 :linenos: :language: python -Then, we'll add those policies to the configuration: +Now add those policies to the configuration: .. literalinclude:: src/authorization/tutorial/__init__.py :lines: 16-22 @@ -112,7 +110,7 @@ represented by this policy: it is required. The ``callback`` is a haven't added that module yet, but we're about to. Viewing Your Changes -~~~~~~~~~~~~~~~~~~~~ +-------------------- When we're done configuring a root factory, adding a authentication and authorization policies, and adding routes for ``/login`` and ``/logout``, @@ -122,11 +120,12 @@ your application's ``__init__.py`` will look like this: :linenos: :language: python -Adding ``security.py`` ----------------------- +Adding an authentication policy callback +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Add a ``security.py`` module within your package (in the same directory as -:file:`__init__.py`, :file:`views.py`, etc.) with the following content: +Add a ``tutorial/security.py`` module within your package (in the same +directory as :file:`__init__.py`, :file:`views.py`, etc.) with the +following content: .. literalinclude:: src/authorization/tutorial/security.py :linenos: @@ -152,7 +151,7 @@ and the permission associated with the ``add_page`` and ``edit_page`` views, the ``editor`` user should be able to add and edit pages. Adding Login and Logout Views ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To our ``views.py`` we'll add a ``login`` view callable which renders a login form and processes the post from the login form, checking credentials. @@ -203,7 +202,10 @@ head of the ``views.py`` file: :language: python Changing Existing Views ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ + +Add permision declarations +-------------------------- Then we need to change each of our ``view_page``, ``edit_page`` and ``add_page`` view callables in ``views.py``. Within each of these views, @@ -216,6 +218,9 @@ something like this to each view body: from pyramid.security import authenticated_userid logged_in = authenticated_userid(request) +Return a logged_in flag to the renderer +--------------------------------------- + We'll then change the return value of these views to pass the `resulting `logged_in`` value to the template, e.g.: @@ -250,7 +255,7 @@ a user whom is a member of the group named ``group:editors`` will able to invoke the views associated with the ``add_page`` or ``edit_page`` routes. Adding the ``login.pt`` Template --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add a ``login.pt`` template to your templates directory. It's referred to within the login view we just added to ``views.py``. @@ -258,8 +263,8 @@ referred to within the login view we just added to ``views.py``. .. literalinclude:: src/authorization/tutorial/templates/login.pt :language: xml -Change ``view.pt`` and ``edit.pt`` ----------------------------------- +Add a "Logout" link when logged in +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We'll also need to change our ``edit.pt`` and ``view.pt`` templates to display a "Logout" link if someone is logged in. This link will @@ -294,7 +299,7 @@ Our ``view.pt`` template will look something like this when we're done: :language: xml Viewing the Application in a Browser ------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We can finally examine our application in a browser. The views we'll try are as follows: -- cgit v1.2.3 From e5958645c42b18c269f9da627c623fa686b8e336 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Tue, 13 Mar 2012 15:18:09 -0700 Subject: Improved the Authorization chapter - Highlighted the added lines in the listings - Simplified 'Viewing the application in a browser' and added link to Starting the application --- docs/tutorials/wiki2/authorization.rst | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index aadd5097f..b76fd9a6c 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -118,6 +118,7 @@ your application's ``__init__.py`` will look like this: .. literalinclude:: src/authorization/tutorial/__init__.py :linenos: + :emphasize-lines: 2-3,7,16-18,20-22,25-26 :language: python Adding an authentication policy callback @@ -280,46 +281,56 @@ class="app-welcome align-right">`` div: Seeing Our Changes To ``views.py`` and our Templates ----------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Our ``views.py`` module will look something like this when we're done: .. literalinclude:: src/authorization/tutorial/views.py :linenos: + :emphasize-lines: 11,14-18,56,59,71,74,89-115,117-121 :language: python +(Only the highlighted lines need to be added.) + Our ``edit.pt`` template will look something like this when we're done: .. literalinclude:: src/authorization/tutorial/templates/edit.pt + :emphasize-lines: 41-43 :language: xml +(Only the highlighted lines need to be added.) + Our ``view.pt`` template will look something like this when we're done: .. literalinclude:: src/authorization/tutorial/templates/view.pt + :emphasize-lines: 41-43 :language: xml +(Only the highlighted lines need to be added.) + Viewing the Application in a Browser ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We can finally examine our application in a browser. The views we'll -try are as follows: +We can finally examine our application in a browser (See +:ref:`wiki2-start-the-application`). Launch a browser and visit +each of the following URLs, check that the result is as expected: -- Visiting ``http://localhost:6543/`` in a browser invokes the +- ``http://localhost:6543/`` invokes the ``view_wiki`` view. This always redirects to the ``view_page`` view of the FrontPage page object. It is executable by any user. -- Visiting ``http://localhost:6543/FrontPage`` in a browser invokes +- ``http://localhost:6543/FrontPage`` invokes the ``view_page`` view of the FrontPage page object. -- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser +- ``http://localhost:6543/edit_page/FrontPage`` invokes the edit view for the FrontPage object. It is executable by only the ``editor`` user. If a different user (or the anonymous user) invokes it, a login form will be displayed. Supplying the credentials with the username ``editor``, password ``editor`` will display the edit page form. -- Visiting ``http://localhost:6543/add_page/SomePageName`` in a - browser invokes the add view for a page. It is executable by only +- ``http://localhost:6543/add_page/SomePageName`` + invokes the add view for a page. It is executable by only the ``editor`` user. If a different user (or the anonymous user) invokes it, a login form will be displayed. Supplying the credentials with the username ``editor``, password ``editor`` will -- cgit v1.2.3