From ead3c7e169dbac62f97cbaffc15f3c40430b70ea Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 19 Jul 2011 08:26:05 -0400 Subject: - Fixed two typos in wiki2 (SQLA + URL Dispatch) tutorial. --- docs/tutorials/wiki2/authorization.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 76ce4b83f..df5e228fd 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -54,7 +54,7 @@ inside our ``models.py`` file. Add the following statements to your ``models.py`` file: .. literalinclude:: src/authorization/tutorial/models.py - :lines: 3-4,45-49 + :lines: 3-4,45-50 :linenos: :language: python @@ -228,7 +228,7 @@ We'll then change the return value of these views to pass the `resulting .. code-block:: python :linenos: - return dict(page = context, + return dict(page = page, content = content, logged_in = logged_in, edit_url = edit_url) -- cgit v1.2.3 From 5edd54f05b05330fa6e899a1bb1650cc7a2df33c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 27 Nov 2011 04:08:20 -0500 Subject: - The SQLAlchemy Wiki tutorial has been updated. It now uses ``@view_config`` decorators and an explicit database population script. Closes #359. --- docs/tutorials/wiki2/authorization.rst | 153 +++++++++++++++++---------------- 1 file changed, 78 insertions(+), 75 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index df5e228fd..ab04ea405 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -4,27 +4,22 @@ Adding Authorization ==================== -Our application currently allows anyone with access to the server to -view, edit, and add pages to our wiki. For purposes of demonstration -we'll change our 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. -:app:`Pyramid` provides facilities for :term:`authorization` and -:term:`authentication`. We'll make use of both features to provide security -to our application. - -We will add an :term:`authentication policy` and an -:term:`authorization policy` to our :term:`application -registry`, 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 will 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. +:app:`Pyramid` provides facilities for :term:`authentication` and +:term:`authorization`. We'll make use of both features to provide security +to our application. Our application currently allows anyone with access to +the server to view, edit, and add pages to our wiki. We'll change our +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. The source code for this tutorial stage can be browsed at `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/ @@ -54,7 +49,7 @@ inside our ``models.py`` file. Add the following statements to your ``models.py`` file: .. literalinclude:: src/authorization/tutorial/models.py - :lines: 3-4,45-50 + :lines: 1-4,35-39 :linenos: :language: python @@ -92,14 +87,14 @@ We'll change our ``__init__.py`` file to enable an declarative security checking. We need to import the new policies: .. literalinclude:: src/authorization/tutorial/__init__.py - :lines: 2-3,8 + :lines: 2-3,7 :linenos: :language: python Then, we'll add those policies to the configuration: .. literalinclude:: src/authorization/tutorial/__init__.py - :lines: 15-21 + :lines: 16-22 :linenos: :language: python @@ -111,49 +106,12 @@ represented by this policy: it is required. The ``callback`` is a ``groupfinder`` function in the current directory's ``security.py`` file. We haven't added that module yet, but we're about to. -We'll also change ``__init__.py``, adding a call to -:meth:`pyramid.config.Configurator.add_view` that points at our ``login`` -:term:`view callable`. This is also known as a :term:`forbidden view`: - -.. literalinclude:: src/authorization/tutorial/__init__.py - :lines: 25,41-43 - :linenos: - :language: python - -A forbidden view configures our newly created login view to show up when -:app:`Pyramid` detects that a view invocation can not be authorized. - -A ``logout`` :term:`view callable` will allow users to log out later: - -.. literalinclude:: src/authorization/tutorial/__init__.py - :lines: 26,34 - :linenos: - :language: python - -We'll also add ``permission`` arguments with the value ``edit`` to the -``edit_page`` and ``add_page`` views. This indicates that the view -callables which these views reference cannot be invoked without the -authenticated user possessing the ``edit`` permission with respect to the -current context. - -.. literalinclude:: src/authorization/tutorial/__init__.py - :lines: 37-40 - :linenos: - :language: python - -Adding these ``permission`` arguments causes Pyramid to make the -assertion that only users who possess the effective ``edit`` permission at -the time of the request may invoke those two views. We've granted the -``group:editors`` principal the ``edit`` permission at the root model via its -ACL, so only the 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. - Viewing Your Changes ~~~~~~~~~~~~~~~~~~~~ -When we're done configuring a root factory, adding an authorization policy, -and adding views, your application's ``__init__.py`` will look like this: +When we're done configuring a root factory, adding a authentication and +authorization policies, and adding routes for ``/login`` and ``/logout``, +your application's ``__init__.py`` will look like this: .. literalinclude:: src/authorization/tutorial/__init__.py :linenos: @@ -191,30 +149,54 @@ views, the ``editor`` user should be able to add and edit pages. Adding Login and Logout Views ----------------------------- -We'll add a ``login`` view callable which renders a login form and -processes the post from the login form, checking credentials. +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. We'll also add a ``logout`` view callable to our application and provide a link to it. This view will clear the credentials of the logged in user and redirect back to the front page. -We'll add a different file (for presentation convenience) to add login -and the logout view callables. Add a file named ``login.py`` to your -application (in the same directory as ``views.py``) with the following -content: +The ``login`` view callable will look something like this: -.. literalinclude:: src/authorization/tutorial/login.py +.. literalinclude:: src/authorization/tutorial/views.py + :pyobject: login :linenos: :language: python +The ``logout`` view callable will look something like this: + +.. literalinclude:: src/authorization/tutorial/views.py + :pyobject: logout + :linenos: + :language: python + +The ``login`` view callable is decorated with two ``@view_config`` +decorators, one which associates it with the ``login`` route, the other which +associates it with the ``HTTPForbidden`` context. The one which associates +it with the ``login`` route makes it visible when we visit ``/login``. The +one which associates it with the ``HTTPForbidden`` context makes it the +:term:`forbidden view`. The forbidden view is displayed whenever Pyramid or +your application raises an HTTPForbidden exception. In this case, we'll be +relying on the forbidden view to show the login form whenver someone attempts +to execute an action which they're not yet authorized to perform. + +The ``logout`` view callable is decorated with a ``@view_config`` decorator +which associates it with the ``logout`` route. This makes it visible when we +visit ``/login``. + +We'll need to import some stuff to service the needs of these two functions: +the ``HTTPForbidden`` exception, a number of values from the +``pyramid.security`` module, and a value from our newly added +``tutorial.security`` package. + Changing Existing Views ----------------------- Then we need to change each of our ``view_page``, ``edit_page`` and -``add_page`` views in ``views.py`` to pass a "logged in" parameter to its -template. We'll add something like this to each view body: +``add_page`` view callables in ``views.py``. Within each of these views, +we'll need to pass a "logged in" parameter to its template. We'll add +something like this to each view body: -.. ignore-next-block .. code-block:: python :linenos: @@ -224,7 +206,6 @@ template. We'll add something like this to each view body: We'll then change the return value of these views to pass the `resulting `logged_in`` value to the template, e.g.: -.. ignore-next-block .. code-block:: python :linenos: @@ -233,6 +214,28 @@ We'll then change the return value of these views to pass the `resulting logged_in = logged_in, edit_url = edit_url) +We'll also need to add a ``permission`` value to the ``@view_config`` +decorator for each of the ``add_page`` and ``edit_page`` view callables. For +each, we'll add ``permission='edit'``, for example: + +.. code-block:: python + :linenos: + + @view_config(route_name='edit_page', renderer='templates/edit.pt', + permission='edit') + +See the ``permission='edit'`` we added there? This indicates that the view +callables which these views reference cannot be invoked without the +authenticated user possessing the ``edit`` permission with respect to the +current :term:`context`. + +Adding these ``permission`` arguments causes Pyramid to make the assertion +that only users who possess the effective ``edit`` permission at the time of +the request may invoke those two views. We've granted the ``group:editors`` +principal the ``edit`` permission at the root model via its ACL, so only the +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 -------------------------------- -- cgit v1.2.3 From d1ad7044480901123b9c744b686b579491c36683 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 29 Jan 2012 13:32:45 -0500 Subject: show decorators along with view callables, fixes #393 --- docs/tutorials/wiki2/authorization.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index ab04ea405..56237a1b9 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -159,14 +159,14 @@ logged in user and redirect back to the front page. The ``login`` view callable will look something like this: .. literalinclude:: src/authorization/tutorial/views.py - :pyobject: login + :lines: 90-116 :linenos: :language: python The ``logout`` view callable will look something like this: .. literalinclude:: src/authorization/tutorial/views.py - :pyobject: logout + :lines: 118-122 :linenos: :language: python -- cgit v1.2.3 From c6a299ad7159ffcabe201fa79f485c388d837971 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 14 Feb 2012 05:57:06 -0500 Subject: - Don't create a ``session`` instance in SQLA Wiki tutorial, use raw ``DBSession`` instead (this is more common in real SQLA apps). --- docs/tutorials/wiki2/authorization.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 56237a1b9..b1d0bf37c 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -159,14 +159,14 @@ logged in user and redirect back to the front page. The ``login`` view callable will look something like this: .. literalinclude:: src/authorization/tutorial/views.py - :lines: 90-116 + :lines: 87-113 :linenos: :language: python The ``logout`` view callable will look something like this: .. literalinclude:: src/authorization/tutorial/views.py - :lines: 118-122 + :lines: 115-119 :linenos: :language: python -- cgit v1.2.3 From a7fe30f0eabd6c6fd3bcc910faa41720a75056de Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 22 Feb 2012 19:24:09 -0500 Subject: - New API: ``pyramid.config.Configurator.add_forbidden_view``. This is a wrapper for ``pyramid.Config.configurator.add_view`` which does the right thing about permissions. It should be preferred over calling ``add_view`` directly with ``context=HTTPForbidden`` as was previously recommended. - New API: ``pyramid.view.forbidden_view_config``. This is a decorator constructor like ``pyramid.view.view_config`` that calls ``pyramid.config.Configurator.add_forbidden_view`` when scanned. It should be preferred over using ``pyramid.view.view_config`` with ``context=HTTPForbidden`` as was previously recommended. - Updated the "Creating a Not Forbidden View" section of the "Hooks" chapter, replacing explanations of registering a view using ``add_view`` or ``view_config`` with ones using ``add_forbidden_view`` or ``forbidden_view_config``. - Updated all tutorials to use ``pyramid.view.forbidden_view_config`` rather than ``pyramid.view.view_config`` with an HTTPForbidden context. --- docs/tutorials/wiki2/authorization.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index b1d0bf37c..900bf0975 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -159,33 +159,35 @@ logged in user and redirect back to the front page. The ``login`` view callable will look something like this: .. literalinclude:: src/authorization/tutorial/views.py - :lines: 87-113 + :lines: 89-115 :linenos: :language: python The ``logout`` view callable will look something like this: .. literalinclude:: src/authorization/tutorial/views.py - :lines: 115-119 + :lines: 117-121 :linenos: :language: python -The ``login`` view callable is decorated with two ``@view_config`` -decorators, one which associates it with the ``login`` route, the other which -associates it with the ``HTTPForbidden`` context. The one which associates -it with the ``login`` route makes it visible when we visit ``/login``. The -one which associates it with the ``HTTPForbidden`` context makes it the -:term:`forbidden view`. The forbidden view is displayed whenever Pyramid or -your application raises an HTTPForbidden exception. In this case, we'll be -relying on the forbidden view to show the login form whenver someone attempts -to execute an action which they're not yet authorized to perform. +The ``login`` view callable is decorated with two decorators, a +``@view_config`` decorators, which associates it with the ``login`` route, +the other a ``@forbidden_view_config`` decorator which turns it in to an +:term:`exception view` when Pyramid raises a +:class:`pyramid.httpexceptions.HTTPForbidden` exception. The one which +associates it with the ``login`` route makes it visible when we visit +``/login``. The other one makes it a :term:`forbidden view`. The forbidden +view is displayed whenever Pyramid or your application raises an +HTTPForbidden exception. In this case, we'll be relying on the forbidden +view to show the login form whenver someone attempts to execute an action +which they're not yet authorized to perform. The ``logout`` view callable is decorated with a ``@view_config`` decorator which associates it with the ``logout`` route. This makes it visible when we visit ``/login``. We'll need to import some stuff to service the needs of these two functions: -the ``HTTPForbidden`` exception, a number of values from the +the ``pyramid.view.forbidden_view_config`` class, a number of values from the ``pyramid.security`` module, and a value from our newly added ``tutorial.security`` package. -- cgit v1.2.3 From 533c89ebe807f02f5eae3240e770864b21f78168 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Mon, 12 Mar 2012 17:57:13 -0700 Subject: Clarify two steps in the SQL wiki tutorial - Highlight the added or changed lines --- docs/tutorials/wiki2/authorization.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 900bf0975..5c60640b7 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -189,7 +189,13 @@ visit ``/login``. We'll need to import some stuff to service the needs of these two functions: the ``pyramid.view.forbidden_view_config`` class, a number of values from the ``pyramid.security`` module, and a value from our newly added -``tutorial.security`` package. +``tutorial.security`` package. Add the following import statements to the +head of the ``views.py`` file: + +.. literalinclude:: src/authorization/tutorial/views.py + :lines: 9-18,24-25 + :linenos: + :language: python Changing Existing Views ----------------------- -- cgit v1.2.3 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(-) (limited to 'docs/tutorials/wiki2/authorization.rst') 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(-) (limited to 'docs/tutorials/wiki2/authorization.rst') 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(-) (limited to 'docs/tutorials/wiki2/authorization.rst') 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 From 692fd6816616ed5b3cb9ef3c0f2c6eff2276da93 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Mar 2012 00:05:06 -0400 Subject: master->1.3-branch --- docs/tutorials/wiki2/authorization.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index b76fd9a6c..a40cbdb3a 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -27,8 +27,8 @@ We will do the following steps: (``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/ -`_. +`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/authorization/ +`_. Adding A Root Factory ~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From b3e608bac815a7d3fc639d78ec38edc5f97df859 Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Sat, 17 Mar 2012 09:27:13 -0700 Subject: Improve text of SQLAlchemy wiki tutorial. A mixture of typo fixes and wording improvements. --- docs/tutorials/wiki2/authorization.rst | 68 +++++++++++++++++----------------- 1 file changed, 35 insertions(+), 33 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index b76fd9a6c..338ec54be 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -7,8 +7,8 @@ Adding Authorization :app:`Pyramid` provides facilities for :term:`authentication` and :term:`authorization`. We'll make use of both features to provide security to our application. Our application currently allows anyone with access to -the server to view, edit, and add pages to our wiki. We'll change our -application to allow only people whom possess a specific username (`editor`) +the server to view, edit, and add pages to our wiki. We'll change that +to allow only people who 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. @@ -41,13 +41,12 @@ Open ``models.py`` and add the following statements: :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 -allow :app:`Pyramid` declarative security to work properly. The context -object generated by the root factory during a request will be decorated with -security declarations. When we begin to use a custom root factory to generate -our contexts, we can begin to make use of the declarative security features -of :app:`Pyramid`. +``__init__.py`` file. The objects generated by the root factory will +be used as the :term:`context` of each request to our application. +Those context objects will be decorated with security +declarations. When we use a custom root factory to generate +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 the new class we created @@ -65,7 +64,7 @@ to a context is interpreted specially by :app:`Pyramid` as an access control list during view callable execution. See :ref:`assigning_acls` for more information about what an :term:`ACL` represents. -.. note: Although we don't use the functionality here, the ``factory`` used +.. note:: Although we don't use the functionality here, the ``factory`` used to create route contexts may differ per-route as opposed to globally. See the ``factory`` argument to :meth:`pyramid.config.Configurator.add_route` for more info. @@ -147,9 +146,10 @@ We've given the ``editor`` user membership to the ``group:editors`` by mapping him to this group in the ``GROUPS`` data structure (``GROUPS = {'editor':['group:editors']}``). Since the ``groupfinder`` function consults the ``GROUPS`` data structure, this will mean that, as a -result of the ACL attached to the root returned by the root factory, -and the permission associated with the ``add_page`` and ``edit_page`` -views, the ``editor`` user should be able to add and edit pages. +result of the ACL attached to the :term:`context` object returned by +the root factory, 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -176,20 +176,20 @@ The ``logout`` view callable will look something like this: :language: python The ``login`` view callable is decorated with two decorators, a -``@view_config`` decorators, which associates it with the ``login`` route, -the other a ``@forbidden_view_config`` decorator which turns it in to an -:term:`exception view` when Pyramid raises a -:class:`pyramid.httpexceptions.HTTPForbidden` exception. The one which -associates it with the ``login`` route makes it visible when we visit -``/login``. The other one makes it a :term:`forbidden view`. The forbidden -view is displayed whenever Pyramid or your application raises an -HTTPForbidden exception. In this case, we'll be relying on the forbidden -view to show the login form whenver someone attempts to execute an action -which they're not yet authorized to perform. +``@view_config`` decorator, which associates it with the ``login`` +route, and a ``@forbidden_view_config`` decorator which turns it in to +an :term:`exception view`. The one which associates it with the +``login`` route makes it visible when we visit ``/login``. The other +one makes it a :term:`forbidden view`. The forbidden view is +displayed whenever Pyramid or your application raises an +:class:`pyramid.httpexceptions.HTTPForbidden` exception. In this +case, we'll be relying on the forbidden view to show the login form +whenver someone attempts to execute an action which they're not yet +authorized to perform. The ``logout`` view callable is decorated with a ``@view_config`` decorator which associates it with the ``logout`` route. This makes it visible when we -visit ``/login``. +visit ``/logout``. We'll need to import some stuff to service the needs of these two functions: the ``pyramid.view.forbidden_view_config`` class, a number of values from the @@ -222,8 +222,8 @@ something like this to each view body: 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.: +We'll then change the return value of these views to pass the resulting +``logged_in`` value to the template, e.g.: .. code-block:: python :linenos: @@ -248,12 +248,14 @@ callables which these views reference cannot be invoked without the authenticated user possessing the ``edit`` permission with respect to the current :term:`context`. -Adding these ``permission`` arguments causes Pyramid to make the assertion -that only users who possess the effective ``edit`` permission at the time of -the request may invoke those two views. We've granted the ``group:editors`` -principal the ``edit`` permission at the root model via its ACL, so only the -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 these ``permission`` arguments causes Pyramid to make the +assertion that only users who possess the effective ``edit`` +permission at the time of the request may invoke those two views. +We've granted the ``group:editors`` :term:`principal` the ``edit`` +permission in the :term:`root factory` via its ACL, so only a user who +is a member of the group named ``group:editors`` will be able to +invoke the views associated with the ``add_page`` or ``edit_page`` +routes. Adding the ``login.pt`` Template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -322,7 +324,7 @@ each of the following URLs, check that the result is as expected: - ``http://localhost:6543/FrontPage`` invokes the ``view_page`` view of the FrontPage page object. -- ``http://localhost:6543/edit_page/FrontPage`` +- ``http://localhost:6543/FrontPage/edit_page`` 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 -- cgit v1.2.3 From ef501bb1618e12ec9f0a57ba5cf873616f7c440a Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Sat, 17 Mar 2012 10:12:34 -0700 Subject: Fix typos. --- docs/tutorials/wiki2/authorization.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 338ec54be..c695c7da4 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -64,10 +64,12 @@ to a context is interpreted specially by :app:`Pyramid` as an access control list during view callable execution. See :ref:`assigning_acls` for more information about what an :term:`ACL` represents. -.. note:: Although we don't use the functionality here, the ``factory`` used - to create route contexts may differ per-route as opposed to globally. See - the ``factory`` argument to - :meth:`pyramid.config.Configurator.add_route` for more info. +.. note:: + + Although we don't use the functionality here, the ``factory`` used + to create route contexts may differ per-route as opposed to globally. See + the ``factory`` argument to + :meth:`pyramid.config.Configurator.add_route` for more info. We'll pass the ``RootFactory`` we created in the step above in as the ``root_factory`` argument to a :term:`Configurator`. -- cgit v1.2.3 From f67963b501d426401f3543ea3429f15236399567 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Mon, 26 Mar 2012 18:53:19 -0600 Subject: Mark line with yellow in SQL wiki - issue #510 --- docs/tutorials/wiki2/authorization.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 8c1c50ff6..88698eebf 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -291,7 +291,7 @@ 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 + :emphasize-lines: 11,14-18,56,59,71,74,86,89-115,117-121 :language: python (Only the highlighted lines need to be added.) -- cgit v1.2.3 From 611582fafe01261777289bf3bd71a83413f977ab Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Sun, 1 Apr 2012 08:21:39 -0500 Subject: Improved Adding Authorization in SQL wiki tutorial - Removed unneeded logged_in assignment - Moved up text to the corresponding section - Normalize references to view callables - Simplify text in Add permission declarations --- docs/tutorials/wiki2/authorization.rst | 73 ++++++++++++++-------------------- 1 file changed, 29 insertions(+), 44 deletions(-) (limited to 'docs/tutorials/wiki2/authorization.rst') diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 88698eebf..55c2ab7d3 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -204,79 +204,64 @@ head of the ``views.py`` file: :linenos: :language: python -Changing Existing Views -~~~~~~~~~~~~~~~~~~~~~~~ +Add permission declarations +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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, -we'll need to pass a "logged in" parameter to its template. We'll add -something like this to each view body: +Add a ``permission='edit'`` parameter to the ``@view_config`` +decorator for ``add_page()`` and ``edit_page()``, for example: .. code-block:: python :linenos: - from pyramid.security import authenticated_userid - logged_in = authenticated_userid(request) + @view_config(route_name='add_page', renderer='templates/edit.pt', + permission='edit') + +The result is that only users who possess the ``edit`` +permission at the time of the request may invoke those two views. + +We've granted the ``group:editors`` :term:`principal` the ``edit`` +permission in the :term:`root factory` via its ACL, so only a user who +is a member of the group named ``group:editors`` will be able to +invoke the views associated with the ``add_page`` or ``edit_page`` +routes. 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.: +Change the return value of the ``view_page``, +``edit_page`` and ``add_page`` view callables in ``views.py`` +to pass a ``logged_in`` value to the template, e.g.: .. code-block:: python :linenos: return dict(page = page, content = content, - logged_in = logged_in, + logged_in = authenticated_userid(request), edit_url = edit_url) -We'll also need to add a ``permission`` value to the ``@view_config`` -decorator for each of the ``add_page`` and ``edit_page`` view callables. For -each, we'll add ``permission='edit'``, for example: - -.. code-block:: python - :linenos: - - @view_config(route_name='edit_page', renderer='templates/edit.pt', - permission='edit') - -See the ``permission='edit'`` we added there? This indicates that the view -callables which these views reference cannot be invoked without the -authenticated user possessing the ``edit`` permission with respect to the -current :term:`context`. - -Adding these ``permission`` arguments causes Pyramid to make the -assertion that only users who possess the effective ``edit`` -permission at the time of the request may invoke those two views. -We've granted the ``group:editors`` :term:`principal` the ``edit`` -permission in the :term:`root factory` via its ACL, so only a user who -is a member of the group named ``group:editors`` will be 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``. +Create ``tutorial/tutorial/templates/login.pt`` with the following +content: .. literalinclude:: src/authorization/tutorial/templates/login.pt :language: xml +The above template is referred to within the login view we just +added to ``views.py``. + Add a "Logout" link when logged in ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We'll also need to change our ``edit.pt`` and ``view.pt`` templates to +We'll change our ``edit.pt`` and ``view.pt`` templates to display a "Logout" link if someone is logged in. This link will invoke the logout view. -To do so we'll add this to both templates within the ``