Track Devise login activity
Branch: master
Clone or download
Latest commit 04b6272 Oct 21, 2018

README.md

AuthTrail

Track Devise login activity

🍊 Battle-tested at Instacart

Installation

Add this line to your application’s Gemfile:

gem 'authtrail'

And run:

rails generate authtrail:install
rails db:migrate

How It Works

A LoginActivity record is created every time a user tries to login. You can then use this information to detect suspicious behavior. Data includes:

  • scope - Devise scope
  • strategy - Devise strategy
  • identity - email address
  • success - whether the login succeeded
  • failure_reason - if the login failed
  • user - the user if the login succeeded
  • context - controller and action
  • ip - IP address
  • user_agent and referrer - from browser
  • city, region, and country - from IP
  • created_at - time of event

Features

Exclude certain attempts from tracking - useful if you run acceptance tests

AuthTrail.exclude_method = lambda do |info|
  info[:identity] == "capybara@example.org"
end

Write data somewhere other than the login_activities table

AuthTrail.track_method = lambda do |info|
  # code
end

Use a custom identity method

AuthTrail.identity_method = lambda do |request, opts, user|
  if user
    user.email
  else
    request.params.dig(opts[:scope], :email)
  end
end

Associate login activity with your user model

class User < ApplicationRecord
  has_many :login_activities, as: :user # use :user no matter what your model name
end

The LoginActivity model uses a polymorphic association so it can be associated with different user models.

Geocoding

IP geocoding is performed in a background job so it doesn’t slow down web requests. You can disable it entirely with:

AuthTrail.geocode = false

Set job queue for geocoding

AuthTrail::GeocodeJob.queue_as :low

Geocoding Performance

To avoid calls to a remote API, download the GeoLite2 City database and configure Geocoder to use it.

Add this line to your application’s Gemfile:

gem 'maxminddb'

And create an initializer at config/initializers/geocoder.rb with:

Geocoder.configure(
  ip_lookup: :geoip2,
  geoip2: {
    file: Rails.root.join("lib", "GeoLite2-City.mmdb")
  }
)

Data Protection

Protect the privacy of your users by encrypting fields that contain personal information, such as identity and ip. attr_encrypted is great for this.

class LoginActivity < ApplicationRecord
  attr_encrypted :identity, ...
  attr_encrypted :ip, ...
end

You should also make it clear that you collect this information in your privacy policy.

Other Notes

We recommend using this in addition to Devise’s Lockable module and Rack::Attack.

Check out Hardening Devise and Secure Rails for more best practices.

Works with Rails 4.2+

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help: