Skip to content

Commit 0cd248f

Browse files
author
Çağrı Kaan Yıldırım
authored
Merge pull request #1575 from MicrosoftEdge/yildirimcagri-web-authentication-requested-review2
BasicAuthenticationRequested API review
2 parents b6da5fb + a770271 commit 0cd248f

1 file changed

Lines changed: 276 additions & 0 deletions

File tree

‎specs/WebAuthenticationRequested.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
<!-- USAGE
2+
* Fill in each of the sections (like Background) below
3+
* Wrap code with `single line of code` or ```code block```
4+
* Before submitting, delete all <!-- TEMPLATE marked comments in this file,
5+
and the following quote banner:
6+
-->
7+
> See comments in Markdown for how to use this spec template
8+
9+
<!-- TEMPLATE
10+
The purpose of this spec is to describe a new WebView2 feature and its APIs.
11+
12+
There are two audiences for the spec. The first are people
13+
that want to evaluate and give feedback on the API, as part of
14+
the submission process. When it's complete
15+
it will be incorporated into the public documentation at
16+
docs.microsoft.com (https://docs.microsoft.com/en-us/microsoft-edge/webview2/).
17+
Hopefully we'll be able to copy it mostly verbatim.
18+
So the second audience is everyone that reads there to learn how
19+
and why to use this API.
20+
-->
21+
22+
23+
# Background
24+
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.
25+
26+
27+
# Description
28+
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:
29+
1) Provide credentials
30+
2) Cancel the login altogether
31+
3) Ask the user for credentials via the default login prompt
32+
We also propose CoreWebView2BasicAuthenticationResponse, the runtime class that represents the app's response with credentials to the basic authentication request.
33+
34+
# Examples
35+
## Provide credentials
36+
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.
37+
38+
```cpp
39+
40+
CHECK_HRESULT(webview2->add_BasicAuthenticationRequested(
41+
Callback<ICoreWebView2BasicAuthenticationRequestedEventHandler>(
42+
[this](
43+
ICoreWebView2* sender,
44+
ICoreWebView2BasicAuthenticationRequestedEventArgs* args)
45+
{
46+
wil::com_ptr<ICoreWebView2Deferral> deferral;
47+
48+
args->GetDeferral(&deferral);
49+
ShowCustomLoginUI().then([web_auth_args = wil::make_com_ptr(args), deferral](LPCWSTR userName, LPCWSTR password)
50+
{
51+
wil::com_ptr<ICoreWebView2BasicAuthenticationResponse> basicAuthenticationResponse;
52+
CHECK_HRESULT(web_auth_args->get_Response(&basicAuthenticationResponse));
53+
CHECK_HRESULT(basicAuthenticationResponse->put_UserName(userName));
54+
CHECK_HRESULT(basicAuthenticationResponse->put_Password(password));
55+
deferral->Complete();
56+
});
57+
58+
return S_OK;
59+
})
60+
.Get(),
61+
&m_BasicAuthenticationRequestedToken));
62+
```
63+
64+
```c#
65+
webView.CoreWebView2.BasicAuthenticationRequested += delegate (object sender, CoreWebView2BasicAuthenticationRequestedEventArgs args)
66+
{
67+
using (CoreWebView2Deferral deferral = args.GetDeferral())
68+
{
69+
Credential credential = await ShowCustomLoginUIAsync();
70+
args.Response.UserName = credential.UserName;
71+
args.Response.Password = credential.Password;
72+
deferral.Complete();
73+
}
74+
};
75+
```
76+
77+
## Cancel authentication prompt
78+
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.
79+
80+
```cpp
81+
CHECK_HRESULT(webview2->add_BasicAuthenticationRequested(
82+
Callback<ICoreWebView2BasicAuthenticationRequestedEventHandler>(
83+
[this](
84+
ICoreWebView2* sender,
85+
ICoreWebView2BasicAuthenticationRequestedEventArgs* args)
86+
{
87+
CHECK_HRESULT(args->put_Cancel(true));
88+
89+
return S_OK;
90+
})
91+
.Get(),
92+
&m_BasicAuthenticationRequestedToken));
93+
```
94+
95+
```c#
96+
webView.CoreWebView2.BasicAuthenticationRequested += delegate (object sender, CoreWebView2BasicAuthenticationRequestedEventArgs args)
97+
{
98+
args.Cancel = true;
99+
};
100+
```
101+
102+
## Read authentication challenge string
103+
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.
104+
105+
```cpp
106+
webview2->add_BasicAuthenticationRequested(
107+
Callback<ICoreWebView2BasicAuthenticationRequestedEventHandler>(
108+
[this](
109+
ICoreWebView2* sender,
110+
ICoreWebView2BasicAuthenticationRequestedEventArgs* args)
111+
{
112+
CHECK_HRESULT(args->get_Challenge(&challenge));
113+
if (!ValidateChallenge(challenge.get()))
114+
{ // Check the challenge string
115+
CHECK_HRESULT(args->put_Cancel(true));
116+
}
117+
return S_OK;
118+
})
119+
.Get(),
120+
&m_BasicAuthenticationRequestedToken));
121+
```
122+
123+
```c#
124+
webView.CoreWebView2.BasicAuthenticationRequested += delegate (object sender, CoreWebView2BasicAuthenticationRequestedEventArgs args)
125+
{
126+
if (!ValidateChallenge(args.Challenge))
127+
{
128+
args.Cancel = true;
129+
}
130+
};
131+
```
132+
133+
# Remarks
134+
135+
136+
# API Notes
137+
138+
139+
# API Details
140+
```idl
141+
/// WebView2 enables you to host web content using the latest Microsoft Edge
142+
/// browser and web technology.
143+
144+
[uuid(76eceacb-0462-4d94-ac83-423a6793775e), object, pointer_default(unique)]
145+
interface ICoreWebView2_4 : ICoreWebView2_3
146+
{
147+
/// ...
148+
149+
/// Add an event handler for the BasicAuthenticationRequested event.
150+
/// BasicAuthenticationRequested event is raised when WebView encounters a Basic HTTP
151+
/// Authentication request as described in
152+
/// https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication or an NTLM authentication request.
153+
///
154+
/// The host can provide a response with credentials for the authentication or
155+
/// cancel the request. If the host doesn't set the Cancel property to true or
156+
/// set either UserName or Password properties on the Response property, then WebView2 will show the default
157+
/// authentication challenge dialog prompt to the user.
158+
///
159+
HRESULT add_BasicAuthenticationRequested(
160+
[in] ICoreWebView2BasicAuthenticationRequestedEventHandler* eventHandler,
161+
[out] EventRegistrationToken* token);
162+
/// Remove an event handler previously added with add_WebResourceRequested.
163+
HRESULT remove_BasicAuthenticationRequested(
164+
[in] EventRegistrationToken token);
165+
}
166+
167+
/// This is the CoreWebView2BasicAuthenticationRequestedEventHandler interface
168+
[uuid(f87e5d35-3248-406b-81dd-1c36aab8081d), object, pointer_default(unique)]
169+
interface ICoreWebView2BasicAuthenticationRequestedEventHandler : IUnknown
170+
{
171+
/// Called to provide the implementer with the event args for the
172+
/// corresponding event.
173+
HRESULT Invoke(
174+
[in] ICoreWebView2* sender,
175+
[in] ICoreWebView2BasicAuthenticationRequestedEventArgs* args);
176+
}
177+
178+
/// Represents a Basic HTTP authentication response that contains a user name
179+
/// and a password as according to RFC7617 (https://tools.ietf.org/html/rfc7617)
180+
[uuid(bc9cfd60-29c4-4943-a83b-d0d2f3e7df03), object, pointer_default(unique)]
181+
interface ICoreWebView2BasicAuthenticationResponse : IUnknown
182+
{
183+
/// User name provided for authentication.
184+
[propget] HRESULT UserName([out, retval] LPWSTR* userName);
185+
/// Set user name property
186+
[propput] HRESULT UserName([in] LPCWSTR userName);
187+
188+
/// Password provided for authentication.
189+
[propget] HRESULT Password([out, retval] LPWSTR* password);
190+
/// Set password property
191+
[propput] HRESULT Password([in] LPCWSTR password);
192+
}
193+
194+
/// Event args for the BasicAuthenticationRequested event. Will contain the
195+
/// request that led to the HTTP authentication challenge, the challenge
196+
/// and allows the host to provide credentials response or cancel the request.
197+
[uuid(51d3adaa-159f-4e48-ad39-a86beb2c1435), object, pointer_default(unique)]
198+
interface ICoreWebView2BasicAuthenticationRequestedEventArgs : IUnknown
199+
{
200+
/// The URI that led to the authentication challenge
201+
[propget] HRESULT Uri([out, retval] LPWSTR* value);
202+
203+
/// The authentication challenge string
204+
[propget] HRESULT Challenge([out, retval] LPWSTR* challenge);
205+
206+
/// Response to the authentication request with credentials. This object will be populated by the app
207+
/// if the host would like to provide authentication credentials.
208+
[propget] HRESULT Response([out, retval] ICoreWebView2BasicAuthenticationResponse** response);
209+
210+
/// Cancel the authentication request. False by default.
211+
/// If set to true, Response set will be ignored.
212+
[propget] HRESULT Cancel([out, retval] BOOL* cancel);
213+
/// Set the Cancel property.
214+
[propput] HRESULT Cancel([in] BOOL cancel);
215+
216+
/// Returns an `ICoreWebView2Deferral` object. Use this deferral to
217+
/// defer the decision to show the Basic Authentication dialog.
218+
HRESULT GetDeferral([out, retval] ICoreWebView2Deferral** deferral);
219+
}
220+
221+
```
222+
223+
```c#
224+
namespace Microsoft.Web.WebView2.Core
225+
{
226+
/// Event args for the BasicAuthenticationRequested event. Will contain the
227+
/// request that led to the HTTP authentication challenge, the challenge
228+
/// and allows the host to provide authentication response or cancel the request.
229+
runtimeclass CoreWebViewBasicAuthenticationRequestedEventArgs
230+
{
231+
/// The web resource request that led to the authentication challenge
232+
CoreWebView2WebResourceRequest Request { get; };
233+
234+
/// The HTTP basic authentication challenge string
235+
String Challenge { get; };
236+
237+
/// Cancel the authentication request. False by default.
238+
/// If set to true, Response will be ignored.
239+
bool Cancel { get; set; };
240+
241+
/// Response to the authentication request with credentials. This object will be populated by the app
242+
/// if the host would like to provide authentication credentials.
243+
CoreWebView2BasicAuthenticationResponse Response { get; };
244+
245+
/// Returns an `ICoreWebView2Deferral` object. Use this deferral to
246+
/// defer the decision to show the Basic Authentication dialog.
247+
CoreWebView2Deferral GetDeferral();
248+
}
249+
250+
/// Represents a Basic HTTP authentication response that contains a user name
251+
/// and a password as according to RFC7617 (https://tools.ietf.org/html/rfc7617)
252+
runtimeclass CoreWebView2BasicAuthenticationResponse
253+
{
254+
/// User name provided for authentication.
255+
String UserName { get; set; }
256+
257+
/// Password provided for authentication
258+
String Password { get; set; };
259+
}
260+
261+
runtimeclass CoreWebView2
262+
{
263+
...
264+
265+
/// Add an event handler for the BasicAuthenticationRequested event.
266+
/// BasicAuthenticationRequested event is raised when WebView encountered a Basic HTTP
267+
/// Authentication request.
268+
///
269+
/// The host can populate the response object with credentials it wants to use for the authentication or
270+
/// cancel the request. If the host doesn't handle the event, WebView will show
271+
/// the authentication challenge dialog prompt to user.
272+
///
273+
event Windows.Foundation.TypedEventHandler<CoreWebView2, CoreWebViewBasicAuthenticationRequestedEventArgs> BasicAuthenticationRequested;
274+
}
275+
}
276+
```

0 commit comments

Comments
 (0)