WebAuthnクライアント機能

Passkeys Cheat Sheet — dev-focused WebAuthn reference. Trusted by Ally, Stanford CS & more.

Get Cheat Sheet

WebAuthnは、パスキーの基盤となる最新の標準規格です。従来のパスワードに依存するのではなく、公開鍵暗号を活用することで、生体認証（指紋や顔認識）や物理的なセキュリティキーを含むパスキーでの認証を可能にします。この変化はセキュリティを強化するだけでなく、パスワード管理の煩わしさをなくすことでユーザー体験（UX）を大きく向上させます。

WebAuthn Level 3標準では、新しいクライアント機能（ブラウザAPIの getClientCapabilities() を通じて取得可能）が導入されました。これは、開発者やプラットフォームがパスキーを実装する際に、より多くのコントロールと柔軟性を持てるようにすることを目的としています。これらのアップデートにより、デバイス、ブラウザ、プラットフォーム間でパスキーを統合するプロセスがシンプルになり、よりスムーズで一貫したユーザー体験を提供できるようになります。

この記事では、以下の疑問にお答えします。

1. WebAuthnクライアント機能とは何か？
2. どのようなWebAuthnクライアント機能が存在するのか？
3. WebAuthnクライアント機能はパスキーの実装をどう改善するのか？
4. なぜWebAuthnクライアント機能が開発者やプロダクトマネージャーにとって重要なのか？

最後まで読めば、現代のユーザーの期待に応える、シームレスで安全な認証フローを作成するために、これらの機能をどう活用できるかがわかるはずです。

WebAuthnクライアント機能とは、ブラウザやプラットフォームが「どのWebAuthn機能をサポートしているか」を伝えるための仕組みです。簡単に言うと、ユーザーのデバイスで利用できる認証方法や設定をWebサイトに知らせる「機能のチェックリスト」のような役割を果たします。これにより、クライアントの機能に合わせて認証フローを最適化し、よりスムーズで安全な体験を提供できるようになります。

例えば、ブラウザが生体認証（Touch IDなど）をサポートしていると通知してきた場合、指紋でログインするオプションをユーザーに提示するようログインフローを設計できます。逆に、ブラウザが特定の機能をサポートしていない場合は、パスワードやSMSによるワンタイムパスワード（OTP）などの代替手段を提供します。実際のところ、サポートされていない機能や途中で中断された認証プロセスは、一般的なブラウザエラーとして表示されることがあるため、チームはこれらの結果を明確なWebAuthnエラー分類にマッピングしておくべきです。

WebAuthn Level 3標準では、パスキーの実装をより多機能で使いやすくするための新しいクライアント機能がいくつか導入されています。getClientCapabilities() API呼び出しの最初のサポートは、Safari 17.4で導入されました。

ブラウザのサポート状況を確認するには、以下のコードスニペットが便利です。

// Check if PublicKeyCredential is supported in the current browser
if (typeof PublicKeyCredential === "undefined") {
    console.log("PublicKeyCredential is not supported in this browser.");
}
 
// Check if getClientCapabilities method exists on PublicKeyCredential
if (typeof PublicKeyCredential.getClientCapabilities === "function") {
    try {
        let capabilities = await PublicKeyCredential.getClientCapabilities();
        console.log(capabilities);
    } catch (error) {
        console.error("Error getting client capabilities:", error);
    }
} else {
    console.log("getClientCapabilities is not supported in this browser");
}

getClientCapabilities() を使用すると、Webサイトやアプリはクライアント（ブラウザやデバイスなど）に問い合わせて、どのWebAuthn機能をサポートしているかを確認できます。クライアントの機能を把握することで、生体認証などの利用可能な機能を最大限に活用し、特定の機能がない場合には代替手段を提供するなど、認証フローを最適化できます。

Subscribe to our Passkeys Substack for the latest news.

Subscribe

ここでは、WebAuthnのクライアント機能と、それがパスキーの統合にどう影響するかを詳しく見ていきましょう。

