CoreWebView2.ClientCertificateRequested Event

Definition

Namespace:

Microsoft.Web.WebView2.Core

Assembly:

Microsoft.Web.WebView2.Core.dll

Package:

Microsoft.Web.WebView2 v1.0.2478.35

ClientCertificateRequested is raised when WebView2 is making a request to an HTTP server that needs a client certificate for HTTP authentication. Read more about HTTP client certificates at RFC 8446 The Transport Layer Security (TLS) Protocol Version 1.3.

public event EventHandler<Microsoft.Web.WebView2.Core.CoreWebView2ClientCertificateRequestedEventArgs> ClientCertificateRequested;

member this.ClientCertificateRequested : EventHandler<Microsoft.Web.WebView2.Core.CoreWebView2ClientCertificateRequestedEventArgs> 

Public Custom Event ClientCertificateRequested As EventHandler(Of CoreWebView2ClientCertificateRequestedEventArgs) 

Event Type

EventHandler<CoreWebView2ClientCertificateRequestedEventArgs>

Examples

// Turn off client certificate selection dialog using ClientCertificateRequested event handler
// that disables the dialog. This example hides the default client certificate dialog and
// always chooses the last certificate without prompting the user.
private bool _isCustomClientCertificateSelection = false;
void EnableCustomClientCertificateSelection()
{
    // Safeguarding the handler when unsupported runtime is used.
    try
    {
        if (!_isCustomClientCertificateSelection)
        {
            webView.CoreWebView2.ClientCertificateRequested += WebView_ClientCertificateRequested;
        }
        else
        {
            webView.CoreWebView2.ClientCertificateRequested -= WebView_ClientCertificateRequested;
        }
        _isCustomClientCertificateSelection = !_isCustomClientCertificateSelection;

        MessageBox.Show(this,
            _isCustomClientCertificateSelection ? "Custom client certificate selection has been enabled" : "Custom client certificate selection has been disabled",
            "Custom client certificate selection");
    }
    catch (NotImplementedException exception)
    {
        MessageBox.Show(this, "Custom client certificate selection Failed: " + exception.Message, "Custom client certificate selection");
    }
}

void WebView_ClientCertificateRequested(object sender, CoreWebView2ClientCertificateRequestedEventArgs e)
{
    IReadOnlyList<CoreWebView2ClientCertificate> certificateList = e.MutuallyTrustedCertificates;
    if (certificateList.Count() > 0)
    {
        // There is no significance to the order, picking a certificate arbitrarily.
        e.SelectedCertificate = certificateList.LastOrDefault();
        // Continue with the selected certificate to respond to the server.
        e.Handled = true;
    }
    else
    {
        // Continue without a certificate to respond to the server if certificate list is empty.
        e.Handled = true;
    }
}

// This example hides the default client certificate dialog and shows a custom dialog instead.
// The dialog box displays mutually trusted certificates list and allows the user to select a certificate.
// Selecting `OK` will continue the request with a certificate.
// Selecting `CANCEL` will continue the request without a certificate
private bool _isCustomClientCertificateSelectionDialog = false;
void DeferredCustomClientCertificateSelectionDialog()
{
    // Safeguarding the handler when unsupported runtime is used.
    try
    {
        if (!_isCustomClientCertificateSelectionDialog)
        {
            webView.CoreWebView2.ClientCertificateRequested += delegate (
                object sender, CoreWebView2ClientCertificateRequestedEventArgs args)
            {
                // Developer can obtain a deferral for the event so that the WebView2
                // doesn't examine the properties we set on the event args until
                // after the deferral completes asynchronously.
                CoreWebView2Deferral deferral = args.GetDeferral();

                System.Threading.SynchronizationContext.Current.Post((_) =>
                {
                    using (deferral)
                    {
                        IReadOnlyList<CoreWebView2ClientCertificate> certificateList = args.MutuallyTrustedCertificates;
                        if (certificateList.Count() > 0)
                        {
                            // Display custom dialog box for the client certificate selection.
                            var dialog = new ClientCertificateSelectionDialog(
                                                        title: "Select a Certificate for authentication",
                                                        host: args.Host,
                                                        port: args.Port,
                                                        client_cert_list: certificateList);
                            if (dialog.ShowDialog() == true)
                            {
                                // Continue with the selected certificate to respond to the server if `OK` is selected.
                                args.SelectedCertificate = (CoreWebView2ClientCertificate)dialog.CertificateDataBinding.SelectedItem;
                            }
                            // Continue without a certificate to respond to the server if `CANCEL` is selected.
                            args.Handled = true;
                        }
                        else
                        {
                            // Continue without a certificate to respond to the server if certificate list is empty.
                            args.Handled = true;
                        }
                    }

                }, null);
            };
            _isCustomClientCertificateSelectionDialog = true;
            MessageBox.Show("Custom Client Certificate selection dialog will be used next when WebView2 is making a " +
                "request to an HTTP server that needs a client certificate.", "Client certificate selection");
        }
    }
    catch (NotImplementedException exception)
    {
        MessageBox.Show(this, "Custom client certificate selection dialog Failed: " + exception.Message, "Client certificate selection");
    }
}

Remarks

The host have several options for responding to client certificate requests:

	Scenario	Handled	Cancel	SelectedCertificate
	Respond to server with a certificate	True	False	MutuallyTrustedCertificate value
	Respond to server without certificate	True	False	null
	Display default client certificate selection dialog prompt	False	False	n/a
	Cancel the request	n/a	True	n/a

If the host don't handle the event, WebView2 will show the default client certificate selection dialog prompt to the user.