WebView2 アプリの基本認証

[アーティクル]
04/04/2023

基本認証 は、HTTP プロトコルの一部である認証アプローチです。

Basic authentication for WebView2 apps includes a sequence of authentication and navigation steps to retrieve a webpage from an HTTP server. The WebView2 control acts as an intermediary for communication between the host app and the HTTP server.

資格情報の送信に HTTPS を使用する

警告: 基本認証を使用する場合は、HTTPS を使用する必要があります。それ以外の場合、ユーザー名とパスワードは暗号化されません。他の形式の認証を検討することもできます。

基本認証の HTTP 標準には、暗号化されていない認証資格情報 (ユーザー名とパスワード) が含まれています。そのため、資格情報が暗号化されていることを確認するには、を使用 httpsする必要があります。

基本認証イベントは、一連のイベントの途中で発生します。

NavigationStarting - ナビゲーションイベント
ContentLoading - navigation event
BasicAuthenticationRequested
DOMContentLoaded
NavigationCompleted - navigation event

詳細については、「 WebView2 アプリのナビゲーションイベント」を参照してください。

HTTP サーバー、WebView2 コントロール、およびホストアプリ間の通信

HTTP サーバーは認証 (ユーザー名とパスワードの資格情報) を確認し、エラードキュメントまたは要求された Web ページを返します。
WebView2 コントロール インスタンスによってイベントが発生します。 WebView2 コントロールは、HTTP サーバーとホストアプリの間に位置します。 WebView2 コントロールは、ホストアプリと HTTP サーバー間の通信の仲介役として機能します。
ホストアプリを作成します。ホストアプリは、イベントの引数 (EventArgs) 応答オブジェクトにユーザー名とパスワードを設定します。

BasicAuthenticationRequestedEventArgs にはプロパティがあります Response 。プロパティは Response 、ユーザー名とパスワードのプロパティを含むオブジェクトです。

次の図は、WebView2 アプリの基本認証のナビゲーションイベントのフローを示しています。

ホストアプリは、URI に移動するように WebView2 コントロールに指示します。
WebView2 コントロールは、指定された URI でドキュメントを取得することを要求する HTTP サーバーと通信します。
HTTP サーバーは WebView2 コントロールに応答し、"認証なしでその URI (ドキュメント) を取得することはできません" と応答します。
WebView2 コントロールは、ホストアプリに "認証が必要です" (イベント) BasicAuthenticationRequested を通知します。
ホストアプリは、WebView2 コントロールにユーザー名とパスワードを指定することで、そのイベントに応答します。
WebView2 コントロールはもう一度 HTTP サーバーから URI を要求しますが、今回は認証 (ユーザー名とパスワード) を使用します。
HTTP サーバーは、資格情報 (ユーザー名とパスワード) を評価します。
HTTP サーバーは資格情報を拒否し、新しい資格情報を要求する場合があります。
HTTP サーバーは、ユーザー名とパスワードを拒否する場合があります。WebView2 コントロールに "その URI/ドキュメントの取得は許可されていません" と表示される場合があります。
WebView2 コントロールは、HTTP サーバーによって返されるエラーページをレンダリングします。レンダリングは、イベントとDOMContentLoadedイベントの間でContentLoading発生します。
HTTP サーバーは認証資格情報を受け入れ、要求されたドキュメントを返す場合があります。
WebView2 コントロールは、返されたドキュメントをレンダリングします。 The rendering occurs between the ContentLoading event and DOMContentLoaded event.

コード例: 事前に認識されている資格情報を提供するアプリ

次の簡略化された例は、事前に認識されている資格情報 (ユーザー名とパスワード) を提供するホストアプリを示しています。この例は、 WebView2Samples リポジトリ > WebView2APISample > ScenarioAuthentication.cpp にあるコードのわずかに変更されたバージョンです。

次の理由から、この例は現実的ではありません。

実際には、やのように"user""pass"ハードコーディングするのではなく、ユーザーにユーザー名とパスワードの入力を求めます。
このコードは同期的ですが、代わりに非同期コードを使用する可能性があります。

より現実的なコードについては、以降のセクションを参照してください。

