パスキーの基本・実装

WebAuthn の登録の流れ:challenge・options・verify で何を確かめるか

11 分で読めます

この記事の要点

  • 登録は「サーバーが options を作る → ブラウザが create() を呼ぶ → サーバーが応答を検証して保存する」の 3 段です。
  • options の要は、1 回限りの challenge、個人情報を含まない user.id、既存の鍵を並べた excludeCredentials、residentKey と userVerification の指定です。
  • 検証では、種類・challenge・オリジン・RP ID のハッシュ・フラグ・アルゴリズムを確かめ、credential ID が他の利用者に登録済みでないことを見てから保存します。

WebAuthn の登録は、サーバーが options (challenge や RP ID、利用者の ID を含む) を作り、ブラウザが navigator.credentials.create() で認証器にパスキーを作らせ、返ってきた応答をサーバーが検証して公開鍵を保存する、という 3 段の流れです。サーバーが確かめるのは、応答の種類が登録であること、challenge が自分の発行したものであること、オリジンと RP ID が正しいこと、利用者の確認などのフラグ、アルゴリズム、そして credential ID が他の利用者に使われていないことです。手順は W3C の WebAuthn Level 3 の「7.1 Registering a New Credential」に定められています。

全体の流れ

ブラウザ                     サーバー (RP)                    認証器
   |  1. 登録を始めたい  -->   |                                 |
   |  <-- 2. options          | challenge を作って保存           |
   |  3. create(options) -------------------------------------->  |
   |                          |       利用者の確認・鍵の組の作成  |
   |  <-------------------------------------- 4. 公開鍵と署名など |
   |  5. 応答を送る  ------>  | 6. 検証して公開鍵を保存          |

登録はログイン済みの利用者に対して行うのが基本です。誰の鍵を作るのかを、サーバーが自分のセッションで決めるためです。

1. サーバーが options を作る

navigator.credentials.create() に渡す PublicKeyCredentialCreationOptions を、サーバーで作ります。

json
{
  "rp": { "id": "example.jp", "name": "Example" },
  "user": {
    "id": "<64 バイトのランダムな値 (base64url)>",
    "name": "taro@example.jp",
    "displayName": "山田 太郎"
  },
  "challenge": "<16 バイト以上のランダムな値 (base64url)>",
  "pubKeyCredParams": [
    { "type": "public-key", "alg": -8 },
    { "type": "public-key", "alg": -7 },
    { "type": "public-key", "alg": -257 }
  ],
  "excludeCredentials": [
    { "type": "public-key", "id": "<登録済みの credential ID>", "transports": ["internal"] }
  ],
  "authenticatorSelection": { "residentKey": "preferred", "userVerification": "preferred" },
  "attestation": "none",
  "timeout": 300000
}

各項目の意味です。

項目 内容
rp.id RP ID。ページのドメインか、その親のドメイン。パスキーはこの範囲でしか使えない
rp.name 認証ダイアログに出すサービス名
user.id user handle。64 バイト以下。仕様は個人を特定する情報 (利用者名やメールアドレス) を入れてはならないとし、64 バイトのランダムな値を推奨している
user.name / displayName ダイアログやパスキーの一覧に出る名前
challenge サーバーが作る乱数。仕様は 16 バイト以上を推奨。サーバー側に保存し、1 回だけ使う
pubKeyCredParams 受け付ける署名アルゴリズム。仕様は少なくとも -8 (EdDSA)、-7 (ES256)、-257 (RS256) を含めるよう推奨している
excludeCredentials この利用者の登録済みの鍵。同じ認証器に 2 本目を作らせないため
authenticatorSelection.residentKey discoverable credential を求めるか。required / preferred / discouraged
authenticatorSelection.userVerification 生体認証や PIN による利用者の確認を求めるか。required / preferred / discouraged
attestation 認証器の出所の証明を求めるか。既定は none
timeout 待ち時間の目安 (ミリ秒)。仕様上はヒントで、ブラウザが変えてよい

challenge の扱い

challenge は、応答が今回の登録のために作られたことを保証するためのものです。サーバー側で、利用者 (またはセッション) と結び付けて保存し、検証に使ったら消します。有効期限も付けます。同じ challenge を 2 回受け付けると、過去の応答を使い回されるおそれがあります。

residentKey と userVerification の選び方

  • 利用者名を入れないログインや、入力欄の自動入力 (conditional UI) を主な入口にするなら、residentKey は required にします。
  • userVerification を required にすると、生体認証や PIN を使えない認証器では登録できなくなります。preferred にして、検証の時点で UV のフラグを記録しておく方法もあります。

attestation

attestation は、認証器の機種や出所を RP が確かめるための、任意の証明です。none にすると、ブラウザは個人を識別しうる情報を識別できない値に置き換えます。特定の認証器だけを許したい社内向けの用途などでなければ、none で足ります。

2. ブラウザが create() を呼ぶ

サーバーから受け取った JSON を、ブラウザの API が受け取れる形に変えて呼び出します。PublicKeyCredential.parseCreationOptionsFromJSON() を使うと、base64url の文字列を ArrayBuffer に戻す処理を自分で書かずに済みます (MDN では 2025 年 3 月から主要なブラウザで使えるようになった機能とされています。古いブラウザ向けには変換を自前で書くか、ライブラリを使います)。

