実装・SealGate
Next.js (App Router) でパスキーのログインを実装する:Route Handler と自動入力
7 分で読めます
この記事の要点
- パスキーの登録とログインは「options を取る → ブラウザで署名 → verify に送る」の 2 往復で、Next.js では 1 つの動的な Route Handler で受けられる。
- Next.js 15 以降は Route Handler の params と cookies() が Promise なので、await してから使う。
- 登録はログイン済みの利用者だけに許し、signed_in はブラウザの値ではなくサーバーのセッションで決める。
Next.js の App Router でパスキーのログインを足すには、app/api/passkey/[step]/route.ts の 1 つの Route Handler で options と verify の 2 つの要求を受け、ブラウザ SDK から届いた JSON に API キーを付けて SealGate に中継します。ログインの verify が成功したら、受け取った external_id で既存のセッションを発行します。Next.js 15 以降は Route Handler の params と cookies() が Promise なので、どちらも await してから使います。登録はログイン済みの利用者だけに許し、signed_in はサーバーのセッションで決めます。
全体の流れ
パスキーの登録もログインも、2 往復で終わります。
- ブラウザ: SDK が
/api/passkey/optionsに{ kind: 'login' }を POST - Route Handler: SealGate の
POST /v1/login/optionsを呼び、challenge_idとoptionsを返す - ブラウザ: 端末の認証 (指紋・顔・画面ロック) で署名し、SDK が
/api/passkey/verifyに送る - Route Handler:
POST /v1/login/verifyを呼び、成功ならexternal_idで自分のセッションを発行
API キーはサーバーだけが持ち、ブラウザには出しません。WebAuthn の challenge の生成や署名の検証は SealGate が行い、利用者の情報とセッションは開発者側に残ります。
準備
- Next.js 15 以降 (App Router)
- SealGate の管理画面でプロジェクトを作り、テスト環境の API キー (
sk_test_で始まる) を発行する。テスト環境はrp_idがlocalhost、許可するオリジンがhttp://localhost:3000で始まるので、next devの既定のポートでそのまま試せる .env.localにSEALGATE_API_KEY=sk_test_...を書く (NEXT_PUBLIC_は付けない。付けるとブラウザに出る)- ブラウザ SDK を入れる:
npm install sealgate-browser
既存のログインには、少なくとも次の 2 つの関数があるものとします。名前は例です。
getCurrentUser(): 今のリクエストのログイン中の利用者を返す (いなければnull)createSession(userId): その利用者のセッションを発行し、Cookie を付ける
Route Handler
app/api/passkey/[step]/route.ts を作ります。step には options か verify が入ります。
// app/api/passkey/[step]/route.ts
import type { NextRequest } from 'next/server';
import { createSession, getCurrentUser } from '@/lib/auth'; // 既存のログインの仕組み
const BASE = 'https://api.sealgate.jp/v1';
async function sealgate(path: string, payload: unknown) {
const res = await fetch(`${BASE}${path}`, {
method: 'POST',
headers: {
authorization: `Bearer ${process.env.SEALGATE_API_KEY}`,
'content-type': 'application/json',
},
body: JSON.stringify(payload),
});
return { res, json: await res.json() };
}
function bad(status: number, code: string, message: string) {
return Response.json({ error: { code, message } }, { status });
}
export async function POST(
req: NextRequest,
{ params }: { params: Promise<{ step: string }> },
) {
const { step } = await params; // Next.js 15 以降、params は Promise
const body = await req.json();
if (step !== 'options' && step !== 'verify') return bad(404, 'not_found', 'Unknown step');
if (body.kind === 'register') {
// 登録はログイン済みの利用者だけ。signed_in はブラウザの値を使わず、ここで決める
const user = await getCurrentUser();
if (!user) return bad(401, 'unauthorized', 'Sign in first');
const { res, json } =
step === 'options'
? await sealgate('/register/options', {
external_id: user.id, // メールアドレスではなく内部の ID
display_name: user.email, // 認証ダイアログに出す名前
signed_in: true,
})
: await sealgate('/register/verify', {
challenge_id: body.challenge_id,
response: body.response,
name: typeof body.name === 'string' ? body.name : undefined,
});
return Response.json(json, { status: res.status });
}
if (body.kind === 'login') {
if (step === 'options') {
// external_id を付けなければ、端末に保存されたパスキーから選ぶ (自動入力もこの形)
const { res, json } = await sealgate('/login/options', {});
return Response.json(json, { status: res.status });
}
const { res, json } = await sealgate('/login/verify', {
challenge_id: body.challenge_id,
response: body.response,
});
if (!res.ok) return Response.json(json, { status: res.status });
await createSession(json.external_id); // ここからは既存のセッション
return Response.json({ ok: true });
}
return bad(400, 'invalid_request', 'Unknown kind');
}ポイントは 3 つです。
paramsをawaitする。 Next.js 15 で Route Handler のcontext.paramsは Promise になりました。同期的にparams.stepと読むと動きません。- 登録の
nameを verify に渡す。 SDK のsg.register({ name: 'この端末' })で渡した値は、options と verify の両方の POST に入ります。SealGate の/v1/register/verifyはname(64 文字まで) を受け付けるので、端末の呼び名として残せます。 - ログインの応答を絞る。 verify の応答には
end_user_idやcredential_idも入っています。ブラウザが要るのはログインできたかどうかだけなので、ここでは{ ok: true }だけを返しています。
セッションの発行
createSession は既存の仕組みを使います。Cookie で持つ場合、Route Handler では cookies() も await します。
// lib/auth.ts (例)
import { cookies } from 'next/headers';
export async function createSession(userId: string) {
const sessionId = await saveSession(userId); // 既存のセッションの保存先
const cookieStore = await cookies();
cookieStore.set('session', sessionId, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
path: '/',
});
}パスキーのログインでも、パスワードのログインと同じセッションを発行します。セッションの持ち方を分ける必要はありません。
ログインの画面
ログインの画面はクライアントコンポーネントにします。入力欄の自動入力 (conditional UI) を画面の表示と同時に待ち受け、ボタンでのログインも用意します。
// app/login/passkey-login.tsx
'use client';
import { useRouter } from 'next/navigation';
import { useEffect, useState } from 'react';
import { SealGate, SealGateError } from 'sealgate-browser';
const sg = new SealGate({
optionsUrl: '/api/passkey/options',
verifyUrl: '/api/passkey/verify',
});
export function PasskeyLogin() {
const router = useRouter();
const [error, setError] = useState('');
useEffect(() => {
let active = true;
(async () => {
if (!(await SealGate.conditionalMediationAvailable())) return;
try {
// 利用者が候補を選ぶまで解決しない
await sg.login({}, { mediation: 'conditional' });
if (active) router.push('/dashboard');
} catch (e) {
if (e instanceof SealGateError && e.code === 'aborted') return;
if (active) setError('パスキーでログインできませんでした。');
}
})();
return () => {
active = false;
SealGate.abort(); // 画面を離れるときは待ち受けを止める
};
}, [router]);
async function loginWithButton() {
SealGate.abort(); // 自動入力の待ち受けを止めてから始める
try {
await sg.login();
router.push('/dashboard');
} catch (e) {
if (e instanceof SealGateError && (e.code === 'cancelled' || e.code === 'aborted')) return;
setError('パスキーでログインできませんでした。');
}
}
return (
<div>
<input name="username" autoComplete="username webauthn" />
{/* 既存のパスワードの欄とログインボタンはそのまま */}
<button type="button" onClick={loginWithButton}>
パスキーでログイン
</button>
{error && <p role="alert">{error}</p>}
</div>
);
}- 自動入力には、入力欄の
autoComplete="username webauthn"が要ります。React では属性名がautoCompleteです。 SealGate.abort()で中断された呼び出しはcode: 'aborted'で失敗します。ボタンに切り替えたときや、画面を離れたときのものなので、エラーとして表示しません。cancelledは利用者がダイアログを閉じたか時間切れです。これもエラーの表示は控えめにします。
パスキーを登録する画面
登録は、ログイン済みの利用者の設定画面などに置きます。
// app/settings/add-passkey.tsx
'use client';
import { useState } from 'react';
import { SealGate, SealGateError } from 'sealgate-browser';
const sg = new SealGate({
optionsUrl: '/api/passkey/options',
verifyUrl: '/api/passkey/verify',
});
export function AddPasskey() {
const [message, setMessage] = useState('');
async function add() {
try {
await sg.register({ name: 'この端末' });
setMessage('パスキーを登録しました。次回からこの端末でログインできます。');
} catch (e) {
if (!(e instanceof SealGateError)) throw e;
if (e.code === 'already_registered') setMessage('この端末には登録済みです。');
else if (e.code === 'cancelled') setMessage('');
else setMessage('登録できませんでした。');
}
}
if (!SealGate.supported()) return null; // パスキーに対応していないブラウザでは出さない
return (
<div>
<button type="button" onClick={add}>パスキーを登録する</button>
{message && <p role="status">{message}</p>}
</div>
);
}already_registered は、同じ認証器にこの利用者のパスキーが既にあるときに返ります。SealGate は既存のパスキーを excludeCredentials に入れて返すため、認証器が二重の登録を断ります。
ログインの直後に登録を勧める画面の作り方は ログインの後にパスキーの登録を促す画面 で扱います。
公開の前に確かめること
- 本番の環境を作る。 本番の
rp_id(例:example.jp) と許可するオリジンを設定した本番の環境を足し、sk_live_のキーを本番のサーバーの環境変数に入れる。rp_idの決め方は RP ID とオリジンの決め方 を参照 - CSRF の対策。 Route Handler で状態を変える処理には、既存のフォームと同じ対策 (Origin ヘッダーの確認や CSRF トークン) を入れる。SDK の
extraに渡した値は options と verify の両方の POST に付き、fetchInitでヘッダーも足せる - エラーの扱い。 SealGate のエラーは
{ "error": { "code", "message" } }の形で、SDK はそのcodeでSealGateErrorを投げる。challenge_expired(5 分で失効) やverification_failedのときは、もう一度ログインを試せるようにする - 端末の管理。 失くした端末のパスキーを、設定画面から失効できるようにしておく。
GET /v1/users/{external_id}/credentialsでその利用者の鍵を一覧にし、選ばれた鍵がその一覧にあることを確かめてからDELETE /v1/credentials/{credential_id}を呼ぶ
API の詳細は ドキュメント を参照してください。料金は LP の料金表 にあります。
よくある質問
Server Actions で書けますか?
SDK は optionsUrl と verifyUrl に JSON を POST する作りなので、Route Handler で受けるのが素直です。
params を await しないとどうなりますか?
Next.js 15 以降、params は Promise です。params.step を同期的に読むと期待した値になりません。
Pages Router でも使えますか?
使えます。API Routes で同じように options と verify を中継します。
出典
関連する記事
パスキーの基本・実装
WebAuthn の登録の流れ:challenge・options・verify で何を確かめるか
パスキーの登録(WebAuthn の registration ceremony)を、サーバーが作る options、ブラウザの create()、サーバーでの検証、保存するデータの順に整理します。W3C WebAuthn Level 3 の手順に沿って確かめる項目を説明します。
実装
パスキーの自動入力(conditional UI)の実装:入力欄の候補にパスキーを出す
ユーザー名の入力欄の自動入力にパスキーを出す conditional UI(conditional mediation)の仕組みと実装を整理します。autocomplete の指定、対応の確かめ方、challenge の扱い、ボタンとの切り替えと中断、つまずきやすい点です。
実装・SealGate
既存のログインにパスキー認証を導入する手順:パスワードを残したまま始める
パスワードのログインを作り直さずに、パスキーを後から足す手順を整理します。RP ID の決め方、ログインの後の登録、ボタンと自動入力のログイン、端末の管理、復旧、パスワードとの併存と閉じる期限まで、公開までに決めることを順に説明します。