WebAuthnトランスポート：internalとhybridの取り扱い

Passkeys for Super Funds and Financial Institutions
Join our Webinar on 7th November to learn how Super Funds and Financial Institutions can implement passkeys

Join now

注：WebAuthnの仕様では、トランスポートが空の場合はすべてのトランスポートがサポートされていることを意味します。

複数のプラットフォームでパスキーを実装する際、開発者は重要な決断を迫られます。

• 最適なクロスデバイス認証体験を保証するために、WebAuthnのトランスポート、特にinternalとhybridトランスポートをどのように扱うべきか？

その答えは、WebAuthnトランスポートを理解することにあります。これは、認証器がリライングパーティとどのように通信するかを決定する技術的な詳細です。 理論上は単純に見えるトランスポートですが、その実装はウェブブラウザ、ネイティブiOS、ネイティブ Androidアプリケーションで大きく異なり、特にinternalとhybridトランスポートの扱いに違いが見られます。

この記事では、WebAuthnトランスポートがさまざまなプラットフォームでどのように機能するかを検証し、internalとhybridトランスポートを扱うための2つの異なるアプローチを、それぞれのトレードオフと共に紹介します。

この記事の構成：

1. WebAuthnトランスポート：ウェブ、iOS、Androidにおけるinternal、hybrid、プラットフォーム認証器
2. 2つのアプローチ：仕様準拠 vs. 最適化されたinternalおよびhybridトランスポートの取り扱い
3. クロスデバイス認証実装のベストプラクティスと推奨事項

WebAuthnトランスポートは、認証器とクライアントデバイス間の通信方法を定義します。 WebAuthn Level 3仕様では、6種類のトランスポートが定義されています。

usb：YubiKeyや他のFIDO2セキュリティトークンなど、USBポート経由で接続するハードウェアセキュリティキーで使用されます。

nfc：近距離無線通信（NFC）を介して認証器との通信を可能にし、ユーザーはセキュリティキーやNFC対応デバイスをタップして認証できます。

ble：Bluetooth Low Energyを介した認証を容易にし、外部の認証器とのワイヤレス通信を可能にします。

smart-card：スマートカードリーダーで使用され、スマートカードによる認証を可能にします。

hybrid：クロスデバイス認証を可能にします。通常、ユーザーがQRコードをスキャンしてデバイス間で認証する場合（例えば、スマートフォンを使ってデスクトップブラウザで認証するなど）に使われます。このトランスポートは、デスクトップとモバイルデバイスの両方でQRコードのプロンプトをトリガーする可能性があり、コンテキストによっては望ましくない場合もあります。注：hybridはWebAuthn Level 3で追加されました。

internal：認証器がデバイス自体に組み込まれているものです。iPhoneのiCloudキーチェーン（Face IDやTouch IDで検証）、PCのWindows Hello、AndroidデバイスのGoogleパスワードマネージャーなどがこれにあたります。これらはプラットフォーム認証器です。

パスキーが作成されると、認証器はサポートするトランスポートを通知します。この情報はリライングパーティ（バックエンド）に送信され、バックエンドはそれをクレデンシャルと一緒に永続化すべきです。認証時には、リライングパーティがこれらのトランスポートをallowCredentialsリストに入れてクライアントに送り返すことで、ブラウザやプラットフォームがユーザーにどの認証方法を提示するかを決定するのに役立ちます。

トランスポートの扱いはプラットフォームによって大きく異なり、これが開発者が直面する互換性の課題を生み出しています。

ブラウザは認証器からトランスポート情報を受け取り、認証フローでそれを尊重します。Chrome、Safari、Edgeでパスキーを作成すると、ブラウザのクレデンシャルマネージャーがトランスポートデータを提供しますが、その内容は基盤となる認証器によって異なります。

プラットフォーム認証器：Windows Helloは、デバイスに紐づく性質を反映して["internal"]のみを提供します。しかし、Chromeが認証器としてGoogleパスワードマネージャーを使用する場合、GoogleパスワードマネージャーがAndroidスマートフォン経由のクロスデバイス認証をサポートしているため、["internal", "hybrid"]を提供します。

ハードウェアセキュリティキー：実際の能力に基づいて["usb", "nfc"]のような特定のトランスポートを提供します。

クラウド同期されるクレデンシャルマネージャー：SafariのiCloudキーチェーンやChromeのGoogleパスワードマネージャーは、ローカル認証とクロスデバイス認証の両方をサポートするために、通常["internal", "hybrid"]を提供します。

この情報はウェブのコンテキストでは信頼性高く流れますが、具体的なトランスポートはブラウザがクレデンシャル保存のためにどの認証器を選択するかによります。

ドキュメント： W3C WebAuthn Specification

AndroidのCredential Manager APIは、ウェブブラウザと同様に動作します。ネイティブAndroidアプリでパスキーを作成すると、Credential Managerはウェブの挙動を反映したトランスポート情報を提供します。プラットフォーム認証器は自身の能力を正確に報告し、システムはトランスポートデータを一貫して処理します。Android開発者は、特別な処理なしでこの情報に頼ることができます。

ドキュメント： Android Credential Manager

iOSはより複雑な状況を呈します。AppleのAuthenticationServicesフレームワークは、認証器の種類によってトランスポートの扱いが異なります。

プラットフォーム認証器（iCloudキーチェーン、Face IDやTouch IDで検証）：パスキー作成時に、しばしば空のトランスポート配列を返します。これはパスキーにトランスポート能力がないという意味ではなく、単にiOSがそれを明示的に報告しないだけです。WebAuthn標準によれば、トランスポートを省略することはどのトランスポートでも受け入れ可能であることを意味するため、hybrid認証は引き続き機能します。

セキュリティキー：iOSデバイスで使用される場合、期待されるパターンに従ってトランスポート情報（例：["usb"]、["nfc"]）を提供します。

ドキュメント： Apple AuthenticationServices

開発者は、仕様に厳密に従うか、ユーザー体験のためにinternalとhybridトランスポートを最適化するかの選択に直面します。それぞれのアプローチには利点と欠点があります。

このアプローチはWebAuthn仕様に沿っており、クレデンシャル登録時に認証器から提供されたトランスポートをそのまま使用し、認証時に変更せずに送り返します。

実装：パスキーが作成されたら、認証器のレスポンスからtransports配列を永続化します。認証時には、allowCredentialsリストにこれらのトランスポートをそのまま含めます。

{
    "allowCredentials": [
        {
            "id": "credential-id-base64",
            "type": "public-key",
            "transports": ["internal", "hybrid"]
        }
    ]
}

利点：

• 仕様準拠：WebAuthn標準に正確に従うため、将来のプラットフォーム更新との互換性が保証されます。
• セキュリティキーの信頼性：常に正確なトランスポート情報を提供するハードウェアセキュリティキー（YubiKeyなど）には完璧に機能します。
• 無効な選択肢の防止：実際にサポートされていない認証方法の提示を避けます。例えば、Windows Helloクレデンシャルに対してQRコードをトリガーしません。

欠点：

• iOSの空配列の挙動：iOSのプラットフォーム認証器は空のトランスポートを返します。仕様上これは「どのトランスポートでも可」を意味し、セキュリティキーを含むすべての認証オプションが表示される可能性があります。
• 不要な選択肢が表示される可能性：コンシューマー向けアプリケーションで期待されていないセキュリティキーのオプション（USB、NFC）が表示されることがあります。
• 一貫性のないユーザー体験：同じアカウントでも、プラットフォームによって異なる認証オプションが提示されます。

最適なケース：標準準拠を優先するアプリケーション、多様な認証器タイプが存在するエンタープライズ環境。

このアプローチは、特定の最適化目標に基づいてinternalとhybridトランスポートを選択的に変更することで、ユーザー体験を優先します。一律のルールではなく、以下の一般的な最適化シナリオを考えてみましょう。

問題：iOSのプラットフォーム認証器は空のトランスポート配列を返します。これを空のままにしたり、バックエンドで埋めたりすると、ユーザーはプラットフォームの選択肢と並んでセキュリティキーのプロンプト（USB、NFC）を目にする可能性があり、コンシューマー向けアプリケーションで混乱を生じさせます。

解決策：iOSプラットフォーム認証器のトランスポートを明示的に["hybrid", "internal"]に設定します。これにより、プラットフォーム認証とクロスデバイスフローのみが提供され、セキュリティキーの選択肢は非表示になります。

// iOSプラットフォーム認証器のクレデンシャルを永続化する際
if (platform === "iOS" && authenticatorAttachment === "platform") {
    transports = ["hybrid", "internal"];
}

結果：iOSで作成されたパスキーに対して、セキュリティキーのプロンプトがないクリーンな認証UIが実現します。

問題：モバイルデバイスで認証する際に、クロスデバイス認証のためのQRコードを表示すると、ユーザー体験が悪くなります。ユーザーはすでにパスキーが利用可能なモバイルデバイスを使用しているからです。

解決策：ユーザーがモバイルデバイスから認証している場合、hybridトランスポートを削除し、["internal"]のみを残します。

// 認証用のallowCredentialsを構築する際
const transports = isMobileDevice
    ? credentials.transports.filter((t) => t !== "hybrid")
    : credentials.transports;

結果：モバイルユーザーには不要なQRコードのプロンプトなしに、直接的な認証オプションのみが表示されます。

⚠️ 注意：トランスポートの操作が、プラットフォーム間で常に一貫した結果を生むとは限りません。広範なテストによると、ブラウザとOSの組み合わせによってトランスポートの扱いが異なることがわかっています。

• 一部のプラットフォームでは、トランスポートからhybridを除外してもQRコードが表示されます。
• 他のプラットフォームでは、hybridが含まれていてもQRコードが非表示になります。
• 挙動は、Windows、macOS、iOS上のChrome、Edge、Safari、Firefox間で大きく異なります。

行き詰まりのリスク：過度に制限的なトランスポートフィルタリングは、ユーザーが全くログインできなくなる認証の行き詰まりを生み出す可能性があります。例えば、hybridを削除すると、ユーザーが借り物のデバイスから認証する必要がある正当なクロスデバイス認証シナリオを妨げるかもしれません。トランスポートの最適化を展開する前に、必ず代替の認証方法を提供し、対象プラットフォームで徹底的にテストしてください。

これらは最適化のヒントです：WebAuthnは、トランスポートの操作以外にも、ヒントなど、認証UXを最適化するための他のメカニズムを提供しています。

トランスポートの挙動は予測不能：hybridトランスポートを介したクロスデバイス認証（CDA）は、ブラウザとOSの組み合わせによって一貫性のない挙動を示します。実際のテストでは、トランスポートの値が特定のUIの挙動を保証するものではないことが示されています。プラットフォームはトランスポートをそれぞれ異なる方法で解釈・処理するため、予期しない結果につながることがあります。

プラットフォーム固有の複雑さ：トランスポートを明示的に制御する場合、プラットフォームの違いを考慮する必要があります。

• iOS：プラットフォーム認証器に対して空の配列を送信するため、埋める必要があります。
• Windows Hello：["internal"]のみを維持する必要があります。hybridを追加すると不要なQRコードがトリガーされます。
• ウェブ＆Android：一般的に正確なトランスポート情報を提供します。
• CDAのバリエーション：トランスポート配列にhybridが存在するかどうかにかかわらず、QRコードのプロンプトが表示されたりされなかったりします。

エンドツーエンドの理解が必要：トランスポートを明示的に制御することは、フロー全体の責任を負うことを意味します。各トランスポートの組み合わせが、対象となるすべてのプラットフォームでどのように動作するかを理解し、徹底的にテストする必要があります。トランスポートの操作は、ユーザーにとって有効な認証パスが存在しない認証の行き詰まりを生み出す可能性があります。

利点：

• カスタマイズされたUX：特定のコンテキストでユーザーに表示される認証オプションを正確に制御できます。
• iOSの空配列問題を解決：iOSが提供しないトランスポートを明示的に定義します。
• コンテキストに応じた最適化：デバイスタイプに応じて認証UIを適応させます。

欠点：

• 予測不能な挙動：トランスポートの操作は一貫したUIの挙動を保証しません。広範なテストによると、プラットフォームはトランスポートを異なる方法で解釈し、トランスポートの値に関係なくオプションを表示したり非表示にしたりすることがあります。
• 認証の行き詰まりのリスク：過度に制限的なトランスポートフィルタリングは、特にクロスデバイスのシナリオで、ユーザーが完全に認証できなくなる可能性があります。
• 仕様からの逸脱：仕様の推奨から外れるため、将来のプラットフォーム変更で問題が発生する可能性があります。
• メンテナンスの負担：プラットフォームが進化するにつれて、継続的なプラットフォーム固有のロジックと更新が必要になります。
• 複雑さ：iOSの空配列、Windows Helloの制約、その他のプラットフォームの癖を手動で処理する必要があります。
• テストのオーバーヘッド：すべての最適化ルールは、すべてのプラットフォームの組み合わせで検証が必要です。

最適なケース：特定のUX要件を持つコンシューマー向けアプリケーション、プラットフォーム固有のロジックを維持するリソースを持つチーム、厳密な仕様準拠よりも合理化された認証フローを優先するシナリオ。

WebAuthnトランスポートの扱いは、単独で存在するものではありません。それはパスキー実装戦略全体の一部です。実際のデプロイでは、internalとhybridトランスポートの使用に関して異なる意味を持つ2つの一般的なアプローチがあります。

このアプローチは、柔軟性と標準準拠を優先し、ユーザーが互換性のある任意の認証器で認証できるようにします。

実装の特徴：

• 認証UI：既存のログインオプション（ユーザー名/パスワード）と並んでパスキーボタンが表示されます。
• allowCredentials：空の配列[]に設定し、どのクレデンシャルでも一致できるようにします。
• 認証器の種類：セキュリティキー、クロスデバイス認証（QRコード）、プラットフォーム認証器のすべてをサポートします。
• ネイティブアプリの要件：セキュリティキーを含むすべての認証方法をサポートする必要があります。
• preferImmediatelyAvailableCredentials：定義上、セキュリティキーとQRコードログインを除外するため、使用できません。
• トランスポートの扱い：セキュリティキーのトランスポート（usb、nfc、ble）を含む、すべてのトランスポートタイプに対応する必要があります。

トランスポートへの影響：

allowCredentialsが空の場合、認証時のトランスポートの重要性は低くなります。プラットフォームは利用可能なすべてのオプションを表示します。しかし、これはユーザーがセキュリティキーのプロンプト、QRコード、プラットフォームオプションを同時に目にする可能性があり、コンシューマー向けアプリケーションでは選択の麻痺を引き起こす可能性があります。

最適なケース：エンタープライズ環境、セキュリティキーのサポートを必要とする多様なユーザーベースを持つアプリケーション、最大限の認証柔軟性を優先するシナリオ。

このアプローチは、パスキー作成をプラットフォーム認証器に制限し、IDファーストフローを使用することで、コンシューマーのUXを最適化します。

実装の特徴：

• パスキー作成：authenticatorAttachment: "platform"を介してプラットフォーム認証器のみを許可します。
• 認証フロー：IDファースト - ユーザーは認証前にメールアドレス/ユーザー名を入力します。
• allowCredentials：IDがわかると、ユーザーの特定のクレデンシャルで埋められます（空ではない）。
• 認証器の種類：プラットフォーム認証器とクロスデバイス認証。セキュリティキーは通常除外されます。
• ネイティブアプリの最適化：preferImmediatelyAvailableCredentialsを使用できます。これは定義上、セキュリティキーとクロスデバイス認証を除外します。
• クロスデバイス認証：ウェブでは利用可能。ネイティブアプリでpreferImmediatelyAvailableCredentialsを使用する場合は利用できませんが、このシナリオはまれです（ユーザーは通常、使用しているデバイスにパスキーを持っています）。
• トランスポートの扱い：internalとhybridトランスポートのみに焦点を当てます。

トランスポートへの影響：

allowCredentialsにはトランスポート情報を含む特定のクレデンシャルが含まれるため、トランスポートの扱いが非常に重要になります。

最適なケース：コンシューマー向けアプリケーション、ネイティブモバイルアプリ、認証器の柔軟性よりも合理化されたUXを優先するシナリオ、IDファーストフローがすでに存在するプラットフォーム。

すでにアカウントの存在を漏洩させている、またはIDファーストフロー（ユーザーがログインオプションを見る前にメールアドレスを入力する）を使用しているプラットフォームでは、コンシューマー向けに最適化されたアプローチが自然に適合します。ユーザーがIDを提供すると、

1. バックエンドが既存のパスキーをクエリします。
2. 特定のクレデンシャルとそのトランスポートを含むallowCredentialsを返します。
3. プラットフォームはトランスポートに基づいて認証UIを最適化できます。
4. 追加のアカウント列挙リスクはありません（IDはすでに提供済み）。

これらのシナリオでは、トランスポートはセキュリティ上の懸念ではなく、最適化ツールとなり得ます。デバイスのコンテキスト（モバイル vs. デスクトップ）やクレデンシャルの能力に基づいて認証オプションを調整できます。

推奨：すでにIDファーストフローを使用しているプラットフォームや、アカウント列挙が懸念事項でないプラットフォームでは、明示的なトランスポート処理を伴うコンシューマー向けアプローチが、特にpreferImmediatelyAvailableCredentialsがシームレスな生体認証を可能にするネイティブモバイルアプリケーションにおいて、優れたUXを提供します。

internalとhybridトランスポートの扱いについてどのアプローチを選択するかにかかわらず、問題を最小限に抑えるために以下のプラクティスに従ってください。

登録時にトランスポートを永続化する：常にクレデンシャルIDと公開鍵と一緒に、認証器のレスポンスからtransports配列を保存します。このデータは認証フローに不可欠です。

空の配列を適切に処理する：iOSプラットフォーム認証器から空のトランスポート配列を受け取った場合：

• 仕様準拠：空のままにするか、transportsプロパティを省略します。これは「どのトランスポートでも可」を意味します。
• 最適化アプローチ：["internal", "hybrid"]で埋め、表示される認証オプションを制御します。

すべての対象プラットフォームでテストする：すべての組み合わせをカバーするテストマトリックスを作成します。

• 登録：ウェブ、iOSネイティブ、Androidネイティブ
• 認証：ウェブ、iOSネイティブ、Androidネイティブ
• QRコードが期待通りに表示され、不適切な場合には非表示になることを確認します。

空の配列 vs. プロパティの欠落を理解する：空のトランスポート配列[]とtransportsプロパティの欠落は、どちらも仕様によれば「どのトランスポートでも受け入れ可能」として扱われるのが一般的です。しかし、実装の詳細はプラットフォームによって異なります。

プラットフォームの変更を監視する：WebAuthnの実装は進化します。Apple、Google、Microsoftは定期的に認証器の挙動を更新します。トランスポートの扱いに影響を与える可能性のある変更について、常に情報を入手しておきましょう。

WebAuthnのトランスポート、特にinternalとhybridトランスポートは、クロスデバイス認証に大きな実践的影響を与える技術的な詳細です。トランスポートの扱いに関する戦略は、より広範なパスキー実装アプローチと対象プラットフォームに合わせるべきです。

トランスポートの決定はより大きな戦略の中に存在する：トランスポートをどのように扱うかは、最大限の柔軟性（空のallowCredentials）を目指すのか、コンシューマーのUX（IDファーストと特定のクレデンシャル）を目指すのかによって決まります。後者の場合、トランスポートは最適化のために非常に重要になります。

プラットフォームの違いには対応が必要：ウェブとAndroidは信頼できるトランスポート情報を提供しますが、iOSのプラットフォーム認証器は空の配列を返します。Windows Helloは["internal"]のみを送信します。これらの違いを理解することは、本番環境でのデプロイに不可欠です。

2つの有効なトランスポートアプローチ：仕様準拠（認証器のトランスポートを信頼する）は、エンタープライズや最大限の柔軟性を求めるシナリオに適しています。明示的な制御（トランスポートを最適化する）は、IDファーストフローを持つコンシューマー向けアプリケーションやネイティブモバイルアプリに適しています。

IDファーストがトランスポートの最適化を可能にする：ユーザーが最初にIDを提供する場合、トランスポートの扱いは強力なUXツールになります。モバイルでの不要なQRコードの表示を防ぎ、セキュリティキーのオプションを非表示にし、認証を合理化できます。これらは追加のアカウント列挙の懸念なしに実現できます。

エンタープライズ / 最大限の柔軟性を求める場合：

• 空のallowCredentialsを使用してすべての認証器タイプをサポートします。
• 認証器が提供するトランスポートを信頼します。
• ユーザーに多くの認証オプションが表示されることを受け入れます。
• 実装がよりシンプルで、互換性が広いです。

コンシューマー向けアプリケーション / ネイティブアプリの場合：

• IDファーストの認証フローを実装します。
• プラットフォーム認証器に制限します（authenticatorAttachment: "platform"）。
• 特定のクレデンシャルと最適化されたトランスポートを含むallowCredentialsを使用します。
• ネイティブアプリでpreferImmediatelyAvailableCredentialsを有効にします。
• iOSの空配列を["hybrid", "internal"]で埋めます。
• モバイルデバイスでhybridをフィルタリングしてQRコードを防ぎます。
• 合理化された認証オプションにより、優れたUXを実現します。

すでにIDファーストフローを持つプラットフォームの場合：

• アカウント列挙はすでに問題ではありません。
• コンシューマー向けアプローチは既存のUXと自然に調和します。
• トランスポートの最適化はすぐにUXの向上をもたらします。
• ほとんどのコンシューマー向けアプリケーションで推奨されるアプローチです。

まず仕様に準拠し、次に戦略に基づいて最適化する：

1. 登録時に受け取ったトランスポートをそのまま永続化します。
2. 全体的な戦略（最大限の柔軟性 vs. コンシューマー向け最適化）を決定します。
3. コンシューマー向け最適化を選択した場合：IDファーストフローを実装し、トランスポートを最適化します。
4. 選択した戦略に合わせて、iOSの空配列を適切に処理します。
5. ウェブ、iOSネイティブ、Androidネイティブプラットフォームで徹底的にテストします。

WebAuthnを取り巻く環境は進化し続けています。プラットフォームベンダーは定期的に実装を更新し、WebAuthn Level 3のような仕様は新しい機能をもたらします。トランスポートの扱いをより広範な認証戦略と整合させる柔軟なシステムを構築することで、エコシステムが成熟するにつれて、パスキー実装の堅牢性を保ち、優れたユーザー体験を提供し続けることができます。