Devise OTP

If config.otp_mandatory is enabled, you must ensure users are redirected to the enrollment form. Use the ensure_mandatory_{scope}_otp! method in your controllers. This works similarly to authenticate_{scope}!. It is best used as a before_action alongside your standard authentication check.

class ApplicationController < ActionController::Base
  before_action :authenticate_user!
  before_action :ensure_mandatory_user_otp!
end

To add Devise OTP to your Rails application, first ensure Devise is already installed. Then, add the gem to your Gemfile and run bundle. Finally, run the installation generator to add configuration options to your Devise initializer.

Steps:

1. Add gem "devise-otp" to your Gemfile.
2. Run bundle.
3. Run rails g devise_otp:install.

# Add to Gemfile
gem "devise-otp"

# Run in terminal
$ bundle
$ rails g devise_otp:install

To implement OTP for your users, you need to generate your Devise model and then add the OTP module to it. You should also provide a way for users to access their OTP settings via a link in your navigation.

Steps:

1. Generate your Devise model (e.g., User) if you haven't already: rails g devise MODEL.
2. Add OTP to that model: rails g devise_otp MODEL.
3. Add a link to the OTP Token settings in your views. Replace user with the lowercase name of your model.

Example link: <%= link_to "OTP Token", user_otp_token_path %>

# 1. Create Devise model
rails g devise User

# 2. Add OTP to the model
rails g devise_otp User

<%# 3. Add link to navigation (replace 'user' with your model name) %>
<%= link_to "OTP Token", user_otp_token_path %>

Custom Views

To modify the default OTP views, use the generator to eject them into your application: rails g devise_otp:views

By default, files are placed in app/views/devise. To change this location, configure config.otp_controller_path in your Devise initializer.

Custom CSS

To use the default styling, import the CSS file into your application's stylesheet: @import url("devise-otp.css");

Alternatively, you can copy the contents of devise-otp.css directly into your own stylesheet.

# Eject views
rails g devise_otp:views

/* In your application.css */
@import url("devise-otp.css");

Use the devise_otp Rails generator to automatically inject the :otp_authenticatable directive into your specified model and generate the necessary ActiveRecord migration. This simplifies the setup of Two-Factor Authentication by modifying the model file to include the OTP module and creating the database columns required for OTP storage.

rails generate devise_otp ModelName

Run the Devise OTP install generator to set up the extension in your Rails application. This generator injects configuration templates into config/initializers/devise.rb and copies the default English locale file to config/locales/devise.otp.en.yml.

rails generate devise_otp:install

The following configuration keys are available for the Devise::Models configuration block to customize OTP behavior:

• otp_authentication_timeout: Duration for which an OTP challenge remains valid.
• otp_drift_window: Number of 30-second windows allowed for clock drift during TOTP validation.
• otp_trust_persistence: Configuration for how long a device is trusted.
• otp_mandatory: Boolean indicating if OTP is required for all users.
• otp_credentials_refresh: Setting for refreshing credentials.
• otp_issuer: The name of the issuer displayed in authenticator apps (defaults to the Rails application's module parent name).
• otp_recovery_tokens: The number of recovery tokens to generate/provide.
• otp_controller_path: The path for the OTP controller.

The module provides methods to verify both standard time-based TOTP tokens and one-time recovery HOTP tokens.

Time-based OTP (TOTP)

Use validate_otp_token(token) or validate_otp_time_token(token) to verify a standard TOTP token. Validation accounts for clock drift based on the configured otp_drift_window.

Recovery OTP (HOTP)

Use validate_otp_recovery_token(token) to verify a recovery token. Note that successful validation of a recovery token automatically increments the otp_recovery_counter on the model.

Unified Validation

validate_otp_token(token, recovery: true/false) allows you to specify which type of token is being provided.

# Validate a standard TOTP token
if user.validate_otp_token(params[:token])
  # success
end

# Validate a recovery token
if user.validate_otp_token(params[:token], true)
  # success
end