// Prerequisite: Before using this code, make sure you read the section "Use HTTPS 
// for sending credentials" in this article.
    webView.CoreWebView2.BasicAuthenticationRequested += delegate (
       object sender, 
       CoreWebView2BasicAuthenticationRequestedEventArgs args)
    {
        args.Response.UserName = "user";
        args.Response.Password = "pass";
    };

Api：

// Prerequisite: Before using this code, make sure you read the section "Use HTTPS 
// for sending credentials" in this article.
if (auto webView10 = m_webView.try_query<ICoreWebView2_10>())
{
   CHECK_FAILURE(webView10->add_BasicAuthenticationRequested(
      Callback<ICoreWebView2BasicAuthenticationRequestedEventHandler>(
            [this](
               ICoreWebView2* sender,
               ICoreWebView2BasicAuthenticationRequestedEventArgs* args)
            {
               wil::com_ptr<ICoreWebView2BasicAuthenticationResponse> basicAuthenticationResponse;
               CHECK_FAILURE(args->get_Response(&basicAuthenticationResponse));
               CHECK_FAILURE(basicAuthenticationResponse->put_UserName(L"user"));
               CHECK_FAILURE(basicAuthenticationResponse->put_Password(L"pass"));

               return S_OK;
            })
            .Get(),
      &m_basicAuthenticationRequestedToken));
}
else
{
   FeatureNotAvailable();
}

APIs:

ICoreWebView2BasicAuthenticationRequestedEventHandler
ICoreWebView2BasicAuthenticationRequestedEventArgs
- get_Cancel
- put_Cancel
- get_Challenge
- get_Response
- get_Uri
- GetDeferral

コード例: ユーザーに資格情報の入力を求める

この例では、ユーザーに資格情報 (ユーザー名とパスワード) を求めるホストアプリを示し、非同期コードを使用します。

この例は、次の機能を追加することで、上記のサンプルに基づいています。

ユーザー名とパスワードの入力を求めるダイアログを表示します。
引数の GetDeferral メソッドを event 呼び出します。

