path: root/docs/tutorials/wiki2/authentication.rst

.. _wiki2_adding_authentication:

=====================
Adding authentication
=====================

:app:`Pyramid` provides facilities for :term:`authentication` and
:term:`authorization`. In this section we'll focus solely on the authentication
APIs to add login and logout functionality to our wiki.

We will implement authentication with the following steps:

* Add a :term:`security policy` (``security.py``).
* Add routes for ``/login`` and ``/logout`` (``routes.py``).
* Add login and logout views (``views/auth.py``).
* Add a login template (``login.jinja2``).
* Add "Login" and "Logout" links to every page based on the user's
  authenticated state (``layout.jinja2``).
* Make the existing views verify user state (``views/default.py``).
* Redirect to ``/login`` when a user is not logged in and is denied access to any of the views that require permission (``views/auth.py``).
* Show a custom "403 Forbidden" page if a logged in user is denied access to any views that require permission (``views/auth.py``).


Authenticating requests
-----------------------

The core of :app:`Pyramid` authentication is a :term:`security policy`
which is used to identify authentication information from a ``request``,
as well as handling the low-level login and logout operations required to
track users across requests (via cookies, headers, or whatever else you can
imagine).


Add the security policy
~~~~~~~~~~~~~~~~~~~~~~~

Update ``tutorial/security.py`` with the following content:

.. literalinclude:: src/authentication/tutorial/security.py
   :linenos:
   :language: python

Here we've defined a new security policy named ``MySecurityPolicy``, which is implementing most of the :class:`pyramid.interfaces.ISecurityPolicy` interface by tracking an :term:`identity` using a signed cookie implemented by :class:`pyramid.authentication.AuthTktCookieHelper` (lines 8-34).
The security policy outputs the authenticated ``tutorial.models.User`` object for the logged-in user as the :term:`identity`, which is available as ``request.identity``.

Our new :term:`security policy` defines how our application will remember, forget, and identify users.
It also handles authorization, which we'll cover in the next chapter (if you're wondering why we didn't implement the ``permits`` method yet).

Identifying the current user is done in a few steps:

#. :app:`Pyramid` invokes a method on the policy requesting identity, userid, or permission to perform an operation.

#. The policy starts by calling :meth:`pyramid.request.RequestLocalCache.get_or_create` to load the identity.

#. The ``MySecurityPolicy.load_identity`` method asks the cookie helper to pull the identity from the request.
   This value is ``None`` if the cookie is missing or the content cannot be verified.

#. The policy then translates the identity into a ``tutorial.models.User`` object by looking for a record in the database.
   This is a good spot to confirm that the user is actually allowed to access our application.
   For example, maybe they were marked deleted or banned and we should return ``None`` instead of the ``user`` object.

#. The result is stored in the ``identity_cache`` which ensures that subsequent invocations return the same identity object for the request.

Finally, :attr:`pyramid.request.Request.identity` contains either ``None`` or a ``tutorial.models.User`` instance.

Note the usage of the ``identity_cache`` is optional, but it has several advantages in most scenarios:

- It improves performance as the identity is necessary for many operations during the lifetime of a request.

- It provides consistency across method invocations to ensure the identity does not change while processing the request.

It is up to individual security policies and applications to determine the best approach with respect to caching.
Applications with long-running requests may want to avoid caching the identity, or tracking some extra metadata to re-verify it periodically against the authentication source.


Add new settings
~~~~~~~~~~~~~~~~

Our authentication policy is expecting a new setting, ``auth.secret``. Open
the file ``development.ini`` and add the highlighted line below:

.. literalinclude:: src/authentication/development.ini
   :lines: 19-21
   :emphasize-lines: 3
   :lineno-match:
   :language: ini

Finally, best practices tell us to use a different secret in each environment, so
open ``production.ini`` and add a different secret:

.. literalinclude:: src/authentication/production.ini
   :lines: 17-19
   :emphasize-lines: 3
   :lineno-match:
   :language: ini

And ``testing.ini``:

.. literalinclude:: src/authentication/testing.ini
   :lines: 17-19
   :emphasize-lines: 3
   :lineno-match:
   :language: ini


Add permission checks
~~~~~~~~~~~~~~~~~~~~~

:app:`Pyramid` has full support for declarative authorization, which we'll
cover in the next chapter. However, many people looking to get their feet wet
are just interested in authentication with some basic form of home-grown
authorization. We'll show below how to accomplish the simple security goals of
our wiki, now that we can track the logged-in state of users.

Remember our goals:

* Allow only ``editor`` and ``basic`` logged-in users to create new pages.
* Only allow ``editor`` users and the page creator (possibly a ``basic`` user)
  to edit pages.

Open the file ``tutorial/views/default.py`` and fix the following import:

.. literalinclude:: src/authentication/tutorial/views/default.py
   :lines: 3-7
   :lineno-match:
   :emphasize-lines: 2
   :language: python

Insert the highlighted line.

In the same file, now edit the ``edit_page`` view function:

.. literalinclude:: src/authentication/tutorial/views/default.py
   :lines: 49-68
   :lineno-match:
   :emphasize-lines: 9-11
   :language: python

Only the highlighted lines need to be changed.

If the user either is not logged in or the user is not the page's creator
*and* not an ``editor``, then we raise ``HTTPForbidden``.

In the same file, now edit the ``add_page`` view function:

.. literalinclude:: src/authentication/tutorial/views/default.py
   :lines: 70-
   :lineno-match:
   :emphasize-lines: 3-5,15
   :language: python

Only the highlighted lines need to be changed.

If the user either is not logged in or is not in the ``basic`` or ``editor`` roles, then we raise ``HTTPForbidden``, which will trigger our forbidden view to compute a response.
However, we will hook this later to redirect to the login page.
Also, now that we have ``request.identity``, we no longer have to hard-code the creator as the ``editor`` user, so we can finally drop that hack.

