Update WebAuthenticationRequested.md

Updated event's name to BasicAuthenticationRequest to clarify the scenario for the event.

Author: Cagri Yildirim

specs/WebAuthenticationRequested.md

@@ -21,50 +21,50 @@
 
 
 # Background
-By default HTTP basic authentication requests inside WebView2 show the authentication UI, which is a dialog prompt in which the user can type in user name and password credentials just like in the Edge browser. We have been requested by WebView2 app developers to provide finer granularity for managing HTTP Basic authentications inside WebView2, including the ability to hide the login UI and provide credentials.
+By default HTTP basic authentication and NTLM authentication requests inside WebView2 show the authentication UI, which is a dialog prompt in which the user can type in user name and password credentials just like in the Edge browser. We have been requested by WebView2 app developers to provide finer granularity for managing HTTP Basic/NTLM authentications inside WebView2, including the ability to hide the login UI and provide credentials.
 
 
 # Description
-We propose a new event for WebView2, CoreWebView2WebAuthenticationRequested that will allow developers to listen on and override the HTTP Basic authentication requests in WebView2. When there is a HTTP Basic authentication request in WebView2, the developer will have a choice to:
+We propose a new event for WebView2, CoreWebView2BasicAuthenticationRequested that will allow developers to listen on and override the HTTP Basic authentication requests in WebView2. When there is a HTTP Basic/NTLM authentication request in WebView2, the developer will have a choice to:
   1) Provide credentials
   2) Cancel the login altogether
   3) Ask the user for credentials via the default login prompt
-We also propose CoreWebView2WebAuthenticationResponse, the runtime class that represents the app's response with credentials to the basic authentication request.
+We also propose CoreWebView2BasicAuthenticationResponse, the runtime class that represents the app's response with credentials to the basic authentication request.
 
 # Examples
 ## Provide credentials
 The developer can provide the authentication credentials on behalf of the user when it encounters the Basic authentication request. In this case, the default login dialog prompt will no longer be shown to the user. If the developer provided credentials are wrong, the server may keep responding with Unauthorized, which will lead to an infinite loop so the developer should pay attention to this.
 
 ```cpp
 
-    webview2->add_WebAuthenticationRequested(
-        Callback<ICoreWebView2WebAuthenticationRequestedEventHandler>(
+    webview2->add_BasicAuthenticationRequested(
+        Callback<ICoreWebView2BasicAuthenticationRequestedEventHandler>(
             [this](
                 ICoreWebView2* sender,
-                ICoreWebView2WebAuthenticationRequestedEventArgs* args)
+                ICoreWebView2BasicAuthenticationRequestedEventArgs* args)
             {
                 wil::com_ptr<ICoreWebView2Environment> webviewEnvironment;
                 m_appWindow->GetWebViewEnvironment()->QueryInterface(
                     IID_PPV_ARGS(&webviewEnvironment));
                 wil::com_ptr<ICoreWebView2Deferral> deferral;
-                wil::com_ptr<ICoreWebView2WebAuthenticationRequestedEventArgs> web_auth_args = args;
+                wil::com_ptr<ICoreWebView2BasicAuthenticationRequestedEventArgs> web_auth_args = args;
                 args->GetDeferral(&deferral);
                 ShowCustomLoginUI().then([web_auth_args, deferral](LPCWSTR userName, LPCWSTR password) {
-                    wil::com_ptr<ICoreWebView2WebAuthenticationResponse> webAuthenticationResponse;
-                    args->get_Response(&webAuthenticationResponse);
-                    webAuthenticationResponse->put_UserName(userName);
-                    webAuthenticationResponse->put_Password(password);
+                    wil::com_ptr<ICoreWebView2BasicAuthenticationResponse> basicAuthenticationResponse;
+                    args->get_Response(&basicAuthenticationResponse);
+                    basicAuthenticationResponse->put_UserName(userName);
+                    basicAuthenticationResponse->put_Password(password);
                     deferral->Complete();
                 }
                 
                 return S_OK;
             })
             .Get(),
-        &m_webAuthenticationRequestedToken));
+        &m_BasicAuthenticationRequestedToken));
 ```
 
 ```c#
-webView.CoreWebView2.WebAuthenticationRequested += delegate (object sender, CoreWebView2WebAuthenticationRequestedEventArgs args)
+webView.CoreWebView2.BasicAuthenticationRequested += delegate (object sender, CoreWebView2BasicAuthenticationRequestedEventArgs args)
 {
     CoreWebView2Deferral deferral = args.GetDeferral();
     Credential credential = await ShowCustomLoginUIAsync();
@@ -78,36 +78,36 @@ webView.CoreWebView2.WebAuthenticationRequested += delegate (object sender, Core
 The developer can block the authentication request. In this case, the default login dialog prompt will no longer be shown to the user and the server will respond as if the user clicked cancel.
 
 ```cpp
