MFA, passkeys and social login

Passwords alone leave accounts open to phishing and credential stuffing. When a user’s password appears in a leaked database, anyone who finds it can sign in. Multi-factor authentication stops that: even with the password, an attacker still needs a second factor the user carries. Passkeys go further by replacing the password entirely with a key pair on the user’s device. Social login with OAuth lets users sign in with a provider they trust, but only when the Rails app checks a token on the POST that starts the flow; without that check, an attacker can forge the sign-in and bind their own provider account to the victim’s session.

This lesson adds TOTP (Time-Based One-Time Password) two-factor authentication with recovery codes, explains passkey registration and sign-in ceremonies, and shows how to add OAuth sign-in without opening a login-CSRFlogin CSRF: An attack where a forged request starts the OAuth flow with the attacker's provider identity, binding it to the victim's session so the attacker can access anything the victim does. hole. It ends with a comparison of the Rails 8 authentication generator, Devise and Rodauth for different app sizes.

TOTP adds a second factor from a shared secret and the clock

TOTPTOTP: Time-based One-Time Password: a six-digit code derived from a shared secret and the current 30-second Unix time step, used as a second factor. is the second factor most users know: an authenticator app such as Google Authenticator or Authy shows a six-digit code that changes every 30 seconds. The server and the app share a secret; both compute the same code from that secret and the current Unix time divided by 30.

The rotp gem (6.3.0) implements RFC 6238 in Ruby:

# TOTP enrolment with rotp: secret generation, provisioning URI, code verification
# and recovery codes stored as SHA-256 digests.
require "rotp"
require "digest"

# --- TOTP secret and provisioning ---
# A real app calls ROTP::Base32.random, which reads SecureRandom and so differs every time. This page needs one
# fixed output, so the secret is drawn from a seeded generator over the Base32 alphabet instead. Never do this in
# an app: a predictable secret is a predictable second factor.
BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567".freeze
secret_rng = Random.new(20_261_018)
base32_secret = Array.new(26) { BASE32_ALPHABET[secret_rng.rand(32)] }.join
puts "Base32 secret: #{base32_secret}"

totp = ROTP::TOTP.new(base32_secret, issuer: "Kaksha")
provisioning_uri = totp.provisioning_uri("teacher@kaksha.example")
puts "Provisioning URI: #{provisioning_uri}"

# --- Verify a code at a fixed time ---
# Unix timestamp 1700000000 is 2023-11-14 22:13:20 UTC
fixed_time = Time.at(1700000000)
code_at_fixed_time = totp.at(fixed_time)
puts "Code at #{fixed_time.utc}: #{code_at_fixed_time}"

# Verify the code at that exact time
verified = totp.verify(code_at_fixed_time, at: fixed_time)
puts "Verified at exact time: #{verified.nil? ? 'no' : 'yes'}"

# --- Drift: accept a code from the previous 30-second step ---
# 1700000000 sits in the step that starts at 1699999980 (1700000000 - 1700000000 % 30).
# The step before it starts at 1699999950, so 1699999975 is inside the PREVIOUS step.
previous_step_time = Time.at(1699999975)
code_previous_step = totp.at(previous_step_time)
puts "Code from previous step (#{previous_step_time.utc}): #{code_previous_step}"

# Without drift, verification at the fixed time fails
verified_no_drift = totp.verify(code_previous_step, at: fixed_time)
puts "Verified previous-step code without drift: #{verified_no_drift.nil? ? 'no' : 'yes'}"

# With drift_behind: 30, it succeeds
verified_with_drift = totp.verify(code_previous_step, at: fixed_time, drift_behind: 30)
puts "Verified previous-step code with drift_behind=30: #{verified_with_drift.nil? ? 'no' : 'yes'}"

# --- Recovery codes: stored as SHA-256 digests, single-use ---
RecoveryCode = Struct.new(:digest, :used) do
  def self.generate(count = 10)
    count.times.map do |i|
      # In production: SecureRandom.alphanumeric(12)
      # Here we use a predictable value for determinism
      plain = "RECOVERY-#{i.to_s.rjust(4, '0')}"
      new(Digest::SHA256.hexdigest(plain), false)
    end
  end

  def matches?(plain)
    Digest::SHA256.hexdigest(plain) == digest
  end

  def consume!
    self.used = true
  end
end