js
const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJSON);
const credential = await navigator.credentials.create({ publicKey });
await fetch('/api/passkey/register/verify', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(credential.toJSON()),
});

認証器は利用者の確認 (指紋・顔・PIN など) をして、RP ID 向けの鍵の組を作ります。excludeCredentials に入っている鍵を既に持つ認証器では、作成を断ります。

返ってくる応答には、主に次のものが入っています。

  • id / rawId: credential ID
  • response.clientDataJSON: 種類 (webauthn.create)・challenge・オリジンなど、ブラウザが記録した内容
  • response.attestationObject: 認証器のデータ (RP ID のハッシュ、フラグ、署名の回数、credential ID と公開鍵) と attestation
  • response.transports: その認証器への接続の方法 (internal、hybrid、usb など)

3. サーバーが検証する

W3C WebAuthn Level 3 の 7.1 節は、RP が確かめる手順を順に定めています。要点を並べると次のとおりです。

  1. clientDataJSON の type が webauthn.create である
  2. challenge が、このセッションで発行して保存した値と一致する
  3. origin が、RP として受け付けるオリジンである (iframe の中で使う場合は topOrigin も確かめる)
  4. 認証器のデータの rpIdHash が、RP ID の SHA-256 ハッシュと一致する
  5. UP (User Present) のフラグが立っている (仕様は、mediation が conditional の登録だけを例外としています)
  6. 利用者の確認を必須にしているなら、UV (User Verified) のフラグが立っている
  7. BE (Backup Eligibility) が立っていないのに BS (Backup State) が立っている、という矛盾が無い
  8. 公開鍵のアルゴリズムが pubKeyCredParams で示したものの 1 つである
  9. attestation の形式に応じて検証し、方針に照らして受け入れるかを決める (none を受け入れる方針もある)
  10. credential ID が 1023 バイト以下である
  11. その credential ID が、どの利用者にもまだ登録されていない

この手順は、ライブラリや外部の API を使えば自分で書く必要はありません。ただ、何を確かめているかを知っておくと、エラーの原因を追いやすくなります。たとえばオリジンの不一致は、テスト環境と本番環境で RP ID やオリジンの設定を取り違えたときによく起きます。

4. 保存するもの

仕様は、登録が通ったときに RP が保存する「credential record」の項目を挙げています。

項目 用途
id (credential ID) ログインのときに鍵を特定する
publicKey 署名の検証に使う
signCount 署名の回数。複製の兆候を見るのに使う
uvInitialized 利用者の確認がされたか
transports 次回のログインで、ブラウザに接続の方法を伝える
backupEligible / backupState 同期できる種類か、いまバックアップされているか

これに、利用者の ID、名前 (「iPhone」など)、登録日時、最後に使った日時を足しておくと、端末の一覧や復旧の画面を作るときに困りません。

よくあるつまずき

  • user.id にメールアドレスを入れる: 仕様に反し、認証器の中に個人情報が残ります。ランダムな値にします。
  • excludeCredentials を渡さない: 同じ認証器に同じ利用者の鍵が増え、一覧で見分けがつかなくなります。
  • challenge を使い回す: 検証に使ったら必ず消します。
  • RP ID とオリジンの取り違え: ページのドメインが RP ID と一致するか、その下にあることを確かめます。

SealGate で実装する場合

SealGate では、options の作成と検証を API が行います。開発者のサーバーは、ログイン済みの利用者について次の 2 つを呼ぶだけです。

  • POST /v1/register/options に external_id (個人を表さない ID) と display_name を渡すと、challenge_id と options が返ります。options.excludeCredentials には既存の鍵が入り、authenticatorSelection.residentKey と userVerification には環境の設定 (resident_key・user_verification) の値が入ります。
  • ブラウザの SDK (sg.register()) が認証器を動かした後、POST /v1/register/verify に challenge_id と response (RegistrationResponseJSON) を渡すと、201 で credential_id と end_user_id が返ります。name (64 文字まで) を付けると端末の呼び名になります。

challenge は 5 分で失効し、1 回しか使えません (410 challenge_expired)。署名の検証に失敗した場合は 401 (verification_failed)、許可していないオリジンからの応答は 403 (origin_not_allowed) です。既にパスキーを持つ利用者に足すときは signed_in: true か recovery_token が要ります。同じ認証器での二重登録は認証器が断り、SDK は already_registered で知らせます。登録した鍵の aaguid・transports・backup_eligible・backed_up は GET /v1/users/{external_id}/credentials で確かめられます。

詳しくは ドキュメントの登録の節 をご覧ください。

よくある質問

challenge はどのくらいの長さにすればよいですか?

WebAuthn の仕様は、少なくとも 16 バイトのランダムな値を推奨しています。暗号論的に安全な乱数から作り、1 回だけ使います。

attestation は direct にした方が安全ですか?

一般向けのサービスでは、none で困ることはほとんどありません。認証器の機種を限りたい場合に、attestation を求めて検証の方針を決めます。

user.id と credential ID は何が違いますか?

user.id は RP が決める利用者の ID で、同じ利用者のすべてのパスキーで共通です。credential ID は認証器が作る鍵ごとの ID で、パスキー 1 本ごとに違います。

出典

関連する記事

ブログの一覧へ