These simple checks should protect our views.


Login, logout
-------------

Now that we've got the ability to detect logged-in users, we need to add the
``/login`` and ``/logout`` views so that they can actually login and logout!


Add routes for ``/login`` and ``/logout``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Go back to ``tutorial/routes.py`` and add these two routes as highlighted:

.. literalinclude:: src/authentication/tutorial/routes.py
   :lines: 3-6
   :lineno-match:
   :emphasize-lines: 2-3
   :language: python

.. note:: The preceding lines must be added *before* the following
   ``view_page`` route definition:

   .. literalinclude:: src/authentication/tutorial/routes.py
      :lines: 6
      :lineno-match:
      :language: python

   This is because ``view_page``'s route definition uses a catch-all
   "replacement marker" ``/{pagename}`` (see :ref:`route_pattern_syntax`),
   which will catch any route that was not already caught by any route
   registered before it. Hence, for ``login`` and ``logout`` views to
   have the opportunity of being matched (or "caught"), they must be above
   ``/{pagename}``.


Add login, logout, and forbidden views
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a new file ``tutorial/views/auth.py``, and add the following code to it:

.. literalinclude:: src/authentication/tutorial/views/auth.py
   :linenos:
   :language: python

This code adds three new views to the application:

- The ``login`` view renders a login form and processes the post from the
  login form, checking credentials against our ``users`` table in the database.

  The check is done by first finding a ``User`` record in the database, then
  using our ``user.check_password`` method to compare the hashed passwords.

  At a privilege boundary we are sure to reset the CSRF token using :meth:`pyramid.csrf.new_csrf_token`.
  If we were using sessions we would want to invalidate that as well.

  If the credentials are valid, then we use our authentication policy to store
  the user's id in the response using :meth:`pyramid.security.remember`.

  Finally, the user is redirected back to either the page which they were
  trying to access (``next``) or the front page as a fallback. This parameter
  is used by our forbidden view, as explained below, to finish the login
  workflow.

- The ``logout`` view handles requests to ``/logout`` by clearing the
  credentials using :meth:`pyramid.security.forget`, then redirecting them to
  the front page.

  At a privilege boundary we are sure to reset the CSRF token using :meth:`pyramid.csrf.new_csrf_token`.
  If we were using sessions we would want to invalidate that as well.

- The ``forbidden_view`` is registered using the
  :class:`pyramid.view.forbidden_view_config` decorator. This is a special
  :term:`exception view`, which is invoked when a
  :class:`pyramid.httpexceptions.HTTPForbidden` exception is raised.

  By default, the view will return a "403 Forbidden" response and display our ``403.jinja2`` template (added below).

  However, if the user is not logged in, this view will handle a forbidden error by redirecting the user to ``/login``.
  As a convenience, it also sets the ``next=`` query string to the current URL (the one that is forbidding access).
  This way, if the user successfully logs in, they will be sent back to the page which they had been trying to access.


Add the ``login.jinja2`` template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create ``tutorial/templates/login.jinja2`` with the following content:

.. literalinclude:: src/authentication/tutorial/templates/login.jinja2
   :language: html

The above template is referenced in the login view that we just added in
``tutorial/views/auth.py``.


Add "Login" and "Logout" links
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open ``tutorial/templates/layout.jinja2`` and add the following code as
indicated by the highlighted lines.

.. literalinclude:: src/authentication/tutorial/templates/layout.jinja2
   :lines: 35-48
   :lineno-match:
   :emphasize-lines: 2-12
   :language: html

The ``request.identity`` will be ``None`` if the user is not authenticated, or a
``tutorial.models.User`` object if the user is authenticated. This check will
make the logout link shown only when the user is logged in, and conversely the
login link is only shown when the user is logged out.


Add the ``403.jinja2`` template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create ``tutorial/templates/403.jinja2`` with the following content:

.. literalinclude:: src/authentication/tutorial/templates/403.jinja2
   :language: html

The above template is referenced in the forbidden view that we just added in ``tutorial/views/auth.py``.


Viewing the application in a browser
------------------------------------

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, checking that the result is as expected:

- 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.

- http://localhost:6543/login invokes the ``login`` view, and a login form will be displayed.
  On every page, there is a "Login" link in the upper right corner while the user is not authenticated, else it is a "Logout" link when the user is authenticated.

  Supplying the credentials with either the username ``editor`` and password ``editor``, or username
  ``basic`` and password ``basic``, will authenticate the user and grant access for that group.

  After logging in (as a result of hitting an edit or add page and submitting valid credentials), we will see a "Logout" link in the upper right hand corner.
  When we click it, we are logged out, redirected back to the front page, and a "Login" link is shown in the upper right hand corner.

- http://localhost:6543/FrontPage invokes the ``view_page`` view of the ``FrontPage`` page object.

- http://localhost:6543/FrontPage/edit_page invokes the ``edit_page`` view for
  the ``FrontPage`` page object.  It is executable by only the ``editor`` user.
  If a different user invokes it, then the "403 Forbidden" page will be displayed.
  If an anonymous user invokes it, then a login form will be displayed.

- http://localhost:6543/add_page/SomePageName invokes the ``add_page`` view for a page.
  If the page already exists, then it redirects the user to the ``edit_page`` view for the page object.
  It is executable by either the ``editor`` or ``basic`` user.
  If an anonymous user invokes it, then a login form will be displayed.

- http://localhost:6543/SomePageName/edit_page invokes the ``edit_page`` view
  for an existing page, or generates an error if the page does not exist. It is
  editable by the ``basic`` user if the page was created by that user in the
  previous step. If instead the page was created by the ``editor`` user, then
  the login page should be shown for the ``basic`` user.