Once you have your Web API developed, before exposing it to your clients, based upon your needs you may need to secure some or all parts of your API Service so that only verified users can access your API service. This securing in ASP.NET can be achieved using the authentication and authorization mechanisms.

Authentication

Authentication is the process of determining whether someone or something is, in fact, who or what it is claimed to be. By using the authentication mechanism, we make sure that every request received by the Web API service is sent from a client with proper credentials.

Authentication Using Message Handlers

A message handler is a class that receives an HTTP request and returns an HTTP response. Message handlers are derived classes from the abstract class HttpMessageHandler. They are good for cross-cutting concerns that operate at the level of HTTP messages (rather than controller actions). For example, a message handler might:

• read or modify request headers
• add a response header to responses
• validate requests before they reach the controller

In a Web API, typically, a series of message handlers are chained together, forming a pattern called delegating handler.

The order in which these handlers are set up is important as they will be executed sequentially. 

The most important handler sits at the very top, guarding everything that comes in. If the checks pass, it will pass this request down the chain to the next delegating handler, and so on. 

If all goes well, it will then arrive at the API Controller and execute the desired action. However, if any of the checks fail within the handlers, then the request is denied and a response is sent to the client.

With this much theory in hand, now let's write code for our handlers. We will create two message handlers in this article:

1. APIKeyHandler: Handler responsible for intercepting an HTTP request and ensuring its header contains an API key
2. AuthHandler: Handler responsible for authenticating a user's credentials and roles
   

API Key Authentication

In your Web API project, create a folder called MessageHandlers and add a class APIKeyHandler.cs.

public class APIKeyHandler : DelegatingHandler
    {
        //set a default API key 
        private const string yourApiKey = "X-some-key";

        protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            bool isValidAPIKey = false;
            IEnumerable<string> lsHeaders;
            //Validate that the api key exists

            var checkApiKeyExists = request.Headers.TryGetValues("API_KEY", out lsHeaders);

            if (checkApiKeyExists)
            {
                if (lsHeaders.FirstOrDefault().Equals(yourApiKey))
                {
                    isValidAPIKey = true;
                }                
            }
                
            //If the key is not valid, return an http status code.
            if (!isValidAPIKey)
                return request.CreateResponse(HttpStatusCode.Forbidden, "Bad API Key");

            //Allow the request to process further down the pipeline
            var response = await base.SendAsync(request, cancellationToken);

            //Return the response back up the chain
            return response;
        }
    }

The APIKeyHandler.cs inherits from DelegatingHandler, which in turn inherits from HttpMessageHandler. This allows us to override the functionality for inspecting an HTTP request and control whether we want to allow this request to flow down the pipeline to the next handler and controller or halt the request by sending a custom response.

In this class, we are achieving this by overriding the SendAsync method. This method looks for an API key (API_KEY) in the header of every HTTP request, and passes the request to the controller only if a valid API key is present in the request header.

Now, to see this handler in action, we need to first register it to our application in the Application_Start method from the Global.asax file.

GlobalConfiguration.Configuration.MessageHandlers.Add(new APIKeyHandler());

Try calling any method that you have exposed through your Web API controllers and you should see "Bad API Key" as response.

For a demo in this article, I am using the same project and the URLs that I have created in my previous article, "Developing an ASP.NET Web API".

Let's verify that the APIKeyHandler is working alright by creating an HTTP Request with correct headers. For that, we need to create an HTTP header with key value:

"API_KEY" : "X-some-key"

I am using a Mozilla browser plugin called "HTTP Tool" for creating HTTP request headers here.

The HTTP request is now passed all the way to the controller by the handler.

So our API key check handler is in place now. This secures our Web API to make sure only those clients that are provided with valid API keys can access this service. Next we will look at how we can implement security based on user roles.

Basic Authentication

Basic authentication, as its name suggests, is the most simple and basic form of authenticating HTTP requests. The client sends Base64-encoded credentials in the Authorize header on every HTTP request, and only if the credentials are verified does the API return the expected response. Basic authentication doesn't require server-side session storage or implementation of cookies as every request is verified by the API.

Once basic authentication implementation in Web API is understood, it will be very easy to hook other forms of authentication. Only the authentication process will be different, and the Web API hooks, where it is done, will be the same.

For verifying user credentials, we create an IPrincipal object which represents the current security context.

Add a new folder called Security and a new class TestAPIPrincipal.cs in it.

public class TestAPIPrincipal : IPrincipal
    {
        //Constructor
        public TestAPIPrincipal(string userName)
        {
            UserName = userName;
            Identity = new GenericIdentity(userName);
        }

        public string UserName { get; set; }
        public IIdentity Identity { get; set; }
        public bool IsInRole(string role)
        {
            if (role.Equals("user"))
            {
                return true;
            }
            else
            {
                return false;
            }
        }        
    }

The IIdentity object associated with the principal has a property called IsAuthenticated. If the user is authenticated, this property will return true; otherwise, it will return false.

Now, let's create another handler called AuthHandler.cs.