conditionalCreate は、特定の条件に基づいてパスキーの自動作成を可能にします。パスワードマネージャーが対応していれば、パスワードの自動入力時に自動的にパスキーを作成するといった使い方が考えられます。この機能は、パスワードからパスキーへの移行を自動的に行うことで、パスキーの普及とその後の利用を促進するのに役立ちます。

conditionalCreate と同様に、conditionalGet はパスキーでのログインを自動的にトリガーします。これは、パスワードレスだけでなく、ユーザーネームレス（ユーザー名を入力せず、モーダルやドロップダウンからパスキーを選ぶだけで認証できる状態）を実現する、最高のパスキーUXを提供したいシナリオで非常に役立ちます。この機能を使うことで、適切なタイミングでのみパスキー認証が行われるようになり、不要なプロンプトを減らしてユーザー体験を向上させることができます。

hybridTransport は、パスキーを異なるデバイス間で使用できるようにし、シームレスなクロスデバイス認証（QRコードやBluetooth経由）を実現します。例えば、スマートフォンに保存されたパスキーを使って、デスクトップ上のサービスにログインすることができます。この機能により、デバイスごとにパスキーを手動で転送したり、従来のログイン方法に頼ったりすることなく、安全かつ統合された認証体験を提供できます。

Windows Hello、Face ID、Touch IDなどのプラットフォームオーセンティケーターは、デバイスに直接組み込まれており、生体認証やデバイスネイティブな方法（PINパターンなど）で認証できるため、より高速でスムーズ、かつ安全なパスキー体験を提供します。

userVerifyingPlatformAuthenticator は、パスキー認証にユーザー検証（アクティブな指紋スキャンや顔認識など）が確実に行われるようにし、セキュリティの層をさらに一段階引き上げます。

relatedOrigins 機能により、同じ組織が所有する異なるドメイン（例: amazon.com と amazon.de）間でシームレスな認証が可能になります。例えば、企業が複数のドメインやサブドメインを管理している場合、ユーザーは一度ログインするだけで、各ドメインで再認証することなくすべてのプロパティにアクセスできます。この機能はユーザー体験を効率化し、摩擦を減らすため、国際的な環境やマルチサービスプラットフォームを展開する企業にとって特に価値があります。

signalAllAcceptedCredentials(options) メソッドは、特定のユーザーのWebAuthnクレデンシャルIDの完全なリストを提供します。ユーザーがすでに認証されている場合、プライバシー漏洩のリスクがないため、WebAuthnのリライングパーティは signalUnknownCredential() よりもこのメソッドを使用すべきです。このメソッドは、現在接続されているオーセンティケーターにまだ反映されていない最近の変更を含め、ユーザーの公開鍵クレデンシャルの包括的な概要を提供します。

例を見てみましょう。あるユーザー（userId: A）が、Base64URLエンコードで X と Y となるクレデンシャルIDを持つ2つのパスキーを持っています。その後、ユーザーがWebサービス（example.com）のアカウント設定でパスキーXを削除したとします（公開鍵が削除されます）。ここで、以下のスニペットを実行します。

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "A", // WebAuthn User Handle, Base64URL.
    allAcceptedCredentialIds: ["Y"],
});

上記コードの実行時にオーセンティケーターが利用可能であれば、オーセンティケーターは今後の認証プロセスからパスキーXを削除または非表示にします。ただし、実行時にオーセンティケーターが接続されていない可能性もあるため、リライングパーティはサインインのたびになど、定期的にこのコードを実行することが推奨されます。

allAcceptedCredentialIds に含まれていないパスキーは削除または非表示にされ、元に戻せない可能性があります。そのため、有効なWebAuthnクレデンシャルIDがリストから誤って削除されないよう、リライングパーティは十分に注意する必要があります。有効なクレデンシャルIDを誤って削除してしまった場合、リライングパーティはパスキーの「非表示」を解除するため、できるだけ早く別の signalAllAcceptedCredentials(options) 呼び出しにそのIDを含める必要があります。パスキーが非表示ではなく完全に削除されてしまった場合、修復はほぼ不可能です。

Experiment with passkey flows in the Passkeys Debugger.

Try for Free

signalCurrentUserDetails(options) メソッドは、ユーザーの現在の名前とWebAuthnの表示名をクライアントに伝えます。このメソッドが呼び出されると、クライアントは定義された手順に従ってこのアクションを実行します。