codes = RecoveryCode.generate(3)
puts "\nRecovery codes (show once, never again):"
3.times { |i| puts "  RECOVERY-#{i.to_s.rjust(4, '0')}" }
puts "Stored digests: #{codes.map { |c| c.digest[0..15] + '...' }.join(', ')}"

# Attempt to use a recovery code
attempt = "RECOVERY-0001"
matched = codes.find { |c| !c.used && c.matches?(attempt) }
if matched
  matched.consume!
  puts "\nRecovery code #{attempt} accepted and consumed."
else
  puts "\nRecovery code #{attempt} rejected (invalid or already used)."
end

# Second attempt with the same code fails
matched_again = codes.find { |c| !c.used && c.matches?(attempt) }
puts "Second use of #{attempt}: #{matched_again ? 'accepted' : 'rejected (already used)'}"

Base32 secret: E6KMBF6KDVIJLYG232SLC2DGR4
Provisioning URI: otpauth://totp/Kaksha:teacher%40kaksha.example?secret=E6KMBF6KDVIJLYG232SLC2DGR4&issuer=Kaksha
Code at 2023-11-14 22:13:20 UTC: 521373
Verified at exact time: yes
Code from previous step (2023-11-14 22:12:55 UTC): 159710
Verified previous-step code without drift: no
Verified previous-step code with drift_behind=30: yes

Recovery codes (show once, never again):
  RECOVERY-0000
  RECOVERY-0001
  RECOVERY-0002
Stored digests: e93f5082f1e07de1..., d018d77fffdbf936..., 78f34b00cc969f83...

Recovery code RECOVERY-0001 accepted and consumed.
Second use of RECOVERY-0001: rejected (already used)

The example creates a secret, builds the provisioning URI an authenticator app scans, verifies a code at a fixed time and shows that a code from the previous 30-second step is accepted with drift_behind: 30. It then demonstrates recovery codes: stored as SHA-256 digests, each can be used exactly once.

Enrolment stores the secret only after a valid code

A user enables TOTP in their account settings. The server:

1. Generates a random secret and stores it in the user’s session (not yet in the database).
2. Shows a QR code of the provisioning URI and asks the user to scan it.
3. Asks the user to enter the code the app shows.
4. If the code is valid, encrypts that secret with Active Record EncryptionActive Record Encryption: Rails' built-in column encryption with encrypts: the ciphertext is stored in the database and decrypted with keys from credentials, so a database leak does not expose the plain values. and stores it in the database.

Recovery codes are hashed and spent once

A user who loses their phone cannot generate TOTP codes. Recovery codes are a backup: ten random strings printed once at enrolment time. Each can be used once to sign in without a TOTP code.

Store recovery codes as SHA-256 digests, not in plain text. When a user presents one, hash it and compare. If it matches, delete that digest so it cannot be used again. One row per code is enough: belongs_to :user and a digest column with a unique index, so a code can be found by its hash and destroyed once it is spent.

The example above shows a RecoveryCode struct that stores a digest and marks a code as used by deleting it.

Passkeys replace the password with a key pair on the device

Passkeyspasskey: A public-key credential stored on a device (phone, laptop or hardware key) that proves identity by signing a challenge; the private key never leaves the device. replace passwords with a key pair: the private key stays on the device (a phone, a laptop or a hardware key), and the public key goes to the server. Signing in proves the user holds the private key without ever sending it.

The protocol behind passkeys is WebAuthnWebAuthn: The browser API that lets a site register and authenticate passkeys; it talks to the device's authenticator and returns a signed assertion the server can verify.. A Rails app acts as the relying partyIn WebAuthn, the relying party is the server that issues challenges, verifies responses and stores credentials.: it sends challenges and verifies responses. The browser handles the cryptography and talks to the authenticator.

Registration hands the server a public key

Registration creates a credential. The server sends a challenge and user information; the browser asks the authenticator to create a key pair; the authenticator returns a signed attestation that includes the public key. The server stores the public key and the credential ID.

The JSON shapes the server and browser exchange:

# WebAuthn challenge shapes (illustrative, no actual WebAuthn ceremony)
#
# This script prints the JSON shapes a Rails server and browser exchange
# during passkey registration and authentication. It uses plain hashes,
# not the webauthn-ruby gem, because that gem is not installed in the
# pinned toolchain. The shapes follow the WebAuthn specification.
require "json"
require "base64"

