Skip to content

2 段階認証

TOTP・リカバリーコード・テナントによる 2FA の強制。ログイン後の入力とセットアップの画面は実装済みで、管理画面は未実装

概要

2 段階認証は、メール/パスワードまたは OAuth のログインの後に TOTP(Time-based One-Time Password)を要求する仕組みである。実装には totp-rs を使う。テナントオーナーはテナント全体に 2FA を強制でき、強制されたテナントでは 2FA を満たさない利用者のリソースへのアクセスを 403 で拒否する。パスキーのログインには TOTP を要求しない。パスキーはパスキー認証、OAuth は OAuth ログインの機能に依存する。

用語

語 意味
第一認証 メール/パスワードまたは OAuth によるログイン
半認証 セッションの half_authed が true の状態。TOTP の入力と設定に関わる API だけが通る
完全認証 セッションの half_authed が false の状態
TOTP が有効 users.totp_enabled が true で、かつ totp_credentials.is_verified が true の状態
2FA を満たす TOTP が有効か、パスキーを 1 件以上登録している状態

振る舞い

TOTP の設定

設定は 2 段階で進む。setup がシークレットを未検証のまま保存し、利用者が認証アプリに登録したあと、verify-setup が初回のコードを確かめて有効にする。どちらも半認証のセッションで呼べるので、テナントの強制で半認証になった利用者もここで設定を済ませられる。

sequenceDiagram
    actor U as 利用者
    participant A as 認証アプリ
    participant B as API
    participant D as DB

    U->>B: POST /v1/auth/2fa/totp/setup
    B->>B: シークレットを生成
    B->>D: 未検証の credential を保存し、古い行を置き換える
    B-->>U: otpauth URI と QR コード(PNG の data URI)
    U->>A: QR コードを読み取る
    A-->>U: 6 桁のコード
    U->>B: POST /v1/auth/2fa/totp/verify-setup
    B->>B: コードを検証
    B->>D: is_verified と totp_enabled を true にし、リカバリーコード 10 個のハッシュを保存
    B-->>U: リカバリーコードの平文
  • TOTP が有効な利用者が呼ぶと 409(2fa-already-enabled)を返す
  • setup を呼ばずに verify-setup を呼ぶと 400(2fa-not-enabled)を返す
  • verify-setup が成功すると、セッションの half_authed を false にしてセッション ID を更新する
  • otpauth URI は otpauth://totp/TaskApp:user%40example.com?secret=BASE32SECRET&issuer=TaskApp の形で、issuer は TOTP_ISSUER の値である

リカバリーコードの平文を返すのは、verify-setup の応答と再生成の応答だけである。

ログイン

第一認証に成功したとき、service::login_session::establish_login_session がセッションを確立する。パスワードと OAuth コールバックの両方がこの関数を呼ぶので、2FA の要否の判定は経路によって変わらない。2FA が必要ならセッションを半認証にする。半認証のセッションでは通常の API が 403 になる。

sequenceDiagram
    actor U as 利用者
    participant B as API
    participant R as セッション(Redis)

    U->>B: POST /v1/auth/login
    B->>B: パスワードを検証
    alt 2FA が必要
        B->>R: user_id と half_authed=true を保存
        B-->>U: 200 と requires_2fa / requires_2fa_setup
        U->>B: POST /v1/auth/2fa/verify
        B->>B: TOTP またはリカバリーコードを検証
        B->>R: half_authed=false にしてセッション ID を更新
        B-->>U: 204
    else 2FA が不要
        B->>R: user_id と half_authed=false を保存
        B-->>U: 204
    end

POST /v1/auth/login の 200 の応答の 2 つの値は別々の条件を表す。requires_2fa は TOTP が有効であること、requires_2fa_setup は TOTP が未設定で、関わるテナントのいずれかが 2FA を強制していることを表す。

oauth_callback は利用者を解決したあとに establish_login_session を呼ぶ。TOTP が有効な利用者も、テナントの強制で TOTP の設定が要る利用者も半認証になる。JSON は返さず、半認証なら {フロントの URL}/auth/2fa?redirect_after=... へリダイレクトする。

セッションの状態遷移は次のとおりである。パスキーのログインは半認証を経ない。

stateDiagram-v2
    state "未ログイン" as anon
    state "半認証 half_authed=true" as half
    state "完全認証 half_authed=false" as full

    [*] --> anon
    anon --> half: 第一認証に成功し 2FA が必要
    anon --> full: 第一認証に成功し 2FA が不要
    anon --> full: パスキーで認証
    half --> full: 2fa/verify に成功
    half --> full: 2fa/totp/verify-setup に成功

