CherryPy Project Download

lg_authority

available at http://www.github.com/wwoods/lamegame_cherrypy_authority

About

lg_authority is an authentication and authorization control suite for CherryPy. It handles user registration, group management, and provides functions for denying access to protected resources. The module is designed to be (relatively) easy to use, but at the same time be extensible enough that it may be customized through standard CherryPy configuration.

Supported registration methods:

  • E-mail - Either required to create an account, or supplementary for account recovery
  • OpenID - If python-openid is installed, users may choose to use an OpenID instead of a password. lg_authority also allows users to use your site as an OpenID provider.
  • Admin approved only - If you only have a small number of approved users for your app (such as an internal team), lg_authority lets those users request accounts and you approve them.
  • Recaptcha - Validate that registering users are, in fact, humans (requires recaptcha-client and valid configuration)

The module also provides:

  • Namespaced, expiring, key-value storage - currently supports ram, sqlite3, and mongodb
  • Non-locking sessions - usually used in place of cherrypy.lib.sessions
  • User information in handlers - cherrypy.user.name = logged in username; cherrypy.user itself is a dict of known user attributes
  • Long-term storage for user activities - cherrypy.user.slate is like a session, except it may span multiple logins

Installation

This software should be compatible with both python 2 and 3, though features may be limited depending the python language support of the libraries that those features depend on. For instance, the mongodb storage driver requires pymongo, which is available only for Python 2 at the time of this writing.

Either download and extract the source from github or use git to clone from git://github.com/wwoods/lamegame_cherrypy_authority.git. Then run

  python setup.py install

From the source directory to install lg_authority.

Example Usage

Unlike a conventional tool, lg_authority also requires a mounted object through which it serves its special pages for authentication and user management. This object is presumed by the default configuration to be mounted at /auth on the webserver.

Complete Simple Example

The following code runs a cherrypy application that uses lg_authority for authentication.

import cherrypy
import lg_authority

#Restrict default access to logged in users
@lg_authority.groups('auth')
class Root(object):
    """CherryPy server root"""

    auth = lg_authority.AuthRoot()
    auth__doc = "The object that serves authentication pages"

    #Allow everyone to see the index page
    @cherrypy.expose
    @lg_authority.groups('any')
    def index(self):
        return '<p>Welcome!</p><p>Would you like to <a href="protected">view protected information?</a></p>'

    #This method inherits restricted access from the Root class it belongs to
    @cherrypy.expose
    def protected(self):
        return '<p>Welcome, {user}!</p><p><a href="auth/logout">Logout</a> and try again?<p>'.format(user=cherrypy.user.name)

#Turn on lg_authority for our website
cherrypy.config.update({
    'tools.lg_authority.on': True
    })

#Run the webserver
cherrypy.quickstart(Root())

Checking a user's groups without denying them

You can use the following snippet to investigate a user's groups (e.g. to show an edit button if they are allowed to edit the page) as in the following snippet:

import cherrypy
import lg_authority

class MyWiki(object):
    @cherrypy.expose
    def default(self, page, edit=None):
        if edit is not None:
            lg_authority.require_groups('wiki_edit')
            #User can edit, fetch edit information
            #...
        else:
            p = self.fetch_page(page)
            if lg_authority.check_groups('wiki_edit'):
                p += '<a href="{0}?edit=true">Edit</a>'.format(cherrypy.url())
        return p

Configuration

See lg_authority/common_config.py for a rather large dict of all configuration variables and their default values.

site_ prefix

Any configuration variables prefixed with site_ implies that they are loaded once, and should not be overridden by various access paths. Usually these would be set in the [global] configuration section.

groups

The groups configuration item is an OR'd list of groups required to access a url. lg_authority.groups() simply sets this configuration item.

If membership in more than one group is required to access a resource, then use "all:" as the first required group. This shortcut will cause access to be denied unless the user is a member of ALL of the groups listed. Example: tools.lg_authority.groups = [ 'all:', 'wiki_edit', 'admin' ]

Storage Mediums

Below are the storage mediums supported by lg_authority. Which storage engine is used is picked by the site_storage configuration item, and the engine's configuration is placed in the site_storage_conf configuration item.

For instance, a basic cherrypy configuration file for sqlite3 storage might be:

[global]
tools.lg_authority.site_storage = "sqlite3"
tools.lg_authority.site_storage_conf = {
    "file": "lg_auth.db"
    }

RAM

To use RAM as your storage engine, set site_storage = "ram". No further configuration is necessarily.

Sqlite3

To use Sqlite3 as your storage engine, set site_storage = "sqlite3".

Available configuration options:

  • file - Specify a relative or absolute path to the sqlite3 database file.

PyMongo?

You must have the pymongo python module installed to use this storage type. Set site_storage = "pymongo" to use pymongo to store your data in mongodb.

Available configuration options:

  • host - Optional. Specify the host address of the mongodb instance. Defaults to localhost.
  • port - Optional. Specify the host port of the mongodb instance. Defaults to 27017.
  • db - Required. Specify the database to use for storing information.
  • collection_base - Optional. If specified, this is prefixed to all of the collections created for holding slates.

Wishlist

Upcoming Features

Before anything is put in the features list, I thought it might be good to make note of my near-future intentions:

  • cherrypy.user.name -> cherrypy.user.id
  • cherrypy.user will actually be an alias for the user's slate, so you will be able to read/write information about the user.
  • More internal linking - less URL hacking to logout / etc (the AuthRoot's index provides a few links, but few of those link back)
  • Built-in Response wrapping support, so that the pages actually look like part of your webpage
  • Default CSS (in the default response wrapper), just so that it's less ugly out of the box
  • Unit tests :)

Features

  • Put things here that should be considered for inclusion in the library... or post an issue on github.

Documentation Complaints

  • Put things here that are issues with this page.

Hosted by WebFaction

Log in as guest/cherrypy to create/edit wiki pages