LockBox

LockBox is a centralized API authentication service written by the DNC Innovation Lab. It lets your API users share a single identity across multiple services.

It is licensed under the New BSD License (see the LICENSE file for details).

The server is a Ruby on Rails application, while the client is pure Rack middleware (which means it integrates nicely with any modern Ruby web framework, including Rails 2.3+).

Lockbox handles things like rate limiting, API key signup and management, and supports HMAC authentication as well as plain-text key exchange.

Client Installation

gem install lockbox_middleware

Rails 2

Add the following lines to the “config/environment.rb” file:

config.gem 'lockbox_middleware'
config.middleware.use 'LockBox'

You may want to restrict the “config.middleware.use” line to the config/environments/production.rb file so that your test and development environments aren’t trying to access the LockBox server.

Rails 3

Untested.

Client Configuration

LockBox needs a configuration file named “lockbox.yml” in order to work. In a Rack app (incl. Rails), this file should be placed in app_root/config/lockbox.yml.

You should define (for each of your environments), the base_uri of your app and the relative paths you want to protect with LockBox.

Here’s an example lockbox.yml:

common: &COMMON
  protected_paths:
    - ^/api/
production: 
  <<: *COMMON
  base_uri: http://lockbox.foo.org
development: 
  <<: *COMMON
  base_uri: http://localhost:3001
cucumber: 
  <<: *COMMON
  base_uri: http://localhost:3001
test: 
  <<: *COMMON
  base_uri: http://localhost:3001

Graphite Integration

The lockbox-middleware gem supports sending runtime metrics to Graphite (graphite.wikidot.com/) via statsd-client. This is off by default, but can be turned on by adding the keys ‘statsd_host’, ‘statsd_port’, and ‘graphite_prefix’ to your lockbox.yml file. For example:

statsd_host:      statsd.example.com
statsd_port:      8125
graphite_prefix:  my.app.lockbox_middleware

Server Installation

Running your own LockBox server is pretty easy. Just clone this repository (I’d stick with the master branch) and set it up under your favorite Rails hosting environment. It has only been tested with PostgreSQL, but it’s not doing anything exotic with the DB, so it will probably work with other databases too.

The gem dependencies are generally kept up to date in the Gemfile, so you can use bundler:

gem install bundler
bundle install

Or you can use the Rails 2 gem installer:

rake gems:install

Then you should configure the database.yml for the test environment and run ‘rake spec’ in the app root to have RSpec (gem install rspec-rails) run all of the tests. If these all pass, then you’re probably good to go.

Download

Github: github.com/dnclabs/lockbox/tree/master

Authors

Nathan Woodhull
Chris Gill
Brian Cardarella
Wes Morgan
Dave Steinberg