Using HttpClient with SSL/TLS-based client side authentication

The HttpClient is a the new class for making HTTP requests and receiving the associated HTTP responses, introduced in the 4.5 version of .NET. In a previous post  – The new .NET HttpClient class – we described its the core concepts and architecture. One of the main takeaways was the concept of client handler, which is just a message handler responsible for delivering the HTTP messages to the network stack and receiving the responses from it. Typically, the client handler will be at the end of the message handler pipeline used by the client.

The current’s post goal is to describe how to configure this new HTTP client class with client-side authentication based on the TLS (Transport Layer Security) protocol.

The HttpClient class does not contain any configuration properties or methods related to TLS. This is because the HttpClient class is independent of the used HTTP message transport mechanism. Namely, it is even possible to connect a HttpClient directly to an HttpServer instance, without any network intervention, as described in another post.

Instead, the TLS configuration requires dealing directly with one of the available client handlers presented in the previous post : HttpClientHandler and WebRequestHandler.

The first option is to explicitly configure the HttpClient with a HttpClientHandler instance, containing its ClientCertificateOptions property set to Automatic.

The resulting HttpClient can then be used normally: if during a connection handshake the server requires the client certificate, the HttpClientHandler instance will automatically select a compatible client certificate for the user’s personal certificate store.

var client = new HttpClient(

 new HttpClientHandler{
   ClientCertificateOptions = ClientCertificateOption.Automatic
 });
// ...

This option is the only one available for Windows Store applications.

For classical scenarios (e.g. console, WinForms or WPF applications) there is a second option using the WebRequestHandler, which provides more control over the configuration.

var clientHandler = new WebRequestHandler()
clientHandler.ClientCertificates.Add(cert);
var client = new HttpClient(clientHandler)

where cert is a X509Certificate2 instance representing the client certificate.
This instance can be constructed directly from a PFX file or obtained from a Windows certificate store

X509Store store = null;
try
{
  store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
  store.Open(OpenFlags.OpenExistingOnly | OpenFlags.ReadOnly);
  // select the certificate from store.Certificates ...
}
finally
{
  if(store != null) store.Close();
}

And that’s it. Hope it helps.

2 thoughts on “Using HttpClient with SSL/TLS-based client side authentication

  1. Alberto Silva

    Hi Pedro,
    I’m using the HttpClient against a https URL, and I get the following error message:
    “A ligação subjacente foi fechada: Não foi possível estabelecer uma relação de confiança para o canal seguro SSL/TLS.”

    However, the request works fine in fiddler2, any hint?

    Reply
    1. pedrofelix Post author

      1) When it fails, do you have Fiddler in the middle? If so, is it correctly configured to analyze TLS traffic?

      2) Does the subject name in the certificate matches the host in the URL?

      3) Isn’t there any more info on the exception or on event viewe?

      4) The WebRequestHandler, which you can pass to the HttpClient ctor, has a ServerCertificateValidationCallback property that lets you define a validation callback.
      The info passed into this callback has information about the failure reason

      Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s