2要素認証ログインの実装について

こんにちは、YOUTRUSTのやまでぃ（YOUTRUST/X）です。

最近のわたくしごとですが

きんぴらごぼうにハマっています。しらたきも入れちゃいます。ごぼうとにんじんを切って炒め、醤油酒みりん大さじ2と砂糖と出汁を少々とで10分くらい煮込めば完成です。食べる前に冷ますことを忘れずに。火が入ることと味が染みることは別で、冷める過程で染みていくようです。直近1ヶ月くらいで今まで人生で食べたごぼうの量を超えたと思います。

今回はなんの話？

Railsアプリケーションにログイン時に2要素認証を導入する方法について、具体的なコードと共に紹介します。

今回紹介する2要素認証について

今回は、認証の三大要素「記憶」「所有」「生体」のうちの、メールアドレスとパスワードによる「記憶」と、スマホのAuthenticatorによる「所有」の2要素で認証を行う例を紹介します。

実際にYOUTRUSTの本番環境で動作しているコードではないですが、多少簡略化しつつも実際のコードに近い内容となっています。雰囲気を掴んでもらえたらうれしいです。

具体的には下記のような機能になります。

2要素認証の設定（ログイン後の設定画面など）
- 2要素認証が設定されていない場合、
  - 設定開始ボタンを押下すると、QRコードとコード入力フォームが出現する。
  - QRコードをスマホのAuthenticatorで読み取る。
  - Authenticatorに表示されている正しいコードをフォームに入力する。
  - 複数個のバックアップコードが表示されて設定が完了する。
- 2要素認証が設定されている場合、
  - 解除することができる。（バックアップコードも無効になる）
ログイン画面
- 2要素認証が設定されていない場合、
  - メールアドレスとパスワードでログインできる。
- 2要素認証が設定されている場合、
  - メールアドレスとパスワードの入力後、コード（6桁の数字）入力画面に遷移。
  - 正しいコードを入力するとログインできる。
- 2要素認証が設定されているが、Authenticatorにアクセスできない場合、
  - メールアドレスとパスワードの入力後、バックアップコード入力画面に遷移できる。
  - 正しいバックアップコードを入力するとログインできる。（使用したコードは使えなくなる）

コード紹介

それではここから大量のコードを例示しつつ、上記の実装方法について紹介していきます！

※大事なことなので改めて、本記事で紹介するRailsのアプリケーションコードは記事用の擬似的なコードです。弊社の実際のコードとは異なり簡略化されています。実際に本番環境のアプリケーション上に実装する際は、リリース前に脆弱性診断を受けることをおすすめします。（or OPEN CODEでは実際のコードを公開しているので是非参加してみてください）

※「UseCaseやCommandって何？」と思われた方は、こちらを参照してください。

使用gem
関連Models
- User
- UserTwoFactorAuthentication
関連ルーティング
関連Controllers（2要素認証の設定）
- Api::TwoFactorAuthenticationController
- Api::TwoFactorAuthenticationBackupCodesController
関連UseCases（2要素認証の設定）
- CreateTwoFactorAuthenticationUseCse
- （省略）ActivateTwoFactorAuthenticationUseCase
- （省略）DestroyTwoFactorAuthenticationUseCase
- （省略）GenerateTwoFactorAuthenticationBackupCodesUseCase
関連Commands（2要素認証の設定）
- CreateTwoFactorAuthenticationCommand
- ActivateTwoFactorAuthenticationCommand
- （省略）CreateTwoFactorAuthenticationCommand
- GenerateTwoFactorAuthenticationBackupCodesCommand
関連Controllers（ログイン）

使用gem

Devise…言わずと知れたRackベースの認証ライブラリ
Devise-Two-Factor...2要素認証のためのDevise拡張ライブラリ
RQRCode...文字列であるURLをQRコードの画像に変換してくれるライブラリ

関連Controllers（ログイン）

class SignInController < ApplicationController
  include OtpSessionMethods

  prepend_before_action :require_no_authentication, only: :create
  prepend_before_action :allow_params_authentication!, only: :create

  def create
    # see: https://github.com/heartcombo/devise/blob/main/lib/devise/controllers/helpers.rb#L113
    user = warden.authenticate(:database_authenticatable, scope: :user)

    if !user
      # ログイン失敗（不正なメールアドレス or パスワード）
      flash[:alert] = t('devise.failure.invalid')
      redirect_to sign_in_path
    elsif user.otp_required_for_login?
      # 2要素認証のコード入力画面へ
      sign_out :user

      # [大事] メールアドレスとパスワードの認証は完了していることをセッションで保持
      update_session(user: user)

      redirect_to sign_in_two_factor_authentication_path(state: session_otp_state)
    else
      # ログイン成功
      sign_in user
      redirect_to after_sign_in_path_for
    end
  end
