Devise::TokenAuthenticatable

This gem provides the extracted Token Authenticatable module of devise. It includes the functionality that was also in version 3.1.2 of devise. With the inclusion of this module a user is able to sign in via an authentication token. This token can be given via a query string or HTTP Basic Authentication. See the hint below to understand which version of this gem supports which version of devise.

Use this gem as a starting point for your own token authentication mechanism for devise. Furthermore, if you need token authentication in connection with newer devise releases this gem might be an appropriate solution, too.

Installation

Add this line to your application's Gemfile:

gem 'devise-token_authenticatable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install devise-token_authenticatable

Which version to use for which version of devise?

devise-token_authenticatable	devise
~> 0.1	~> 3.2.0
~> 0.2	~> 3.3.0
~> 0.3	~> 3.4.0
~> 0.4.0, < 0.4.9	~> 3.5.0, < 3.5.2
~> 0.4.9	~> 3.5.2
~> 0.5.x, <= 1.0.0	>= 4.0.0, < 4.4.0

Usage

Create needed columns with corresponding migration:

  def change
    add_column :users, :authentication_token, :text
    add_column :users, :authentication_token_created_at, :datetime

    add_index :users, :authentication_token, unique: true
  end

Add :token_authenticatable to your devise model:

class User < ActiveRecord::Base
  devise :database_authenticatable, :token_authenticatable
end

Configuration

This gem can be configured as shown in the following:

Devise::TokenAuthenticatable.setup do |config|
  # enables the expiration of a token after a specified amount of time,
  # requires an additional field on the model: `authentication_token_created_at`
  # defaults to nil
  config.token_expires_in = 1.day

  # set the authentication key name used by this module,
  # defaults to :auth_token
  config.token_authentication_key = :other_key_name

  # enable reset of the authentication token before the model is saved,
  # defaults to false
  config.should_reset_authentication_token = true

  # enables the setting of the authentication token - if not already - before the model is saved,
  # defaults to false
  config.should_ensure_authentication_token = true
end

Enable devise's HTTP Auth for the token strategy as shown below:

# initializers/devise.rb
Devise.setup do |config|
  # ...
  config.http_authenticatable = true
  # or
  config.http_authenticatable = [:token]
  # ...
end

Troubleshooting

Using a new user's auth token does not result in invalidating an old users session. How can I ignore session storage when using token authentication?

Add :token_auth to your devise configuration:

Devise.setup do |config|
  config.skip_session_storage = [:http_auth, :token_auth]
end

Documentation

For your convenience there is also a source code documentation.

Contributing

1. Fork it.
2. Create your feature branch (git checkout -b my-new-feature).
3. Commit your changes (git commit -am 'Add some feature').
4. Push to the branch (git push origin my-new-feature).
5. Create new Pull Request.
6. Get a thank you!