README

lg_authority - A general purpose, multi-backend capable authentication and permissions framework for CherryPy.
=================================================

Dependencies
============
Required:
    cherrypy

Optional:
    pymongo - For MongoDB backend
    python-openid - For Open ID support


Installation
============
1. git clone git://github.com/wwoods/lamegame_cherrypy_authority.git
2. cd lamegame_cherrypy_authority
3. sudo python setup.py install (or python setup.py install --user to install without sudo)


Example Usage (just want to block out non-logged-in users)
==========================================================
import cherrypy
import lg_authority

@lg_authority.groups('auth')
class Root(object):
    auth = lg_authority.AuthRoot()

    @cherrypy.expose
    def index(self):
        return "Logged in!"

cherrypy.config.update({ 
    'tools.lg_authority.on': True, 
    # Uncomment the following two lines to persist changed user / group data
    # 'tools.lg_authority.site_storage': 'sqlite3', 
    # 'tools.lg_authority.site_storage_conf': { 'file': 'test.db' } })
cherrypy.quickstart(Root())


Storage Options
===============

The different storage options are laid out in lg_authority/slates/storage.  Currently, there are the following and their options:

ram - Store session and user data in memory only; it will get erased when the
    server restarts, and does not support coordination between different 
    instances.
    Options: No options.

sqlite3 - Store session in a sqlite3 file database.  Data is persisted through 
    the file.
    Options: file - The file to store session and user information in.

pymongo - Store session information in a mongodb backend.
    Options:
        host - The host address of the mongodb server to connect to
        port - The port
        db - The name of the mongodb database to store auth collections in
        collection_base - An optional prefix for all of the collections created
            and maintained by lg_authority.


OpenID
======

Being an openID server
======================
If python-openid is installed, then there is an OpenID endpoint set up automatically at (authroot)/openid.  If you would like your site root to be an open ID endpoint, put the following meta tag in the index page (e.g. http://www.lamegameproductions.com):

<meta http-equiv="x-xrds-location" content="https://www.lamegameproductions.com/auth/openid/xrds" />

Replace www.lamegameproductions.com/auth with your auth root.  It is probably wise to ensure that the xrds location is accessed through https.

Users may also use the /auth/openid URL as an endpoint, even if you don't put that meta tag on your root.