Repository is archived
No commit activity in last 3 years
No release in over 3 years
Rack middleware for the LockBox centralized API authorization service. Brought to you by the DNC Innovation Lab.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme

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

Copyright 2010 Democratic National Committee, All Rights Reserved.