Session based authentication and role based security for a Pyramid web application.
Python Mako
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.gitignore adding .gitignore Oct 3, 2012
.travis.yml release: 0.8. Sep 19, 2015 manifest: include templates. May 8, 2013
setup.cfg release: `v0.5.1`. May 7, 2013 release: 0.10.1. Apr 26, 2016

Build Status

pyramid_simpleauth is a package that implements session based authentication and role based security for a Pyramid web application.

There are many other auth implementations for Pyramid, including apex and pyramid_signup and you can, of course, easily roll your own, for example following the excellent pyramid_auth_demo. This package aims to be:

  • relatively simple: with a limited feature set
  • extensible: with event hooks and overrideable templates
  • performant: minimising db queries


If you install the package and include it in your Pyramid application, it will lock down your application and expose views at:

  • /auth/signup
  • /auth/login
  • /auth/authenticate (login via AJAX)
  • /auth/logout
  • /auth/change_username
  • /auth/change_password
  • /auth/confirm (email confirmation)
  • /auth/prefer_email (set email as the user's preferred email)

You get a user instance and an is_authenticated flag added to the request:

# e.g.: in a view callable
if request.is_authenticated:
    display = request.user.username

Plus UserSignedUp, UserloggedIn, UserLoggedOut, UserChangedPassword, UserChangedUsername, EmailPreferred and EmailAddressConfirmed events to subscribe to:

def my_event_handler(event):
    request = event.request
    user = event.user
    # e.g.: send confirmation email

Flags at request.is_post_login and request.is_post_signup, stored in the session, that allow you to test whether the current request is immediately after a login or signup event. And a request.user_json property (useful to write into a template to pass data to the client side).

model.get_confirmation_link(request, email) returns a confirmation_link that will be accepted by /auth/confirm and that can typically be included in an email sent to a user who wish to validate an email address.

The EmailAddressConfirmed and EmailPreferred events give you access to the Email object as['email'], eg:

def email_address_confirmed(event):
  email_address =['email'].address
  session = event.request.session
  session.flash("%s has been confirmed successfully" % email_address)


Install using pip or easy_install, e.g.:

pip install pyramid_simpleauth


Include the package along with a session factory, pyramid_tm and pyramid_basemodel in the configuration portion of your Pyramid app:

# Configure a session factory, here, we're using `pyramid_beaker`.

# Either include `pyramid_tm` or deal with committing transactions yourself.

# Either include `pyramid_basemodel` and provide an `sqlalchemy.url` in your
# `.ini` settings, or bind the SQLAlchemy models and scoped `Session` to a
# database engine yourself.

# Include the package.

The signup and login forms inherit from a base layout template. You can override this base layout template by writing your own, e.g.:

# my_package:my_templates/layout.mako
    <link href="my_great.css" rel="stylesheet" type="text/css" />
    <div class="my-great-markup">

Then in your main app factory / package configuration use, e.g.:


Or you can nuke the signup and login templates directly, e.g.:


To change the url path for the authentication views, specify a simpleauth.url_prefix in your application's .ini configuration:

# defaults to 'auth', resulting in urls that start with `/auth/...`
simpleauth.url_prefix = 'another'

You can also specify where to redirect to after signup, login, logout, username change, password change, email confirmation or preferred email selection. These are all configured using route names, with the route being provided the additional traversal information of the user's username and an optional view name. (This means you can expose a simple named route, or a hybrid route, as you prefer. The hybrid route will attempt traversal on the username).

To redirect to a different named route after signup / login or logout use:

simpleauth.after_signup_route = 'another' # defaults to 'users'
simpleauth.after_login_route = 'another' # defaults to 'index'
simpleauth.after_logout_route = 'another' # defaults to 'index'

Note that a next parameter passed to the login page, password change page, username change page, email confirmation page or preferred email selection page will take precedence over the specific routes.

To redirect to a different route and view after login, password change, username change, email confirmation or preferred email selection, use configuration directives such as:

simpleauth.after_confirm_email_route = 'basepath' # defaults to 'users'
simpleauth.after_confirm_email_view = 'viewname', # defaults to 'account'

This would redirect user bob to /basepath/bob/viewname. Redirect configuration directives for each of those views are named following the patterns simpleauth.after_<view_name>_route and simpleauth.after_<view_name>_view, where <view_name> can be any of login, change_username, change_password, confirm_email and prefer_email.

Be careful in the case of username change because if your next URL contains a username, it won't be valid anymore after the username has changed, eg. if you instruct the username change page to redirect to /basepath/bob/viewname but the username changes to become alice, the redirect will cause a "page not found" error. In this case, if you want to include a username in your custom redirect, you should use the configuration-based redirect location will take into account the new username.

By default the app redirects after signup to a route named 'users'. This is not exposed by pyramid_simpleauth by default but the package does provide a .tree.UserRoot root factory that looks up .model.Users by username and a default __acl__ property on the .model.User class. These are entirely optional: you can choose instead to use a different named route, or expose a simple named route using, e.g.:

config.add_route('users', 'some/path')

However, if you want to use the machinery provided, with the baked in security and traversal, you can expose a user profile view, or perhaps a welcome page at /users/:username using, e.g.:

config.add_route('users', 'users/*traverse', factory=UserRoot,

To avoid configuring the authorisation and authentication policies (e.g.: if you're going to set these up yourself) use:

simpleauth.set_auth_policies = false

To avoid locking down your app to require a 'view' permission for all views by default (secure but perhaps draconian):

simpleauth.set_default_permission = False


I've only tested the package under Python 2.6 and 2.7 atm. It should work under Python 3 but I have problems installing the passlib dependency (or any decent password encryption library) under Python 3.

You'll need nose, coverage, mock and WebTest. Then, e.g.:

$ nosetests --cover-package=pyramid_simpleauth --cover-tests --with-doctest --with-coverage
Name                        Stmts   Miss  Cover   Missing
pyramid_simpleauth             19      0   100%      26      0   100%   
pyramid_simpleauth.hooks       13      0   100%   
pyramid_simpleauth.model       56      0   100%   
pyramid_simpleauth.schema      83      0   100%   
pyramid_simpleauth.tests      197      0   100%   
pyramid_simpleauth.tree        18      0   100%   
pyramid_simpleauth.view        76      0   100%   
TOTAL                         488      0   100%   
Ran 42 tests in 16.408s