実装・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 往復で終わります。

  1. ブラウザ: SDK が /api/passkey/options に { kind: 'login' } を POST
  2. Route Handler: SealGate の POST /v1/login/options を呼び、challenge_id と options を返す
  3. ブラウザ: 端末の認証 (指紋・顔・画面ロック) で署名し、SDK が /api/passkey/verify に送る
  4. 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 が入ります。

ts
// 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 します。

ts
// 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) を画面の表示と同時に待ち受け、ボタンでのログインも用意します。

tsx
// 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 は利用者がダイアログを閉じたか時間切れです。これもエラーの表示は控えめにします。

パスキーを登録する画面

登録は、ログイン済みの利用者の設定画面などに置きます。

tsx
// 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 を中継します。

出典

関連する記事

ブログの一覧へ