概要
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 を更新するotpauthURI は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 を返す。
- TOTP が有効でなければ
400(2fa-not-enabled)を返す require_2faのテナントに関わる利用者なら403(forbidden)を返す。試行の回数を消費する前に拒否する- コードを検証する
- 同じトランザクションで
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 で拒むので、画面から消せない。次のサインインで置き換わる |