例を見てみましょう。WebAuthnユーザーID A のユーザーが、Webサイト（example.com）のアカウント設定で自分の名前を更新したとします。その際、リライングパーティは以下のコードを実行できます。

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "A", // user ID, Base64URL.
    name: "New user name",
    displayName: "New display name",
});

これにより、オーセンティケーターはローカルに保存されているパスキーのメタデータを更新します。最大のメリットは、将来のConditional UI（条件付きUI）やパスキーの自動入力リクエストにおいて、選択画面やドロップダウンメニューに更新された名前とWebAuthn表示名が表示されるようになる点です。

signalUnknownCredential(options) メソッドは、ユーザーがパスキーを削除した場合など、特定のWebAuthnクレデンシャルIDがリライングパーティによって認識されていないことを知らせます。signalAllAcceptedCredentials(options) とは異なり、このメソッドは受け入れられたクレデンシャルIDの完全なリストやWebAuthnユーザーハンドルを提供する必要がないため、未認証の呼び出し元へのプライバシー漏洩を防ぐことができます。

例を見てみましょう。ユーザーがWebサイト（example.com）のアカウント設定で、クレデンシャルID X のパスキーを削除したとします（公開鍵が削除されます）。しかし、秘密鍵はユーザーのデバイスにまだ残っています。つまり、将来のConditional UIやパスキーの自動入力によるログインリクエスト（allowCredentials リストが空の場合）では、依然としてそのパスキーが選択できてしまいます。しかし、公開鍵はすでに削除されているためログイン試行は失敗します。そこで、リライングパーティは以下を実行すべきです。

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "X", // credential ID the user just tried, Base64URL
});

これにより、オーセンティケーターはクレデンシャルID X のパスキーを将来の認証プロセスから削除または非表示にします。

WebAuthn Level 3標準はまだドラフト段階であるため、これらの新しいクライアント機能の普及はまだ完全ではありません。各ブラウザは徐々にこれらの機能を実装していますが、サポート状況は異なります。以下は、主要なブラウザにおける利用可能状況の最新の概要です。

Level 3が成熟し、より多くのブラウザがこれらの機能を出荷するにつれて、普及のペースは加速していくでしょう。現在どれくらいのユーザーが getClientCapabilities() を利用できるかを確認したい場合は、無料の State of Passkeys で実際のデータを確認できます。ブラウザのリリースノートや関連ドキュメントを定期的にチェックし、今後の幅広い互換性に備えることをお勧めします。

See how many people actually use passkeys.

View Adoption Data

開発者として、この新しいWebAuthnクライアント機能の検出が何を意味し、アプリでどう活用すべきか疑問に思うかもしれません。以下に、これらの機能の活用に関するおすすめのアプローチを紹介します。

ただし、2024年11月時点では、まだすべてのブラウザが getClientCapabilities() APIをサポートしているわけではないことに注意してください。すべてのブラウザが対応するまでの間は、こちら で提供されているポリフィルを使用できます。

ページ読み込みや認証フローの開始時に、コードの早い段階で getClientCapabilities() を使用して、クライアントがサポートしている機能を検出しましょう。これにより、デバイスやブラウザで機能するパスキーの機能を動的に提供し、体験をカスタマイズできます。例えば、プラットフォーム認証がサポートされている場合はそれを推奨し、そうでない場合は代替手段（SMS OTPやハードウェアセキュリティキーなど）を提示することができます。

現在パスワードを使用しているWebサイトやアプリにパスキーを追加する場合、conditionalCreate 機能はパスキーの普及を大きく後押しします。対応するクレデンシャルマネージャー（2024年10月時点ではApple Passwordsのみ）でのパスワード自動入力時に、バックグラウンドでパスキーが自動的に生成され、今後の自動入力時にはそのパスキーが優先されるようになります。

パスキーの導入率だけでなく、パスキーによるログインの利用率も高めるためには、conditionalGet をチェックして、デバイスやブラウザがConditional UI（パスキーの自動入力）を利用できるか確認してみてください。この方法なら、OSやブラウザから積極的にパスキーの利用が提案され、パスワードの自動入力よりもさらに手間がかからないため、ユーザーに作成したパスキーでのログインを自然に促すことができます。