-    webview2->add_WebAuthenticationRequested(
-        Callback<ICoreWebView2WebAuthenticationRequestedEventHandler>(
+    webview2->add_BasicAuthenticationRequested(
+        Callback<ICoreWebView2BasicAuthenticationRequestedEventHandler>(
             [this](
                 ICoreWebView2* sender,
-                ICoreWebView2WebAuthenticationRequestedEventArgs* args)
+                ICoreWebView2BasicAuthenticationRequestedEventArgs* args)
             {
                 args->put_Cancel(true);
 
                 return S_OK;
             })
             .Get(),
-        &m_webAuthenticationRequestedToken));
+        &m_BasicAuthenticationRequestedToken));
 ```
 
 ```c#
-webView.CoreWebView2.WebAuthenticationRequested += delegate (object sender, CoreWebView2WebAuthenticationRequestedEventArgs args)
+webView.CoreWebView2.BasicAuthenticationRequested += delegate (object sender, CoreWebView2BasicAuthenticationRequestedEventArgs args)
 {
     args.Cancel = true;
 };
 ```
 
-## Read authorization challenge string
-Developer can read the authorization challenge string sent by server. Note that if the developer doesn't cancel or provide a response, the default login dialog prompt will be shown to the user.
+## Read authentication challenge string
+Developer can read the authentication challenge string sent by server. Note that if the developer doesn't cancel or provide a response, the default login dialog prompt will be shown to the user.
 
 ```cpp
-webview2->add_WebAuthenticationRequested(
-    Callback<ICoreWebView2WebAuthenticationRequestedEventHandler>(
+webview2->add_BasicAuthenticationRequested(
+    Callback<ICoreWebView2BasicAuthenticationRequestedEventHandler>(
         [this](
             ICoreWebView2* sender,
-            ICoreWebView2WebAuthenticationRequestedEventArgs* args)
+            ICoreWebView2BasicAuthenticationRequestedEventArgs* args)
         {
             args->get_Challenge(&challenge);
             if (!ValidateChallenge(challenge.get())) { // Check the challenge string
@@ -116,11 +116,11 @@ webview2->add_WebAuthenticationRequested(
             return S_OK;
         })
         .Get(),
-    &m_webAuthenticationRequestedToken));
+    &m_BasicAuthenticationRequestedToken));
 ```
 
 ```c#
