Basic Authentication Using Message Handler in Web API

Back to: ASP.NET Web API Tutorial

Implementing Basic Authentication using a Message Handler in ASP.NET Web API provides a robust security mechanism for authenticating API requests. This comprehensive guide will walk you through the entire process, including code examples, step-by-step instructions, and best practices.

Prerequisites

Before you begin, ensure you have:

  1. A working knowledge of ASP.NET Web API.
  2. Visual Studio or a code editor of your choice.
  3. Basic familiarity with C# and HTTP protocols.

Step 1: Create a Custom Authentication Handler

  1. Create a custom authentication handler by inheriting from DelegatingHandler in your ASP.NET Web API project.
using System.Net;
using System.Net.Http;
using System.Text;
using System.Threading;
using System.Threading.Tasks;

public class BasicAuthenticationHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        // Extract credentials from the request headers
        if (!request.Headers.Authorization?.Scheme.Equals("Basic", StringComparison.OrdinalIgnoreCase) ?? true)
        {
            return UnauthorizedResponse();
        }

        string encodedCredentials = request.Headers.Authorization.Parameter;
        string credentials = Encoding.UTF8.GetString(Convert.FromBase64String(encodedCredentials));
        string[] parts = credentials.Split(':');
        string username = parts[0];
        string password = parts[1];

        // Perform authentication logic here (e.g., check credentials against a database)
        if (!IsValidUser(username, password))
        {
            return UnauthorizedResponse();
        }

        // Continue processing the request
        return await base.SendAsync(request, cancellationToken);
    }

    private HttpResponseMessage UnauthorizedResponse()
    {
        var response = new HttpResponseMessage(HttpStatusCode.Unauthorized)
        {
            ReasonPhrase = "Unauthorized",
            Content = new StringContent("Invalid credentials")
        };
        return response;
    }

    private bool IsValidUser(string username, string password)
    {
        // Implement your custom authentication logic here
        // You may check against a database, a user store, or any other authentication source
        // Return true if the user is valid, otherwise false
    }
}

In this BasicAuthenticationHandler, we check if the incoming request has Basic Authentication headers, extract the credentials, and validate them using the IsValidUser method.

Step 2: Register the Custom Authentication Handler

  1. Register the custom authentication handler in your Web API configuration (typically in the WebApiConfig.cs file).
public static void Register(HttpConfiguration config)
{
    // Register the custom authentication handler
    config.MessageHandlers.Add(new BasicAuthenticationHandler());

    // Other configuration settings
}

Step 3: Securing API Endpoints

  1. Secure your API endpoints by adding the [Authorize] attribute to controllers or actions that require authentication.
[Authorize]
public class SecureController : ApiController
{
    // This controller or action is secured with Basic Authentication
}

Step 4: Testing Authentication

  1. Test your authentication by sending HTTP requests with Basic Authentication headers containing valid credentials.
GET https://yourapi.com/api/secure-resource
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Replace dXNlcm5hbWU6cGFzc3dvcmQ= with the Base64-encoded username:password credentials.

Conclusion

By following this comprehensive guide, you’ve successfully implemented Basic Authentication using a Message Handler in ASP.NET Web API. This approach enhances the security of your API by verifying the credentials of incoming requests and allowing access only to authenticated users. Customize the BasicAuthenticationHandler to integrate with your authentication source, whether it’s a database, user store, or other identity provider, to achieve a secure and robust authentication mechanism.