# A server draws the challenge and the user handle from SecureRandom, so they differ on every request. This page
# needs one fixed output, so both come from a seeded generator here. A real challenge is unpredictable or it does
# not prevent replay.
BYTES = Random.new(20_261_019)

# --- Registration (credential creation) challenge ---
# The server sends this to navigator.credentials.create()

def base64url(bytes)
  Base64.urlsafe_encode64(bytes, padding: false)
end

user_id = base64url(BYTES.bytes(16))
challenge = base64url(BYTES.bytes(32))

registration_options = {
  publicKey: {
    rp: {
      id: "kaksha.example",
      name: "Kaksha"
    },
    user: {
      id: user_id,
      name: "teacher@kaksha.example",
      displayName: "Asha Sharma"
    },
    challenge: challenge,
    pubKeyCredParams: [
      { type: "public-key", alg: -7 },   # ES256 (ECDSA with P-256)
      { type: "public-key", alg: -257 }  # RS256 (RSASSA-PKCS1-v1_5)
    ],
    timeout: 60000,
    authenticatorSelection: {
      residentKey: "preferred",
      userVerification: "preferred"
    },
    attestation: "none"
  }
}

puts "=== Registration challenge (server to browser) ==="
puts JSON.pretty_generate(registration_options)

# --- Authentication challenge ---
# The server sends this to navigator.credentials.get()
# allowCredentials lists the credential IDs the user has registered

credential_id_1 = base64url(BYTES.bytes(32))
auth_challenge = base64url(BYTES.bytes(32))

authentication_options = {
  publicKey: {
    rpId: "kaksha.example",
    challenge: auth_challenge,
    timeout: 60000,
    userVerification: "preferred",
    allowCredentials: [
      {
        type: "public-key",
        id: credential_id_1,
        transports: ["internal", "hybrid"]
      }
    ]
  }
}

puts "\n=== Authentication challenge (server to browser) ==="
puts JSON.pretty_generate(authentication_options)

# --- Key fields explained ---
puts "\n=== Key fields ==="
puts "rp.id: The relying-party ID (domain). The authenticator binds the credential to it."
puts "user.id: A server-chosen identifier for the user (not the email)."
puts "challenge: A random value the authenticator signs; prevents replay."
puts "pubKeyCredParams: Which algorithms the server accepts (ES256 and RS256 here)."
puts "allowCredentials: During authentication, the credential IDs the user has registered."

=== Registration challenge (server to browser) ===
{
  "publicKey": {
    "rp": {
      "id": "kaksha.example",
      "name": "Kaksha"
    },
    "user": {
      "id": "Z0aAtdB2RULoUJH3E-t-xQ",
      "name": "teacher@kaksha.example",
      "displayName": "Asha Sharma"
    },
    "challenge": "becGLSu7Mw7d_8peoP70BGiAAljSyW6MkELOvC6ibxM",
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -7
      },
      {
        "type": "public-key",
        "alg": -257
      }
    ],
    "timeout": 60000,
    "authenticatorSelection": {
      "residentKey": "preferred",
      "userVerification": "preferred"
    },
    "attestation": "none"
  }
}

=== Authentication challenge (server to browser) ===
{
  "publicKey": {
    "rpId": "kaksha.example",
    "challenge": "ePiCbT-E8S4LHBCbx3YTZyZdA8B9i4y2LWSOJk9iU9o",
    "timeout": 60000,
    "userVerification": "preferred",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "oQRBWSZ77cfG7MSJ-xvMuXI-GPJqbYv40vRzUjYsDO4",
        "transports": [
          "internal",
          "hybrid"
        ]
      }
    ]
  }
}

=== Key fields ===
rp.id: The relying-party ID (domain). The authenticator binds the credential to it.
user.id: A server-chosen identifier for the user (not the email).
challenge: A random value the authenticator signs; prevents replay.
pubKeyCredParams: Which algorithms the server accepts (ES256 and RS256 here).
allowCredentials: During authentication, the credential IDs the user has registered.

Sign-in proves the device still holds the private key

When the user signs in, the server sends a new challenge and a list of credential IDs the user has registered. The browser asks the authenticator to sign the challenge with the matching private key. The server verifies the signature with the stored public key.

The relying-party ID ties a credential to one domain