end

class SignInTwoFactorAuthenticationController < ApplicationController
  include OtpSessionMethods

  prepend_before_action :require_no_authentication, only: :create
  prepend_before_action :allow_params_authentication!, only: :create
  before_action :redirect_if_invalid_attempt, only: :create
  before_action :redirect_if_invalid_otp_session, only: :create

  def create
    otp_user_id = delete_session_otp_user_id
    delete_session_otp_user_id_expires_at
    delete_session_otp_state

    user = User.find(otp_user_id)

    # see: https://github.com/devise-two-factor/devise-two-factor/blob/v5.0.0/lib/devise_two_factor/models/two_factor_authenticatable.rb#L36
    if user.user_two_factor_authentication.validate_and_consume_otp!(params[:code])
      # コードによるログイン成功
      sign_in user
      redirect_to after_sign_in_path_for
    else
      flash[:alert] = t('devise.failure.invalid')
      redirect_to sign_in_path
    end
  end

  private

  def redirect_if_invalid_attempt
    return if params[:code].present?

    flash[:alert] = t('devise.failure.invalid_otp_attempt')
    redirect_to sign_in_path
  end
end

class SignInTwoFactorAuthenticationBackupCodeController < ApplicationController
  include OtpSessionMethods

  prepend_before_action :require_no_authentication, only: :create
  prepend_before_action :allow_params_authentication!, only: :create
  before_action :redirect_if_invalid_attempt, only: :create
  before_action :redirect_if_invalid_otp_session, only: :create

  def create
    otp_user_id = delete_session_otp_user_id
    delete_session_otp_user_id_expires_at
    delete_session_otp_state

    user = User.find(otp_user_id)

    # see: https://github.com/devise-two-factor/devise-two-factor/blob/v5.0.0/lib/devise_two_factor/models/two_factor_backupable.rb#L34
    if user.user_two_factor_authentication.invalidate_otp_backup_code!(params[:backup_code])
      user.save!

      # コードによるログイン成功
      sign_in user
      redirect_to after_sign_in_path_for
    else
      flash[:alert] = t('devise.failure.invalid')
      redirect_to sign_in_path
    end
  end

  private

  def redirect_if_invalid_attempt
    return if params[:backup_code].present?

    flash[:alert] = t('devise.failure.invalid_otp_attempt')
    redirect_to sign_in_path
  end 
end

module OtpSessionMethods
  extend ActiveSupport::Concern

  included do
    def redirect_if_invalid_otp_session
      # 必要なセッション値が存在しない場合は、ログイン画面へリダイレクト
      if session_otp_user_id.nil? || session_otp_user_id_expires_at.nil? || session_otp_state.nil?
        flash[:alert] = t('devise.failure.invalid_otp_attempt')
        return redirect_to sign_in_path
      end

      # セッションのstateが不正な場合は、ログイン画面へリダイレクト
      if session_otp_state != params[:state]
        flash[:alert] = t('devise.failure.invalid_otp_attempt')
        return redirect_to sign_in_path
      end

      # セッションが期限切れになっていた場合は、ログイン画面へリダイレクト
      if Time.zone.at(session_otp_user_id_expires_at.to_i <= current_time
        flash[:alert] = t('devise.failure.timeout_otp_session')
        return redirect_to sign_in_path
      end
    end

    def update_session(user:)
      session[:otp_user_id] = user.id
      session[:otp_user_id_expires_at] = 3.minutes.since.to_i # 3分間
      session[:otp_state] = SecureRandom.hex(32)
    end

    def delete_session_otp_user_id
      session.delete(:otp_user_id)
    end

    def delete_session_otp_user_id_expires_at
      session.delete(:otp_user_id_expires_at]
    end

    def delete_session_otp_state
      session.delete(:otp_state)
    end

    def session_otp_user_id
      session[:otp_user_id]
    end

    def session_otp_user_id_expires_at
      session[:otp_user_id_expires_at]
    end

    def session_otp_state
      session[:otp_state]
    end
  end
end