// Prerequisite: Before using this code, make sure you read the section "Use HTTPS 
// for sending credentials" in this article.
webView.CoreWebView2.BasicAuthenticationRequested += delegate (
    object sender, 
    CoreWebView2BasicAuthenticationRequestedEventArgs args)
{
    // We need to show UI asynchronously so we obtain a deferral.
    // A deferral will delay the CoreWebView2 from
    // examining the properties we set on the event args until
    // after we call the Complete method asynchronously later.
    // This gives us time to asynchronously show UI.
    CoreWebView2Deferral deferral = args.GetDeferral();

    // We avoid potential reentrancy from running a message loop in the
    // event handler by showing our download dialog later when we
    // complete the deferral asynchronously.
    System.Threading.SynchronizationContext.Current.Post((_) =>
    {
        using (deferral)
        {
            // When prompting the end user for authentication its important
            // to show them the URI or origin of the URI that is requesting
            // authentication so the end user will know who they are giving
            // their username and password to.

            // Its also important to display the challenge to the end user
            // as it may have important site specific information for the
            // end user to provide the correct username and password.

            // Use an app or UI framework method to get input from the end user.
            TextInputDialog dialog = new TextInputDialog(
                title: "Authentication Request",
                description: "Authentication request from " + args.Uri + "\r\n" +
                    "Challenge: " + args.Challenge,
                defaultInput: "username\r\npassword");
            bool userNameAndPasswordSet = false;

            if (dialog.ShowDialog().GetValueOrDefault(false))
            {
                string[] userNameAndPassword = dialog.Input.Text.Split(
                    new char[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries);
                if (userNameAndPassword.Length > 1)
                {
                    args.Response.UserName = userNameAndPassword[0];
                    args.Response.Password = userNameAndPassword[1];
                    userNameAndPasswordSet = true;
                }
            }

            // If we didn't get a username and password from the end user then
            // we cancel the authentication request and don't provide any
            // authentication.
            if (!userNameAndPasswordSet)
            {
                args.Cancel = true;
            }
        }
    }, null);
};

APIs:

CoreWebView2BasicAuthenticationRequestedEventArgs Class
- プロパティ:
  - Cancel
  - Challenge
  - Response
  - Uri
- メソッド：
  - GetDeferral()

// Prerequisite: Before using this code, make sure you read the section "Use HTTPS 
// for sending credentials" in this article.
if (auto webView10 = m_webView.try_query<ICoreWebView2_10>())
{
    CHECK_FAILURE(webView10->add_BasicAuthenticationRequested(
        Callback<ICoreWebView2BasicAuthenticationRequestedEventHandler>(
            [this](
                ICoreWebView2* sender,
                ICoreWebView2BasicAuthenticationRequestedEventArgs* argsRaw)
            {
                // Make a smart pointer copy of the event args so we can take it
                // into our lambda below.
                wil::com_ptr<ICoreWebView2BasicAuthenticationRequestedEventArgs>
                    args = argsRaw;

                // We need to show UI asynchronously so we obtain a deferral.
                // A deferral will delay the CoreWebView2 from
                // examining the properties we set on the event args until
                // after we call the Complete method asynchronously later.
                // This gives us time to asynchronously show UI.
                wil::com_ptr<ICoreWebView2Deferral> deferral;
                CHECK_FAILURE(args->GetDeferral(&deferral));

                HWND mainWindowHwnd = m_appWindow->GetMainWindow();

                m_appWindow->RunAsync([args, deferral, mainWindowHwnd]()
                    {
                        wil::com_ptr<ICoreWebView2BasicAuthenticationResponse>
                            basicAuthenticationResponse;
                        CHECK_FAILURE(args->get_Response(&basicAuthenticationResponse));

                        wil::unique_cotaskmem_string uri;
                        CHECK_FAILURE(args->get_Uri(&uri));

                        wil::unique_cotaskmem_string challenge;
                        CHECK_FAILURE(args->get_Challenge(&challenge));

                        // When prompting the end user for authentication its important
                        // to show them the URI or origin of the URI that is requesting
                        // authentication so the end user will know who they are giving
                        // their username and password to.
                        std::wstring prompt = L"Authentication request from ";
                        prompt += uri.get();
                        // Its also important to display the challenge to the end user
                        // as it may have important site specific information for the
                        // end user to provide the correct username and password.
                        prompt += L"\r\nChallenge: ";
                        prompt += challenge.get(); 

                        // Use an app or UI framework method to get input from the end user.
                        TextInputDialog dialog(
                            mainWindowHwnd, 
                            L"Authentication Request",
                            L"User name and password",
                            prompt.c_str(),
                            L"username\r\npassword");
                        bool userNameAndPasswordSet = false;

                        if (dialog.confirmed)
                        {
                            const std::wstring& userNameAndPassword = dialog.input;
                            std::size_t separatorIdx = userNameAndPassword.find(L"\r\n");
                            if (separatorIdx != std::wstring::npos)
                            {
                                std::wstring userName =
                                    userNameAndPassword.substr(0, separatorIdx);
                                std::wstring password =
                                    userNameAndPassword.substr(separatorIdx + 2);

                                basicAuthenticationResponse->put_UserName(userName.c_str());
                                basicAuthenticationResponse->put_Password(password.c_str());

                                userNameAndPasswordSet = true;
                            }
                        }

                        // If we didn't get a username and password from the end user then
                        // we cancel the authentication request and don't provide any
                        // authentication.
                        if (!userNameAndPasswordSet)
                        {
                            args->put_Cancel(TRUE);
                        }

                        // We've finished our asynchronous work and so we complete the
                        // deferral to let the CoreWebView2 know that we're done changing
                        // values on the event args.
                        deferral->Complete();
                    });

                return S_OK;
            })
            .Get(),
        &m_basicAuthenticationRequestedToken));
}
else
{
    FeatureNotAvailable();
}

APIs:

ICoreWebView2BasicAuthenticationRequestedEventArgs
- get_Cancel
- put_Cancel
- get_Challenge
- get_Response
- get_Uri
- GetDeferral

ナビゲーションのしくみ

このセクションでは、ナビゲーションのしくみに関する省略可能な背景情報を提供します。

ナビゲーションは、複数のナビゲーションイベントに対応します。 ナビゲーションでは、上の図のボックスから始まる各再試行をNavigationStarting、ボックスをNavigationCompleted介して意味します。

新しいナビゲーションが開始されると、新しいナビゲーション ID が割り当てられます。新しいナビゲーションでは、HTTP サーバーによって WebView2 コントロールにドキュメントが渡されました。これは"ドキュメントを持つ" ナビゲーションです。

ナビゲーションの一環として、WebView2 コントロールは対応するページ (要求されたページまたはエラーページ、HTTP サーバーから返されるページ) をレンダリングし、"success" または "failure" の結果によって成功または失敗したイベントが NavigationCompleted 発生します。

For more information, see Navigation events for WebView2 apps.

基本認証のナビゲーション

フローには、次の 2 種類のナビゲーションがあります。

"サーバー要求認証" ナビゲーション。
"サーバーが WebView2 コントロールにドキュメントを渡しました" ナビゲーション。

最初の種類のナビゲーションの後、サーバーは認証を求め、アプリは (新しいナビゲーション ID を使用して) その種類のナビゲーションをもう一度試す必要があります。新しいナビゲーションでは、ホストアプリがイベント引数応答オブジェクトから取得した内容が使用されます。

HTTP サーバーには HTTP 認証が必要な場合があります。この場合、上に一覧表示されている ナビゲーション イベントを含む最初のナビゲーションがあります。 HTTP サーバーは 401 または 407 の HTTP 応答を返します。そのため NavigationCompleted 、イベントに対応するエラーが発生します。その後、WebView2 によって空白のページがレンダリングされ、イベントが BasicAuthenticationRequested 発生します。これにより、ユーザーに資格情報の入力を求めるメッセージが表示される可能性があります。

イベントが BasicAuthenticationRequested 取り消された場合、後続のナビゲーションはなく、WebView2 は空白のページを表示するために残ります。

イベントが BasicAuthenticationRequested 取り消されない場合、WebView2 は最初のナビゲーションをもう一度実行しますが、今回は指定された資格情報を使用します。以前と同じナビゲーションイベントがすべて再び表示されます。

資格情報が HTTP サーバーで受け入れられない場合、ナビゲーションは 401 または 407 で再度失敗します。その場合、クラスインスタンスでイベントが CoreWebView2 再度発生 BasicAuthenticationRequested し、ナビゲーションは上記のように続行されます。

資格情報が HTTP サーバーによって受け入れられる場合、ナビゲーションは成功します。 HTTP サーバーが認証を拒否した場合、ナビゲーションは失敗します (通常、サーバーはエラーページを返します)。

イベントの前後のナビゲーションは個別の BasicAuthenticationRequested ナビゲーションであり、個別のナビゲーション ID を持っています。

ナビゲーション event args には、プロパティがあります NavigationId。 NavigationId 1 つのナビゲーションに対応するナビゲーションイベントを結び付けます。は NavigationId 、再試行など、各ナビゲーション中も変わりません。次にイベントフローを通過する際に、別 NavigationId のが使用されます。

WebView2 アプリの基本認証

資格情報の送信に HTTPS を使用する

ナビゲーションイベントの順序

HTTP サーバー、WebView2 コントロール、およびホストアプリ間の通信

ナビゲーションイベントのシーケンス

コード例: 事前に認識されている資格情報を提供するアプリ

コード例: ユーザーに資格情報の入力を求める

ナビゲーションのしくみ

基本認証のナビゲーション

API リファレンスの概要

関連項目

その他のリソース

WebView2 アプリの基本認証

資格情報の送信に HTTPS を使用する

ナビゲーション イベントの順序

HTTP サーバー、WebView2 コントロール、およびホスト アプリ間の通信

ナビゲーション イベントのシーケンス

コード例: 事前に認識されている資格情報を提供するアプリ

コード例: ユーザーに資格情報の入力を求める

ナビゲーションのしくみ

基本認証のナビゲーション

API リファレンスの概要

関連項目

その他のリソース

ナビゲーションイベントの順序

HTTP サーバー、WebView2 コントロール、およびホストアプリ間の通信

ナビゲーションイベントのシーケンス