Devise Token Auth

Devise Token Auth implements several security measures by default to protect authentication tokens:

• Token Rotation: Tokens are changed after every request to mitigate replay attacks.
• Cryptographic Strength: Tokens are generated using cryptographically secure random number generators.
• Hashing: Tokens are hashed using BCrypt and are never stored in plain-text.
• Timing Attack Protection: Tokens are compared using secure comparison techniques to prevent timing attacks.
• Token Expiration: Tokens are invalidated after 2 weeks, requiring users to re-authenticate.

Critical Requirement: You must use HTTPS to ensure tokens are not intercepted in transit. The gem does not manage transport layer security.

By default, devise_token_auth implements a strict token rotation policy. After every successful API request, the current access-token is invalidated and a new one is generated.

To maintain a valid session, the client must extract the new token from the access-token header of the response and include it in the access-token header of the subsequent request. If a client attempts to reuse an old token that has already been invalidated by a previous successful request, the request will fail.

To allow additional parameters during registration or account updates, override the DeviseTokenAuth::RegistrationsController and use the configure_permitted_parameters method to permit the new keys via the devise_parameter_sanitizer.

class RegistrationsController < DeviseTokenAuth::RegistrationsController
  before_action :configure_permitted_parameters

  protected

  def configure_permitted_parameters
    devise_parameter_sanitizer.permit(:sign_up, keys: %i(name))
    devise_parameter_sanitizer.permit(:account_update, keys: %i(name))
  end
end

To completely disable OAuth authentication, you must perform two steps:

1. Remove the :omniauthable module from the devise block in your User model.
2. Instruct the routes to skip mounting the omniauth_callbacks controller in config/routes.rb using the skip option in mount_devise_token_auth_for.

# 1. app/models/user.rb
class User < ActiveRecord::Base
  # omit :omniauthable here
  devise :database_authenticatable, :confirmable,
         :recoverable, :trackable, :validatable,
         :registerable

  include DeviseTokenAuth::Concerns::User
end

# 2. config/routes.rb
Rails.application.routes.draw do
  mount_devise_token_auth_for 'User', at: 'auth', skip: [:omniauth_callbacks]
end

To use email authentication, your Rails application must be configured to send emails via Action Mailer. For local development, it is recommended to use mailcatcher.

Example configuration for using Mailcatcher in your development environment:

# config/environments/development.rb
Rails.application.configure do
  config.action_mailer.default_url_options = { host: 'your-dev-host.dev' }
  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = { address: 'your-dev-host.dev', port: 1025 }
end

To use Devise Token Auth in your Rails application, add the gem to your Gemfile and run bundle install.

gem 'devise_token_auth'

bundle install

If you are using ActiveAdmin, it extends from your app's ApplicationController. Including DeviseTokenAuth::Concerns::SetUserByToken in your main ApplicationController can cause conflicts.

To resolve this, create a dedicated ApiController for your API routes and keep the standard ApplicationController for ActiveAdmin and other non-API routes.

# app/controllers/api_controller.rb
# API routes extend from this controller
class ApiController < ActionController::Base
  include DeviseTokenAuth::Concerns::SetUserByToken
end

# app/controllers/application_controller.rb
# leave this for ActiveAdmin, and any other non-api routes
class ApplicationController < ActionController::Base
end

Use the Rails generator to perform a one-step installation. This will create an initializer, update your model, append routes, and include necessary controller concerns.

For standard ActiveRecord usage:

rails g devise_token_auth:install [USER_CLASS] [MOUNT_PATH]

For Mongoid usage:

rails g devise_token_auth:install_mongoid [USER_CLASS] [MOUNT_PATH]

Arguments:

• USER_CLASS: The name of the class to use for user authentication (defaults to User).
• MOUNT_PATH: The path at which to mount the authentication routes (defaults to auth).

Example:

rails g devise_token_auth:install User auth

You can configure standard Devise settings by creating config/initializers/devise.rb.

Key tasks include:

• Setting the mailer_sender address.
• Loading the ORM (e.g., :active_record or :mongoid).
• Configuring navigational_formats (e.g., setting to [:json] when using rails-api to avoid ActionDispatch::Flash middleware issues).

Devise.setup do |config|
  # The e-mail address that mail will appear to be sent from
  config.mailer_sender = "support@myapp.com"

  # ==> ORM configuration
  require 'devise/orm/active_record'

  # If using rails-api, tell devise to not use ActionDispatch::Flash
  # middleware b/c rails-api does not include it.
  config.navigational_formats = [:json]
end

To support multiple user models (e.g., User and Admin), follow these steps:

1. Generate the new model: Run the devise_token_auth:install generator for the new model. This creates the model and sets up authentication routes with a base path.

   rails g devise_token_auth:install Admin admin_auth

2. Configure Routes: Because controllers default to the first available Devise mapping, you must wrap routes for subsequent models within a devise_scope block to ensure they authorize requests using the correct class.

3. Restrict Controllers: Once configured, the new model's controllers will have access to specific authentication methods based on the model name (e.g., authenticate_admin!, current_admin, and admin_signed_in?).