Implementing IP Whitelisting and Blacklisting Middleware in ASP.NET Core

Date- Jun 10,2026 290

aspnetcore middleware

Overview

IP Whitelisting and Blacklisting are essential security mechanisms used to control access to applications based on the originating IP addresses of requests. Whitelisting allows only specified IP addresses to access the application, while blacklisting denies access to specified IP addresses. Each method addresses different security requirements and can be used in conjunction with other security practices to prevent unauthorized access and mitigate potential threats.

These techniques are particularly relevant in environments where applications are exposed to the public internet. For example, a financial institution may only allow requests from known IP addresses, such as those of its branches or trusted partners. Conversely, a company may blacklist IP addresses associated with malicious activity or known bots to protect its resources. In both cases, implementing IP filtering can significantly reduce the attack surface of an application.

Prerequisites

ASP.NET Core SDK: Ensure you have the .NET SDK installed to create and run ASP.NET Core applications.
Basic C# Knowledge: Familiarity with C# programming is necessary to understand middleware implementation.
Understanding Middleware: A grasp of how middleware works in ASP.NET Core is essential for effective implementation.
IDE: An integrated development environment like Visual Studio or Visual Studio Code for coding and debugging.

Creating Middleware for IP Whitelisting

To implement IP whitelisting in an ASP.NET Core application, we need to create custom middleware that checks incoming requests against a list of allowed IP addresses. If the request's IP address is not in the whitelist, the middleware should return an unauthorized response.

using Microsoft.AspNetCore.Http;
using System.Collections.Generic;
using System.Net;
using System.Threading.Tasks;

public class IpWhitelistingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly HashSet _whitelistedIps;

    public IpWhitelistingMiddleware(RequestDelegate next, IEnumerable whitelistedIps)
    {
        _next = next;
        _whitelistedIps = new HashSet(whitelistedIps);
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var remoteIp = context.Connection.RemoteIpAddress;
        if (!_whitelistedIps.Contains(remoteIp))
        {
            context.Response.StatusCode = StatusCodes.Status403Forbidden;
            await context.Response.WriteAsync("Forbidden: Your IP is not allowed.");
            return;
        }
        await _next(context);
    }
}

The above code defines a middleware class called IpWhitelistingMiddleware. It takes a RequestDelegate and a collection of whitelisted IP addresses as parameters. The constructor initializes the middleware, storing the allowed IPs in a HashSet for efficient lookups.

The InvokeAsync method retrieves the remote IP address of the incoming request using context.Connection.RemoteIpAddress. It checks if the IP is in the whitelist; if not, it sets the response status code to 403 Forbidden and sends a message indicating access is denied. If the IP is allowed, it calls the next middleware in the pipeline using await _next(context).

Registering the Middleware

To use the middleware, we need to register it in the Startup.cs file of the ASP.NET Core application. This involves configuring the middleware in the Configure method.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    var whitelistedIps = new List
    {
        IPAddress.Parse("192.168.1.1"),
        IPAddress.Parse("203.0.113.5")
    };

    app.UseMiddleware(whitelistedIps);
    // Other middleware registrations
}

In this code snippet, we define a list of whitelisted IPs and register the IpWhitelistingMiddleware using app.UseMiddleware. This ensures that all incoming requests are checked against the specified IP addresses before proceeding to the next middleware.

Creating Middleware for IP Blacklisting

IP blacklisting middleware works similarly to whitelisting but denies access to specific IP addresses instead. To implement this, we create another middleware class that checks incoming requests against a blacklist.

using Microsoft.AspNetCore.Http;
using System.Collections.Generic;
using System.Net;
using System.Threading.Tasks;

public class IpBlacklistingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly HashSet _blacklistedIps;

    public IpBlacklistingMiddleware(RequestDelegate next, IEnumerable blacklistedIps)
    {
        _next = next;
        _blacklistedIps = new HashSet(blacklistedIps);
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var remoteIp = context.Connection.RemoteIpAddress;
        if (_blacklistedIps.Contains(remoteIp))
        {
            context.Response.StatusCode = StatusCodes.Status403Forbidden;
            await context.Response.WriteAsync("Forbidden: Your IP is blacklisted.");
            return;
        }
        await _next(context);
    }
}

This code defines the IpBlacklistingMiddleware class that initializes with a list of blacklisted IP addresses. The InvokeAsync method checks if the incoming request's remote IP is in the blacklist. If so, it returns a 403 Forbidden response; otherwise, it calls the next middleware.

Registering the Blacklisting Middleware

Similar to whitelisting, we must register the blacklisting middleware in the Startup.cs file.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    var blacklistedIps = new List
    {
        IPAddress.Parse("192.168.1.100"),
        IPAddress.Parse("203.0.113.10")
    };

    app.UseMiddleware(blacklistedIps);
    // Other middleware registrations
}

In this case, we define a list of blacklisted IPs and register the IpBlacklistingMiddleware in the pipeline. Requests from any of the blacklisted IP addresses will be denied access.

Edge Cases & Gotchas

When implementing IP whitelisting and blacklisting, there are several edge cases and pitfalls to consider. One common issue arises when dealing with proxies or load balancers that may alter the RemoteIpAddress. Ensure that your application appropriately handles forwarded headers if it is behind a proxy.

app.UseForwardedHeaders(new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});

Another potential pitfall is the use of CIDR notation for IP ranges. In such cases, you will need to implement additional logic to parse and check whether an IP falls within a specified range, which can complicate your middleware implementation.

Performance & Best Practices

Performance is a critical consideration when implementing IP filtering. Using a HashSet for storing IP addresses allows for O(1) average time complexity for lookups, which is essential for maintaining responsiveness in high-traffic applications. Always prefer using collections optimized for search operations.

Another best practice is to cache the IP lists, especially for large applications. This approach minimizes the overhead of repeatedly checking against a potentially large list of IPs. You can utilize in-memory caching or distributed caching solutions depending on your deployment architecture.

Real-World Scenario

Let's consider a real-world scenario where we create an ASP.NET Core web application that implements both whitelisting and blacklisting. This application will allow only requests from a predefined set of IP addresses while blocking known malicious IPs.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Add services for MVC or other services
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        var whitelistedIps = new List
        {
            IPAddress.Parse("192.168.1.1"),
            IPAddress.Parse("203.0.113.5")
        };

        var blacklistedIps = new List
        {
            IPAddress.Parse("192.168.1.100"),
            IPAddress.Parse("203.0.113.10")
        };

        app.UseMiddleware(blacklistedIps);
        app.UseMiddleware(whitelistedIps);

        app.UseRouting();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapGet("/", async context =>
            {
                await context.Response.WriteAsync("Welcome to the secure application!");
            });
        });
    }
}

This example demonstrates how to set up a simple web application where both IP whitelisting and blacklisting middleware are registered. The application responds with a welcome message only to requests from IPs that are whitelisted and not blacklisted.

Conclusion

IP whitelisting and blacklisting are vital techniques for securing ASP.NET Core applications.
Custom middleware can effectively handle IP filtering based on predefined lists.
Performance considerations are crucial; using appropriate data structures can enhance responsiveness.
Understanding edge cases, such as handling proxies and CIDR notation, can prevent common pitfalls.
Real-world scenarios demonstrate the practical application of these techniques in securing web applications.