SSL Certificate Based Authentication In Web API Project

Table of Contents

• Introduction
• Objectives
• SSL Client Certificates
• How to Install SSL Certificate
• SSL Authentication Code
• IP Whitelisting
• References

Introduction

This document describes the purpose, features and implementation of SSL Certificate based authentication in Web API projects.

Objectives

Web API assumes that authentication happens in the host. For web-hosting, the host is IIS, which uses HTTP modules for authentication. You can configure your project to use any of the authentication modules built in to IIS or ASP.NET, or write your own HTTP module to perform custom authentication.

Several common authentication schemes are not secure over plain HTTP. In particular, Basic authentication and forms authentication send unencrypted credentials. To be secure, these authentication schemes must use SSL. In addition, SSL client certificates can be used to authenticate clients.

SSL Client Certificates

SSL provides authentication by using Public Key Infrastructure certificates. The server must provide a certificate that authenticates the server to the client. It is less common for the client to provide a certificate to the server, but this is one option for authenticating clients. To use client certificates with SSL, you need a way to distribute signed certificates to your users. For many application types, this will not be a good user experience, but in some environments (for example, enterprise) it may be feasible.

Advantages

1. Certificate credentials are stronger than username/password.
2. SSL provides a complete secure channel, with authentication, message integrity, and message encryption.

Disadvantages

1. You must obtain and manage PKI certificates.
2. The client platform must support SSL client certificates.

To configure IIS to accept client certificates, open IIS Manager and perform the following steps:

1. Click the site node in the tree view.
2. Double-click the SSL Settings feature in the middle pane.
3. Under Client Certificates, select one of these options:

   Accept: IIS will accept a certificate from the client, but does not require one.

   Require: Require a client certificate. (To enable this option, you must also select "Require SSL")

Using Client Certificates in Web API

On the server side, you can get the client certificate by calling GetClientCertificate() on the request message. The method returns null if there is no client certificate. Otherwise, it returns an X509Certificate2 instance. Use this object to get information from the certificate, such as the issuer and subject. Then you can use this information for authentication and/or authorization.

How to Install SSL Certificate

There are total two certificates that you need to install and configure on your development machine,

1. Install the Certificate.cer certificate in your Trusted Root Certification Authorities for the Local Machine store using MMC (right-click over the Trusted Root Certification Authorities folder | All Tasks | Import).
   
   Example screenshot:
   
   
   
   
2. Install the ClientCert.pfx certificate in the Personal store of Local Computer using MMC. Notice that the certificate shows it was issued by your Certificate Authority.
   
   

We already installed certificates on PY server. Following procedure shows how to install required certificates on server.

1. Install above 2 certificates on server.
   
   
2. Install the PvtSSLCert.pfx certificate in the Personal store of Local Computer using MMC. Notice that the certificate shows it was issued byyour Certificate Authority.
   
   

SSL Authentication Code

using System;
using System.Security.Claims;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using Microsoft.Owin;
namespaceProject.Owin.Middleware
{
    ///<summary>
    /// CertificateAuthenticationMiddleware class is used to secure the web API using certificate based
    /// Authentication. This class inherits OwinMiddlerware class.
    ///</summary>

    publicclassCertificateAuthenticationMiddleware: OwinMiddleware
    {
        conststring OwinCertFunc = "ssl.LoadClientCertAsync";
        conststring OwinCert = "ssl.ClientCertificate";
        conststring OwinCertError = "ssl.ClientCertificateErrors";
        public CertificateAuthenticationMiddleware(OwinMiddleware next): base(next)
        {}

            ///<summary>
            /// The Invoke() method is invocked from startup class of OWIN for security.
            ///</summary>
            ///<param name="context"></param>
            ///<returns></returns>

        publicasyncoverrideTask Invoke(IOwinContext context)
        {
            if (context.Environment.Keys.Contains(OwinCertFunc))
            {
                try
                {
                    var task = (context.Environment[OwinCertFunc] asFunc < Task > );
                    awaitTask.Run(task);
                    if (context.Environment.Keys.Contains(OwinCert))
                    {
                        var cert = context.Environment[OwinCert] asX509Certificate;
                        if (cert != null) context.Request.Environment.Add(SystemContants.OwinMannatechClientInfo, cert.Subject);
                        else
                        {
                            context.Response.StatusCode = 403;
                            return;
                        }
                    }
                    else
                    {
                        context.Response.StatusCode = 403;
                        return;
                    }
                    // Exception certError;
                    if (context.Environment.Keys.Contains(OwinCertError))
                    {
                        //certError = context.Environment[OwinCertError] as Exception;
                        context.Response.StatusCode = 403;
                        return;
                    }
                }
                catch (Exception ex)
                {
                    context.Response.StatusCode = 403;
                    return;
                }
            }
            else
            {
                context.Response.StatusCode = 403;
                return;
            }
            await Next.Invoke(context);
        }
    }
}

