.. _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 an :term:`authentication policy` and a ``request.user`` computed property (``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 denied access to any of the views that require permission, instead of a default "403 Forbidden" page (``views/auth.py``). Authenticating requests ----------------------- The core of :app:`Pyramid` authentication is an :term:`authentication 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 authentication policy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a new file ``tutorial/security.py`` with the following content: .. literalinclude:: src/authentication/tutorial/security.py :linenos: :language: python Here we've defined: * A new authentication policy named ``MyAuthenticationPolicy``, which is subclassed from Pyramid's :class:`pyramid.authentication.AuthTktAuthenticationPolicy`, which tracks the :term:`userid` using a signed cookie (lines 7-11). * A ``get_user`` function, which can convert the ``unauthenticated_userid`` from the policy into a ``User`` object from our database (lines 13-17). * The ``get_user`` is registered on the request as ``request.user`` to be used throughout our application as the authenticated ``User`` object for the logged-in user (line 27). The logic in this file is a little bit interesting, so we'll go into detail about what's happening here: First, the default authentication policies all provide a method named ``unauthenticated_userid`` which is responsible for the low-level parsing of the information in the request (cookies, headers, etc.). If a ``userid`` is found, then it is returned from this method. This is named ``unauthenticated_userid`` because, at the lowest level, it knows the value of the userid in the cookie, but it doesn't know if it's actually a user in our system (remember, anything the user sends to our app is untrusted). Second, our application should only care about ``authenticated_userid`` and ``request.user``, which have gone through our application-specific process of validating that the user is logged in. In order to provide an ``authenticated_userid`` we need a verification step. That can happen anywhere, so we've elected to do it inside of the cached ``request.user`` computed property. This is a convenience that makes ``request.user`` the source of truth in our system. It is either ``None`` or a ``User`` object from our database. This is why the ``get_user`` function uses the ``unauthenticated_userid`` to check the database. Configure the app ~~~~~~~~~~~~~~~~~ Since we've added a new ``tutorial/security.py`` module, we need to include it. Open the file ``tutorial/__init__.py`` and edit the following lines: .. literalinclude:: src/authentication/tutorial/__init__.py :linenos: :emphasize-lines: 11 :language: python 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 for production, so open ``production.ini`` and add a different secret: .. literalinclude:: src/authentication/production.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: 5-9 :lineno-match: :emphasize-lines: 2 :language: python Change the highlighted line. In the same file, now edit the ``edit_page`` view function: .. literalinclude:: src/authentication/tutorial/views/default.py :lines: 45-60 :lineno-match: :emphasize-lines: 5-7 :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: 62-76 :lineno-match: :emphasize-lines: 3-5,13 :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 return a "403 Forbidden" response to the user. However, we will hook this later to redirect to the login page. Also, now that we have ``request.user``, 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. 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. - 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. 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-46 :lineno-match: :emphasize-lines: 2-10 :language: html The ``request.user`` 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. 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/FrontPage invokes the ``view_page`` view of the ``FrontPage`` page object. 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. - 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 (or the anonymous user) invokes it, then a login form will be displayed. Supplying the credentials with the username ``editor`` and password ``editor`` will display the edit page form. - 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 a different user (or the anonymous user) invokes it, then a login form will be displayed. Supplying the credentials with either the username ``editor`` and password ``editor``, or username ``basic`` and password ``basic``, will display the edit page form. - 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. - After logging in (as a result of hitting an edit or add page and submitting the login form with the ``editor`` credentials), we'll see a "Logout" link in the upper right hand corner. When we click it, we're logged out, redirected back to the front page, and a "Login" link is shown in the upper right hand corner.