Merge branch 'master' of github.com:Pylons/pyramid

1 files changed, 112 insertions, 0 deletions

diff --git a/docs/quick_tutorial/authorization.rst b/docs/quick_tutorial/authorization.rst
new file mode 100644
index 000000000..6b10d3409
--- /dev/null
+++ b/docs/quick_tutorial/authorization.rst
@@ -0,0 +1,112 @@
+===========================================
+21: Protecting Resources With Authorization
+===========================================
+
+Assign security statements to resources describing the permissions
+required to perform an operation.
+
+Background
+==========
+
+Our application has URLs that allow people to add/edit/delete content
+via a web browser. Time to add security to the application. Let's
+protect our add/edit views to require a login (username of
+``editor`` and password of ``editor``.) We will allow the other views
+to continue working without a password.
+
+Objectives
+==========
+
+- Introduce the Pyramid concepts of authentication, authorization,
+  permissions, and access control lists (ACLs)
+
+- Make a :term:`root factory` that returns an instance of our
+  class for the top of the application
+
+- Assign security statements to our root resource
+
+- Add a permissions predicate on a view
+
+- Provide a :term:`Forbidden view` to handle visiting a URL without
+  adequate permissions
+
+Steps
+=====
+
+#. We are going to use the authentication step as our starting point:
+
+   .. code-block:: bash
+
+    $ cd ..; cp -r authentication authorization; cd authorization
+    $ $VENV/bin/python setup.py develop
+
+#. Start by changing ``authorization/tutorial/__init__.py`` to
+   specify a root factory to the :term:`configurator`:
+
+   .. literalinclude:: authorization/tutorial/__init__.py
+    :linenos:
+
+#. That means we need to implement
+   ``authorization/tutorial/resources.py``
+
+   .. literalinclude:: authorization/tutorial/resources.py
+    :linenos:
+
+#. Change ``authorization/tutorial/views.py`` to require the ``edit``
+   permission on the ``hello`` view and implement the forbidden view:
+
+   .. literalinclude:: authorization/tutorial/views.py
+    :linenos:
+
+#. Run your Pyramid application with:
+
+   .. code-block:: bash
+
+    $ $VENV/bin/pserve development.ini --reload
+
+#. Open http://localhost:6543/ in a browser.
+
+#. If you are still logged in, click the "Log Out" link.
+
+#. Visit http://localhost:6543/howdy in a browser. You should be
+   asked to login.
+
+Analysis
+========
+
+This simple tutorial step can be boiled down to the following:
+
+- A view can require a *permission* (``edit``)
+
+- The context for our view (the ``Root``) has an access control list
+  (ACL)
+
+- This ACL says that the ``edit`` permission is available on ``Root``
+  to the ``group:editors`` *principal*
+
+- The registered ``groupfinder`` answers whether a particular user
+  (``editor``) has a particular group (``group:editors``)
+
+In summary: ``hello`` wants ``edit`` permission, ``Root`` says
+``group:editors`` has ``edit`` permission.
+
+Of course, this only applies on ``Root``. Some other part of the site
+(a.k.a. *context*) might have a different ACL.
+
+If you are not logged in and visit ``/hello``, you need to get
+shown the login screen. How does Pyramid know what is the login page to
+use? We explicitly told Pyramid that the ``login`` view should be used
+by decorating the view with ``@forbidden_view_config``.
+
+Extra Credit
+============
+
+#. Perhaps you would like experience of not having enough permissions
+   (forbidden) to be richer. How could you change this?
+
+#. Perhaps we want to store security statements in a database and
+   allow editing via a browser. How might this be done?
+
+#. What if we want different security statements on different kinds of
+   objects? Or on the same kinds of objects, but in different parts of a
+   URL hierarchy?