User Specific Rate Limiting

Welcome to the third lesson of the implementing rate limiting course! In our previous lessons, we explored global and endpoint-specific rate limiting, which gave us the tools to protect our api from being overwhelmed by too many requests. However, treating all users the same way can lead to frustrating experiences for legitimate users while potentially being too lenient with bad actors.

In this lesson, we'll shift our focus toward creating a more intelligent and user-friendly approach to rate limiting. We'll learn how to customize 429 responses so users understand exactly what's happening when they exceed their limits. More importantly, we'll implement per-user rate limits that distinguish between authenticated and anonymous users, ensuring fair access while maintaining robust security.

By the end of this lesson, you'll have the skills to build rate limiting systems that not only protect your api but also provide a positive experience for your users.

The 429 status code is an HTTP response status code that indicates "Too Many Requests." When a server returns this status, it's telling the client that they've sent too many requests within a given time period and have exceeded the configured rate limit. This is a standard way for servers to communicate that the client needs to slow down.

Customizing these responses is crucial for several reasons. First, a generic 429 response leaves users confused about why their request failed and what they should do next. Second, by including additional information such as retry-after headers and helpful messages, you guide users toward the correct behavior. Third, providing links to documentation or support channels can help users who genuinely need assistance understand their options.

Think of a well-crafted 429 response as a helpful sign rather than a roadblock. It should inform users about the limitation, explain when they can try again, and optionally point them toward resources if they need higher limits.

When implementing rate limiting, striking the right balance between security and user experience is essential. Without customized 429 responses, users encounter cryptic error messages that damage their perception of your api. Without per-user rate limits, you risk treating legitimate power users the same as potential attackers, which creates unnecessary friction.

Consider a scenario where multiple employees at a company access your api from the same office network. With simple IP-based limiting, they all share the same quota, meaning one user's heavy usage could block everyone else. This is clearly unfair to legitimate users.

By implementing user-specific rate limits, you gain several advantages. Authenticated users can receive higher request limits than anonymous users, reflecting their trusted status. Users on shared networks like offices or universities avoid collective penalties for individual behavior. Additionally, you can more effectively track and limit abusive users even if they change IP addresses, since their user ID remains constant.

To improve the user experience, we need to replace generic error responses with clear, helpful messages that guide users toward resolution. In ASP.NET Core, we accomplish this by configuring the OnRejected callback within the RateLimiterOptions.

Let's start by setting up the basic structure in our Program.cs file with the necessary imports and service configuration:

using System.Threading.RateLimiting;
using Microsoft.AspNetCore.RateLimiting;

var builder = WebApplication.CreateBuilder(args);

Next, we'll add our rate limiter configuration with a custom rejection handler. The AddFixedWindowLimiter method creates a limiter that allows a specific number of requests within a fixed time window:

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("customLimiter", limiterOptions =>
    {
        limiterOptions.Window = TimeSpan.FromSeconds(30);
        limiterOptions.PermitLimit = 5;
        limiterOptions.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        limiterOptions.QueueLimit = 0;
    });

Now we add the key part: the global rejection handler that runs whenever any rate limiter denies a request. This handler extracts useful metadata and constructs an informative response:

    options.OnRejected = async (context, cancellationToken) =>
    {
        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
        context.HttpContext.Response.ContentType = "application/json";

        var retryAfter = context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfterValue)
            ? (int)retryAfterValue.TotalSeconds
            : 30;

        var response = new
        {
            error = "Too Many Requests",
            message = "You have reached your request limit. Please try again later or contact support.",
            retryAfter = retryAfter
        };

        await context.HttpContext.Response.WriteAsJsonAsync(response, cancellationToken);
    };
});

Finally, we wire up the middleware, register our endpoint, and start the application:

var app = builder.Build();

app.UseRateLimiter();

app.MapGet("/api/snippets/public-endpoint", () =>
    Results.Ok(new { message = "Public endpoint with custom 429 responses" })
).RequireRateLimiting("customLimiter");

app.Run();

The RetryAfter metadata is automatically calculated by ASP.NET Core's rate limiting middleware based on when the current window expires. By extracting and including this value, we tell users exactly how long they need to wait before making another request, which is far more helpful than leaving them to guess.

Now let's implement a more sophisticated rate limiter that applies different limits based on user authentication status. Before diving into the code, it's important to understand json web tokens (jwt), which are commonly used for authentication in modern web applications.