POST /v1/auth/logout は AuthUser を使うので、半認証のセッションでは 403 になる。

TOTP の検証

検証の条件は次のとおりである。

項目 値
アルゴリズム HMAC-SHA1(RFC 6238 標準)
桁数 6 桁
ステップ 30 秒
許容スキュー ±1 ステップ(±30 秒)
試行の上限 利用者ごとに最初の試行から 15 分のあいだ 5 回まで

試行の回数は Redis のカウンター 2fa_attempts:{user_id} で数える。コードを検証する前に Lua スクリプトで試行を予約するので、同時リクエストでも 6 回目以降は検証まで進まず 429 になる。5 回目の失敗も 429 を返す。検証に成功するとカウンターを消す。verify-setup・verify・無効化・再生成は TOTP の検証を伴い、同じカウンターを共有する。

リカバリーコード

リカバリーコードの規則は次のとおりである。

  • 生成数は 10 個である
  • 形式は XXXX-XXXX-XXXX で、大文字英数字 12 文字をハイフンで区切る。文字は I・O・0・1 を除く 32 種である
  • HMAC-SHA256 のハッシュのみを DB に保存し、平文は保存しない
  • 比較では入力から英数字以外を取り除いて大文字にしてからハッシュし、未使用の行と比べる。ハッシュの比較には subtle の定数時間比較を使う
  • 1 回使用したら used_at を設定する。更新の条件に used_at IS NULL を含めるので、同じコードの同時使用は 1 回だけ成功する
  • 再生成は古いコードをすべて消し、新しいコードを 10 個返す。要求するのは TOTP のコードで、リカバリーコードでは再生成できない

POST /v1/auth/2fa/verify の本文には code か recovery_code を指定する。両方を指定するとリカバリーコードを検証し、どちらも無ければ 401(invalid-2fa-code)を返す。

無効化

DELETE /v1/auth/2fa/totp の本文には POST /v1/auth/2fa/verify と同じく TOTP かリカバリーコードを指定する。次の順に処理して 204 を返す。

  1. TOTP が有効でなければ 400(2fa-not-enabled)を返す
  2. require_2fa のテナントに関わる利用者なら 403(forbidden)を返す。試行の回数を消費する前に拒否する
  3. コードを検証する
  4. 同じトランザクションで users.totp_enabled = false にし、totp_credentials と recovery_codes の行を消す

サービス管理者は POST /v1/admin/users/{id}/reset-2fa で同じ行を消せる。こちらは対象者のセッションも失効させる。規則はサービス管理者の API にある。

テナントの強制

強制されたテナントに関わる利用者が TOTP 未設定のままパスワードか OAuth でログインすると、セッションは半認証になる。TOTP を設定するか(verify-setup)、パスキーでログインするまで、半認証は解けない。

flowchart TD
    login["パスワードまたは OAuth で第一認証"] --> enabled{"TOTP が有効か"}
    enabled -- はい --> half2fa["半認証。requires_2fa=true"]
    half2fa --> verify["POST /v1/auth/2fa/verify"]
    verify --> full["完全認証"]
    enabled -- いいえ --> forced{"関わるテナントに require_2fa があるか"}
    forced -- いいえ --> full
    forced -- はい --> halfsetup["半認証。requires_2fa_setup=true"]
    halfsetup --> setup["setup と verify-setup"]
    setup --> full

ログイン時の判定と所属判定は基準が違う。ログイン時の半認証の判定は TOTP だけを見るので、パスキー登録済みでもパスワードでログインすると半認証になる。所属判定は登録済みのパスキーも満たす扱いにする。

project にだけ参加しテナントに参加しないゲスト(project-only guest)も、関わるテナントの require_2fa の対象である。

リクエストごとの判定

2FA を満たさない利用者は、そのテナントのリソースへのアクセスを 403(2fa-setup-required)で拒否される。強制前から持っている完全認証のセッション・PAT・Device Token も同じで、ログイン時だけでなくテナントの所属判定(has_tenant_access)がリクエストごとに確かめる。判定は所属が決まった後に行うので、無関係な利用者にテナントの強制設定は漏れない。

所属判定を通らない経路には、同じ判定を個別に置く。

  • オーナー専用の API(テナント更新・削除、Drive クォータ、GitHub 連携など)は、2FA を満たさないオーナーを 403(2fa-setup-required)で拒否する
  • ファイル本文の配信(GET /v1/drive/files/{id}/content)も同じ判定を通す。共有トークン(?token=)での配信は利用者を問わないので対象外である
  • 通知(/v1/users/me/notifications の一覧・未読数・既読化)は 403 にせず、強制下のテナントの通知を結果から外す