-webView.CoreWebView2.WebAuthenticationRequested += delegate (object sender, CoreWebView2WebAuthenticationRequestedEventArgs args)
+webView.CoreWebView2.BasicAuthenticationRequested += delegate (object sender, CoreWebView2BasicAuthenticationRequestedEventArgs args)
 {
     if (args.Challenge.Equals("Expected login credentials")) {
         args.Cancel = true;
@@ -144,66 +144,66 @@ interface ICoreWebView2_4 : ICoreWebView2_3
 {
   /// ...
 
-  /// Add an event handler for the WebAuthenticationRequested event.
-  /// WebAuthenticationRequested event is raised when WebView encounters a Basic HTTP
+  /// Add an event handler for the BasicAuthenticationRequested event.
+  /// BasicAuthenticationRequested event is raised when WebView encounters a Basic HTTP
   /// Authentication request as described in
   /// https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication.
   ///
   /// The host can provide a response with credentials for the authentication or
   /// cancel the request. If the host doesn't set the Cancel property to true or
   /// populate the Response property, then WebView2 will show the default
-  /// authorization challenge dialog prompt to the user.
+  /// authentication challenge dialog prompt to the user.
   ///
-  HRESULT add_WebAuthenticationRequested(
-    [in] ICoreWebView2WebAuthenticationRequestedEventHandler* eventHandler,
+  HRESULT add_BasicAuthenticationRequested(
+    [in] ICoreWebView2BasicAuthenticationRequestedEventHandler* eventHandler,
     [out] EventRegistrationToken* token);
   /// Remove an event handler previously added with add_WebResourceRequested.
-  HRESULT remove_WebAuthenticationRequested(
+  HRESULT remove_BasicAuthenticationRequested(
       [in] EventRegistrationToken token);
 }
 
-/// This is the CoreWebView2WebAuthenticationRequestedEventHandler interface
+/// This is the CoreWebView2BasicAuthenticationRequestedEventHandler interface
 [uuid(f87e5d35-3248-406b-81dd-1c36aab8081d), object, pointer_default(unique)]
-interface ICoreWebView2WebAuthenticationRequestedEventHandler : IUnknown
+interface ICoreWebView2BasicAuthenticationRequestedEventHandler : IUnknown
 {
   /// Called to provide the implementer with the event args for the
   /// corresponding event.
   HRESULT Invoke(
       [in] ICoreWebView2* sender,
-      [in] ICoreWebView2WebAuthenticationRequestedEventArgs* args);
+      [in] ICoreWebView2BasicAuthenticationRequestedEventArgs* args);
 }
 
 /// Represents a Basic HTTP authentication response that contains a user name
 /// and a password as according to RFC7617 (https://tools.ietf.org/html/rfc7617)
 [uuid(bc9cfd60-29c4-4943-a83b-d0d2f3e7df03), object, pointer_default(unique)]
-interface ICoreWebView2WebAuthenticationResponse : IUnknown
+interface ICoreWebView2BasicAuthenticationResponse : IUnknown
 {
-  /// User name provided for authorization.
+  /// User name provided for authentication.
   [propget] HRESULT UserName([out, retval] LPWSTR* userName);
   /// Set user name property
   [propput] HRESULT UserName([in] LPCWSTR userName);
 
-  /// Password provided for authorization
+  /// Password provided for authentication
   [propget] HRESULT Password([out, retval] LPWSTR* password);
   /// Set password property
   [propput] HRESULT Password([in] LPCWSTR password);
 }
 
-/// Event args for the WebAuthorizationRequested event. Will contain the
-/// request that led to the HTTP authorization challenge, the challenge
-/// and allows the host to provide authentication response or cancel the request.
+/// Event args for the BasicAuthenticationRequested event. Will contain the
+/// request that led to the HTTP authentication challenge, the challenge
+/// and allows the host to provide credentials response or cancel the request.
 [uuid(51d3adaa-159f-4e48-ad39-a86beb2c1435), object, pointer_default(unique)]
-interface ICoreWebView2WebAuthenticationRequestedEventArgs : IUnknown
+interface ICoreWebView2BasicAuthenticationRequestedEventArgs : IUnknown
 {
-  /// The web resource request that led to the authorization challenge
+  /// The web resource request that led to the authentication challenge
   [propget] HRESULT Request([out, retval] ICoreWebView2WebResourceRequest** request);
 
-  /// The authorization challenge string
+  /// The authentication challenge string
   [propget] HRESULT Challenge([out, retval] LPWSTR* challenge);
 
   /// Response to the authentication request with credentials. This object will be populated by the app
   /// if the host would like to provide authentication credentials.
-  [propget] HRESULT Response([out, retval] ICoreWebView2WebAuthenticationResponse** response);
+  [propget] HRESULT Response([out, retval] ICoreWebView2BasicAuthenticationResponse** response);
   
   /// Cancel the authentication request. False by default.
   /// If set to true, Response set will be ignored.
@@ -221,15 +221,15 @@ interface ICoreWebView2WebAuthenticationRequestedEventArgs : IUnknown
 ```c#
 namespace Microsoft.Web.WebView2.Core
 {
-    /// Event args for the WebAuthorizationRequested event. Will contain the
-    /// request that led to the HTTP authorization challenge, the challenge
+    /// Event args for the BasicAuthenticationRequested event. Will contain the
+    /// request that led to the HTTP authentication challenge, the challenge
     /// and allows the host to provide authentication response or cancel the request.
-    runtimeclass CoreWebViewWebAuthenticationRequestedEventArgs
+    runtimeclass CoreWebViewBasicAuthenticationRequestedEventArgs
     {
-        /// The web resource request that led to the authorization challenge
+        /// The web resource request that led to the authentication challenge
         CoreWebView2WebResourceRequest Request { get; };
 
-        /// The HTTP basic authorization challenge string
+        /// The HTTP basic authentication challenge string
         String Challenge { get; };
 
         /// Cancel the authentication request. False by default.
@@ -238,33 +238,33 @@ namespace Microsoft.Web.WebView2.Core
 
         /// Response to the authentication request with credentials. This object will be populated by the app
         /// if the host would like to provide authentication credentials.
-        CoreWebView2WebAuthenticationResponse Response { get; };
+        CoreWebView2BasicAuthenticationResponse Response { get; };
     }
 
     /// Represents a Basic HTTP authentication response that contains a user name
     /// and a password as according to RFC7617 (https://tools.ietf.org/html/rfc7617)
-    runtimeclass CoreWebView2WebAuthenticationResponse
+    runtimeclass CoreWebView2BasicAuthenticationResponse
     {
-        /// User name provided for authorization.
+        /// User name provided for authentication.
         String UserName { get; set; }
 
-        /// Password provided for authorization
+        /// Password provided for authentication
         String Password { get; set; };
     }
 
     runtimeclass CoreWebView2
     {
         ...
 
-        /// Add an event handler for the WebAuthenticationRequested event.
-        /// WebAuthenticationRequested event is raised when WebView encountered a Basic HTTP
+        /// Add an event handler for the BasicAuthenticationRequested event.
+        /// BasicAuthenticationRequested event is raised when WebView encountered a Basic HTTP
         /// Authentication request.
         ///
         /// The host can populate the response object with credentials it wants to use for the authentication or
         /// cancel the request. If the host doesn't handle the event, WebView will show
-        /// the authorization challenge dialog prompt to user.
+        /// the authentication challenge dialog prompt to user.
         ///
-        event Windows.Foundation.TypedEventHandler<CoreWebView2, CoreWebViewWebAuthenticationRequestedEventArgs> WebAuthenticationRequested;
+        event Windows.Foundation.TypedEventHandler<CoreWebView2, CoreWebViewBasicAuthenticationRequestedEventArgs> BasicAuthenticationRequested;
     }
 }
 ```