Devise OTP implements two-factors authentication for Devise, using an rfc6238 compatible Time-Based One-Time Password Algorithm. It uses the rotp library for generation and verification of codes.
If you are upgrading from version 0.1.x, you will need to regenerate your views.
It currently has the following features:
- Url based provisioning of token devices, compatible with Google Authenticator.
- Browsers can be set as 'trusted' for a limited time. During that time no OTP challenge is asked again when logging from that browser (but normal login will).
- Two factors authentication can be optional at user discretion, recommended (it nags the user on every sign-in) or mandatory (users must enroll OTP after signing-in next time, before they can navigate the site). The settings is global, or per-user. ( incomplete, see below)
- Optionally, users can obtain a list of HOTP recovery tokens to be used for emergency log-in in case the token device is lost or unavailable.
Compatible token devices are:
- A shared secret is generated on the server, and stored both on the token device (ie: the phone) and the server itself.
- The secret is used to generate short numerical tokens that are either time or sequence based.
- Tokens can be generated on a phone without internet connectivity.
- The token provides an additional layer of security against password theft.
- OTP's should always be used as a second factor of authentication(if your phone is lost, you account is still secured with a password)
- Google Authenticator allows you to store multiple OTP secrets and provision those using a QR Code
Although there's an adjustable drift window, it is important that both the server and the token device (phone) have their clocks set (eg: using NTP).
Add this line to your application's Gemfile:
gem 'devise'
gem 'devise-otp'
And then execute:
$ bundle
Or install it yourself as:
$ gem install devise-otp
To setup Devise, you need to do the following (but refer to https://github.com/plataformatec/devise for more information)
Install Devise:
rails g devise:install
Setup the User or Admin model
rails g devise MODEL
Configure your app for authorisation, edit your Controller and add this before_filter:
before_filter :authenticate_user!
Make sure your "root" route is configured in config/routes.rb
Run the following generator to add the necessary configuration options to Devise's config file:
rails g devise_otp:install
After you've created your Devise user models (which is usually done with a "rails g devise MODEL"), set up your Devise OTP additions:
rails g devise_otp MODEL
Don't forget to migrate:
rake db:migrate
If you want to customise your views (which you likely will want to), you can use the generator:
rails g devise_otp:views
The install generator also installs an english copy of a Devise OTP i18n file. This can be modified (or used to create other language versions) and is located at: config/locales/devise.otp.en.yml
With this extension enabled, the following is expected behaviour:
- Users may go to /MODEL/otp/token and enable their OTP state, they might be asked to provide their password again (and OTP token, if it's enabled)
- Once enabled they're shown an alphanumeric code (for manual provisioning) and a QR code, for automatic provisioning of their authetication device (for instance, Google Authenticator)
- If config.otp_mandatory or model_instance.otp_mandatory, users will be required to enable, and provision, next time they successfully sign-in.
The install generator adds some options to the end of your Devise config file (config/initializers/devise.rb)
config.otp_mandatory- OTP is mandatory, users are going to be asked to enroll the next time they sign in, before they can successfully complete the session establishment.config.otp_authentication_timeout- how long the user has to authenticate with their token. (defaults to3.minutes)config.otp_drift_window- a window which provides allowance for drift between a user's token device clock (and therefore their OTP tokens) and the authentication server's clock. Expressed in minutes centered at the current time. (default:3)config.otp_credentials_refresh- Users that have logged in longer than this time ago, are going to be asked their password (and an OTP challenge, if enabled) before they can see or change their otp informations. (defaults to15.minutes)config.otp_recovery_tokens- Whether the users are given a list of one-time recovery tokens, for emergency access (default:10, set tofalseto disable)config.otp_trust_persistence- The user is allowed to set his browser as "trusted", no more OTP challenges will be asked for that browser, for a limited time. (default:1.month, set to false to disable setting the browser as trusted)config.otp_uri_application- The name of this application, to be added to the provisioning url as '<user_email>/application_name' (defaults to the Rails application class)
- 2D barcodes for provisioning are currently produced with the google charts api. You can, of course, use your own source in the template, but I am looking for a solution with no external dependencies (feedback welcome).
- recommended mode (nag the user each time) is not fully implemented. Right now you can make 2FA mandatory, or leave it to the user.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
I started this extension by forking devise_google_authenticator, and this project still contains some chunk of code from it, esp. in the tests and generators. At some point, my design goals were significantly diverging, so I refactored most of its code. Still, I want to thank the original author for his relevant contribution.
MIT Licensed