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

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 2 段階認証

## 概要

2 段階認証は、メール/パスワードまたは OAuth のログインの後に TOTP（Time-based One-Time Password）を要求する仕組みである。実装には [`totp-rs`](https://github.com/constantoine/totp-rs) を使う。テナントオーナーはテナント全体に 2FA を強制でき、強制されたテナントでは 2FA を満たさない利用者のリソースへのアクセスを `403` で拒否する。パスキーのログインには TOTP を要求しない。パスキーは[パスキー認証](https://docs.koyori.app/dev/features/auth/passkeys)、OAuth は [OAuth ログイン](https://docs.koyori.app/dev/features/auth/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` が初回のコードを確かめて有効にする。どちらも半認証のセッションで呼べるので、テナントの強制で半認証になった利用者もここで設定を済ませられる。

```mermaid
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` になる。

```mermaid
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=...` へリダイレクトする。

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

```mermaid
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](https://docs.koyori.app/dev/features/admin#api) にある。

### テナントの強制

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

```mermaid
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](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/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 段階認証を有効化・無効化し、リカバリーコードを再生成する操作は、アカウント設定の[セキュリティ](https://docs.koyori.app/dev/features/account-settings#セキュリティ)の画面にある。上の入力とセットアップの部品を埋め込んで使う。

## 未実装と既知の制限

次の画面が無い。

| 無い画面 | 内容 |
|---|---|
| テナントの強制 | `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` で拒むので、画面から消せない。次のサインインで置き換わる |

Source: https://docs.koyori.app/dev/features/auth/2fa/index.mdx