The relying-party IDrelying-party ID: The domain (without port) a passkey credential is bound to; a page on any other domain gets no signature from that credential, which stops phishing. is usually the domain: kaksha.example for an app at https://kaksha.example. The authenticator binds the credential to this ID, so a credential created for kaksha.example cannot be used on attacker.example.

The origin the browser sends must match the ID. The spec allows the relying-party ID to be a registrable domain suffix of the origin’s effective domain, so a credential created with the ID kaksha.example works on both kaksha.example and staging.kaksha.example. Set the ID to the registrable parent domain (no leading dot), or register a separate credential on staging.

OAuth sign-in starts with a POST so login CSRF cannot forge it

OAuth and OpenID Connect let users sign in with a provider such as Google, GitHub or Microsoft. The user does not create a password on your site; your app trusts the provider to authenticate them.

The OmniAuth gem handles the OAuth flow. In OmniAuth 2.x, the provider login starts with a POST to /auth/:provider, not a GET. This change prevents login CSRF: an attacker who tricks a user into clicking a link to /auth/github cannot bind the attacker’s GitHub account to the victim’s session, because a GET does not start the flow.

The omniauth-rails_csrf_protection gem (2.0.1) adds one more check: it requires Rails’ authenticity token on that POST. Without this gem, an attacker could still forge a POST from another site (browsers send cookies by default). With it, the POST must carry the token from the Rails form or the CSRF meta tag:

# config/initializers/omniauth.rb
#
# OmniAuth 2.x with omniauth-rails_csrf_protection.
# The provider login (POST /auth/:provider) checks Rails' authenticity token.
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :github,
           Rails.application.credentials.github[:client_id],
           Rails.application.credentials.github[:client_secret],
           scope: "user:email"

  provider :google_oauth2,
           Rails.application.credentials.google[:client_id],
           Rails.application.credentials.google[:client_secret],
           scope: "email,profile"
end

# omniauth-rails_csrf_protection checks the authenticity token on POST.
# GET requests to /auth/:provider return 404 (OmniAuth 2.x default).
OmniAuth.config.allowed_request_methods = [:post]

The OWASP CSRF Prevention Cheat Sheet recommends token verification on login forms. This gem applies that recommendation to OmniAuth’s provider POST.

Link an account only by a verified email

When a user signs in with a provider for the first time, your app must decide whether to create a new account or link to an existing one. The safest rule: link only when the provider reports a verified email that matches an existing account’s verified email. Never link by unverified email; the attacker could register with any address at a permissive provider.

The generator, Devise and Rodauth each fit a different app

The Rails 8 authentication generator gives you code you own: a User model, a Session model, a Current object and controllers for sign-in, sign-out and password reset. You add sign-up, email verification, MFA and social login yourself.

Devise (5.0.4) bundles modules for confirmable, lockable, recoverable, rememberable, trackable and more. It generates views and controllers and handles many edge cases.

Rodauth (via rodauth-rails 2.2.3) is a security-first library with a different philosophy. It stores sessions in the database by default, supports MFA and WebAuthn out of the box, and enforces strict defaults.

Practise

Interview questions

Warm-up (fresher to 2–5 years): What is a passkey, in one sentence, and how is it different from a password?

A passkey is a public-key credential stored on a device (phone, laptop or hardware key) that proves identity by signing a challenge with a private key the server never sees. A password is a shared secret: both the user and the server (as a hash) hold the same value, and anyone who learns it can use it. A passkey cannot be phished because the authenticator checks the origin before signing; a password can be entered on a spoofed page.

Key takeaways

• TOTP adds a second factor by computing a code from a shared secret and the current time; store that secret encrypted and provide recovery codes hashed and single-use.
• Passkeys replace passwords with a key pair: the private key stays on the device, the server stores the public key, and signing proves possession without revealing the key.
• The passkey registration and authentication ceremonies exchange challenges and signed responses; the authenticator binds credentials to the relying-party ID, which stops phishing.
• OmniAuth 2.x starts provider login with POST, and omniauth-rails_csrf_protection checks the Rails authenticity token on that POST, which together prevent login CSRF.
• Link a provider account to an existing user only when both the provider and your app have verified the same email address.
• The generator, Devise and Rodauth fit different projects: the generator for full control, Devise for its modules, Rodauth for security-first defaults.