hybridTransport を活用して、クロスデバイス認証（QRコードやBluetooth経由）を有効にしましょう。これにより、ユーザーがデスクトップからサービスにアクセスしている場合でも、スマートフォンを使ってシームレスにログインできるようになります。

WebAuthnのクライアント機能は、現在存在しているパスキーのギャップを埋めるための大きな前進です。この記事では、WebAuthnクライアント機能に関する重要な疑問にお答えしました。

1. WebAuthnクライアント機能とは？ これらの機能がブラウザやプラットフォームによる特定の機能のサポート状況を知らせ、開発者が認証フローをより細かく制御できるようになる仕組みを説明しました。
2. どのようなWebAuthnクライアント機能が存在するのか？ getClientCapabilities、conditionalCreate、hybridTransport など、Level 3標準で導入された新しい機能の概要を紹介しました。
3. WebAuthnクライアント機能はパスキーの実装をどう改善するのか？ これらの機能がどのように統合を効率化し、クロスデバイスの利用を強化し、セキュリティを向上させるかについて解説しました。
4. なぜWebAuthnクライアント機能が開発者にとって重要なのか？ これらの機能は、現代のユーザーの期待に応えるシームレスで安全な認証体験の構築に役立ち、実装をより簡単かつ効果的にします。

ぜひ、新しいWebAuthn Level 3の機能を試してみて、ブラウザでの普及状況について最新情報をチェックしてみてください。パスキーを実装し、これらの高度な機能を活用したいとお考えの場合は、専門的なサポートについてお気軽にお問い合わせください。

ページ読み込み時や認証フローの初期段階で getClientCapabilities() を呼び出し、サポートされている機能を動的に検出します。これにより、プラットフォーム認証がサポートされている場合はそれを提示し、サポートされていない場合はSMS OTPやハードウェアセキュリティキーなどの代替手段にフォールバックさせることができます。

signalAllAcceptedCredentials は有効なクレデンシャルIDの完全なリストとWebAuthnユーザーハンドルを必要とするため、プライバシー漏洩を防ぐ目的で、ユーザーが認証されている場合にのみ呼び出すべきです。一方、signalUnknownCredential は完全なリストを必要とせずに、認識できない単一のクレデンシャルIDを通知するため、ログインに失敗した後などの未認証の状況でも安全に呼び出すことができます。

relatedOrigins 機能により、同じ組織が所有する異なるドメイン（例: amazon.com と amazon.de）間でシームレスな認証が可能になります。ユーザーは一度ログインするだけで、各ドメインで再認証することなくすべてのプロパティにアクセスできるため、国際的な環境やマルチサービス環境での摩擦を減らすことができます。

2024年11月現在、すべてのブラウザが getClientCapabilities() をサポートしているわけではないため、一時的な対策として github.com/MasterKale/webauthn-polyfills で利用可能なポリフィルを使用できます。WebAuthn Level 3標準が成熟し、Chrome 133、Edge 133、Firefox 135、Safari 17.4ですでにサポートが出荷されているため、普及は今後加速すると予想されています。

Corbadoについて

Corbadoは、大規模なconsumer認証を運用するCIAMチームのためのPasskey Intelligence Platformです。IDPのログや一般的なanalyticsツールでは見えないものを可視化します。どのデバイス、OSバージョン、ブラウザ、credential managerがpasskeyに対応しているか、なぜ登録がログインにつながらないのか、WebAuthnフローのどこで失敗するか、OSやブラウザのアップデートがいつ静かにログインを壊すか — Okta、Auth0、Ping、Cognito、あるいは自社IDPを置き換えることなく、すべてを把握できます。2つのプロダクト：Corbado Observeは passkeyとその他あらゆるログイン方式のobservabilityを提供します。Corbado Connectは analytics内蔵のmanaged passkeyを追加します（既存のIDPと併用）。VicRoadsはCorbadoで500万人超のユーザーにpasskeyを提供しています（passkey有効化率+80%）。 Passkeyエキスパートに相談する →