Ruby gem to implement Google's MFA authenticator
Ruby gem to implement Google's MFA authenticator
Rails (ActiveRecord) integration with the Google Authenticator apps for Android and the iPhone. Uses the Authlogic style for cookie management.
Add this line to your application's Gemfile:
gem 'google-authenticator-rails'And then execute:
$ bundleOr install it yourself as:
$ gem install google-authenticator-railsExample:
class User
acts_as_google_authenticated
end
@user = User.new
@user.set_google_secret # => true
@user.google_secret_value # => 16-character plain-text secret, whatever the name of the secret column
@user.google_qr_uri # => http://path.to.chart/qr?with=params
@user.google_authentic?(123456) # => true
@user.clear_google_secret! # => true
@user.google_secret_value # => nilWhen setting up an account with GoogleAuthenticatorRails you need to provide a label for that account (to distinguish it from other accounts).
GoogleAuthenticatorRails allows you to customize how the record will create that label. There are three options:
email on the model:column_name optionExample:
…Here's what the labels look like in Google Authenticator for iPhone:
The "google secret" is where GoogleAuthenticatorRails stores the
secret token used to generate the MFA code.
You can also specify a column for storing the google secret. The default is google_secret.
Example
class User
acts_as_google_authenticated :google_secret_column => :mfa_secret
end
@user = User.new
@user.set_google_secret
@user.mfa_secret # => "56ahi483"You can specify a custom drift value. Drift is the number of seconds that the client and server are allowed to drift apart. Default value is 5 seconds.
class User
act_as_google_authenticated :drift => 31
endYou can also specify which column the appropriate MfaSession subclass should use to look up the record:
Example
class User
acts_as_google_authenticated :lookup_token => :salt
endThe above will cause the UserMfaSession class to call User.where(:salt => cookie_salt) or User.scoped(:conditions => { :salt => cookie_salt }) to find the appropriate record.
GoogleAuthenticatorRails makes one very large assumption when attempting to lookup a record. If your MfaSession subclass is named UserMfaSession it assumes you're trying to lookup a User record. Currently, there is no way to configure this, so if you're trying to lookup a VeryLongModelNameForUser you'll need to name your MfaSession subclass VeryLongModelNameForUserMfaSession.
For example:
# app/models/user.rb
class User Error: GoogleAuthenticatorRails::Session::Persistence::TokenNotFound
end
endThe above example will fail because the User class doesn't have a persistence_token method. The fix for this is to configure actions_as_google_authentic to use the right column:
# app/models/user.rb
class User :salt
end
# Model has attributes:
# id: integer
# name: string
# salt: string
# app/models/user_mfa_session.rb
class UserMfaSession 'example.com'
endYou can also use a Proc to set a dynamic issuer for multi-tenant applications or any other custom needs:
class User
acts_as_google_authenticated :issuer => Proc.new { |user| user.admin? ? "Example Admin" : "example.com" }
endThis way your user will have the name of your site at the authenticator card besides the current token.
Here's what the issuers look like in Google Authenticator for iPhone:
This is a very rough outline of how GoogleAuthenticatorRails is meant to manage the sessions and cookies for a Rails app.
# Gemfile
gem 'rails'
gem 'google-authenticator-rails'First add a field to your user model to hold the Google token.
class AddGoogleSecretToUser true, :secure => true, :domain => :all }Additional cookie option symbols can be found in the Ruby on Rails guide.
If you want to manually destroy the MFA cookie (for example, when a user logs out), just call
UserMfaSession::destroyNormally, if an attacker gets access to the application database, they will be able to generate correct authentication codes,
elmininating the security gains from two-factor authentication. If the application's secret_key_base is handled more securely
than the database (by, for example, never putting it on the server filesystem), protection against database compromise can
be gained by setting the :encrypt_secrets option to true. Newly-created secrets will then be stored in encrypted form.
Existing non-encrypted secrets for all models for which the :encrypt_secrets option has been set to true
can be encrypted by running
rails google_authenticator:encrypt_secretsThis may be reversed by running
rails google_authenticator:decrypt_secretsthen by removing, or setting false, the :encrypt_secrets option.
If secret_key_base needs to change, set old_secret_key_base to the old key in config/secrets.yml before generating the new key.
Then run
rails google_authenticator:reencrypt_secretsto change all encrypted google secret fields to use the new key.
If the app is not running under Rails version 4.1 or above, encryption will be disabled, and a warning issued if :encrypt_secrets
is enabled on a model.
If encryption is enabled for a model, the Google secret column of its table must be able to hold at least 162 characters, rather than just 32.
git checkout -b my-new-feature)git commit -am 'Added some feature')git push origin my-new-feature)MIT.
No open issues yet, or sync has not completed.