Category Archives: Uncategorized

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()
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;
  store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
  store.Open(OpenFlags.OpenExistingOnly | OpenFlags.ReadOnly);
  // select the certificate from store.Certificates ...
  if(store != null) store.Close();

And that’s it. Hope it helps.

Alice in Claims: the WIF claims class model


This is the seventh post in a series about claims based identity management and the Windows Identity Foundation (WIF).

The first six were:

In this post, we describe WIF’s class model for claims based identities.

Claims Class Model

The old identity model

Since the beginning, the Microsoft .NET Base Class Library defined two interfaces for representing identities:

  • The IIdentity interface, which aims tp represent an identity, is characterized by
  • The IPrincipal interface represents the subject of an action, and it is characterized by

In this model a subject is solely characterized by a role membership function and a name based identity. We will see below that the new claims based model extends this information with claims collections.

The concrete implementations of the IIdentity include: the GenericIdentity class, the WindowsIdentity class and the FormsIdentity class.

The IPrincipal interface is implemented by classes such as: the GenericPrincipal class, the WindowsPrincipal class and the RolePrincipal class.

Instances implementing the IPrincipal interface are exposed by properties and methods such as:

The new model

The WIF model builds upon the old model by defining two new interfaces, as shown in the following diagram:


In its essence, the new model extends the old one by characterizing an identity not only by a name string but also by a claim collection, where a claim has a value, a type and an issuer.

When using WIF, instances of this new model are exposed in the same places as before, namely by property System.Web.HttpContext.User.

The new model also contains some methods and properties not address in this post, which are only relevant in delegation scenarios. This theme will be the subject of a future post.

Alice in Claims: Windows Identity Foundation


This is the sixth post in a series about claims based identity management and the Windows Identity Foundation (WIF).

The first five were:

In this post, we introduce the Windows Identity Foundation – WIF.

Windows Identity Foundation


The Windows Identity Foundation SDK is composed by:

  • The Microsoft.IdentityModel.dll .NET assembly
  • The FedUtil command line tool.
  • A Visual Studio add-in.


The Microsoft.IdentityModel.dll assembly contains class models for:

  • Claims-based identity representation.
  • A claims and token issuance pipeline.
  • A claims and token consumption pipeline.
  • Host adaptation layer supporting the above generic pipelines over the ASP.NET and WCF “hosts”.

The FedUtil command line generates configuration files based on federation metadata.

Finally, the Visual Studio add-in contain templates for:

  • Identity consumers – ASP.NET sites and WCF services.
  • Identity producers – ASP.NET and WCF based security token services.

In the next post, we will begin our in-depth analysis of WIF by looking into the class model for claims based identity representation.

Alice in Claims: not only for federation


This is the fifth post in a series about claims based identity management and the Windows Identity Foundation (WIF).

The first four were:

In this post, we show that the claims based model is useful in scenarios other than federation.

A scenario

Considerer the scenario presented in the following figure, where webapp1 and webapp2 are intranet web applications, deployed inside a windows domain and using windows based authentication.


In such a scenario, identity management is rather simple:

  • The user identity is managed by Active Directory (AD), namely domain group membership.
  • This user identity information is seamlessly made available to the web apps, using the integrated support for windows authentication available in ASP.NET.

However, consider the augmented scenario depicted in the next figure, where access must also be available from outside the windows domains, using password based or certificate based user authentication. Note that, for security reasons, the used passwords may be different from the ones used in the domain.

Since integrated windows authentication is not readily available in this scenario, each web app must deal with the identity management issues, namely authentication and group membership. This may imply the creation of credential and identity stores in each web app.NotOnlyForFederation2

In such a scenario, the usage of a claims based model, as showed next, solves this problems.NotOnlyForFederation3

  • Users are initially authenticated by the Identity Provider (IdP), releasing the web apps from this burden. This also simplifies the introduction of new authentication mechanisms, because the web apps are not impacted by these changes.
  • The web apps consume the claims (e.g. group membership, roles, authorizations) issued by the IdP. The claim issuance process can use other sources of information other than active directory, namely for storing user attributes that do not fit in AD’s schema.
  • Any change to the user’s identity (e.g. role change) is readily made available to all the internal web apps.

The advantages obtained from the use of a claims based model and an IdP are similar to the use of integrated windows authentication, but with the added benefits:

  • Authentication is not limited to windows mechanisms.
  • User identity attributes are not limited to the ones stored in the AD. Namely, the claims issuance process may also include the evaluation of authorization policies, releasing the web apps from this task.
  • By using commonly used specifications, it is easier to integrate application not based on Windows technologies.

Finally, the use of claims based model and an internal IdP paves the way to future federation scenarios where

  • Partners must access the web apps, or
  • Domain users must access external apps, namely cloud based apps.


Alice in Claims: the anatomy of a token


This is the fourth post in a series about claims based identity management and the Windows Identity Foundation (WIF).

The first three were:

The previous post presented the protocols for requesting and exchanging security tokens between identity providers and identity consumers. In this post, we dissect the structure of a commonly used token type: SAML assertions.

A SAML assertion

The following excerpt shows the high-level structure of a SAML  2.0 assertion.

    IssueInstant="2010-07-04T22:57:50.284Z" Version="2.0"
          Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />

  • The top-level element is the Assertion element.
  • The Assertion/Issuer element defines the token issuer’s identity, in the form of an URL.
  • The Assertion/ds:Signature contains a signature computed over the assertion contents.
  • The Assertion/Subject contains information regarding the assertion’s subject, i. e., to whom or what do the contained claims apply. This information is carried in the SubjectConfirmation element, which in this case states that this token is a bearer token: the token subject is anyone in possession of the token.
  • The Assertion/Condition define the conditions for token acceptance by a consumer, which in this case are:
    • Time period (NotBefore and NotOnOrAfter attributes)
    • Consumer identity (AudienceRestriction element). Any consumer that does not match any of the audience restriction URLs should not accept the token.
  • Finally, the Assertion/AttributeStatement and Assertion/AuthnStatement contains the issued claims, which will be detailed next.

Attribute statement

The following XML excerpt shows the AttributeStatement contents, defining the issued claims:

  • One name claim (type = “http://…/name”) with value “Alice”
  • Two role claims (type = “http://…/role”) with values “Developer” and “LeadDeveloper”.

Authentication Statement

Finally, the next XML fragment shows the AuthnStatement element containing the authentication type claim, also called authentication context. In this example, Alice used a password based mechanism to authenticate herself when requesting the claims from the identity provider.

<AuthnStatement AuthnInstant="2010-07-04T22:57:49.396Z">


For completeness, the next XML fragment presents the signature contents.

<ds:Signature xmlns:ds="">
        Algorithm="…/xml-exc-c14n#" />
        Algorithm=…#rsa-sha256 />
             Algorithm=http://...#enveloped-signature />
             Algorithm="http://…/xml-exc-c14n#" />
          Algorithm=…#sha256 />
  <KeyInfo xmlns="">
  • The Signature/Element defines the signed data, which is this case is the complete SAML Assertion. Note that the URI attribute matches the ID attribute in the Assertion element. Since the signature is inside the signed data, an “enveloped-signature” transform is used.
  • The Signature/KeyInfo/X509Data/X509Certificate contains the issuer’s certificate. There are several WIF configuration aspects that relate to this certificate, so its existence should be noted.