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.

What are security tokens?

In the context of the claims model, a security token is an interoperable  container of security-related information, typically identity claims, securely packaged for communication between two or more parties. This packaging ensures properties such as:

• Confidentiality – only the authorized receiver should be able to access the contained information
• Integrity – the authorized receiver should be able to detect any modifications to token, while in transit between the two parties.

On Web Single-Sign On protocols, security tokens are used to securely transport the identity information from the identity provider to the identity consumer. On a delegated authorization protocol, such as OAuth 2.0, security tokens can be used to convey the authorization information from the client to the resource server.

For instance, the SAML (Security Assertion Markup Language) assertion is an example of a very popular token format, used by  Single-Sign On protocols such as: Shibboleth, the SAML protocols and WS-Federation. SAML assertions are XML-based and use the XML Digital Signature and XML Encryption standards for providing integrity and confidentiality.

What is JWT?

JWT stands for  JSON Web Token, and is a new format for packing and protecting security information. It is based on the JSON (JavaScript Object Notation) syntax and aims to be usable in “space constrained environments such as HTTP Authorization headers and URI query parameters”.

The following example (taken from the spec), represents a unprotected token (line breaks added for display purposes)

eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ

The encoded token is composed by a sequence of parts, separated by the ‘.’ character. Each part is the base64url encoding of an octet stream. In this example, both octet stream result from the UTF-8 encoding of JSON objects. The first object (encoded in the first part) is the JWT header

{“alg”:”none”}

The header defines the token cryptographic protection, which is ‘none’ in this case.

The second object (encoded in the second part) is the JWT Claims Set

