FIDO U2F Authentication for Rails Devise
A gem which allows Rails Devise users to authenticate against a second factor.
Getting started
Devise FIDO U2F works with Rails 4.2 or newer and Devise 3.2 onwards. You need to add it to your application's Gemfile with:
gem 'devise_fido_usf'
Afterwards, run bundle install
to install it.
Before being able to use it you need to set it up by running its installation generator:
$ rails generate devise_fido_usf:install
During installation some instructions will be output to your console. Please follow these instructions carefully.
Specifically, you need to adapt your Devise models to include both the FIDO U2F registration and authentication modules. For example you need to add to app/models/user.rb
the following lines:
devise :fido_usf_registerable, :fido_usf_authenticatable', ...
Please ensure that the CSRF token check is always prepended on the action chain of your ApplicationController
. Edit file app/controllers/application_controller.rb
and change the protect_from_forgery
line to include prepend: true
:
class ApplicationController < ActionController::Base
# Prepend the verification of the CSRF token before the action chain.
protect_from_forgery with: :exception, prepend: true
...
end
You need to include u2f-api.js
in your javascript's asset chain by editing app/assets/javascript/application.js
to include:
//= require u2f-api
Now Devise with FIDO U2F is activated. Before using it, you need to migrate pending database changes by executing
$ rails db:migrate
Remember: To use it you always needs to run your development server with SSL. Otherwise, the FIDO U2F protocol will not allow registration or authentication!
FIDO U2F Views
To enable the user to register a FIDO U2F device and to change the appeareance of the authentication screens you need to customize its views.
You can install the devise_fido_usf
views by running
rails generate devise_fido_usf:views
After that, you need to adapt the views to your needs. Take a look at the Devise FIDO U2F example app how it could be integrated into a Rails 5.1 application running Bootstrap v4.
Contributing
This is my first developed and published gem. If you find something unusual or uncommon within my code, please drop me a note how to fix it or make it better. Thank you!
License
The gem is available as open source under the terms of the MIT License.