Two Factor Authentication

Abstract

1. Introduction

Two factor authentication extension for Devise

2. Objective

Two factor authentication extension for Devise

This project demonstrates how Ruby can be applied to a real-world Cybersecurity & Ethical Hacking problem.

3. Key Features / Modules

• Support for 2 types of OTP codes
• Codes delivered directly to the user
• TOTP (Google Authenticator) codes based on a shared secret (HMAC)
• Configurable OTP code digit length
• Configurable max login attempts
• Customizable logic to determine if a user needs two factor authentication
• Configurable period where users won't be asked for 2FA again
• Option to encrypt the TOTP secret in the database, with iv and salt

4. Technology Stack

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Ruby and Bundler
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/Houdini/two_factor_authentication.git
cd two_factor_authentication

1. :second_factor_attempts_count
2. :encrypted_otp_secret_key
3. :encrypted_otp_secret_key_iv
4. :encrypted_otp_secret_key_salt
5. :direct_otp
6. :direct_otp_sent_at
7. :totp_timestamp

devise :database_authenticatable, :registerable, :recoverable, :rememberable,
       :trackable, :validatable, :two_factor_authenticatable

rails g migration AddTwoFactorFieldsToUsers second_factor_attempts_count:integer encrypted_otp_secret_key:string:index encrypted_otp_secret_key_iv:string encrypted_otp_secret_key_salt:string direct_otp:string direct_otp_sent_at:datetime totp_timestamp:timestamp

add_index :users, :encrypted_otp_secret_key, unique: true

config.max_login_attempts = 3  # Maximum second factor attempts count.
config.allowed_otp_drift_seconds = 30  # Allowed TOTP time drift between client and server.
config.otp_length = 6  # TOTP code length
config.direct_otp_valid_for = 5.minutes  # Time before direct OTP becomes invalid
config.direct_otp_length = 6  # Direct OTP code length
config.remember_otp_session_for_seconds = 30.days  # Time before browser has to perform 2fA again. Default is 0.
config.otp_secret_encryption_key = ENV['OTP_SECRET_ENCRYPTION_KEY']
config.second_factor_resource_id = 'id' # Field or method name used to set value for 2fA remember cookie
config.delete_cookie_on_logout = false # Delete cookie when user signs out, to force 2fA again on login

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add logging and alert notifications (email / Telegram)
• Write a threat model document for the tool
• Package it with Docker for safe lab testing

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Which threat or attack does this project defend against?
2. What detection or protection technique is used and what are its limits?
3. How are false positives and false negatives handled?
4. Which cryptographic algorithms or security standards are involved?
5. What legal and ethical rules apply when testing a tool like this?

9. Source Code & License

This project is developed by Houdini and published on GitHub under the MIT License. Please follow the license terms and credit the original author when you use or modify this code.