IP WhiteListing

Using the OWIN middleware here we can whitelist the range of IP Addresses or the specific IP address. If the request comes only from these whitelisted IP addresses then the API respond to that request.

Below is the code of IP whitelisting.

using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Owin;
namespaceProject.Owin.Middleware
{
    ///<summary>
    /// IpWhiteListMiddleware class is used to secure the web API, It gives the acess only those IP addesss
    /// which are configured in "Web.config". This class inherits OwinMiddlerware class.
    ///</summary>

    publicclassIpWhiteListMiddleware: OwinMiddleware
    {
        privatereadonlyHashSet < string > _whitelistIps;
        public IpWhiteListMiddleware(OwinMiddleware next, HashSet < string > whitelistIps): base(next)
            {
                _whitelistIps = whitelistIps;
            }

            ///<summary>
            /// The Invoke() method is invocked from startup class of OWIN for security.
            ///</summary>
            ///<param name="context"></param>
            ///<returns></returns>

        publicasyncoverrideTask Invoke(IOwinContext context)
        {
            if (!_whitelistIps.Contains(context.Request.RemoteIpAddress) && !context.Request.IsLocal())
            {
                //context.Response.StatusCode = 404;

                var response = context.Response;
                var request = context.Request;
                response.OnSendingHeaders(state =>
                {
                    var resp = (OwinResponse) state;
                    resp.StatusCode = 200;
                    resp.ReasonPhrase = "IP address is not registered"; // if you're going to change the status code
                    // you probably should also change the reason phrase

                }, response);
                return;
            }
            await Next.Invoke(context);
        }
    }
}

Startup.cs

publicclassStartup
{
    ///<summary>
    /// Owin Configuration method for IP Whitelisting and the Certificate based authentication
    ///</summary>

    publicvoid Configuration(IAppBuilder app)
    {
        app.UseHttpTracking(newHttpTrackingOptions
        {
            TrackingStore = newHttpTrackingStore(),
                TrackingIdPropertyName = "x-tracking-id",
                MaximumRecordedRequestLength = 64 * 1024,
                MaximumRecordedResponseLength = 64 * 1024,
        });

        string[] IPList = ConfigurationManager.AppSettings["IPWhiteList"].Split(',').Select(s => s.ToString()).ToArray();
        var whitelistIps = newHashSet < string > (IPList);

        //var whitelistIps = new HashSet<string> { "14.140.150.214", "50.200.185.198", "67.208.128.168","10.77.5.52" };

        app.Use(typeof(IpWhiteListMiddleware), whitelistIps);
        app.Use(typeof(CertificateAuthenticationMiddleware));
        var config = newHttpConfiguration();
        WebApiConfig.Register(config);
        app.UseWebApi(config);
        config.Services.Clear(typeof(ModelValidatorProvider));
        log4net.Config.XmlConfigurator.Configure();
    }
}

References

 

• Working with SSL in Web API
• Owin middleware, ASP.NET Web API and client’s IP address

Read more articles on Security in .NET:

• What is SSL and How to Implement in ASP.NET Web Application
• Efficiently Storing Passwords in .NET Framework