How to access ClientCertificate in a host agnostic manner

 When you choose to use Client Certificate as your client credential over SSL, you want to retrieve the x509 Certificate on the server side to do authorization. It is very simple with the latest Web API bits. If you have access to the request message anywhere in the pipeline, such as message handler, action filter or action. you can simply call the extension method shown below. Please be careful that the GetClientCertificate method might return null if the client does not send an valid certificate.

Now getting the client certificate is easy, but how to set it up correctly on self host and web host is not that easy. The following instructions walk you through the process step by step.

Web Host

Step 1: go to the IIS manager, SSL setting, check require client certificate

Step 2: register a custom message handler and verify that the client certificate is something you expect.

Code Snippet

9. public class CustomCertificateMessageHandler : DelegatingHandler
10.     {
11.         protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
12.         {
13.             X509Certificate cert = request.GetClientCertificate();
14.             if (cert != null)
15.             {
16.                 if (cert.Subject.Contains("Some Name you are expecting"))
17.                 {
18.                     Thread.CurrentPrincipal = new GenericPrincipal(new GenericIdentity(cert.Subject), new[] { "Administrators" });
19.                 }
20.             }
21.  
22.             return base.SendAsync(request, cancellationToken);
23.         }
24.     }

Step 3: register the custom message handler.

Code Snippet

30. // Register a message to turn the client cert to a admin role
31.             GlobalConfiguration.Configuration.MessageHandlers.Add(new CustomCertificateMessageHandler());

 

Step 4: Write a RequireAdminAttribute

Code Snippet

10. public class RequireAdminAttribute : AuthorizationFilterAttribute
11.     {
12.         public override void OnAuthorization(HttpActionContext context)
13.         {
14.             // do authorization based on the principle.
15.             IPrincipal principal = Thread.CurrentPrincipal;
16.             if (principal == null || !principal.IsInRole("Administrators"))
17.             {
18.                 context.Response = new HttpResponseMessage(HttpStatusCode.Unauthorized);
19.             }
20.         }
21.     }

Step 5: Add the RequireAdminAttribute to the action.

Code Snippet

7. public class HomeController : ApiController
8.     {
9.         [RequireAdmin]
10.         public HttpResponseMessage Get()
11.         {
12.             return new HttpResponseMessage(HttpStatusCode.OK)
13.             {
14.                 Content = new StringContent("Default User")
15.             };
16.         }
17.  
18.         public HttpResponseMessage Post()
19.         {
20.             return new HttpResponseMessage(HttpStatusCode.OK)
21.             {
22.                 Content = new StringContent("User Posted")
23.             };
24.         }
25.     }

Now your GET action can only be accessed with the administrators.

Self Host

Step 1: Tell the WCF transport, I want to client to send certificate over SSL.

Code Snippet

68.             // client cert
69.             config.ClientCredentialType = HttpClientCredentialType.Certificate;

Step 2: Write some client code to pick a certificate to send

Code Snippet

35.                 WebRequestHandler handler = new WebRequestHandler();
36.                 handler.ClientCertificateOptions = ClientCertificateOption.Manual; // this would pick from the Current user store
37.                 handler.ClientCertificates.Add(GetClientCertificate());
38.                 handler.UseDefaultCredentials = true;
39.                 HttpClient client = new HttpClient(handler);

Implement the GetClientCertificate to retrieve a certificate programmatically.

Then repeat step 2-5 from the web host section to complete the experience.

Hope this helps.

Comments

• Anonymous
  December 18, 2012
  Does the certificate have to be a valid certificate?

• Anonymous
  January 31, 2014
  If you require SSL and a client cert why would GetClientCertificate() result in null? IIS would not allow the request to continue.

• Anonymous
  May 27, 2014
  Is there any sample code that shows how a javascript or .NET client can send a certificate as part of an http request.