{“iss”:”joe”,

“exp”:1300819380,

“http://example.com/is_root”:true}

The JWT Claims Set object is a container of claims, where the object’s property corresponds to the claim type and the property’s value contains the claims value. Some claims types are defined by the JWT spec (e.g. “iss” and “exp”), while others are context specific (e.g. “http://example.com/is_root”).

We will see more examples of JWT tokens after presenting the JWT Security Token Handler.

What are Security Token Handlers?

Security Token Handlers are a concept introduced by the  WIF (Windows Identity Foundation) framework, which is now an integral part of the .NET 4.5 framework. A token handler has multiple responsibilities, namely:

• Serialize and deserialize tokens between a XML or string format and a SecurityToken-derived instance;
• Validate security tokens and extract the contained claims into a claims identity or a claims principal;
• Create a token from a token description.

This behavior is defined by the abstract SecurityTokenHandler class, with multiple concrete derived classes for each token type (e.g. the Saml2SecurityTokenHandler class).

The JTWSecurityTokenHandler class

The recently announced Microsoft.IdentityModel.Tokens.JWT NuGet package contains a new token handler for the JWT token format – the JWTSecurityTokenHandler class – depicted in the next diagram.

As a token handler,  the JWTSecurityTokenHandler can be used to create and validate JWT tokens, as shown by the next example

• First, we create a token handler and a symmetric key, that will be used by both the sending and the receiving party to sign and validate the token, respectively.
• Then, we create a token descriptor, defining the token contents, namely:
  • The contained claims, i.e., the subject of the token,
  • The token issuer name,
  • The intended recipient of the token (AppliesToAddress),
  • The token lifetime, defined by a not before and an expires date-time,
• The token descriptor also contains the signing credentials, namely the symmetric key and the MAC (Message Authentication Code) algorithm identifier (“http://www.w3.org/2001/04/xmldsig-more#hmac-sha256”).
• Then, we use the token handler to create the token from the token descriptor. We also use the token handler to serialize the token into a string.
• On the receiving side, we begin by defining the validation parameters, namely:
  • The allowed audience, i.e., the value defined in the AppliestoAddress property of the token descriptor. This value should be an identifier of the receiving party.
  • The validation cryptographic, in the form of a BinarySecretSecurityToken containing the shared symmetric key.
  • The name of the accepted issuer.
• Finally, we use the token handler to simultaneously deserialize the token, validate its signature and extract the contained claims into a claims principal.
• We end the example by asserting that the claims principal does contains the Name and Role claims inserted in the token by the issuer.

The serialized token is just the concatenation of three base64url encoded parts (line breaks added for display purposes).

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

.

eyJhdWQiOiJodHRwOi8vd3d3LmV4YW1wbGUuY29tIiwiaXNzIjoic2VsZiIsIm5iZiI6MTM1Mzk3NDczNiwi

ZXhwIjoxMzUzOTc0ODU2LCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5

L2NsYWltcy9uYW1lIjoiUGVkcm8iLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYv

aWRlbnRpdHkvY2xhaW1zL3JvbGUiOiJBdXRob3IifQ

.

a-Tu5ojQSyiGSzTb9E5QbEYxyhomywzh2wqKs4El7lc

The first part contains the JWT Header

{“typ”:”JWT”,”alg”:”HS256″}

The second part contains the claims, including the audience, issuer and validity

{“aud”:”http://www.example.com”,

“iss”:”self”,”nbf”:1353973142,”exp”:1353973262,

“http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name“:”Pedro”,

“http://schemas.microsoft.com/ws/2008/06/identity/claims/role”:”Author”}

Finally, the third part is the signature value, computed by the MAC algorithm over the first two parts.

In this post, I will describe the development of a custom host using the Azure Service Bus relaying capabilities. This new host enables the exposure of a Web API on the public cloud, while running on a private machine (e.g. my laptop), that is, a machine without inbound connectivity (e.g. private addresses, firewall, NAT).

This host design is inspired in the self-host architecture, namely the usage of WCF and its integration with the service bus and WCF. Is composed by the following main components, shown in the following diagram.

• The HttpServiceBusConfiguration class derives from HttpConfiguration and adds a couple of properties specific to the this scenario, such as the bus authentication credentials (IssuerName and IssuerSecret).
• The HttpServiceBusServer is initialized with a HttpServiceBusConfiguration and internally performs the following:
• Creates an inner HttpServer instance, using the given configuration.
• Creates a WebServiceHost, using the generic DispatcherService as the service class.
• Adds an endpoint with the WebHttpRelayBinding binding and a TransportClientEndpointBehavior, which configures this endpoint with the credentials required when listening on the bus.
• When a request message is received, the WCF runtime delivers it to the DispatcherService, containing generic asynchronous operations to handle GET requests (BeginGet and EndGet methods) and other HTTP methods (BeginInvoke and EndInvoke).

    [ServiceContract]
    [ServiceBehavior(InstanceContextMode = InstanceContextMode.Single, ConcurrencyMode = ConcurrencyMode.Multiple)]
    internal class DispatcherService
    {
        private readonly HttpServer _server;
        private readonly HttpServiceBusConfiguration _config;

        public DispatcherService(HttpServer server, HttpServiceBusConfiguration config)
        {
            _server = server;
            _config = config;
        }

        [WebGet(UriTemplate = "*")]
        [OperationContract(AsyncPattern = true)]
        public IAsyncResult BeginGet(AsyncCallback callback, object state)
        {
            var context = WebOperationContext.Current;
            return DispatchToHttpServer(context.IncomingRequest, null, 
				context.OutgoingResponse, _config.BufferRequestContent, callback, state);
        }

        public Message EndGet(IAsyncResult ar)
        {
            var t = ar as Task;
            var stream = t.Result;
            return StreamMessageHelper.CreateMessage(MessageVersion.None, "GETRESPONSE", stream ?? new MemoryStream());
        }

        [WebInvoke(UriTemplate = "*", Method = "*")]
        [OperationContract(AsyncPattern = true)]
        public IAsyncResult BeginInvoke(Stream s, AsyncCallback callback, object state)
        {
            var context = WebOperationContext.Current;
            return DispatchToHttpServer(context.IncomingRequest, s, 
				context.OutgoingResponse, _config.BufferRequestContent, callback, state);
        }

        public Message EndInvoke(IAsyncResult ar)
        {
            var t = ar as Task;
            var stream = t.Result;
            return StreamMessageHelper.CreateMessage(MessageVersion.None, "GETRESPONSE", stream ?? new MemoryStream());
        }
		...
    }

• These generic operations convert the WCF requests, represented by the older IncomingWebRequestContext class, into instances of the new HttpRequestMessage class. Then, they pushe these messages into the HttpServer pipeline. When the server finally returns the responses’ HttpResponseMessage instances, the generic operations convert them back into WCF messages.

The code, still in alpha/”works in my machine” status, is available from https://github.com/pmhsfelix/WebApi.Explorations.ServiceBusRelayHost.

Feedback is appreciated.

This post describes a third “out of the box” hosting option: self-hosting. The following code excerpt exemplifies the usage of the HttpSelfHostServer class to host a server on a console application.

    var config = new HttpSelfHostConfiguration("http://localhost:8080");
    config.Routes.MapHttpRoute("default", "{controller}/{id}", 
                                    new { id = RouteParameter.Optional });
    var server = new HttpSelfHostServer(config);
    server.OpenAsync().Wait();
    Console.WriteLine("Server is opened");

The HttpSelfHostServer class derives from HttpServer and and is configured by a HttpSelfHostConfiguration instance, as shown in the following diagram.

Internally, the HttpSelfHostServer uses a WCF channel stack layer to obtain messages from the transport medium and then pushes them into the upper message handler pipeline.

The following section briefly presents the WCF high-level architecture, setting the ground for the description of Web API self-hosting characteristics.

WCF architecture

The WCF architecture is divided into two layers: the channel stack layer and the service model layer, as depicted in the following diagram.

The lower channel stack layer is composed by a stack of channels and behaves similarly to a classical network protocol stack.  The channels are divided into two types: transport channels and protocol channels. Transport channels are responsible by the interface with the transport medium (e.g. TCP, MSMQ, HTTP) (yes, I know, HTTP is not a transport protocol), namely by receiving and sending messages. Protocol channels process the messages that flow up and down through the stack. A typical use case for a protocol channel is the addition of digital signatures at the sending side and the verification of those signatures at the receiving side. The transport channels use encoders to convert between the transport medium byte streams and message instances.

The upper service model layer performs the interface between the messages and methods calls, dealing with tasks such as:

• transforming a received message into a parameter sequence;
• obtaining the service instance to use;
• selecting the method to call;
• obtaining the thread where to call the method.

However, the HttpSelfHostServer doesn’t use the service model layer. Instead, it directly consumes the messages retrieved from channel stack layer.

The concrete channel stack layer organization is described by bindings, as presented in the following diagram.

A binding is a ordered collection of binding elements, where each element roughly describes one channel or encoder. The first binding element describes the upper channel and the last element describes the lower channel, which is always a transport channel.

The HttpSelfHostServer and HttpSelfHostConfiguration classes

Internally, the HttpSelfHostserver.OpenAsync method creates and configures a HttpBinding instance, based on the HttpSelfHostConfiguration instance properties. Then it uses this binding to asynchronously create a WCF channel stack. It also creates a pump that pulls messages from this channel stack, converts them into HttpRequestMessage instances and pushes these new requests into the HttpServer, that is, the message handler pipeline.

When self-hosting, most of the WCF HTTP binding capabilities and settings are available. The configuration of the internally created HttpBinding instance can be accomplished in two ways. The first is to use HttpSelfHostConfiguration properties, such as MaxBufferSize and TransferMode, that will be used to configure the internal HttpBinding instance. The second is to create a HttpSelfHostConfiguration derived class and override the OnConfigureBinding method, which receives the internally created binding instance. This method has the opportunity to change the binding settings before it is used to create the channel stack.

In a future post, I will show how to create a custom host. Until then, comments are welcomed.

In this post, I’m going to address one of the hosting options: web hosting, i.e., hosting on top of the ASP.NET classical pipeline.

Routing

On the ASP.NET platform, routing is commonly performed by adding routes to the RouteTable.Routes static property, which holds a RouteCollection. For example, the following code excerpt shows the default routing defined by the ASP.NET MVC project template.

    protected void Application_Start()
    {
        RegisterRoutes(RouteTable.Routes);
    }

    public static void RegisterRoutes(RouteCollection routes)
    {
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

        routes.MapRoute(
            "Default", // Route name
            "{controller}/{action}/{id}", // URL with parameters
            new { controller = "Home", action = "Index", id = UrlParameter.Optional } 
        );
    }

Most of the routing logic is performed by the UrlRoutingModule, attached to the PostResolveRequestCache ASP.NET pipeline event. On each request, this module matches the current request against the route collection, obtaining a RouteData instance. If there is a match, then:

1. A route handler is obtained from the route data.
2. A HTTP handler, implementing the IHttpHandler interface, is obtained from the route handler.
3. Finally, the current request context is mapped to the above HTTP handler.
   
   As a consequence, at the end of the ASP.NET pipeline the request is sent to this handler .

Web API integration

When hosting on ASP.NET, the Web API specific configuration is defined on a singleton HttpConfiguration object, accessible via the static GlobalConfiguration.Configuration property.

Web API also defines a couple of new RouteCollection extension methods, named MapHttpRoute, to register Web API specific routes. The following code excerpt contains an example configuration.

    HttpConfiguration config = GlobalConfiguration.Configuration;
    config.Routes.MapHttpRoute("default", "{controller}/{id}",  new {id = UrlParameter.Optional});
    // other configuration settings

Notice:

• The static GlobalConfiguration.Configuration property, used to obtain the config reference. Internally, this configuration object points to the global RouteTable.Routes route collection.
• The usage of the MapHttpRoute extension method, when adding the route.

The routes added to the route collection by the MapHttpRoute extension methods use the new HttpControllerRouteHandler route handler . When a route added via MapHttpRoute is matched by a request, the associated route handler returns a new type of handler - the HttpControllerHandler - which implements the asynchronous IAsyncHttpHandler interface. This handler is initialized with the route data, containing the matching information.

When called, the HttpControllerHandler on its BeginProcessRequest method performs the following actions:

1. Creates a HttpRequestMessage instance from the current HttpContext;
2. Creates an HttpServer using the configuration referenced by GlobalConfiguration.Configuration and then pushes the new `HttpRequestMessage` into the server pipeline.

After the request is receive by the HttpServer instance, it enters the host independent phase of the processing (the Web API new pipeline).

The following diagram summarizes the route resolution process and the dispatch into the HttpServer instance (the message handler pipeline).

var config = new HttpConfiguration();
config.Routes.MapHttpRoute("default", "{controller}/{id}", new { id = RouteParameter.Optional });
// additional config ...
var server = new HttpServer(config);
var client = new HttpClient(server);
var r = client.GetAsync("http://can.be.anything/resource")

In the above code, notice how the HttpClient is initialized with the HttpServer, establishing the direct client-server connection.

This feature is relevant on integration or end-to-end testing scenarios, by decreasing the time required for a round-trip and avoiding the self-hosting complexity (e.g. URI access control).

This feature also illustrates an interesting symmetry between the client and server stacks, around the message handler concept, as described in the following paragraphs.

Server side

The last post described the ASP.NET Web API server-side processing architecture : what happens since a HTTP request is received until a response is produced.

As stated in that post, this processing architecture is composed by three layers: hosting, message handler pipeline and controller handling. The hosting layer

• translates HTTP requests, received from lower level APIs, into HttpRequestMessage instances;
• pushes this messages into the above message handler pipeline, wrapped by a HttpServer.  Typically, at the end of this pipeline there is an handler that dispatches the messages to the chosen controller.

Of special relevance is the fact that HttpServer derives from HttpMessageHandler (composite pattern).

Client side

The architecture of the new HttpClient class was also described in a previous post, namely the fact that the HttpClient internally uses a HttpMessageHandler to compute the HTTP response, given the HTTP request.

It is this symmetry - HttpServer is a message handler and HttpClient receives a message handler - that allows the direct connection of the client to the server, bypassing the server side hosting layer, as showed in the following diagram.

Nice, isn’t it?

This post presents a first overview of the ASP.NET Web API processing architecture: what happens since a HTTP request is received until a response is produced.

Processing Architecture

The ASP.NET Web API processing architecture, represented in the following diagram, is composed by three layers: hosting, message handler pipeline and controller handling.

Hosting

The lower layer is responsible for the Web API hosting, i.e., the interface between Web API and an underlying HTTP handling runtime.  Succinctly, this layer is responsible for creating HttpRequestMessage instances, and then pushing them into the upper message handler pipeline. The hosting layer is also responsible for processing the HttpResponseMessage returned back from this handler pipeline.

Currently, there are two “out-of-the-box” hosting options: self-hosting and web hosting, i.e., hosting on top of the ASP.NET classical pipeline.

Self-hosting is based on a pump that retrieves WCF Message instances from a WCF channel stack, converts them into HttpRequestMessage instances and then push those into the upper message handler pipeline.

Web-hosting is based on a specific IHttpAsyncHandler, named HttpControllerHandler, that converts HttpRequest instances into HttpRequestMessage.

The Web API hosting is not limited to these two options. There are already some additional hosts, contributed by the community:

• Louis DeJardin created a host on top of OWIN.
• I’ve created a host based on the Azure Service Bus relaying.

Message Handler Pipeline

The middle layer is composed by a message handler pipeline, similar to the one that existed on WCF Web API. This pipeline is exposed by the HttpServer class, which also extends HttpMessageHandler (composite pattern).

This pipeline provides the extensibility point for “middleware” addressing cross-cutting concerns such as: logging, HTTP authentication, HTTP method translation, …

Usually, at the top of this pipeline, there is a special handler: the HttpControllerDispatcher. This handler is responsible for obtaining and calling a controller to handle the request.

The presence of this HttpControllerDispatcher is only required when using the controller-based programming model (ApiController derived classes). It is also possible to mount a completely different model, just by replacing the pipeline’s top message handler.

Controller Handling

Finally, the upper layer corresponds to the controller specific processing, namely:

• Action selection;
• Filter execution;
• Model binding;
• Action invocation;
• Response content creation via formatters.

This processing is done inside the ApiController instance, called by the HttpControllerDispatcher.

Final Remarks

Future posts will address each one of this layers in more details. Until then, feel free to use the comments.

1. On an elevated console (“Run as administrator”), execute “netsh http add urlacl url=https://+:4443/ user=<your user name>”, to allow the running user to listen on port 4443 using HTTPS (note the use of ‘https’ instead of ‘http’ in the above command).
2. Also on an elevated console, register the server certificate by running

   netsh http add sslcert ipport=0.0.0.0:port certhash=thumbprint appid={app-guid} where

   • port is the listening port (e.g. 4443); the special IP address 0.0.0.0 matches any IP address for the local machine;
   • thumbprint is the certificate’s SHA-1 hash, represented in hexadecimal;
   • app-guid is any GUID (e.g. {00000000-0000-0000-0000-000000000000}) , used to identity the owning application.
3. In the previous post’s Main method, replace the HttpSelfHostConfiguration class with the new MyHttpsSelfHostConfiguration class, containing the following code.

4. class MyHttpsSelfHostConfiguration : HttpSelfHostConfiguration
   {
       public MyHttpsSelfHostConfiguration(string baseAddress) : base(baseAddress){}
       public MyHttpsSelfHostConfiguration(Uri baseAddress) : base(baseAddress){}
       protected override BindingParameterCollection OnConfigureBinding(HttpBinding httpBinding)
       {
           httpBinding.Security.Mode = HttpBindingSecurityMode.Transport;
           return base.OnConfigureBinding(httpBinding);
       }
   }
   
   

5. Change the base address passed to the MyHttpsSelfHostConfiguration constructor: var config = new MyHttpsSelfHostConfiguration(“https://localhost:4443&#8243;);
6. Run the program, open a browser and access https://localhost:4443/hello

That’s it: you now have a self-hosted ASP.NET Web API server, using the secure HTTPS protocol.

1. On an elevated console (“Run as administrator”), execute “netsh http add urlacl url=http://+:8080/ user=<your user name>”, to allow the running user to listen on port 8080.
2. On Visual Studio, create a “Console Application” project.
3. Change the project’s Target Framework property from “.NET Framework 4 Client Profile” to “.NET Framework 4 profile”.
4. Install the AspNetWebApi.Selfhost NuGet package
5. Create a public ApiController derived class.

public class HelloController : ApiController
{
  public HttpResponseMessage Get()
  {
    return new HttpResponseMessage
        {
          Content = new StringContent("Hello HTTP")
        };
  }
}

1. In the program’s Main method,
   1. Create a HttpSelfHostConfiguration, initialized with the base address.
   2. Add the default route: MapHttpRoute(“default”, “{controller}/{id}”, new { id = RouteParameter.Optional });
   3. Create a HttpSelfHostServer, initialized with the above configuration object.
   4. Open the server, bearing in mind that the OpenAsync method is asynchronous.

static void Main(string[] args)
{
  var config = new HttpSelfHostConfiguration("http://localhost:8080");
  config.Routes.MapHttpRoute("default", "{controller}/{id}", new { id = RouteParameter.Optional });
  var server = new HttpSelfHostServer(config);
  server.OpenAsync().Wait();

  Console.WriteLine("Server is opened");
  Console.ReadKey();

1. Run the program, open a browser and access http://localhost:8080/hello.

That’s it. You now have a self-hosted ASP.NET Web API server.