jwt tokens are compact, URL-safe strings that represent claims about a user. When a user logs in, the server generates a token containing their identity information and signs it cryptographically. The client then includes this token with subsequent requests, allowing the server to verify the user's identity without maintaining session state. This stateless approach works perfectly with rate limiting because we can extract user information directly from the token.

Let's build our user-based rate limiter using ASP.NET Core's PartitionedRateLimiter. We start with the imports and authentication setup:

using System.Security.Claims;
using System.Threading.RateLimiting;
using Microsoft.AspNetCore.RateLimiting;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication("Bearer")
    .AddJwtBearer("Bearer", options =>
    {
        options.Authority = builder.Configuration["Jwt:Authority"];
        options.TokenValidationParameters = new Microsoft.IdentityModel.Tokens.TokenValidationParameters
        {
            ValidateAudience = false
        };
    });

builder.Services.AddAuthorization();

The authentication configuration tells ASP.NET Core how to validate incoming jwt tokens. Once configured, the framework automatically populates HttpContext.User with the claims from valid tokens.

Next, we define our policy-based rate limiter that dynamically determines limits based on the request context:

builder.Services.AddRateLimiter(options =>
{
    options.AddPolicy("userBasedLimiter", httpContext =>
    {
        string partitionKey;
        int permitLimit;

        if (httpContext.User.Identity?.IsAuthenticated == true)
        {
            var userId = httpContext.User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
            partitionKey = userId ?? httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown";
            permitLimit = 10;
        }
        else
        {
            partitionKey = httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown";
            permitLimit = 5;
        }

        return RateLimitPartition.GetFixedWindowLimiter(partitionKey, _ =>
            new FixedWindowRateLimiterOptions
            {
                Window = TimeSpan.FromSeconds(30),
                PermitLimit = permitLimit,
                QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
                QueueLimit = 0
            });
    });

This policy function performs several important tasks. It checks whether the current request comes from an authenticated user by examining httpContext.User.Identity?.IsAuthenticated. For authenticated users, it extracts the user ID from the ClaimTypes.NameIdentifier claim and grants 10 requests per 30 seconds. For anonymous users, it falls back to IP-based partitioning with a more restrictive 5 requests per 30 seconds.

The partition key is crucial because it determines who shares a quota. By using the user ID for authenticated users, each logged-in user gets their own independent limit regardless of their IP address.

We include the same custom rejection handler, then wire up the middleware, register our endpoint, and start the application:

    options.OnRejected = async (context, cancellationToken) =>
    {
        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
        context.HttpContext.Response.ContentType = "application/json";

        var retryAfter = context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfterValue)
            ? (int)retryAfterValue.TotalSeconds
            : 30;

        var response = new
        {
            error = "Too Many Requests",
            message = "You have reached your request limit. Please try again later.",
            retryAfter = retryAfter
        };

        await context.HttpContext.Response.WriteAsJsonAsync(response, cancellationToken);
    };
});

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();

app.MapGet("/api/snippets/test-rate-limit", () =>
    Results.Ok(new { message = "Rate limit test endpoint" })
).RequireRateLimiting("userBasedLimiter");

app.Run();

Notice the middleware order: authentication runs first to populate the user context, then authorization validates permissions, and finally the rate limiter checks quotas. This order ensures the rate limiter has access to user identity information.

With our rate limiters configured, we need to apply them to specific endpoints. In minimal APIs, the .RequireRateLimiting() method provides a clean, fluent approach by chaining directly onto endpoint definitions:

app.MapGet("/api/snippets/public-endpoint", () =>
    Results.Ok(new { message = "Public endpoint with custom 429 responses" })
).RequireRateLimiting("customLimiter");

app.MapGet("/api/snippets/test-rate-limit", () =>
    Results.Ok(new { message = "Rate limit test endpoint" })
).RequireRateLimiting("userBasedLimiter");

The .RequireRateLimiting() method accepts the policy name as a parameter, linking each endpoint to its corresponding rate limiter. When a request arrives, the rate limiting middleware evaluates the appropriate policy before the endpoint handler executes. If the request exceeds the limit, the custom rejection handler returns the 429 response without ever reaching the handler.

To verify our implementation works correctly, we can create a C# console application that tests both anonymous and authenticated access patterns. This approach lets us observe the different behavior for each user type.