2FA の設定 API(/v1/auth/2fa/...)と /v1/auth/me は所属判定を通らないので、未設定の利用者も使える。

強制の切り替え

テナントオーナーは POST /v1/tenants/{tenant_id}/require-2fa で require_2fa を切り替える。応答は更新後のテナントである。

有効化(enabled: true)は、操作する本人が 2FA を満たすときだけ受け付ける。満たさなければ 403(2fa-setup-required)を返し、require_2fa は変えない。

無効化(enabled: false)は、オーナー専用の API の中で唯一 2FA の判定を省き、常に受け付ける。

設定

環境変数は次のとおりである。

変数 既定 内容
TOTP_ENCRYPTION_KEY なし TOTP シークレットの暗号鍵。UTF-8 で正確に 32 バイトでなければ起動できない。OAuth トークンの暗号鍵(HKDF で導出する)とは別の鍵である
RECOVERY_CODE_SECRET なし リカバリーコードの HMAC-SHA256 の鍵。32 文字以上
TOTP_ISSUER TaskApp otpauth URI の issuer

脅威と対策

脅威ごとの対策は次のとおりである。

脅威 対策
ブルートフォース 2fa_attempts:{user_id} で検証前に予約し、最初の試行から 15 分のあいだに 6 回目以降は検証せず 429 を返す。成功で消す
リカバリーコードの漏洩 HMAC-SHA256 のハッシュのみを保存する。平文は生成時の応答でのみ返す
TOTP シークレットの漏洩 AES-256-GCM で暗号化して保存する。otpauth URI を返すのは setup の応答だけである
半認証のセッションの悪用 AuthUser と CurrentUser と AdminUser が half_authed: true のセッションを 403 で拒否する(認可の節)
タイミング攻撃 リカバリーコードのハッシュの比較に subtle の定数時間比較を使う

データ

totp_credentials の列は次のとおりである。

列 型 制約 説明
user_id UUID PK, FK users CASCADE 1 利用者 1 シークレット
secret_enc TEXT NOT NULL AES-256-GCM で暗号化した TOTP シークレット(Base32)。形式は base64(nonce 12 バイト + 暗号文)
is_verified BOOLEAN NOT NULL DEFAULT false 初回コード入力で true になるまで有効扱いしない
created_at TIMESTAMPTZ NOT NULL DEFAULT now()

recovery_codes の列は次のとおりである。

列 型 制約 説明
id UUID PK
user_id UUID NOT NULL, FK users CASCADE
code_hash VARCHAR NOT NULL 正規化したコードの HMAC-SHA256(鍵は RECOVERY_CODE_SECRET)を base64url にした値
used_at TIMESTAMPTZ NULL 可 NULL は未使用
created_at TIMESTAMPTZ NOT NULL DEFAULT now()

既存の表には次の列がある。

列 型 制約 説明
users.totp_enabled BOOLEAN NOT NULL DEFAULT false 無効化で false に戻す
tenants.require_2fa BOOLEAN NOT NULL DEFAULT false テナントの強制

列の定義は m20260520000000_initial_schema.rs にある。

API

メソッド パス 説明
POST /v1/auth/2fa/totp/setup TOTP シークレットを生成し、otpauth URI と QR コードを返す
POST /v1/auth/2fa/totp/verify-setup 初回のコードを検証して有効にし、リカバリーコードを返す
POST /v1/auth/2fa/verify ログイン後に TOTP かリカバリーコードを検証する
DELETE /v1/auth/2fa/totp コードを確かめて 2FA を無効にする
POST /v1/auth/2fa/recovery-codes/regenerate TOTP のコードを確かめてリカバリーコードを再生成する
POST /v1/tenants/{tenant_id}/require-2fa テナントの強制を切り替える

認可

操作 誰が スコープ
setup / verify-setup セッションの利用者。半認証も可 セッション専用。Bearer は 403
2fa/verify 半認証のセッションの利用者 セッション専用
無効化・再生成 完全認証のセッションの利用者 セッション専用。Bearer は 403
require-2fa テナントオーナー セッション専用

半認証の扱いは次のエクストラクタ(handler::extractors)で分ける。PAT と Device Token はセッションを持たないので、half_authed の確認の対象にならない。

