DevAuth 0.1.2

Introduction

Many debugging tools provide through-the-web functionality that is private, important to secure, and orthogonal to any other authentication on the system. DevAuth is a tool to provide a single way to restrict access to these tools.

DevAuth is only an authentication system, it does not itself provide any tools. It is only intended for developers, and is not an authentication system that is usable in general-purpose applications.

This is written for the wsgi.org developer_auth spec.

Authentication

There are two means of authentication that DevAuth uses: username/password authentication, and IP-based restrictions. Ideally you would use both of these for higher security. It may also be reasonable to use an IP restriction of 127.0.0.1 for local development.

Username/password authentication can be done with a function that checks the username and password (like valid_login = password_checker(username, password)), or with an Apache htpasswd-style file.

IP based authentication uses deny and allow. If you give IP addresses that are denied, these are entirely rejected; if you give IP addresses that are allowed, then only requests from these IP addresses are allowed. deny takes precedence over allow. These can be lists of IP addresses (with commas), IP masks (like 192.168.0.0/24) or ranges like 192.168.1<->3 (meaning 192.168.{1-3}.*).

Any change in the developer’s IP address will require re-login. Logins may expire (if so configured) and require re-login.

Usage/Configuration

The basic usage of DevAuth is like:

from devauth import DevAuth

app = ... instantiate main app ...
wrapped_app = DevAuth(app, ...configuration...)

The configuration is keyword arguments:

allow:

The allowed IP addresses. This can be a string or a list of strings. See Authentication for the allowed formats. This defaults to "127.0.0.1", i.e., only local access is allowed. None means allow any IP address. Note both environ['REMOTE_ADDR'] and environ['HTTP_X_FORWARDED_FOR'] are checked, and both must pass.

deny:

Similar to allow, except any requests from IP addresses matching these IP addresses will not be allowed to login.

password_file:

This is a filename, the location of a password file as generated by htpasswd. You can create this file like:

$ htpasswd -s devauth.htpasswd username
New password:
Re-type new password:
Adding password for user username

You must use the argument -c to first create the file (without it an entry will be appended). -s hashes your password with SHA; any hash supported by htpasswd will work, but SHA is better than the default.

password_checker:

This is a function to check the username and password. A very simple implementation might be:

def password_checker(username, password):
    return username == 'admin' and password='topsecret'

secret_file, secret:

DevAuth uses a server-side secret to sign the login cookies. You can keep this secret in a file or provide it directly. If you give it a filename and the file doesn’t exist, a file will be created with a randomly generated secret (it is advantageous to keep it in a file because it will persist over restarts, so developers won’t have to re-login).

The default is to keep the secret in $TMP/devauth.txt, where $TMP is replaced with the appropriate system temporary directory.

logger:

A logging logger instance, or the name of a logger. If not given a logger is created with the name DevAuth. This logs logins, failed logins, problems with signed keys, etc.

expiration:

The number of minutes the login is valid for (None means no expiration). This is counted from the time of login, so even if you maintain activity the login will still expire.

login_mountpoint:

This is the URL where the login will take place, it defaults to /.devauth. Then the login is at /.devauth/login and the logout is at /.devauth/logout. Only these two URLs are intercepted, so you can still have things at other URLs like /.devauth/logs (if you do this, you’ll probably replace /.devauth with something specific to your application).

Paste Deploy Configuration

You can use this with Paste Deploy configuration (as used in Pylons and Repoze). It looks something like:

[filter:devauth]
use = egg:DevAuth
allow = 127.0.0.1
        192.168.0.0/16
# Toby's computer:
# (I hate him so much!)
deny = 192.168.0.23
# File created with htpasswd:
password_file = %(here)s/developers.htpasswd
# Login expires after 1 hour:
# So Toby can't hijack my session by using my computer.
# (I hate him so much!)
expiration = 60
# You'll login in at /.devauth/login (the default):
login_mountpoint = /.devauth

[app:myapp]
blah blah blah

[pipeline:main]
pipeline = devauth myapp

For Tool Developers

If you want to check if a developer is logged in, look for environ['x-wsgiorg.developer_user']. This key will have the username as a value. If the page is for developers only, then return 403 Forbidden.