概要
WebAuthn(FIDO2)を使い、Touch ID・Face ID・セキュリティキーなどをパスキーとして登録・使用できる。実装には webauthn-rs を使う。パスキーは利用者の検証(生体または端末の PIN)を必須にして認証するので、「所持(デバイス)+ 生体または PIN」の多要素認証として扱う。パスキーのログインは2 段階認証の TOTP を免除し、パスワードなしの完全なログインとして機能する。既存のメール/パスワードや OAuth に追加で登録でき、代替の認証手段になる。
振る舞い
登録
登録はログイン済みの利用者が既存のアカウントにパスキーを足す操作である。規則は次のとおりである。
- メールアドレスが確認済みでなければ
403になる - 同じ利用者の登録は Redis のロックで 1 つに限り、進行中に開始すると
409(passkey-registration-in-progress)を返す - ロックとチャレンジの状態の TTL はどちらも 5 分である
- 1 利用者が複数のデバイスに登録できる。上限は 20 個で、登録の開始時に確かめ、完了時にも利用者の行をロックして確かめ直す
sequenceDiagram
actor U as 利用者
participant F as ブラウザ
participant B as API
participant R as Redis
participant D as DB
F->>B: POST /v1/auth/passkeys/registration/start
B->>R: 登録ロックを取得
B->>D: 件数の上限と登録済みの credential を確認
B->>R: 登録の状態を保存(TTL 5 分)
B-->>F: PublicKeyCredentialCreationOptions
F->>U: navigator.credentials.create で生体または PIN を要求
U-->>F: 認証器の応答
F->>B: POST /v1/auth/passkeys/registration/finish
B->>R: 登録の状態を取り出して削除
B->>B: 応答を検証
B->>D: passkeys に INSERT
B->>R: 登録ロックを解放
B-->>F: 201
registration/finish の失敗は次のとおりである。
| 状況 | 結果 |
|---|---|
| 上限を超える | 409(passkey-limit-exceeded) |
| ロックや状態が無い | 400 |
| 検証に失敗 | 400(webauthn-error)。ロックを解放する |
ログイン
セッションなしでパスキーだけでログインできる。start が発行した challenge_id を finish に渡して、Redis のチャレンジの状態と対応づける。
sequenceDiagram
participant F as ブラウザ
participant B as API
participant R as Redis
participant D as DB
F->>B: POST /v1/auth/passkeys/authentication/start
B->>R: チャレンジの状態を challenge_id で保存(TTL 5 分)
B-->>F: PublicKeyCredentialRequestOptions と challenge_id
F->>F: navigator.credentials.get
F->>B: POST /v1/auth/passkeys/authentication/finish
B->>R: チャレンジの状態を取り出して削除
B->>D: credential_id で passkeys と利用者を取得
B->>B: 署名と sign_count を検証
B->>D: sign_count と last_used_at を更新
B->>B: セッションを発行(2FA なし)
B-->>F: 204
authentication/finish の結果は次のとおりである。
| 状況 | 結果 |
|---|---|
| 成功 | 204。セッションを発行する |
challenge_id の状態が無い |
400 |
| credential が未登録、利用者のメールが未確認、カウンターの逆行 | 401(invalid-credentials) |
| カウンターが非ゼロからゼロに戻った | 401(possible-credential-clone) |
| 凍結済みの利用者 | 403(account-suspended) |
| 署名の検証に失敗 | 400(webauthn-error) |
Conditional UI
authentication/start の email を省略すると、discoverable credential 用のチャレンジを返す。allowCredentials は空で、mediation: "conditional" が付く。フロントエンドはこの指定で credentials.get() を呼び、ブラウザがパスワードのオートフィルの UI にパスキーを表示する。
email を指定しても、利用者が存在しない・未確認・パスキー未登録なら同じ discoverable のチャレンジに切り替える。パスキーがある場合だけ allowCredentials に credential を列挙する。
再認証
パスキーの追加と削除は、直近の本人確認を求める。セッション cookie だけで通すと、cookie を盗んだ者が自分の鍵を足して居座れる(足した鍵はパスワードの変更の後も残り、パスキーのログインは TOTP も免除する)。足すのを止めても、正規の鍵を消されて締め出されるので、削除も求める。
| 操作 | 再認証 |
|---|---|
登録(registration/start と registration/finish) |
要る。最初の 1 件目も要る |
削除(DELETE /v1/auth/passkeys/{id}) |
要る |
| 一覧・名前の変更・パスキーでのログイン | 要らない |
再認証の手段を足す操作にも、同じ再認証を求める。足す操作が cookie だけで通ると、盗んだ者が、自分の連携を結ぶか自分のパスワードを付けてから、それを手段にして再認証を満たし、パスキーの追加へ進める(二手で通る)。
| 操作 | 再認証 | 理由 |
|---|---|---|
OAuth の連携の追加(ログイン中の GET /v1/auth/oauth/{provider}。reauth=true でないもの) |
要る。開始で断る。連携専用の github_app は要らない |
連携は、再認証の手段になる。github_app はログインにも再認証にも使えないので、足しても手段は増えない |
パスワードの初回設定(POST /v1/auth/password) |
要る | パスワードは、再認証の手段になる |
TOTP の登録(setup と verify-setup) |
要らない | TOTP は再認証の手段ではなく、登録で印も立たない。2FA の検証は半認証のセッション専用で、ログイン済みの cookie では呼べない |
有効期間は 300 秒で、環境変数 REAUTH_WINDOW_SECS で変える。満たさなければ 403(reauth-required)を返す。registration/finish は、start の後に期間が過ぎたら同じ 403 を返し、登録のロックを放す。
本人確認をした時刻は、セッションの reauthed_at_ms に持つ。時刻を立てるのは、資格情報で本人と確かめた次の場合だけである。
| 立てる | 立てない |
|---|---|
| パスワードのログイン(2FA が要る利用者は、2FA の検証で立てる) | OAuth の連携の追加(盗まれたセッションで自分の連携を足して、再認証を満たせてしまう) |
| 2FA の検証(TOTP かリカバリーコード) | TOTP の登録の完了 |
| パスキーのログイン | パスワードの初回設定(足すこと自体は再認証を要する) |
| OAuth のログイン(連携の追加ではない) | |
| 下の再認証の API |
手段は次の三つである。パスワードを持たない利用者は、パスキーか連携を使う。メールの確認コードは使わない。
| 手段 | 呼び出し | 失敗 |
|---|---|---|
| パスワード | POST /v1/auth/reauth/password(password)。成功は 204 |
パスワードを持たない利用者は 400(password-not-set)、誤りは 400(invalid-current-password) |
| 既存のパスキー | POST /v1/auth/reauth/passkey/start、続けて POST /v1/auth/reauth/passkey/finish(credential)。自分のパスキーに限る。challenge は Redis に利用者ごとに 1 つ持ち、GETDEL で使い捨てにする。成功は 204 |
パスキーが無ければ start が 404(passkey-not-found)。他人のパスキーは 401、start の無い finish は 400 |
| 結んだ OAuth の連携 | GET /v1/auth/oauth/{provider}?reauth=true(ログイン済みの利用者のみ)。コールバックで、プロバイダーの利用者が、本人に結んだ連携と一致したら立てる。連携は足さず、セッションも作り直さない |
ログインしていなければ開始が 401。ログインに使えないプロバイダー(github_app)は 401。別の利用者の連携は、時刻を残さずに error_redirect_after へ ?oauth_error= を付けて戻し、利用者も連携も増えない |
要否を先に問う
画面は、再認証を求める操作の前に GET /v1/auth/reauth を引き、要否と使える手段を知る。連携の追加は全画面の遷移なので、403 を受けてからでは JSON の頁で止まる。先に問えば、遷移も入力もせずに本人確認を出せる。
| 欄 | 中身 |
|---|---|
fresh |
本人確認の時刻が有効期間の内か |
expires_at |
有効期間の切れる時刻(RFC 3339)。fresh でなければ null |
remaining_secs |
切れるまでの残りの秒数(切り捨て)。fresh でなければ null。画面はこの値で判じる(expires_at を端末の時計と比べると、端末の時計が進んでいるだけで確かめた直後を切れたと見誤る) |
window_secs |
有効期間の長さ(秒) |
methods.password |
パスワードを持つか |
methods.passkey |
パスキーを持つか |
methods.oauth |
再認証に使える連携(開始用の provider、連携一覧と同じ connection_provider、self-hosted の instance_url)。github_app、設定から外したプロバイダー、許可の一覧から外した instance、issuer を替える前の OIDC の連携は含まない |
問うだけでは時刻を立てない。権限は他の再認証の API と同じく、ログイン中の本人(CurrentUser)である。
画面(設定の「認証方法」)の流れは次のとおりである。
- 連携の追加(
github_appを除く)と、パスワードの初回設定の欄を開く前に、GET /v1/auth/reauthを引く。残りの秒数(remaining_secs)が 15 秒以下なら、切れたとみなす。端末の時計は使わない。 - 要れば、本人確認の dialog(
ReauthDialog)を開く。使える手段を同じ重さで並べ、選んだ手段だけをその場で開く。手段が無ければ、サインインし直す道を示す(サインインで時刻が立つ)。 - パスワードかパスキーで確かめたら、dialog を閉じ、押し直さずに元の操作を続ける。
- 連携で確かめる時は、続ける操作の種類と確かめに使った連携を sessionStorage に置いてから移る(パスワードなどの秘密は置かない)。戻った画面は、その記録があれば元の操作を続ける。
?oauth_error=で戻れば、dialog を開き直して知らせる。 - パスワードの初回設定で、打っている間に期間が切れて
403を受けたら、確かめ直して打った字のまま一度だけ撃ち直す。
パスキーの追加と削除の画面は、まだ無い。作る時は、同じ requireRecentAuth と ReauthDialog を使う。
OAuth の再認証では、プロバイダーにも認証を促すため、gitlab・gitlab_selfhosted・oidc の認可 URL に prompt=login を付ける。github と google には、再認証を強いる手段が無いので付けない。その場合も、連携先の本人でなければ、上の照合で断る。
検証の規則
WebAuthn の設定と検証の規則は次のとおりである。
| 項目 | 規則 |
|---|---|
| RP ID | 環境変数 WEBAUTHN_RP_ID。省略時は origin のホスト名 |
| origin の検証 | EMAIL_VERIFICATION_APP_URL の scheme・host・port を origin とし、webauthn-rs が検証する。サブドメインを許す設定はしていない |
| userVerification | required。生体認証またはデバイスの PIN を必須にする |
| residentKey | webauthn-rs の start_passkey_registration の既定で discouraged。discoverable な credential を作るかは認証器による |
| sign_count | 応答のカウンターが 0 より大きければ、DB の値より大きいことを必須とする。カウンターが 0 の場合、DB の値も 0 なら「非対応の認証器」として許容し、DB の値が 0 より大きければクローンの疑いとして拒否する |
| challenge の TTL | Redis で 5 分。GETDEL で取り出すので使い捨てである |
| crossOrigin と topOrigin | 登録と認証の応答の clientDataJSON が crossOrigin: true か topOrigin を持つか、JSON として読めなければ 400(webauthn-error)。webauthn-rs 0.5.5 は登録でしか見ないので、認証の分は task が検める。frame の中から呼ばれた操作を断る。断る時は challenge を取り出す前なので、challenge は消えず(登録ではロックも残る)、同じ challenge に正しい応答を送り直せる |
| credential ID の長さ | 1023 byte を超える credential ID の登録は 400(bad-request)(WebAuthn Level 3 の Registering a New Credential の検証の手順) |
| 最後の認証手段の削除 | パスキーが 1 件で、password_hash IS NULL で、ログイン用の oauth_connections が 0 件なら 403(last-auth-method)。github_app の連携はログインに使えないので数えない |
| メール未確認 | 未確認の利用者は登録できず(403)、認証も通らない(401) |
| 再認証 | 追加(registration/start・registration/finish)と削除、OAuth の連携の追加、パスワードの初回設定は、直近 300 秒以内の本人確認を要する。満たさなければ 403(reauth-required)。再認証を参照 |
環境変数は次のとおりである。
| 変数 | 内容 |
|---|---|
WEBAUTHN_RP_ID |
WebAuthn の RP ID。省略時は origin のホスト名 |
EMAIL_VERIFICATION_APP_URL |
origin の元になるフロントの URL |
REAUTH_WINDOW_SECS |
再認証の有効期間(秒)。既定は 300 |
データ
passkeys の列は次のとおりである。
| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
id |
UUID | PK | |
user_id |
UUID | NOT NULL, FK users CASCADE | |
credential_id |
BYTEA | NOT NULL, UNIQUE | WebAuthn が生成する認証器固有 ID |
public_key |
BYTEA | NOT NULL | webauthn-rs の Passkey を JSON にしたもの。公開鍵を含む |
aaguid |
BYTEA | NULL 可 | 認証器モデルの識別子(16 バイト)。取得できない場合とゼロの場合は NULL |
sign_count |
BIGINT | NOT NULL DEFAULT 0 | 署名カウンター。0 はカウンター非対応の認証器 |
name |
VARCHAR(255) | NOT NULL | 利用者が付けた名前 |
last_used_at |
TIMESTAMPTZ | NULL 可 | |
created_at |
TIMESTAMPTZ | NOT NULL DEFAULT now() |
列の定義は m20260520000000_initial_schema.rs にある。
API
| メソッド | パス | 説明 |
|---|---|---|
| POST | /v1/auth/passkeys/registration/start |
登録チャレンジを発行する |
| POST | /v1/auth/passkeys/registration/finish |
登録を完了して DB に保存する(201)。name は 1〜255 文字 |
| POST | /v1/auth/passkeys/authentication/start |
認証チャレンジを発行する。email は省略できる |
| POST | /v1/auth/passkeys/authentication/finish |
認証を検証してセッションを発行する(204) |
| GET | /v1/auth/passkeys |
登録済みのパスキーの一覧。last_used_at は未使用なら含まない |
| PATCH | /v1/auth/passkeys/{id} |
名前を変更する(204) |
| DELETE | /v1/auth/passkeys/{id} |
削除する(204)。検証の規則の最後の認証手段の削除に当たると 403 |
| GET | /v1/auth/reauth |
再認証の要否(fresh・expires_at・window_secs)と使える手段を返す。要否を先に問うを参照 |
| POST | /v1/auth/reauth/password |
パスワードで再認証する(204)。再認証を参照 |
| POST | /v1/auth/reauth/passkey/start |
パスキーでの再認証のチャレンジを発行する。自分のパスキーに限る |
| POST | /v1/auth/reauth/passkey/finish |
パスキーの署名を検めて再認証する(204) |
| GET | /v1/auth/oauth/{provider}?reauth=true |
結んだ連携で再認証する(OAuth のコールバックで完了) |
registration/start の応答は webauthn-rs の CreationChallengeResponse をそのまま JSON にしたもので、publicKey の下に challenge・rp・user・pubKeyCredParams などが入る。excludeCredentials に登録済みの credential を渡すので、同じ認証器を二重に登録しにくい。
authentication/start の応答は webauthn-rs の RequestChallengeResponse の JSON に challenge_id を足したものである。
{
"publicKey": {
"challenge": "base64url-encoded-challenge",
"rpId": "app.example.com",
"allowCredentials": [{ "type": "public-key", "id": "base64url-credential-id" }],
"userVerification": "required"
},
"challenge_id": "uuid"
}registration/finish の credential と authentication/finish の credential は PublicKeyCredential の JSON である。
認可
| 操作 | 誰が | スコープ |
|---|---|---|
| 登録・一覧・名前の変更・削除 | ログイン中の本人(CurrentUser)。他人のパスキーの ID は 404(passkey-not-found) |
セッション専用。有効な Bearer と半認証のセッションは 403 |
| 再認証(要否・パスワード・パスキー) | ログイン中の本人(CurrentUser)。他人のパスキーは 401 |
セッション専用。半認証のセッションは 403 |
| 認証の開始と完了 | 誰でも | 認証不要 |
強制削除(DELETE /v1/admin/users/{id}/passkeys/{passkey_id}) |
サービス管理者(サービス管理者の API) | セッション専用 |
画面
フロントエンドがパスキーの API を使うのは 1 か所だけである。/settings/security の AuthMethodsSection.vue が GET /v1/auth/passkeys を呼び、最後の認証方法の注意書きを出すために件数を数える(アカウント設定の画面)。
未実装と既知の制限
パスキーの画面は無い。
| 無い画面 | 内容 |
|---|---|
| ログイン画面 | パスキーでのログインボタンと、Conditional UI での候補の表示 |
| セキュリティ設定画面 | /settings/security でのパスキーの一覧・追加・名前変更・削除 |
| パスキーの追加と削除の画面 | 再認証は、連携の追加とパスワードの初回設定と同じ ReauthDialog を使う |
決定の記録
| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-11-04 | パスキーを多要素認証として扱い、ログインで TOTP を免除する | 利用者の検証を必須にして認証するので、「所持(デバイス)+ 生体または PIN」が揃う |
| 2026-11-18 | 画面は操作の前に GET /v1/auth/reauth で要否を問い、要れば本人確認の dialog を先に出す。連携で確かめて戻った後は、押し直さずに元の操作を続ける。github_app の連携の追加には再認証を求めない。連携の照合が違えば、403 の JSON ではなく元の画面へ戻す | 連携の追加は全画面の遷移なので、403 を受けてからでは JSON の頁で止まる。github_app は再認証の手段にならず、足しても二手の経路にならない |
| 2026-11-17 | OAuth の連携の追加(開始)とパスワードの初回設定にも、直近 300 秒以内の再認証を求める。TOTP の登録は求めない | 連携とパスワードは再認証の手段なので、cookie だけで足せると、自分の連携かパスワードを足して再認証を満たし、パスキーの追加へ進める(二手の経路)。TOTP は再認証の手段ではなく、印も立たないので、この経路にならない |
| 2026-11-16 | パスキーの追加と削除に、直近 300 秒以内の再認証を求める。手段はパスワード・既存のパスキー・結んだ連携で、メールは使わない。最初の 1 件目の追加にも求める。連携の追加と TOTP の登録は、再認証として数えない | cookie を盗んだ者が自分の鍵を足して居座る、あるいは正規の鍵を消して締め出す攻撃を防ぐ。論文 The State of Passkeys(USENIX Security 26)が、登録に確認を求めない site の危うさを挙げる。連携や TOTP の追加を数えると、盗まれたセッションで再認証を満たせてしまう |
参考
検証の規則と、再認証・crossOrigin と topOrigin の検め・credential ID の長さの検めは、次の論文の攻撃の型でパスキーの実装を点検した結果を含む。
- 論文: Louis Jannett ほか『The State of Passkeys: Studying the Adoption and Security of Passkeys on the Web』(35th USENIX Security Symposium、2026)。発表ページ。103 サイトを評価し、18 サイトで重大、53 サイトで高い重大度の攻撃が通ったと述べる。
- きっかけ: ITmedia NEWS の記事『パスワードより安全なはずが……パスキー対応103サイトを検証→全てに脆弱性 独大学の調査結果』(2026-11-16)。記事。
直しと、論文の型の対応は次のとおりである。
| 直し | 論文の型と章 |
|---|---|
| credential ID の長さの検め(TASK-546) | 型は「Length of credid」。表「Evaluation Results and Test Catalog」に載る |
| crossOrigin と topOrigin の検め(TASK-545) | 型は「Framing」。章「CWE-1021: Improper Restriction of Rendered UI Layers or Frames」 |
| パスキーの追加と削除の再認証(TASK-543) | 型ではなく所見。章「Part 2: How Websites Implement Passkeys」の「Confirming Passkey Registrations」と「Removing Passkeys」 |
| ログイン開始でのメールごとの有無の扱い(TASK-544。今は直さず、課題として残す) | 型は「Allow Credentials」。章「CWE-204: Observable Response Discrepancy」 |