public class AuthHandler : DelegatingHandler
    {
        string _userName = "";
        
        //Method to validate credentials from Authorization
        //header value
        private bool ValidateCredentials(AuthenticationHeaderValue authenticationHeaderVal)
        {
            try
            {
                if (authenticationHeaderVal != null
                    && !String.IsNullOrEmpty(authenticationHeaderVal.Parameter))
                {
                    string[] decodedCredentials
                    = Encoding.ASCII.GetString(Convert.FromBase64String(
                    authenticationHeaderVal.Parameter))
                    .Split(new[] { ':' });

                    //now decodedCredentials[0] will contain
                    //username and decodedCredentials[1] will
                    //contain password.

                    if (decodedCredentials[0].Equals("username")
                    && decodedCredentials[1].Equals("password"))
                    {
                        _userName = "John Doe";
                        return true;//request authenticated.
                    }
                }
                return false;//request not authenticated.
            }
            catch {
                return false;
            }
        }

        protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            //if the credentials are validated,
            //set CurrentPrincipal and Current.User
            if (ValidateCredentials(request.Headers.Authorization))
            {
                Thread.CurrentPrincipal = new TestAPIPrincipal(_userName);
                HttpContext.Current.User = new TestAPIPrincipal(_userName);
            }
            //Execute base.SendAsync to execute default
            //actions and once it is completed,
            //capture the response object and add
            //WWW-Authenticate header if the request
            //was marked as unauthorized.

            //Allow the request to process further down the pipeline
            var response = await base.SendAsync(request, cancellationToken);

            if (response.StatusCode == HttpStatusCode.Unauthorized
                && !response.Headers.Contains("WwwAuthenticate"))
            {
                response.Headers.Add("WwwAuthenticate", "Basic");
            }

            return response;
        }
    }

This class contains a private method ValidateCredentials, which checks for decoded username and password values from the HTTP request header, and also the SendAsync method for intercepting the HTTP request.

If the credentials of the client are valid, then the current IPrincipal object is attached to the current thread, i.e. Thread.CurrentPrincipal. We also set the HttpContext.Current.User to make the security context consistent. This allows us to access the current user's details from anywhere in the application.

Once the request is authenticated, base.SendAsync is called to send the request to the inner handler. If the response contains an HTTP unauthorized header, the code injects a WwwAuthenticate header with the value Basic to inform the client that our service expects basic authentication.

Now, we need to register this handler in the Global.Asax class as we did for our ApiKeyHandler. Make sure that the AuthHandler handler is below the first handler registration to make sure of the right order.

GlobalConfiguration.Configuration.MessageHandlers.Add(new APIKeyHandler());
GlobalConfiguration.Configuration.MessageHandlers.Add(new AuthHandler());

But before we can see basic authentication in action, we will first need to implement authorization.

Authorization

Authorization is verifying whether the authenticated user can perform a particular action or consume a particular resource. This process in Web API happens later in the pipeline, after
authentication and before the controller actions are executed.

Using Authorize Attribute

ASP.NET MVC Web API provides an authorization filter called AuthorizeAttribute which verifies the request's IPrincipal, checks its Identity.IsAuthenticated property, and returns a 401 Unauthorized HTTP status if the value is false and the requested action method will not be executed. This filter can be applied in different levels like the controller level or action level, and can be easily applied using the [Authorize] syntax on top of controllers or actions.

[Authorize]
public class ClassifiedsController : ApiController

Once this attribute is set, it will prevent all action methods in the controller from being accessed by unauthorized users.

First our basic authentication handler kicks in to set the current user's identity IPrincipal object. Then, before this request reaches the controller, AuthorizeAttribute verifies access to the particular controller/action for the current user.

To see this in action, first let's create an HTTP request without proper credentials.

The access gets denied by the AuthorizeAttribute.

Now, let's create another request with Authorization header key/value this time as follows:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Here, the value dXNlcm5hbWU6cGFzc3dvcmQ= is the Base64-encoded form of username:password.

This request gets access rights to the controller/action as expected.

This is an example of securing the entire controller's public Actions.

Action Level Authorization

We can also restrict some parts of the controller actions by setting the [Authorize] attribute at the action level only instead. Doing so will allow us to have both protected and unprotected actions in the same controller.

//[Authorize]
    public class ClassifiedsController : ApiController
    {
        public List<ClassifiedModel> Get(string id)
        {
            return ClassifiedService.GetClassifieds(id);
        }

        [Authorize]
        public List<ClassifiedModel> Get()
        {
            return ClassifiedService.GetClassifieds("");
        }

[AllowAnonymous] Attribute

Another way to have both protected and unprotected actions within the controller is by making use of the [AllowAnonymous] attribute. When we set the [Authorize] attribute in the controller level and set the [AllowAnonymous] attribute for any action inside the controller, that action will skip the [Authorize] attribute.

Role and User Checks

It is also possible to filter certain roles and users for access rights. For example, we can have something like [Authorize(Roles = "Admin")] on the controllers and actions.

Custom Authorization Attribute

Finally, we can also create our own custom authorization attribute depending upon our needs. One of the ways to achieve this is by extending AuthorizeAttribute.

Say we want to restrict our Web API service to only certain parts of the world by restricting access to users that are not within a certain range of IP address. We can create a custom authorize attribute for this purpose by deriving from the AuthorizeAttribute class and overriding the IsAuthorized method.

public class RestrictIPsAttribute: System.Web.Http.AuthorizeAttribute
    {
        protected override bool IsAuthorized(HttpActionContext context)
        {
            var ip = HttpContext.Current.Request.UserHostAddress;

            //check for ip here
            if (ip.Contains(""))
            {
                return true;
            }
            return false;
        }
    }

Once we have our custom Authorize attribute, we can decorate our controllers/actions with it.

[RestrictIPsAttribute]
public List<ClassifiedModel> Get()
{
    return ClassifiedService.GetClassifieds("");
}

Conclusion

In this article, we looked at how we can secure our ASP.NET Web API service before exposing the service to the world outside. We looked at how we can authenticate HTTP requests for valid API keys and for valid user credentials. With this much knowledge in hand, I believe we ready to develop any custom security for our APIs.

For those of you who are either just getting started with Laravel or looking to expand your knowledge, site, or application with extensions, we have a variety of things you can study in Envato Market.

I hope you enjoyed reading as much as learning from this article, and remember to leave any questions or comments in the feed below!