paste.auth.auth_tkt – auth_tkt cookie parsing

Implementation of cookie signing as done in mod_auth_tkt.

mod_auth_tkt is an Apache module that looks for these signed cookies and sets REMOTE_USER, REMOTE_USER_TOKENS (a comma-separated list of groups) and REMOTE_USER_DATA (arbitrary string data).

This module is an alternative to the paste.auth.cookie module; it’s primary benefit is compatibility with mod_auth_tkt, which in turn makes it possible to use the same authentication process with non-Python code run under Apache.

Module Contents

class paste.auth.auth_tkt.AuthTKTMiddleware(app, secret, cookie_name='auth_tkt', secure=False, include_ip=True, logout_path=None, httponly=False, no_domain_cookie=True, current_domain_cookie=True, wildcard_cookie=True)

Middleware that checks for signed cookies that match what mod_auth_tkt looks for (if you have mod_auth_tkt installed, you don’t need this middleware, since Apache will set the environmental variables for you).

Arguments:

secret:

A secret that should be shared by any instances of this application. If this app is served from more than one machine, they should all have the same secret.

cookie_name:

The name of the cookie to read and write from. Default auth_tkt.

secure:

If the cookie should be set as ‘secure’ (only sent over SSL) and if the login must be over SSL. (Defaults to False)

httponly:

If the cookie should be marked as HttpOnly, which means that it’s not accessible to JavaScript. (Defaults to False)

include_ip:

If the cookie should include the user’s IP address. If so, then if they change IPs their cookie will be invalid.

logout_path:

The path under this middleware that should signify a logout. The page will be shown as usual, but the user will also be logged out when they visit this page.

If used with mod_auth_tkt, then these settings (except logout_path) should match the analogous Apache configuration settings.

This also adds two functions to the request:

environ['paste.auth_tkt.set_user'](userid, tokens='', user_data='')

This sets a cookie that logs the user in. tokens is a string (comma-separated groups) or a list of strings. user_data is a string for your own use.

environ['paste.auth_tkt.logout_user']()

Logs out the user.

paste.auth.auth_tkt.make_auth_tkt_middleware(app, global_conf, secret=None, cookie_name='auth_tkt', secure=False, include_ip=True, logout_path=None)

Creates the AuthTKTMiddleware.

secret is requird, but can be set globally or locally.

class paste.auth.auth_tkt.AuthTicket(secret, userid, ip, tokens=(), user_data='', time=None, cookie_name='auth_tkt', secure=False)

This class represents an authentication token. You must pass in the shared secret, the userid, and the IP address. Optionally you can include tokens (a list of strings, representing role names), ‘user_data’, which is arbitrary data available for your own use in later scripts. Lastly, you can override the cookie name and timestamp.

Once you provide all the arguments, use .cookie_value() to generate the appropriate authentication ticket. .cookie() generates a Cookie object, the str() of which is the complete cookie header to be sent.

CGI usage:

token = auth_tkt.AuthTick('sharedsecret', 'username',
    os.environ['REMOTE_ADDR'], tokens=['admin'])
print 'Status: 200 OK'
print 'Content-type: text/html'
print token.cookie()
print
... redirect HTML ...

Webware usage:

token = auth_tkt.AuthTick('sharedsecret', 'username',
    self.request().environ()['REMOTE_ADDR'], tokens=['admin'])
self.response().setCookie('auth_tkt', token.cookie_value())

Be careful not to do an HTTP redirect after login; use meta refresh or Javascript – some browsers have bugs where cookies aren’t saved when set on a redirect.

exception paste.auth.auth_tkt.BadTicket(msg, expected=None)

Exception raised when a ticket can’t be parsed. If we get far enough to determine what the expected digest should have been, expected is set. This should not be shown by default, but can be useful for debugging.