パスキーの基本・実装
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 を、サーバーで作ります。
{
"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 月から主要なブラウザで使えるようになった機能とされています。古いブラウザ向けには変換を自前で書くか、ライブラリを使います)。
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 IDresponse.clientDataJSON: 種類 (webauthn.create)・challenge・オリジンなど、ブラウザが記録した内容response.attestationObject: 認証器のデータ (RP ID のハッシュ、フラグ、署名の回数、credential ID と公開鍵) と attestationresponse.transports: その認証器への接続の方法 (internal、hybrid、usbなど)
3. サーバーが検証する
W3C WebAuthn Level 3 の 7.1 節は、RP が確かめる手順を順に定めています。要点を並べると次のとおりです。
clientDataJSONのtypeがwebauthn.createであるchallengeが、このセッションで発行して保存した値と一致するoriginが、RP として受け付けるオリジンである (iframe の中で使う場合はtopOriginも確かめる)- 認証器のデータの
rpIdHashが、RP ID の SHA-256 ハッシュと一致する - UP (User Present) のフラグが立っている (仕様は、
mediationがconditionalの登録だけを例外としています) - 利用者の確認を必須にしているなら、UV (User Verified) のフラグが立っている
- BE (Backup Eligibility) が立っていないのに BS (Backup State) が立っている、という矛盾が無い
- 公開鍵のアルゴリズムが
pubKeyCredParamsで示したものの 1 つである - attestation の形式に応じて検証し、方針に照らして受け入れるかを決める (
noneを受け入れる方針もある) - credential ID が 1023 バイト以下である
- その 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 本ごとに違います。
出典
関連する記事
実装
RP ID とオリジンの決め方:サブドメインと複数ドメインでパスキーを使う
パスキーの RP ID はあとから変えられません。サブドメインに分かれたサービスや複数のドメインを持つサービスで、RP ID と許可するオリジンをどう決めるか、WebAuthn の仕様のルールと related origin requests を使う場面を整理します。
実装・SealGate
既存のログインにパスキー認証を導入する手順:パスワードを残したまま始める
パスワードのログインを作り直さずに、パスキーを後から足す手順を整理します。RP ID の決め方、ログインの後の登録、ボタンと自動入力のログイン、端末の管理、復旧、パスワードとの併存と閉じる期限まで、公開までに決めることを順に説明します。
実装・SealGate
Next.js (App Router) でパスキーのログインを実装する:Route Handler と自動入力
Next.js の App Router で、既存のログインにパスキーを足す実装例です。Route Handler で options と verify を中継し、ログインの成功で自分のセッションを発行し、入力欄の自動入力とボタンの両方でログインできるようにします。