ネイティブアプリのパスキー：ネイティブ実装とWebView実装の比較

60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

注： System WebViewとEmbedded WebViewはしばしば組み合わせて使用されます。System WebViewがログイン（認証情報の自動共有あり）を処理し、その後Embedded WebViewが設定画面でパスキー管理をレンダリングします。

主な決定要因：

• OAuthベースのログインか？ → System WebView（ASWebAuthenticationSession、Chrome Custom Tabs）
• ウェブの認証をネイティブシェルで再利用したいか？ → Embedded WebView（WKWebView、WebKit 1.12.1+を搭載したAndroid WebView）
• ネイティブファーストのアプリを構築しているか？ → ネイティブ実装（Apple AuthenticationServices、Google Credential Manager）

最新のモバイルプラットフォームでは、ネイティブアプリにパスキーを統合するための3つの異なるアプローチが提供されています。それぞれ、ユーザー体験、技術的複雑さ、OAuthとの互換性においてトレードオフがあります。

1. ネイティブ実装：プラットフォームのAPI（iOSのAuthenticationServices、AndroidのCredential Manager）を使用して、アプリに直接パスキーフローを構築します。シームレスな生体認証で最高のユーザー体験を提供しますが、技術的な実装には中〜高度な労力が必要です。

2. System WebView：プラットフォームのブラウザコンポーネント（iOSのASWebAuthenticationSession / SFSafariViewController、AndroidのChrome Custom Tabs）を使用して認証を処理します。OAuthベースのログインフローに最適で、システムのブラウザと認証情報を共有します。

3. Embedded WebView：カスタマイズ可能なWebView（iOSのWKWebView、AndroidのWebView）をアプリ内に埋め込み、ネイティブアプリの骨格でウェブ認証を再利用します。URLバーなしでネイティブのような外観を提供し、WebViewのUIを完全に制御できます。パスキー機能を有効にするには、権限やエンタイトルメント（iOS）、およびAndroidX WebKit 1.12.1+でのWebView設定（Android）など、追加のセットアップが必要です。

適切な選択は、アプリの認証アーキテクチャ、OAuthプロバイダを使用しているかどうか、UIをどの程度制御する必要があるか、そしてネイティブファーストで構築しているかウェブコンポーネントを再利用しているかによって決まります。

パスキーのネイティブ実装は、プラットフォーム固有のAPIを使用してアプリのUIに直接認証フローを組み込むため、最適なユーザー体験を提供します。ユーザーは、プラットフォームネイティブのダイアログ、シームレスな生体認証、そして可能な限り最速のログイン時間というメリットを享受できます。

ネイティブ実装を選択すべき場合：

• 新しいネイティブアプリを構築する、または認証をネイティブ画面にリファクタリングする場合
• 即時かつサイレントな認証で、最高のユーザー体験を求める場合
• アプリ起動時の自動パスキープロンプト：ネイティブ実装ではpreferImmediatelyAvailableCredentialsを使用して、パスキーが利用可能な場合に自動的にパスキーのオーバーレイを表示できます。これにより、識別子を入力することなく最速のログイン体験が提供されます。
• 認証UIとフローを完全に制御する必要がある場合
• プラットフォーム固有の実装（iOSのSwift、AndroidのKotlin）に投資する意思がある場合

主な利点：preferImmediatelyAvailableCredentials()

ネイティブ実装ではpreferImmediatelyAvailableCredentials()を活用して、パスキーが利用可能な場合にアプリ起動時に即座に表示される自動パスキーオーバーレイを作成できます。このユーザー名不要のフローは、ユーザーが最初に識別子を入力することなく自分のパスキーを即座に確認できるため、可能な限り最速のログイン体験を提供します。この機能はネイティブ実装に限定されており、WebViewの亜種では利用できません。

WebView実装ではConditional UI（入力フィールドでのパスキー提案）を使用できますが、ネイティブの自動オーバーレイは、アプリ起動時に即座に認証が開始されるため、より高いパスキー使用率で優れたUXを提供します。

技術要件の概要：

ネイティブでのパスキー統合には、アプリとウェブドメイン間の暗号化による信頼関係が必要です。これがないと、OSはすべてのWebAuthn操作を拒否します。主な要件は以下の通りです：

1. /.well-known/でホストされるアプリとドメインの関連付けファイル
2. ウェブドメインに一致する正しいRelying Party ID
3. プラットフォーム固有のケーパビリティ（セクション4で詳述）

最大のメリットは、ウェブサイトで作成したパスキーがアプリでシームレスに機能し、その逆も同様であることです。

iOSでパスキーをネイティブに実装するには、AppleのAuthenticationServicesフレームワークを使用します。これはWebAuthn操作のためのAPIを提供します。

主なコンポーネント：

• ASAuthorizationController：認証フローを管理
• ASAuthorizationPlatformPublicKeyCredentialProvider：パスキーリクエストを作成
• パスキーログインを処理するための3つの異なるUIモード：
  • テキストフィールドログイン：従来のユーザー名フィールドで、ボタン送信時にパスキーログインを開始
  • パスキーモーダルオーバーレイ：利用可能なパスキーを一覧表示するOSダイアログ
  • Conditional UI：キーボード上部のQuickTypeバーにパスキーの候補を表示

開発のヒント

• AASAのキャッシュ：AppleはAASAファイルを積極的（最大24時間）にキャッシュするため、テストが困難になることがあります。解決策：テストデバイスでデベロッパモードを有効にし、AASAのURLに?mode=developerを追加して、強制的に最新のファイルを取得します。
• パフォーマンステスト：何百もの認証情報を含むiCloudアカウントでテストし、実際の遅延を観察します。多くのパスキーが保存されている場合、システムオーバーレイにわずかな遅延が生じることがあります。

Androidのネイティブパスキー実装では、Credential Manager API（下位互換性のために古いFIDO2 APIも使用可）を使用します。

主なコンポーネント：

• CredentialManager：すべての認証情報操作のための中央API
• CreatePublicKeyCredentialRequest：パスキー登録用
• GetCredentialRequest：パスキー認証用
• 2つの主要なUIモード：
  • テキストフィールドログイン：従来のユーザー名フィールドで、ボタン送信時にパスキーログインを開始
  • パスキーモーダルオーバーレイ：利用可能なパスキーを一覧表示するOSダイアログ

注：Androidは現在、ネイティブアプリにおいてiOSのConditional UIのようなキーボード候補機能を欠いています（ただし、Conditional UIはウェブアプリでは機能します）。

パスキーをネイティブに実装するには、重要な課題と教訓があります。OSレベルでの統合は、異なるデバイスやOSバージョン間で問題を引き起こす可能性があります。

1. 例えば、私たちのチームは、Appleによるapple-app-site-associationファイル（アプリとウェブの認証情報連携に使用）の積極的なキャッシュや、特定のAndroid OEMの生体認証プロンプトにおける微妙なUIの違いといった問題に遭遇しました。
2. さらに、一部のエンタープライズシナリオでは、管理対象デバイスでポリシーによってパスキーの同期が無効にされている場合があることを考慮してください。iCloud KeychainやGoogleパスワードマネージャーの同期がオフになっている企業環境では、パスキーはデバイスに紐付けられ、ローミングされません。これは計画すべき重要なシナリオです（例えば、ユーザーが新しい携帯電話を入手した場合でもログインできるようにするなど）。
3. 加えて、サードパーティの認証情報マネージャーアプリがフローに影響を与える可能性があります。例えば、ユーザーがアクティブな認証情報プロバイダとして1Passwordのようなパスワードマネージャーを設定している場合、プラットフォームのネイティブ認証情報マネージャーよりも優先され、パスキーの作成と保存を横取りすることがよくあります。

生のプラットフォームAPIを使用してパスキーを実装することもできますが、専用のSDKを使用すると、WebAuthnの複雑さやエッジケースを処理し、組み込みのテレメトリを提供することで、開発を大幅に加速できます。SDKはまた、単体テスト用のモック可能なインターフェースも提供します（シミュレータでは生体認証をテストできないため、これは非常に重要です）。

推奨： ネイティブ実装には、Corbado SDK（iOS Swift Passkey SDK、Android Kotlin Passkey SDK）の使用をお勧めします。これらは、本番環境でのデプロイを通じて発見された数多くのエッジケースを処理し、追加のテレメトリとテストを提供します。

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

Corbado proved to be a trusted partner. Their hands-on, 24/7 support and on-site assistance enabled a seamless integration into VicRoads' complex systems, offering passkeys to 5 million users.

何百万人にも採用されるパスキーを、素早く。CorbadoのAdoption Platformから始めましょう。

無料トライアルを開始

System WebViewは、プラットフォームのネイティブブラウザコンポーネントを使用して、アプリ内で認証を処理します。完全なネイティブ実装とは異なり、System WebViewは実際のシステムブラウザ（iOSではSafari、AndroidではChrome）を使用してウェブコンテンツを表示し、共有Cookie、保存された認証情報、そしておなじみのブラウザのセキュリティインジケータを維持します。

System WebViewを選択すべき場合：

• アプリがOAuthベースのログインを使用している場合：System WebViewはOAuth2/OIDCフローに推奨されるアプローチであり、安全な認証を提供します。
• 既存のウェブベースの認証をモバイルアプリで再利用したい場合
• ネイティブで再構築することなく、複数の認証方法（パスワード、ソーシャルログイン、パスキー）をサポートする必要がある場合
• ウェブとモバイルで単一の認証コードベースを維持したい場合

主な利点：

• OAuth互換性：OAuth/OIDC認証フローのために専用設計
• セキュリティインジケータ：ユーザーは実際のURLとSSL証明書を確認でき、信頼を構築
• 低い実装労力：最小限のネイティブコードで済む
• 一貫したUX：ユーザーがすでに信頼しているおなじみのブラウザインターフェース

プラットフォームコンポーネント：

• iOS：ASWebAuthenticationSession（認証フローに推奨）またはSFSafariViewController（一般的なブラウジング）
• Android：Chrome Custom Tabs（CCT）

GoogleやGitHubのような大手企業は、既存のウェブ認証ページにWebViewオーバーレイを介してモバイルアプリにパスキーログインを追加するためにこのアプローチを採用しました。これは、完全なネイティブ認証の再構築がすぐに実現可能でない場合にうまく機能します。

iOSは、認証のために2つの主要なSystem WebViewコンポーネントを提供します。

ASWebAuthenticationSession（認証に推奨）：

• OAuth/OIDCおよびセキュアなログインフローのために専用設計
• アプリが認証を求めていることをユーザーに自動的にプロンプト表示
• SafariとCookieや認証情報を共有
• iCloud Keychainを介してパスキーをサポート

SFSafariViewController（一般的なブラウジング）：

• アプリ内で完全なSafari体験を提供
• URLバーとセキュリティインジケータを表示
• iOS 11以降ではSafariのCookieを共有しない。Safariセッションの共有が必要な場合はASWebAuthenticationSessionを使用
• カスタマイズ性は低いが、ユーザーにとってはより信頼性が高い

アプリがOAuthベースのログインを使用している場合、ASWebAuthenticationSessionは認証シナリオ専用に設計されており、セキュリティとユーザー体験の最良のバランスを提供するため、推奨される選択肢です。

Chrome Custom Tabs（CCT）は、アプリ内でChromeを利用した認証体験を提供します。

主な機能：

• ChromeブラウザとCookieや認証情報を共有
• URLとセキュリティインジケータを表示
• ツールバーの色やブランディングをカスタマイズ可能
• 高速な読み込みのための事前ウォームアップ

OAuth統合：Chrome Custom TabsはiOSのASWebAuthenticationSessionに相当し、保存されたパスキーへのアクセスを維持しながら、優れたOAuthサポートを提供します。

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

Embedded WebViewは、アプリ内でレンダリングされるウェブコンテンツを完全に制御でき、URLバーなしでCookie、セッション、ナビゲーションを直接操作できます。しかし、この制御にはパスキー機能を有効にするための追加の技術要件が伴います。

Embedded WebViewを選択すべき場合：

• ネイティブライクな体験：アプリが既にカスタマイズされたWebView内に認証を埋め込み、ネイティブなルックアンドフィールを維持しており、この一貫したユーザー体験を維持したい場合
• セッション/Cookieの制御が必要：OAuth認証完了後に、アプリが認証トークンとセッション状態を直接操作する必要がある場合
• 既存の認証フローで、System WebView認証が認証コードは返すものの、埋め込みコンテキストではセッションを返さない場合
• 複数の埋め込みウェブ画面で認証状態を維持する必要がある場合
• ファーストパーティ認証のみ：アプリが直接認証を処理する場合。サードパーティのパスキー実装についてはこちらを参照してください。
• AndroidX WebKit 1.12.1+とランタイムでの機能検出
• ログイン時のConditional UIの制限（Embedded WebViewでは非対応）を受け入れられる場合（管理設定には関係なし）

重要なコンテキスト：

多くのアプリはハイブリッドアプローチを使用しています。最初のOAuth認証はSystem WebViewで処理し（パスキーはシームレスに機能）、認証後に設定画面でパスキーを管理するためにEmbedded WebViewに切り替えます。課題は、Embedded WebView内で直接パスキーを使用しようとするときに発生します。

技術要件：

Embedded WebViewは、System WebViewと比較して追加の設定が必要です。

1. iOS：Associated Domainsエンタイトルメント、AASAファイルの設定
2. Android：AndroidX WebKit 1.12.1+とWebView WebAuthnの設定（機能検出が必要）
3. 両方：正しく設定されたwell-known関連付けファイルとDigital Asset Links

プラットフォームコンポーネント：

• iOS：WKWebView
• Android：android.webkit.WebView

トレードオフ：

• 中程度の複雑さ：WebViewの設定（Android WebKit 1.12.1+）とエンタイトルメントの設定（iOS）が必要
• パスキー採用率の低下：ネイティブと比較して、ユーザーはより多くの摩擦に遭遇する可能性がある
• Conditional UIは非対応：入力フィールドでのパスキーオートフィルはAndroidのEmbedded WebViewでは機能しない
• 限定的なプラットフォームサポート：一部の機能（例：パスキーの自動作成）が一貫して動作しない可能性がある

WebViewを介してパスキーを実装する場合、System WebViewとEmbedded WebViewの違いを理解することが重要です。上記で概説した3つのアプローチ（ネイティブ実装、System WebView、Embedded WebView）は、それぞれ異なるユースケースに対応します。

iOSでは、アプリ内でウェブコンテンツを表示するための複数のオプションがあります：

• WKWebViewは、WebKitフレームワークの一部であるカスタマイズ可能なWebViewです（iOS 8で導入）。ウェブコンテンツの外観や動作を細かく制御できます。
• SFSafariViewControllerは、Appleが提供するビューコントローラで、アプリ内で軽量なSafariブラウザとして機能します。Safariのエンジンを使用します。iOS 11以降では、別のCookieストアを持ち、SafariのCookieを共有しません。Safariセッションの共有が必要な場合はASWebAuthenticationSessionを使用してください。
• SFAuthenticationSession / ASWebAuthenticationSessionは、特にOAuth/OpenIDやその他のセキュアなログインフローを目的とした、特殊なウェブ認証セッションです（iOS 11/12以降で利用可能）。これらも内部でSafariを利用しますが、認証フローに特化しており、共有Cookieやシングルサインオン（SSO）などを自動的に処理します。

Androidでの主な選択肢は次のとおりです：

• Android WebViewは、標準のWebViewウィジェット（android.webkit.WebView）で、アクティビティに埋め込むことができるミニブラウザのようなものです。高度にカスタマイズ可能ですが、アプリのプロセス内で実行されます。
• **Chrome Custom Tabs (CCT)**は、アプリのコンテキスト内でChromeを利用したタブを開く機能です。Custom Tabsはアプリの一部のように見えますが、（インストールされていれば）Chromeブラウザによって動作し、事前読み込み、共有Cookie、そしてユーザーの信頼を得るためのおなじみのURLバーなどの機能を備えています。

以下のセクションでは、これらのiOSおよびAndroid用のWebViewタイプについてもう少し詳しく掘り下げ、パスキー認証フローにどれが最適かを議論します。

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Appleのプラットフォームは、上記の3つのWebViewオプションを提供します。どの選択をするかによって、アプリ内でのパスキーの使いやすさが変わってきます。

iOSでの異なるWebViewの挙動をテストするには、アプリWebView - WKWebView and UIWebView renderingをお勧めします。

WKWebViewは、iOS用の多機能なWebViewコンポーネントです。開発者はWKWebViewを埋め込んで、UIと動作を高度に制御しながらウェブコンテンツをレンダリングできます。WKWebViewはSafariと同じレンダリングエンジンを使用しているため、非常に高性能で、最新のウェブ機能をサポートしています。理論的には、正しく設定すればWKWebViewはWebAuthn（つまりパスキー）を扱うことができますが、セキュリティ上の理由から一部の高度なブラウザ機能が制限される場合があることに注意してください。注意すべき点として、WKWebViewはデフォルトでCookieやキーチェーンデータをMobile Safariと共有しません。そのため、WebViewセッションがSafariのセッションから隔離されているため、ユーザーは再度ログインする必要があるかもしれません。また、WKWebViewのコンテンツはアプリによって完全にカスタマイズできるため、ユーザーにはアドレスバーやSafariのUIが表示されません。これはブランディングには最適ですが、ユーザーがページの正当性を確認する手がかりが少なくなることを意味します（フィッシング対策の懸念）。一部のアプリはWKWebViewを悪用してスクリプトを注入したり、コンテンツを変更したりしています（例えば、TikTokはアプリ内ブラウザを介してトラッキング用のJSを注入していると指摘されました）。そのため、WKWebViewは安全でユーザーが信頼できる方法で使用するよう注意しなければなりません。

SFSafariViewControllerは、アプリ内でSafari体験を提供します。SFSafariViewControllerでURLを開くと、ユーザーがアプリのUI内に留まる点を除けば、本物のSafariブラウザで開くのとほとんど同じです。パスキーにとっての利点は大きいです。なぜなら、本質的にSafariなので、ユーザーのiCloud Keychainと保存されたパスキーにアクセスできるからです。ただし、iOS 11以降ではCookieは共有されません。これは、ユーザーがあなたのサイトのパスキーを既に持っている場合、Safariがそれを見つけ、簡単なログインのためにConditional UIのオートコンプリートを表示できることを意味します。SFSafariViewControllerはカスタマイズ性が低いですが（ツールバーはあまり変更できません）、多くのセキュリティとプライバシー機能を自動的に処理します。URLバーが表示され、HTTPSの南京錠アイコンも付いているため、ユーザーは正しいドメインにいるという安心感を得られます。一般的に、SFSafariViewControllerは生のWKWebViewよりも安全で、実装も簡単だと考えられています（Appleがドロップインとして提供）。主なトレードオフは、ルックアンドフィールの制御をいくらか犠牲にすることです。認証フローの場合、それは通常許容範囲内です。ここでの優先事項はセキュリティとログインの容易さであり、SFSafariViewControllerはSafariのコンテキストを使用することでこれを実現しています。

SFAuthenticationSession / ASWebAuthenticationSession – これらのクラス（後者はより新しいSwiftフレンドリーな名前）は、OAuthやOpenID Connectのようなログインフロー専用に作られています。ウェブページを介してユーザーを認証する必要がある場合（おそらく外部のIdPに対して）、これらのセッションがiOSで推奨される選択肢です。これらはSFSafariViewControllerと非常に似ており、内部でSafariブラウザを利用し、Cookie/ストレージをSafariと共有します。重要な違いは、SFAuthenticationSessionは常にユーザーにウェブページを使用して認証しようとしていることをプロンプト表示し（ユーザーの認識のため）、利用可能な場合はユーザーの既存のSafariセッションを自動的に使用する点です。

その利点は、シームレスなSSO体験です。ユーザーがSafariでプロバイダにすでにログインしている場合、このセッションはそのCookieを使用して再度のログインを回避できます。パスキーにとってこれは重要です。なぜなら、Safari/iCloud Keychainに保存されているパスキー認証情報もここで使用できることを意味するからです。Appleの公式ガイダンスは、ログインフローのように見えるものにはASWebAuthenticationSessionを使用することです。利点はプライバシーの向上（アプリは認証情報やCookieを決して見ない、Safariが処理する）と、組み込みのSSOサポートです。欠点は、認証フローに限定されることです（アプリ内で任意のウェブコンテンツをレンダリングするためには使用しません）。要約すると、iOSでWebViewアプローチを選択する場合、ASWebAuthenticationSessionは、安全で、Safariと状態を共有し、認証専用に作られているため、パスキーを実装するための最良の選択肢となることが多いです。

Want to find out how many people use passkeys?

View Adoption Data

Androidでは、WebViewの決定はクラシックなWebViewとChrome Custom Tabsの間で行われます。

Androidでの異なるWebViewの挙動をテストするには、アプリWebView vs Chrome Custom Tabsをお勧めします。

Android WebView (android.webkit.WebView) は、アクティビティのレイアウトにウェブページを埋め込むことができるコンポーネントです。ナビゲーションを傍受したり、JavaScriptを注入したり、UIをカスタマイズしたりできる点でWKWebViewに似ています。また、アプリのプロセス内で実行されます。パスキーにWebViewを使用するということは、アプリがウェブのログインページを読み込み、そのページがWebAuthnのパスキーセレモニーを開始できることを意味します。最新のAndroid WebViewはWebAuthnをサポートしています（デバイスのWebView実装がAndroid System WebViewまたはChromeコンポーネントを介して最新である場合）。主な考慮事項の1つは、デフォルトではAndroid WebViewはユーザーのChromeブラウザとCookieや保存された認証情報を共有しないことです。そのため、WebViewで作成または使用されたパスキーはChromeには知られていない可能性があり、その逆も同様です。この分離はセキュリティには良いかもしれませんが（アプリはブラウザのCookieを読み取れない）、ユーザーがChromeで既に認証している場合に再度ログインを強制する可能性があります。もう1つの問題は信頼性です。プレーンなWebViewはURLやSSLロックアイコンを表示しないため、ユーザーはフィッシングされないようにアプリを完全に信頼する必要があります。Googleは、フィッシングのリスクがあるため、Google OAuthサインインにWebViewを使用することを禁止しています。パフォーマンス面では、WebViewは問題ありませんが、特に重いページを読み込む場合、ユーザーのデフォルトブラウザを使用するよりも遅くなったり、メモリを多く消費したりすることがあります。

**Chrome Custom Tabs (CCT)**はハイブリッドなアプローチです。アプリの一部のように見えるChromeでレンダリングされたページをアプリが開くことができます。ツールバーの色をカスタマイズしたり、アプリのロゴを追加したりできますが、コンテンツは別のプロセスでChromeによってレンダリングされます。パスキーにとって、CCTにはいくつかの利点があります。ユーザーのCookieと認証情報をChromeと共有するため、ユーザーがChrome（Googleパスワードマネージャー）経由でパスキーを保存している場合、Custom Tabはそれにアクセスできます。ユーザーは実際のURLとセキュリティインジケータも確認でき、これが信頼を築きます。パフォーマンスもしばしば向上します。Chromeはバックグラウンドで「ウォームアップ」して読み込みを高速化できます。そして重要なことに、セキュリティが強力です。本質的にChromeアプリなので、Googleセーフブラウジングのような機能がセッションを保護し、アプリはページに任意のスクリプトを注入できません（特定の攻撃を防ぎます）。

欠点は、ユーザーがChrome（またはサポートされているブラウザ）をインストールし、最新の状態に保つ必要があることです。ほとんどのAndroidユーザーはそうしていますが、特定の地域のデバイスではこれが問題になる可能性があります。全体として、Androidで埋め込みウェブアプローチを採用する場合、Chrome Custom Tabsは統合とセキュリティのバランスが良いため、パスキーフローに推奨されます。実際、これらは多くの点でiOSのSFSafariViewController/ASWebAuthSessionに類似しており、認証にデフォルトブラウザを活用しています。

（余談：AppleのWKWebView対SFSafariViewControllerとAndroidのWebView対CCTには多くの共通点があります。Safari VCとChrome Tabsは両方ともブラウザの状態を共有し、より良いセキュリティを提供しますが、WKWebView/Android WebViewはより多くの制御権を与える代わりにウェブコンテンツを分離します。パスキーの場合、パスキーがシームレスにアクセスおよび作成できるように、状態（Cookie、認証情報ストア）を共有することが通常望ましいです。）

どの実装アプローチを選択するかにかかわらず、パスキー機能を有効にするためには特定の技術要件を満たす必要があります。このセクションでは、well-known関連付けファイル、iOSエンタイトルメント、およびAndroid WebViewの設定に関する包括的なガイダンスを提供します。

管理対象デバイスに関する注意： パスキーの動作は、モバイルデバイス管理（MDM）ポリシーが認証情報ストレージを制御する管理対象デバイスでは大幅に変わります。管理対象デバイスでパスキーをテストする方法については、「管理対象iOSおよびAndroidデバイスでのパスキー」を参照してください。

ネイティブフローおよびEmbedded WebViewフローでは、アプリとウェブドメイン間の暗号化による信頼を確立するために関連付けファイルが必要です。System WebView（ASWebAuthenticationSession）およびChrome Custom Tabsでは、アプリとサイトの関連付けは不要です。

The AASAファイルは、iOSアプリとウェブドメイン間の接続を確立し、パスキーが両方のプラットフォームで機能するようにします。

ファイルの場所: https://yourdomain.com/.well-known/apple-app-site-association

設定要件:

• ドメインの /.well-known/apple-app-site-association でホストする
• 有効なSSL証明書を持つHTTPSで提供する
• Content-Type: application/json
• .well-known パスにリダイレクトがないこと
• アプリのTeam IDとBundle IDを含める

AASAファイルの例:

{
    "webcredentials": {
        "apps": ["TEAMID123.com.example.app"]
    }
}

AASAのキャッシュとテスト:

AppleはAASAファイルを積極的（最大24〜48時間）にCDN経由でキャッシュするため、開発やテストが困難になることがあります。開発中にキャッシュをバイパスするには：

1. テストデバイスでデベロッパーモードを有効にする
2. Xcodeで関連ドメインに ?mode=developer を追加する
3. これにより、iOSはサーバーから直接最新のAASAファイルを取得するようになります

⚠️ 重要：本番リリースで ?mode=developer を使用しないでください。このパラメータは開発専用です。本番環境で使用すると、iOSがAASAファイルを正しく検出できなくなり、パスキー機能が壊れます。

検証: AppleのAASA Validatorを使用して設定を検証してください。

Androidは、アプリとウェブサイト間の関係を検証するためにDigital Asset Linksを使用します。

ファイルの場所: https://yourdomain.com/.well-known/assetlinks.json

設定要件:

• ドメインの /.well-known/assetlinks.json でホストする
• 有効な証明書を持つHTTPSで提供する
• Content-Type: application/json
• アプリの署名証明書から取得したSHA256フィンガープリントを含める

assetlinks.jsonファイルの例:

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
            ]
        }
    }
]

検証: GoogleのDigital Asset Links Generatorを使用して設定を作成および検証してください。

iOSアプリがパスキー機能にアクセスするには、適切なエンタイトルメントが必要です。要件は実装アプローチによってわずかに異なります。

エンタイトルメントファイル（FlutterアプリではRunner.entitlements、ネイティブiOSプロジェクトではYourApp.entitlementsという名前が多い）は、Appleのシステムによって付与される特別な権限と機能を定義します。パスキーの場合、このファイルはAssociated Domainsを設定します。

ファイルの場所: 通常、Xcodeプロジェクトのios/Runner/Runner.entitlementsにあります。

ネイティブ実装とEmbedded WebViewでは、アプリをウェブドメインにリンクするためにAssociated Domainsケーパビリティが必要です。System WebView（ASWebAuthenticationSession）はSafariのコンテキストで実行されるため、これは不要です。

Xcodeでの設定:

1. Xcodeでプロジェクトを開く
2. アプリのターゲットを選択する
3. 「Signing & Capabilities」タブに移動する
4. 「+ Capability」をクリックし、「Associated Domains」を追加する
5. webcredentials:プレフィックスを付けてドメインを追加する

設定例:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:yourdomain.com</string>
        <string>webcredentials:subdomain.yourdomain.com</string>
    </array>
</dict>
</plist>

複数ドメイン: アプリが複数のドメインで動作する必要がある場合は、Related Origin Requests (ROR) が必要になる場合があります。

AndroidのEmbedded WebViewは、AndroidX WebKit 1.12でネイティブのWebAuthnサポートが追加され、カスタムのJavaScriptブリッジコードが不要になりました。System WebView（Chrome Custom Tabs）は設定不要で、認証情報は自動的に機能します。

要件:

• AndroidX WebKit 1.12.1以降（1.14.0+を推奨）
• Digital Asset Linksの設定
• WebAuthnをサポートするWebView APK（機能検出で確認）
• 注：AndroidX CredentialsライブラリはWebViewのWebAuthnには不要で、完全なネイティブ実装にのみ必要

実装:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Web Authenticationがサポートされているか確認
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Web Authenticationを有効にする
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // JavaScriptを有効にする
    webView.settings.javaScriptEnabled = true
}

キーポイント:

• JavaScriptブリッジは不要: WebAuthnはWebViewでネイティブに動作
• 機能検出が必要: 実行時に常にWebViewFeature.WEB_AUTHENTICATIONを確認
• Conditional UIは非対応: mediation:"conditional"（入力フィールドでのパスキーオートフィル）はEmbedded WebViewでは動作しない
• フォールバック戦略: 機能が利用できない場合は、代わりにChrome Custom Tabsを使用

バージョンに関する注意:

• WebKit 1.12.1以降を使用（1.12.0には実行時の可用性の問題があった）
• 機能のサポートはユーザーのWebView APKバージョンに依存 - デバイス上の古いAPKでは機能が公開されない

AndroidX WebKit 1.12.0以前は、Embedded WebViewにネイティブのWebAuthnサポートは存在しませんでした。チームは以下のいずれかを行う必要がありました：

1. Chrome Custom TabsまたはAuth Tabを使用する（推奨）
2. カスタムのJavaScriptブリッジを構築する

古いAndroidバージョンやWebView APKが更新されていないデバイスをサポートする必要がある場合は、AndroidのCredential Manager WebView Integrationガイドでブリッジコードのアプローチを参照してください。しかし、現代のアプリにはネイティブのWebKit 1.12.1+アプローチを使用することを強く推奨します。

推奨: AndroidX WebKit 1.12.1+でネイティブWebAuthnサポートを使用してください。実行時に利用できない場合は、共有認証情報で優れたパスキーサポートを提供するChrome Custom Tabsにフォールバックしてください。

ネイティブアプリにパスキーを実装する際、アプリとウェブドメイン間の信頼を確立する必要があります。このセクションでは、単一ドメイン、複数の関連ドメイン（ROR）、そしてwell-known関連付けファイルが正しく設定されているかを確認する方法について説明します。

単一ドメイン（例：kayak.com）を使用するアプリの場合、以下が必要です：

• iOS用のAASAファイル1つ（https://kayak.com/.well-known/apple-app-site-association）
• Android用のassetlinks.jsonファイル1つ（https://kayak.com/.well-known/assetlinks.json）
• webcredentials:kayak.comで設定されたAssociated Domainsエンタイトルメント

Related Origins (ROR)は、単一のパスキーセットが複数の関連ドメイン（例：kayak.com、kayak.de、kayak.co.uk）で機能できるようにするWebAuthnの機能です。RORは、AASAやassetlinksファイルではなく、各サイトの/.well-known/webauthnエンドポイントを使用して関連オリジンを定義します。

キーポイント:

• ROR設定：各ドメインは、関連オリジンのリストを含む/.well-known/webauthnをホストします。
• アプリ関連付けファイル（AASA/assetlinks）：アプリを対応するウェブサイトにマッピングするためにのみ使用されます。
• iOS 18以降のEmbedded WebView：正しく設定されていればRORをサポートします。
• Associated Domainsエンタイトルメント：アプリが認証する必要のあるすべてのドメインを含めます。

設定例:

アプリがkayak.comとkayak.deで動作する場合、両方のドメインは以下の条件を満たす必要があります：

• 同じTeam IDとBundle IDでそれぞれのAASAファイルをホストする
• アプリのAssociated Domainsエンタイトルメントにリストされている
• 正しく設定され、アクセス可能なwell-knownファイルがある

公開前に、well-knownファイルが正しく設定され、アクセス可能であることを確認してください。AppleとGoogleは、ファイルの可用性を確認するためのCDNベースのテストURLを提供しています。

これらのテストURLの使用方法:

• リンクをクリックして、Apple/Googleがwell-knownファイルを取得できるか確認します
• Appleの?nocache=1パラメータは、CDNキャッシュをバイパスして最新の取得を強制します
• これらのURLを通じてファイルにアクセスできない場合、アプリでパスキー機能は動作しません
• 上記のURLパターンのkayak.comまたはkayak.deを自分のドメインに置き換えてください

テストの注意点: すべてのドメインに正しく設定されたwell-knownファイルがあることを確認してください。いずれかのドメインでファイルが見つからない、または設定が間違っている場合、そのドメインのパスキー機能が壊れる可能性があります。

詳細情報: WebAuthn Relying Party ID in Native Apps

適切な実装アプローチの選択は、アプリの認証アーキテクチャ、OAuth要件、およびセッション制御の必要性に依存します。このデシジョンツリーを使用して、最善の道筋を決定してください。

まず、これらの主要な質問から始めます：

1. アプリはOAuthベースのログイン（OAuth2、OIDC、ソーシャルログインプロバイダ）を使用していますか？

   • はい → System WebView（セクション1.2）
     • iOS: ASWebAuthenticationSession を使用
     • Android: Chrome Custom Tabs を使用
     • 共有認証情報による優れたOAuthサポート

2. ネイティブのようなシェル（URLバーなし、完全なUI制御）でウェブ認証を再利用したいですか？

   • はい → 設定付きの Embedded WebView（セクション1.3）
   • iOS: WKWebView + Associated Domainsエンタイトルメント
   • Android: WebView + AndroidX WebKit 1.12.1+の設定
   • ウェブコンポーネントを再利用しつつ、ネイティブのような外観を提供
   • 注：Conditional UIはEmbedded WebViewではサポートされていません
   • いいえ → System WebViewまたはネイティブを検討

3. 新しいネイティブアプリを構築しているか、ネイティブのログイン画面がありますか？

   • はい → ネイティブ実装（セクション1.1）
     • 最高のユーザー体験
     • 即時かつサイレントな認証
     • プラットフォーム固有の開発が必要

4. 再利用したい既存のウェブ認証がありますか？

   • はい → 迅速な実装のために System WebView
   • いいえ → 最適なUXのために ネイティブ実装

各アプローチが主要な側面でどのように機能するかを以下に示します：

側面の解説:

• パスキー作成: このアプローチを通じてユーザーがどれだけ簡単にパスキーを作成できるか
• パスキー使用: 既存のパスキーを使用する際の認証体験
• パスキー管理: ユーザーがパスキーを表示、編集、または削除する方法
• 技術的複雑さ: 開発工数と継続的なメンテナンス
• OAuthサポート: アプローチがOAuth2/OIDC認証フローをどれだけうまく処理できるか
• セットアップ時間: 一般的な実装期間

推奨：System WebView

アプリがOAuth2、OIDC、またはソーシャルログインプロバイダ（Google、GitHub、Microsoftなど）を介して認証する場合、System WebViewが最適な選択です：

• iOS: ASWebAuthenticationSessionはOAuthフロー専用に設計されています
• Android: Chrome Custom TabsはシームレスなOAuth統合を提供します
• 利点: 最小限のネイティブコード、自動的な認証情報共有
• 実装: ウェブ認証ページにWebAuthnを追加し、それをSystem WebView経由で読み込みます

例: kayak.comやkayak.deのような旅行アプリは、認証にOAuthを使用しています。System WebViewを使用することで、既存のOAuthインフラを維持しつつ、ウェブ認証ページを通じてパスキーサポートを追加できます。

推奨：ハイブリッドアプローチ

最初のOAuth認証にSystem WebViewを使用し、認証後のセッションにはEmbedded WebViewを使用します：

1. 初期認証: System WebViewがOAuth + パスキーログインを処理
2. セッション管理: Cookie/セッション制御が必要な認証済みウェブコンテンツのためにEmbedded WebViewに切り替え
3. 技術的セットアップ: System WebViewとEmbedded WebViewの両方の要件を設定します。Androidの場合、AndroidX WebKit 1.12.1+が含まれていることを確認してください（セクション5参照）

使用場面: OAuth経由で認証するが、その後、直接的なセッション操作が必要な認証済みウェブコンテンツを表示する必要があるアプリ。

推奨：ネイティブ実装

ゼロから構築するか、ネイティブ画面がある場合は、完全にネイティブに移行しましょう：

• iOS: AuthenticationServicesフレームワークを使用
• Android: Credential Manager APIを使用
• 利点: 最高のUX、即時認証、完全な制御
• 独自の利点: preferImmediatelyAvailableCredentialsを使用して、アプリ起動時に自動パスキーオーバーレイを表示します。これはネイティブ実装専用であり、最高のコンバージョン率を提供します。
• SDK推奨: Corbado SDK（iOS、Android）を使用して、本番でテストされたエッジケース処理で開発を加速します。

新しいアプリの場合: 初日からネイティブログインを構築することを強くお勧めします。これにより、最適なUXが実現し、将来のWebViewからネイティブへの移行を回避できます。

推奨：段階的移行

• フェーズ1：System WebViewパスキー - 既存のウェブログインにパスキーサポートを追加し、System WebView（ASWebAuthenticationSession/Chrome Custom Tabs）経由で読み込みます。最小限のネイティブコードで迅速な成果が得られます。
• フェーズ2：ネイティブインターセプト - WebViewを表示する前にネイティブのパスキーチェックを追加します。例：kayak.comは最初にネイティブのパスキー認証を試み、必要に応じてWebViewにフォールバックします。これにより、下位互換性を維持しつつ、高速な生体認証ログインを提供します。
• フェーズ3：完全ネイティブ - パスキーユーザー向けに徐々にネイティブ認証に移行し、レガシーメソッド用にはWebViewを維持します。

この段階的なアプローチにより、既存のユーザーを混乱させることなく、段階的な改善が可能です。

詳細な設定手順については、セクション5を参照してください。

ネイティブアプリでのパスキーのテストには、構造化された多層的なアプローチが必要です。テストピラミッドに従ってください：単体テスト（分離されたロジック）、統合テスト（シミュレータ/エミュレータでのWebAuthnセレモニー）、システムテスト（物理デバイスでのエンドツーエンド）。

必須のテストカテゴリ：

• コアジャーニー: 登録、認証、クロスデバイスフロー、パスキー削除
• プラットフォームカバレッジ: iOS（ネイティブ）、Android（ネイティブ）、OSバージョン全体のウェブブラウザ
• ドメイン関連付け: AASAファイル（iOS）とDigital Asset Links（Android）がアクセス可能であることを確認
• キャンセルフロー: OSプロンプトと生体認証画面でのユーザーのキャンセルをテスト
• エラーハンドリング: バックエンドの障害、ネットワークタイムアウト、認証情報の不一致
• エッジケース: 画面ロックが無効、iCloud/Googleパスワードマネージャーが無効
• OAuthフロー: OAuth + パスキー統合をエンドツーエンドで完了
• 管理対象デバイス: MDM制御環境（管理対象デバイスのテストを参照）
• サードパーティマネージャー: 1Password、Bitwarden、Dashlaneとの互換性
• クロスデバイス認証: QRコードフローとハイブリッドトランスポートのテスト
• Embedded WebView固有: Embedded WebViewを使用する場合、AndroidでWebKit 1.12.1+の設定を確認
• 本番モニタリング: 成功率、失敗、遅延のダッシュボード

自動化戦略、プラットフォーム固有の注意点、および完全な飛行前チェックリストを含む包括的なテストガイダンスについては、専用ガイドを参照してください：ネイティブiOSおよびAndroidアプリでのパスキーフローのテスト。

従来のログイン（パスワード、OAuth）が成功した後に、ユーザーにパスキーの作成を促すことを検討してください。この段階的な変換アプローチは：

• 既存の認証フローを中断しない
• ユーザーが拒否した場合のグレースフルなデグラデーションを可能にする
• 変更を強制することなく、時間とともにパスキーの採用を増やす
• 3つの実装アプローチすべてでうまく機能する

例: System WebViewを介したOAuthログイン後、ネイティブプロンプトを表示：「Face IDでより速くログインしますか？」承認された場合、System WebViewで読み込まれたウェブページを介してパスキーを作成します。

パスキーをネイティブ実装、System WebView、またはEmbedded WebViewのいずれで実装するかを決定することは、セキュリティ、ユーザー体験、開発の複雑さに影響を与える重要な設計上の選択です。万能の答えはありません。

OAuthベースのアプリの場合: System WebView（ASWebAuthenticationSession、Chrome Custom Tabs）が推奨される出発点です。優れたOAuthサポート、最小限の実装工数、および自動的な認証情報共有を提供します。

ネイティブファーストのアプリの場合: できるだけ早くネイティブに移行しましょう。ネイティブのパスキーログインは、preferImmediatelyAvailableCredentialsのような独自の機能を備えた最もシームレスなUXを提供します。これにより、アプリ起動時に自動的にパスキーオーバーレイが表示されます。これはWebView実装では提供できません。iOSとAndroidがパスキーの第一級サポートを提供するようになった今、実際の成功事例は高い採用率を示しています。ツール（オープンソースのSDKやプラットフォームライブラリを含む）も成熟し、妥当な期間でネイティブ統合が達成可能になりました。デバイス管理ポリシー、クロスデバイス同期、サードパーティプロバイダに注意を払う必要がありますが、これらの課題は慎重なエンジニアリングとテストで管理できます。その結果、ユーザーをその簡単さと速さで喜ばせ、セキュリティを大幅に向上させるアプリログインが実現します。

Embedded WebViewのフレーム要件の場合: Embedded WebViewは、2つの実際のシナリオで一般的に使用されます。第一に、OAuthベースのアプリは、最初のログインフローにSystem WebViewを使用し、その後、セッション制御が必要な設定画面でパスキー管理オプションをレンダリングするためにEmbedded WebViewに切り替えることがよくあります。ただし、一部のアプリは両方のフローにSystem WebViewを使い続けることでこれを簡素化しています。第二に、パスキーを採用する前に既にWebViewフレームに認証フローを埋め込んでいたアプリは、一貫性のためにこのパターンを継続します。ネイティブWebAuthnサポートを備えたEmbedded WebView（AndroidX WebKit 1.12.1+）は、設定とセットアップ（権限、エンタイトルメント、WebView設定）が必要ですが、もはやカスタムのJavaScriptブリッジコードは必要ありません。Conditional UIはEmbedded WebViewではサポートされていないことに注意してください。既存の埋め込み認証パターンを維持する場合や、認証後の画面でセッション/Cookie制御が必要な場合にこのアプローチを選択してください。

最終的に、ネイティブアプリのパスキーは、ユーザーの利便性とセキュリティの両方において大きな飛躍を意味します。ネイティブ、System WebView、またはEmbedded WebViewのいずれを介して実装されても、フィッシングのリスクやパスワード管理の負担をユーザーから取り除きます。VicRoadsのネイティブアプリパスキー統合のような実際の導入事例は、自動パスキーオーバーレイのような機能で適切に実行された場合、ネイティブファーストのアプローチが最高のユーザー採用率と満足度をもたらすことを示しています。ユーザーフレンドリーな認証のベストプラクティスに従い、アプリのアーキテクチャに合った実装アプローチ（新しいアプリにはネイティブファースト、OAuthフローにはSystem WebView、既存の埋め込みパターンにはEmbedded WebView）を選択することで、パスキーのビジョンである、誰にとってもシンプルで安全、そして快適な認証を真に実現するパスワードレスの生体認証ログインを提供できます。

ネイティブアプリでパスキーが機能しない場合は、実装アプローチごとにこれらの一般的な問題を確認してください。

• ファイルが有効な証明書を持つHTTPS経由で提供されているか
• 正しいMIMEタイプ：application/json
• .well-knownパスにリダイレクトがないか
• iOS：AASAファイル内のTeam IDとBundle IDが正確に一致しているか
• Android：assetlinks.json内のSHA256フィンガープリントが署名証明書と一致しているか
• Relying Party IDがドメインと一致しているか（プロトコル、ポートなし）
• RP IDの末尾にスラッシュがないか
• WebAuthnオリジン：https://your-domain.com（app://ではない）

• iOS：XcodeでAssociated Domainsケーパビリティがwebcredentials:yourdomain.comで有効になっているか
• Android：AndroidManifest.xmlでDigital Asset Linksが宣言されているか
• ユーザーが画面ロック（生体認証またはPIN）を有効にしているか
• AppleのAASA ValidatorとGoogleのDigital Asset Linksツールでテストする
• Runner.entitlementsファイルに正しい関連ドメインが含まれていることを確認する

• iOS：ASWebAuthenticationSession（推奨）またはSFSafariViewControllerを使用しているか
• Android：Chrome Custom Tabs（プレーンなWebViewではない）を使用しているか
• iOS：必要に応じてAssociated Domainsが設定されていることを確認する
• Cookie/認証情報がシステムブラウザと共有されていることをテストする
• ウェブ認証ページに適切なWebAuthn実装があることを確認する

• iOS：適切なエンタイトルメントで設定されているか
• iOS：Associated Domainsに関連するすべてのドメインが含まれているか
• iOS：AASAファイルがアクセス可能で、正しくフォーマットされているか
• iOS：開発中は?mode=developerでテストする（本番では削除）
• Android：プロジェクトにAndroidX WebKit 1.12.1+（またはそれ以降）が含まれているか
• Android：WebViewFeature.WEB_AUTHENTICATIONのランタイム機能チェック
• Android：setWebAuthenticationSupport()がWEB_AUTHENTICATION_SUPPORT_FOR_APPで呼び出されているか
• Android：WebView設定でJavaScriptが有効になっているか
• Android：ユーザーのWebView APKバージョンがWebAuthn機能をサポートしているか（OSバージョンではなく機能検出を使用）
• Conditional UIが使用されていないか（Embedded WebViewでは非対応）
• WebAuthn機能が利用できない場合はChrome Custom Tabsにフォールバックする

• ユーザーがデフォルト以外の認証情報プロバイダ（1Password、Bitwardenなど）をアクティブにしているか確認する
• プロバイダがパスキーをサポートしているか確認する（すべてのパスワードマネージャーがサポートしているわけではない）
• プラットフォームネイティブの認証情報マネージャー（iCloud Keychain、Googleパスワードマネージャー）でテストする

"NotAllowedError: The request is not allowed by the user agent or the platform in the current context"

• 通常の意味：エンタイトルメントの欠落（iOS）またはWebView機能が利用不可/無効（Android Embedded WebView）
• チェック項目：Associated Domainsの設定、AASAファイルのアクセシビリティ、WebKitのバージョン、機能検出、setWebAuthenticationSupport()の呼び出し

パスキーのプロンプトが表示されない

• 考えられる原因：AASA/assetlinks.jsonが読み込まれていない、間違ったWebViewタイプ、キャッシュされたAASAファイル
• 試すこと：関連付けファイルの検証、テスト用にiOSで?mode=developerを使用、WebViewタイプの確認

詳細なデバッグについては、ネイティブアプリにおけるRelying Party IDに関する記事を参照してください。

Corbado ネイティブSDK:

• iOS SDK (Swift)
• Android SDK (Kotlin)
• Flutter Package

プラットフォームドキュメント:

• Apple: Supporting Passkeys
• Google: Credential Manager

検証ツール:

• Apple AASA Validator
• Google Digital Asset Links Generator