Passkey認証

概要

Passkeyは生体認証（指紋、顔認識）やセキュリティキーを使ったパスワードレス認証です。SDKの auth.passkey 名前空間はWebAuthn APIをラップし、クレデンシャルの作成、アサーション、サーバー側の検証を処理します。

Passkeyとは

PasskeyはFIDO2/WebAuthnクレデンシャルで、ユーザーのデバイスまたはプラットフォーム認証器（iCloudキーチェーン、Googleパスワードマネージャー、Windows Hello）に保存されます：

• フィッシング耐性 — クレデンシャルはオリジン（ドメイン）にバインド
• パスワード不要 — 生体認証またはPINで認証
• デバイス間で同期 — プラットフォーム認証器がクラウド経由でパスキーを同期

サポート確認

PasskeyのUIを表示する前に、ブラウザのWebAuthnサポートを確認します：

// 同期チェック
if (auth.passkey.isSupported()) {
  // Passkeyログインボタンを表示
}

// Conditional UI（オートフィル）が利用可能か確認
const hasConditionalUI = await auth.passkey.isConditionalUIAvailable();

サインアップ

Passkeyで新しいアカウントを作成します。ユーザー作成とWebAuthnクレデンシャル登録を1ステップで行います：

const { data, error } = await auth.passkey.signUp({
  email: '[email protected]',
});

if (error) {
  console.error('サインアップ失敗:', error.message);
  return;
}

console.log('アカウント作成完了:', data.user);
console.log('セッション:', data.session);

サインアップオプション

interface PasskeySignUpOptions {
  /** ユーザーのメールアドレス（必須） */
  email: string;
  /** 表示名（オプション） */
  displayName?: string;
  /** 推奨する認証器タイプ */
  authenticatorType?: 'platform' | 'cross-platform' | 'any';
  /** resident key 要件 */
  residentKey?: 'required' | 'preferred' | 'discouraged';
  /** user verification 要件 */
  userVerification?: 'required' | 'preferred' | 'discouraged';
  /** キャンセル用 AbortSignal */
  signal?: AbortSignal;
}

内部動作

1. SDKがAuthrimサーバーに登録リクエストを送信
2. サーバーがWebAuthn作成オプション（チャレンジ、リライングパーティ情報）を返す
3. ブラウザが生体認証を要求
4. ブラウザが公開鍵クレデンシャルを作成
5. SDKがクレデンシャルをサーバーに送信
6. サーバーがユーザーアカウントを作成、クレデンシャルを保存、セッションを返す

サインイン

既存ユーザーをPasskeyで認証します：

const { data, error } = await auth.passkey.login();

if (error) {
  console.error('ログイン失敗:', error.message);
  return;
}

console.log('おかえりなさい:', data.user);

メールやユーザー名は不要です — ブラウザが現在のオリジンで利用可能なパスキーを提示します。

ログインオプション

interface PasskeyLoginOptions {
  /** Conditional UI（オートフィル）を使用するか */
  conditional?: boolean;
  /** mediation preference */
  mediation?: 'conditional' | 'optional' | 'required' | 'silent';
  /** キャンセル用 AbortSignal */
  signal?: AbortSignal;
}

Conditional UI（オートフィル）

Conditional UIはPasskeyの選択をブラウザのオートフィルメニューに統合します。専用の「Passkeyでサインイン」ボタンの代わりに、保存されたパスワードと同じオートフィルドロップダウンにパスキーが表示されます：

// 利用可能か確認
if (await auth.passkey.isConditionalUIAvailable()) {
  // Conditional UIを開始（非ブロッキング）
  auth.passkey.login({ conditional: true, mediation: 'conditional' })
    .then(({ data, error }) => {
      if (data) {
        console.log('オートフィルでサインイン:', data.user);
      }
    });
}

ヒント

Conditional UIには autocomplete="username webauthn" 属性を持つ <input> 要素が必要です：

<input type="text" autocomplete="username webauthn" placeholder="メールアドレス" />

保留中のConditional UIリクエストをキャンセルするには（例：ページ遷移時）：

auth.passkey.cancelConditionalUI();

追加Passkeyの登録

既存アカウントに新しいパスキーを追加します。ユーザーは既に認証済みである必要があります：

const { data, error } = await auth.passkey.register();

if (error) {
  console.error('登録失敗:', error.message);
  return;
}

console.log('新しいパスキーを登録しました:', data);
// data: PasskeyCredential { credentialId, publicKey, authenticatorType, ... }

これは以下の場合に有用です：

• バックアップとしてセキュリティキーを追加
• 新しいデバイスでパスキーを登録
• 設定/プロフィールページの「パスキーを追加」機能

登録オプション

interface PasskeyRegisterOptions {
  /** Passkey 表示名 */
  displayName?: string;
  /** 推奨する認証器タイプ */
  authenticatorType?: 'platform' | 'cross-platform' | 'any';
  /** resident key 要件 */
  residentKey?: 'required' | 'preferred' | 'discouraged';
  /** user verification 要件 */
  userVerification?: 'required' | 'preferred' | 'discouraged';
  /** キャンセル用 AbortSignal */
  signal?: AbortSignal;
}

エラーハンドリング

よくあるPasskeyエラー：

エラーコード	意味	ユーザーへのアクション
AR003001	WebAuthn非対応	代替ログイン方法を表示
AR003002	ユーザーがセレモニーをキャンセル	リトライまたは代替手段を提供
AR003003	クレデンシャルが見つからない	サインアップまたは別の方法を提案
AR003004	認証器エラー	リトライまたはサポートへ連絡
AR003005	サーバー検証失敗	操作をリトライ

const { data, error } = await auth.passkey.login();

if (error) {
  switch (error.code) {
    case 'AR003002':
      // ユーザーがキャンセル — 何もしないか控えめなメッセージ
      break;
    case 'AR003003':
      // クレデンシャルなし — サインアップを提案
      showMessage('パスキーが見つかりません。サインアップしますか？');
      break;
    default:
      showMessage(error.message);
  }
}

完全な例

import { createAuthrim } from '@authrim/web';

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
});

// サポート確認
if (!auth.passkey.isSupported()) {
  document.getElementById('passkey-section').style.display = 'none';
}

// サインインボタン
document.getElementById('passkey-login').addEventListener('click', async () => {
  const { data, error } = await auth.passkey.login();
  if (error) {
    alert(error.message);
    return;
  }
  window.location.href = '/dashboard';
});

// サインアップボタン
document.getElementById('passkey-signup').addEventListener('click', async () => {
  const email = document.getElementById('email-input').value;
  const { data, error } = await auth.passkey.signUp({ email });
  if (error) {
    alert(error.message);
    return;
  }
  window.location.href = '/dashboard';
});

// パスキー追加ボタン（プロフィールページ、ユーザーは認証済み）
document.getElementById('add-passkey').addEventListener('click', async () => {
  const { data, error } = await auth.passkey.register();
  if (error) {
    alert(error.message);
    return;
  }
  alert('パスキーを追加しました');
});

次のステップ

• Email Code認証 — 代替のパスワードレス方法
• ソーシャルログイン — サードパーティIDプロバイダー
• セッション管理 — ログイン後のセッション操作
• エラーハンドリング — 包括的なエラーハンドリングガイド