paste.auth.cookie – Cookie-based authentication

Cookie “Saved” Authentication

This authentication middleware saves the current REMOTE_USER, REMOTE_SESSION, and any other environment variables specified in a cookie so that it can be retrieved during the next request without requiring re-authentication. This uses a session cookie on the client side (so it goes away when the user closes their window) and does server-side expiration.

Following is a very simple example where a form is presented asking for a user name (no actual checking), and dummy session identifier (perhaps corresponding to a database session id) is stored in the cookie.

>>> from paste.httpserver import serve
>>> from paste.fileapp import DataApp
>>> from paste.httpexceptions import *
>>> from paste.auth.cookie import AuthCookieHandler
>>> from paste.wsgilib import parse_querystring
>>> def testapp(environ, start_response):
...     user = dict(parse_querystring(environ)).get('user','')
...     if user:
...         environ['REMOTE_USER'] = user
...         environ['REMOTE_SESSION'] = 'a-session-id'
...     if environ.get('REMOTE_USER'):
...         page = '<html><body>Welcome %s (%s)</body></html>'
...         page %= (environ['REMOTE_USER'], environ['REMOTE_SESSION'])
...     else:
...         page = ('<html><body><form><input name="user" />'
...                 '<input type="submit" /></form></body></html>')
...     return DataApp(page, content_type="text/html")(
...                    environ, start_response)
>>> serve(AuthCookieHandler(testapp))
serving on...

Module Contents

class paste.auth.cookie.AuthCookieSigner(secret=None, timeout=None, maxlen=None)

save/restore environ entries via digially signed cookie

This class converts content into a timed and digitally signed cookie, as well as having the facility to reverse this procedure. If the cookie, after the content is encoded and signed exceeds the maximum length (4096), then CookieTooLarge exception is raised.

The timeout of the cookie is handled on the server side for a few reasons. First, if a ‘Expires’ directive is added to a cookie, then the cookie becomes persistent (lasting even after the browser window has closed). Second, the user’s clock may be wrong (perhaps intentionally). The timeout is specified in minutes; and expiration date returned is rounded to one second.

Constructor Arguments:

secret

This is a secret key if you want to syncronize your keys so that the cookie will be good across a cluster of computers. It is recommended via the HMAC specification (RFC 2104) that the secret key be 64 bytes since this is the block size of the hashing. If you do not provide a secret key, a random one is generated each time you create the handler; this should be sufficient for most cases.

timeout

This is the time (in minutes) from which the cookie is set to expire. Note that on each request a new (replacement) cookie is sent, hence this is effectively a session timeout parameter for your entire cluster. If you do not provide a timeout, it is set at 30 minutes.

maxlen

This is the maximum size of the signed cookie; hence the actual content signed will be somewhat less. If the cookie goes over this size, a CookieTooLarge exception is raised so that unexpected handling of cookies on the client side are avoided. By default this is set at 4k (4096 bytes), which is the standard cookie size limit.

class paste.auth.cookie.AuthCookieHandler(application, cookie_name=None, scanlist=None, signer=None, secret=None, timeout=None, maxlen=None)

the actual handler that should be put in your middleware stack

This middleware uses cookies to stash-away a previously authenticated user (and perhaps other variables) so that re-authentication is not needed. This does not implement sessions; and therefore N servers can be syncronized to accept the same saved authentication if they all use the same cookie_name and secret.

By default, this handler scans the environ for the REMOTE_USER and REMOTE_SESSION key; if found, it is stored. It can be configured to scan other environ keys as well – but be careful not to exceed 2-3k (so that the encoded and signed cookie does not exceed 4k). You can ask it to handle other environment variables by doing:

environ['paste.auth.cookie'].append('your.environ.variable')

Constructor Arguments:

application

This is the wrapped application which will have access to the environ['REMOTE_USER'] restored by this middleware.

cookie_name

The name of the cookie used to store this content, by default it is PASTE_AUTH_COOKIE.

scanlist

This is the initial set of environ keys to save/restore to the signed cookie. By default is consists only of REMOTE_USER and REMOTE_SESSION; any tuple or list of environment keys will work. However, be careful, as the total saved size is limited to around 3k.

signer

This is the signer object used to create the actual cookie values, by default, it is AuthCookieSigner and is passed the remaining arguments to this function: secret, timeout, and maxlen.

At this time, each cookie is individually signed. To store more than the 4k of data; it is possible to sub-class this object to provide different environ_name and cookie_name

class paste.auth.cookie.AuthCookieEnviron(handler, scanlist)

a list of environment keys to be saved via cookie

An instance of this object, found at environ['paste.auth.cookie'] lists the environ keys that were restored from or will be added to the digially signed cookie. This object can be accessed from an environ variable by using this module’s name.

This middleware uses cookies to stash-away a previously authenticated user (and perhaps other variables) so that re-authentication is not needed. This does not implement sessions; and therefore N servers can be syncronized to accept the same saved authentication if they all use the same cookie_name and secret.

By default, this handler scans the environ for the REMOTE_USER and REMOTE_SESSION key; if found, it is stored. It can be configured to scan other environ keys as well – but be careful not to exceed 2-3k (so that the encoded and signed cookie does not exceed 4k). You can ask it to handle other environment variables by doing:

environ['paste.auth.cookie'].append('your.environ.variable')

Configuration:

cookie_name

The name of the cookie used to store this content, by default it is PASTE_AUTH_COOKIE.

scanlist

This is the initial set of environ keys to save/restore to the signed cookie. By default is consists only of REMOTE_USER and REMOTE_SESSION; any space-separated list of environment keys will work. However, be careful, as the total saved size is limited to around 3k.

secret

The secret that will be used to sign the cookies. If you don’t provide one (and none is set globally) then a random secret will be created. Each time the server is restarted a new secret will then be created and all cookies will become invalid! This can be any string value.

timeout

The time to keep the cookie, expressed in minutes. This is handled server-side, so a new cookie with a new timeout is added to every response.

maxlen

The maximum length of the cookie that is sent (default 4k, which is a typical browser maximum)