Обычная проверка подлинности для приложений WebView2

Обычная проверка подлинности — это подход к проверке подлинности , который является частью протокола 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, чтобы убедиться, что учетные данные зашифрованы.

Порядок событий навигации

Базовое событие проверки подлинности происходит в середине последовательности событий:

1. NavigationStarting — событие навигации
2. ContentLoading - navigation event
3. BasicAuthenticationRequested
4. DOMContentLoaded
5. NavigationCompleted - navigation event

Дополнительные сведения см. в разделе События навигации для приложений WebView2.

Обмен данными между HTTP-сервером, элементом управления WebView2 и ведущим приложением

• HTTP-сервер проверяет проверку подлинности (учетные данные имени пользователя и пароля) и возвращает документ об ошибке или запрошенную веб-страницу.

• Экземпляр элемента управления WebView2 вызывает события. Элемент управления WebView2 находится между HTTP-сервером и ведущим приложением. Элемент управления WebView2 служит посредником для обмена данными между ведущим приложением и HTTP-сервером.

• Вы пишете ведущее приложение. Ведущее приложение задает имя пользователя и пароль для объектов ответа аргументов события (EventArgs).

BasicAuthenticationRequestedEventArgs Response имеет свойство . Свойство Response — это объект, содержащий свойства имени пользователя и пароля.

Последовательность событий навигации

На следующей схеме показан поток событий навигации для базовой проверки подлинности для приложений WebView2:

1. Ведущее приложение сообщает элементу управления WebView2 перейти к URI.

2. Элемент управления WebView2 взаимодействует с HTTP-сервером, запрашивающим получение документа по указанному URI.

3. HTTP-сервер отвечает на элемент управления WebView2: "Вы не можете получить этот URI (документ) без проверки подлинности".

4. Элемент управления WebView2 сообщает ведущему приложению: "Требуется проверка подлинности" (это BasicAuthenticationRequested событие).

5. Ведущее приложение реагирует на это событие, предоставляя имя пользователя и пароль для элемента управления WebView2.

6. Элемент управления WebView2 снова запрашивает URI с HTTP-сервера, но на этот раз с проверкой подлинности (имя пользователя и пароль).

7. HTTP-сервер оценивает учетные данные (имя пользователя и пароль).

8. HTTP-сервер может запретить учетные данные и запросить новые учетные данные.

9. HTTP-сервер может отклонить имя пользователя и пароль; он может сказать элементу управления WebView2 : "Вы не можете получить этот URI/документ".

10. Элемент управления WebView2 отображает страницу ошибки, возвращенную HTTP-сервером. Отрисовка происходит между событием и DOMContentLoaded событиемContentLoading.

11. HTTP-сервер может принять учетные данные проверки подлинности и вернуть запрошенный документ.

12. Элемент управления WebView2 отображает возвращенный документ. The rendering occurs between the ContentLoading event and DOMContentLoaded event.

Пример кода: приложение предоставляет учетные данные, известные заранее

В следующем упрощенном примере показано, как ведущее приложение предоставляет учетные данные (имя пользователя и пароль), которые известны заранее. Этот пример представляет собой немного измененную версию кода, которая находится в репозитории > WebView2Samples WebView2APISample > ScenarioAuthentication.cpp.

Этот пример нереалистичен, так как:

• На практике вы запрашиваете у пользователя имя пользователя и пароль, а не жесткое кодирования, например "user" и "pass".
• Этот код является синхронным, но вместо него вы, вероятно, будете использовать асинхронный код.

Более реалистичный код см. в следующем разделе.

C#

// 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:

• Событие CoreWebView2.BasicAuthenticationRequested
• Класс CoreWebView2BasicAuthenticationRequestedEventArgs

C++

// 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 .

C#

// 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()

C++

// 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 поле.

При запуске новой навигации назначается новый идентификатор навигации. Для новой навигации HTTP-сервер предоставил элементу управления WebView2 документ. Это навигация "есть документ".

В рамках навигации элемент управления WebView2 отрисовывает соответствующую страницу (запрошенную страницу или страницу ошибки, в зависимости от того, что возвращает HTTP-сервер), а результат "успешно" или "сбой" приводит к возникновению события успешного или неудачного NavigationCompleted выполнения.

For more information, see Navigation events for WebView2 apps.

Навигация для обычной проверки подлинности

В потоке существует два типа навигации:

• Навигация по запросу сервера.
• Навигация "Сервер предоставил WebView2 управление документом".

После первого типа навигации сервер запросил проверку подлинности, и приложению необходимо повторить попытку такой навигации (с новым идентификатором навигации). Новая навигация будет использовать все, что ведущее приложение получает от объектов ответа аргументов событий.

ДЛЯ HTTP-сервера может потребоваться проверка подлинности HTTP. В этом случае существует первая навигация с событиями навигации, перечисленными выше. HTTP-сервер возвращает HTTP-ответ 401 или 407, поэтому NavigationCompleted событие имеет соответствующий сбой. Затем WebView2 отрисовывает пустую страницу и вызывает BasicAuthenticationRequested событие, которое может предложить пользователю ввести учетные данные.

BasicAuthenticationRequested Если событие отменено, навигация не будет выполнена, и WebView2 останется для отображения пустой страницы.

BasicAuthenticationRequested Если событие не отменено, WebView2 снова выполнит начальную навигацию, но на этот раз, используя любые предоставленные учетные данные. Вы снова увидите все те же события навигации, что и раньше.

Если учетные данные не принимаются HTTP-сервером, переход снова завершается ошибкой с 401 или 407. В этом случае CoreWebView2 экземпляр класса снова вызывает BasicAuthenticationRequested событие, и навигация продолжается, как описано выше.

Навигация завершается успешно, если учетные данные принимаются HTTP-сервером. Навигация завершается сбоем, если HTTP-сервер запрещает проверку подлинности (обычно сервер возвращает страницу ошибки).

Навигации до и после BasicAuthenticationRequested события являются отдельными навигациями и имеют разные идентификаторы навигации.

Навигация event args имеет свойство : .NavigationId Связывает NavigationId события навигации, соответствующие одной навигации. Значение NavigationId остается неизменным во время каждой навигации, например при повторных попытках. Во время следующего прохода через поток событий используется другое NavigationId .

Обзор справочника по API

C#

• Класс CoreWebView2BasicAuthenticationRequestedEventArgs
• Событие CoreWebView2.BasicAuthenticationRequested
• Класс CoreWebView2Deferral

C++

• Интерфейс ICoreWebView2BasicAuthenticationRequestedEventArgs
• метод add_BasicAuthenticationRequested
• Интерфейс ICoreWebView2Deferral
• ICoreWebView2BasicAuthenticationRequestedEventHandler

См. также

• Проверка подлинности HTTP в MDN.