eadz / rack-u2f

Rack middleware to register and authenticate against U2F devices

Rack::U2f

Rack middleware to require add u2f authentication.

Note: This gem needs a tidy up and will be properly released by end of Nov 2017

Note: U2F only works on https connections.

Installation

Add this line to your application's Gemfile:

gem 'rack-u2f'

And then execute:

$ bundle

Usage

Rack U2F has two components; A Rack app to register U2F devices and Rack Middleware to authenticate against registered U2F devices. When registration is enabled, you can add a u2f device through the u2f_register_path.

For U2F to work, persistence of a counter is required, therefore a storage mechanism is needed. Right now, this gem supports Redis, and ActiveRecord. There is a simple API to add more stores as required.

Config

In rails:

in config/application.rb

config.middleware.use Rack::U2f::AuthenticationMiddleware, {
  store: Rack::U2f::RegistrationStore::RedisStore.new,
  exclude_urls: [/\Au2f/, /\A\/\z/],
  enable_registration: ENV['ENABLE_U2F_REGISTRATION'] == "true",
  after_sign_in_url: '/', # optional, defaults to '/'
  u2f_register_path: '/_u2f_register' #optional, defaults to '/_u2f_register'
}

Store Config

Redis Store

The Rack::U2f::RegistrationStore::RedisStore.new by default uses Redis.new as the redis connection. You can pass in your own connection as the single argument to RedisStore.new(), for example:

store: Rack::U2f::RegistrationStore::RedisStore.new(Redis.new(url: 'redis://10.1.1.1/'))

ActiveRecord Store

Use Rack::U2f::RegistrationStore::ActiveRecordStore.new(ArModel). The ArModel should be an active record model with the following schema;

t.string :key_handle, index: true
t.text :certificate
t.text :public_key
t.integer :counter

Other Config

enable_registration

If enable_registration is true then you will be able to visit /_u2f_register to register a new key. Registration should not be enabled in production. It is possible to mount the registration server separately as it is a rack app.

When authenticated, the session is used for further authentication. You must be using a secure session store.

after_sign_in_url

The url to be directed to after successful sign in, default: "/"

exclude_urls

An array of regular expressions to match on the path to exclude urls from the u2f requirement. Be careful here; generally prefixes is the safest way %r{\A/myprefix}. Keep in mind that people can add things to paths that may cause an otherwise excluded url to match.

Development

There is a demo app in the DemoApp folder. Integration tests will require a fake/software u2f key, and is on the TODO list.

Future Plans

Right now this gem is designed for Admin access to certian parts of the site. In the future, a concept of identity will be added so that you can use it for end users.

An example might be sending a header in a response from a rails controller "X-REQUIRE-U2F: true", which the middleware would pick up. Passing "X-U2F-IDENTITY: #{user_id}" would allow the middleware to handle per-user u2f tokens.

This would replace the current path matching in the middleware.

See also

The ruby-u2f gem, which this gem depends on.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/eadz/rack-u2f

License

The gem is available as open source under the terms of the MIT License.

Todo ( contributions welcome )

Integration tests using a fake token such as the soft token helper from google