エクストラクタ 受理する認証 half_authed の扱い 用途
AuthUser セッション / PAT / Device Token セッションで true なら 403 通常の保護済み API
OptionalAuthUser AuthUser と同じ true のセッションは未認証として扱う コンテンツ配信・OAuth 開始
HalfAuthedUser セッションのみ true を必須とする。false と Bearer は 403 POST /v1/auth/2fa/verify
LoggedInUser セッションのみ 問わない setup / verify-setup
CurrentUser セッションのみ true なら 403 アカウント API
AdminUser セッションのみ true なら 403 /v1/admin/**

画面

ログイン後の入力とセットアップは /auth/2fa(components/auth/TwoFactor.vue)で行う。パスワードのログインが requires_2fa / requires_2fa_setup を返したときと、OAuth コールバックのリダイレクト先がこの画面である。半認証のセッションでも開けるよう、認証ガードの対象から外している。

画面 内容
入力 TOTP のコードとリカバリーコードのどちらでも POST /v1/auth/2fa/verify を実行できる
セットアップ setup の QR コードと手入力用のシークレットを出し、初回コードを verify-setup で確かめる。続けてリカバリーコードを一度だけ表示し、保存の確認(チェックボックス)を経てから先へ進む。コードは画面の中にしか持たないので、開き直しても再掲しない

画面の判別は GET /v1/auth/me と setup の応答で行う。OAuth から直接来るとログインの応答が無いので、この判別を使う。

応答 画面の動作
/v1/auth/me が 200 2FA は済んでいるので戻り先へ進む
/v1/auth/me が 401 期限切れとして再サインインを案内する
/v1/auth/me が 403(半認証) setup を呼ぶ
setup が 409(2fa-already-enabled) 入力の画面にする
setup が 200 セットアップの画面にする

成功後は /v1/auth/me を取り直し、redirect_after へ進む。redirect_after は / 始まりの相対パスだけを受け付ける。// や \ 始まり、外部 URL、/auth/2fa 自身は / にする。

半認証のセッションで通常の画面を開くと /v1/auth/me が 403 になり、認証ガードは /signin ではなく /auth/2fa へ進める。

ロックアウト(429)は案内を出して送信を止める。期限切れ(invalid-2fa-code 以外の 401)は再サインインを案内する。

キャンセルはサインイン画面へ戻すだけである。POST /v1/auth/logout は半認証のセッションを 403 で拒むので、サーバー側のセッションは残り、次のサインインで置き換わる。

ログイン済みの利用者が自分の 2 段階認証を有効化・無効化し、リカバリーコードを再生成する操作は、アカウント設定のセキュリティの画面にある。上の入力とセットアップの部品を埋め込んで使う。

未実装と既知の制限

次の画面が無い。

無い画面 内容
テナントの強制 require_2fa を切り替える設定項目

OAuth を起点に verify まで通す統合テストも無い。

次の項目は、対応するかどうかも決まっていない。

項目 内容
SMS OTP セキュリティが TOTP より低く、SIM スワップ攻撃のリスクがある
メール OTP パスワードリセットの流れに組み込むかどうか
テナントの強制の猶予期間 今は有効化の直後から 403 になる。有効化から何日以内に設定しなければアクセス不可にするか(例: 7 日間の猶予)

決定の記録

日付 決定 理由
2026-05-30 OAuth コールバックもセッションの確立を establish_login_session に任せる OAuth のログインとパスワードのログインで 2FA の判定が食い違わないようにする
2026-09-05 project-only guest も関わるテナントの require_2fa の対象にする ここから漏れると、除名後に残る project_members の行で project へ入れる利用者が 2FA 無しで読み書きできる
2026-10-29 強制の有効化は操作する本人が 2FA を満たすときだけ受け付ける 有効にした途端に本人もテナントの API から締め出される
2026-10-29 強制の無効化は 2FA の判定を省いて常に受け付ける 2FA の無いオーナーが強制下に残った場合の救済経路にする
2026-11-04 パスキーのログインには TOTP を要求しない パスキーは利用者の検証(生体または端末の PIN)を必須にして認証するので、それ自体を多要素認証として扱う
2026-11-04 テナントの所属判定は登録済みのパスキーも 2FA を満たす扱いにする パスキー自体が多要素認証である
2026-11-04 画面のキャンセルはサインインへ戻すだけにし、サーバー側の半認証セッションを消さない POST /v1/auth/logout が半認証のセッションを 403 で拒むので、画面から消せない。次のサインインで置き換わる

Type to search…

↑↓ navigate↵ selectEsc close