First, let's set up the test application with the necessary using statements and helper method for creating tokens:

using System;
using System.IdentityModel.Tokens.Jwt;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Claims;
using System.Text;
using System.Threading.Tasks;
using Microsoft.IdentityModel.Tokens;

class Program
{
    private const string JwtSecretKey = "your-secret-key-here-make-it-long-enough";
    
    static string CreateToken(string userId)
    {
        var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(JwtSecretKey));
        var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
        
        var claims = new[]
        {
            new Claim(ClaimTypes.NameIdentifier, userId),
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
        };
        
        var token = new JwtSecurityToken(
            issuer: "your-issuer",
            audience: "your-audience",
            claims: claims,
            expires: DateTime.UtcNow.AddHours(1),
            signingCredentials: credentials
        );
        
        return new JwtSecurityTokenHandler().WriteToken(token);
    }

Now let's implement the main testing logic that sends requests as both anonymous and authenticated users:

    static async Task Main(string[] args)
    {
        Console.WriteLine("Testing per-user rate limits...");
        
        using var client = new HttpClient();
        client.BaseAddress = new Uri("https://localhost:5001");
        
        Console.WriteLine("\nTesting as anonymous user:");
        for (int i = 1; i <= 7; i++)
        {
            var response = await client.GetAsync("/api/snippets/test-rate-limit");
            if (response.IsSuccessStatusCode)
                Console.WriteLine($"Request {i}: {(int)response.StatusCode} Success");
            else
            {
                var content = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"Request {i}: {(int)response.StatusCode} {content}");
            }
            await Task.Delay(50);
        }
        
        Console.WriteLine("\nTesting as authenticated user:");
        var token = CreateToken("user123");
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
        
        for (int i = 1; i <= 12; i++)
        {
            var response = await client.GetAsync("/api/snippets/test-rate-limit");
            if (response.IsSuccessStatusCode)
                Console.WriteLine($"Request {i}: {(int)response.StatusCode} Success");
            else
            {
                var content = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"Request {i}: {(int)response.StatusCode} {content}");
            }
            await Task.Delay(50);
        }
    }
}

When you run this test application, you should see output similar to the following:

Testing per-user rate limits...

Testing as anonymous user:
Request 1: 200 Success
Request 2: 200 Success
Request 3: 200 Success
Request 4: 200 Success
Request 5: 200 Success
Request 6: 429 {"error":"Too Many Requests","message":"You have reached your request limit. Please try again later.","retryAfter":25}
Request 7: 429 {"error":"Too Many Requests","message":"You have reached your request limit. Please try again later.","retryAfter":25}

Testing as authenticated user:
Request 1: 200 Success
Request 2: 200 Success
Request 3: 200 Success
Request 4: 200 Success
Request 5: 200 Success
Request 6: 200 Success
Request 7: 200 Success
Request 8: 200 Success
Request 9: 200 Success
Request 10: 200 Success
Request 11: 429 {"error":"Too Many Requests","message":"You have reached your request limit. Please try again later.","retryAfter":22}
Request 12: 429 {"error":"Too Many Requests","message":"You have reached your request limit. Please try again later.","retryAfter":22}

The output clearly demonstrates our rate limiting logic in action. Anonymous users successfully complete 5 requests before hitting their limit on request 6. The authenticated user, identified by their jwt token, enjoys a higher quota of 10 requests before being throttled. Notice how the retryAfter value in the response tells users exactly how many seconds remain until they can make new requests.

In this lesson, you've learned how to transform basic rate limiting into a user-friendly, intelligent system that balances security with positive user experiences. We started by understanding why the HTTP 429 status code matters and how customizing these responses helps users understand and respond appropriately to rate limits.

You then implemented per-user rate limiting using ASP.NET Core's partitioned rate limiters, which allowed you to provide different quotas for authenticated and anonymous users. This approach ensures that trusted users receive appropriate access while maintaining protection against abuse. The combination of user-specific partitioning and informative error responses creates an api that is both secure and pleasant to work with.

In our next lesson, we'll build on this foundation to implement role-based rate limiting, giving you even more granular control over user access levels. You'll learn how to assign different quotas based on subscription tiers, user roles, or other custom criteria. In the upcoming practice, you'll apply the concepts from this lesson to reinforce your understanding and gain hands-on experience with user-specific rate limiting.