IpRateLimitMiddleware
NuGet install:
Install-Package AspNetCoreRateLimit
Install-Package AspNetCoreRateLimit.Redis
Startup.cs code:
public void ConfigureServices(IServiceCollection services)
{
// needed to load configuration from appsettings.json
services.AddOptions();
// needed to store rate limit counters and ip rules
services.AddMemoryCache();
//load general configuration from appsettings.json
services.Configure<IpRateLimitOptions>(Configuration.GetSection("IpRateLimiting"));
//load ip rules from appsettings.json
services.Configure<IpRateLimitPolicies>(Configuration.GetSection("IpRateLimitPolicies"));
// inject counter and rules stores
services.AddInMemoryRateLimiting();
//services.AddDistributedRateLimiting<AsyncKeyLockProcessingStrategy>();
//services.AddDistributedRateLimiting<RedisProcessingStrategy>();
//services.AddRedisRateLimiting();
// Add framework services.
services.AddMvc();
// configuration (resolvers, counter key builders)
services.AddSingleton<IRateLimitConfiguration, RateLimitConfiguration>();
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseIpRateLimiting();
app.UseMvc();
}You should register the middleware before any other components.
If you load-balance your app, you'll need to use IDistributedCache with Redis or SQLServer so that all kestrel instances will have the same rate limit store.
Instead of the in-memory stores, you should inject the distributed stores like this:
// inject counter and rules distributed cache stores
services.AddSingleton<IIpPolicyStore, DistributedCacheIpPolicyStore>();
services.AddSingleton<IRateLimitCounterStore,DistributedCacheRateLimitCounterStore>();Configuration and general rules appsettings.json:
"IpRateLimiting": {
"EnableEndpointRateLimiting": false,
"StackBlockedRequests": false,
"RealIpHeader": "X-Real-IP",
"ClientIdHeader": "X-ClientId",
"HttpStatusCode": 429,
"IpWhitelist": [ "127.0.0.1", "::1/10", "192.168.0.0/24" ],
"EndpointWhitelist": [ "get:/api/license", "*:/api/status" ],
"ClientWhitelist": [ "dev-id-1", "dev-id-2" ],
"GeneralRules": [
{
"Endpoint": "*",
"Period": "1s",
"Limit": 2
},
{
"Endpoint": "*",
"Period": "15m",
"Limit": 100
},
{
"Endpoint": "*",
"Period": "12h",
"Limit": 1000
},
{
"Endpoint": "*",
"Period": "7d",
"Limit": 10000
}
]
}If EnableEndpointRateLimiting is set to false then the limits will apply globally and only the rules that have as endpoint * will apply. For example, if you set a limit of 5 calls per second, any HTTP call to any endpoint will count towards that limit.
If EnableEndpointRateLimiting is set to true, then the limits will apply for each endpoint as in {HTTP_Verb}{PATH}. For example if you set a limit of 5 calls per second for *:/api/values a client can call GET /api/values 5 times per second but also 5 times PUT /api/values.
If StackBlockedRequests is set to false, rejected calls are not added to the throttle counter. If a client makes 3 requests per second and you've set a limit of one call per second, other limits like per minute or per day counters will only record the first call, the one that wasn't blocked. If you want rejected requests to count towards the other limits, you'll have to set StackBlockedRequests to true.
The RealIpHeader is used to extract the client IP when your Kestrel server is behind a reverse proxy, if your proxy uses a different header then X-Real-IP use this option to set it up.
The ClientIdHeader is used to extract the client id for white listing. If a client id is present in this header and matches a value specified in ClientWhitelist then no rate limits are applied.
Override general rules for specific IPs appsettings.json:
"IpRateLimitPolicies": {
"IpRules": [
{
"Ip": "84.247.85.224",
"Rules": [
{
"Endpoint": "*",
"Period": "1s",
"Limit": 10
},
{
"Endpoint": "*",
"Period": "15m",
"Limit": 200
}
]
},
{
"Ip": "192.168.3.22/25",
"Rules": [
{
"Endpoint": "*",
"Period": "1s",
"Limit": 5
},
{
"Endpoint": "*",
"Period": "15m",
"Limit": 150
},
{
"Endpoint": "*",
"Period": "12h",
"Limit": 500
}
]
}
]
}The IP field supports IP v4 and v6 values and ranges like "192.168.0.0/24", "fe80::/10" or "192.168.0.0-192.168.0.255".
If you have static rate policies defined in the appsettings.json config file, then you need to seed them at application start-up:
public static async Task Main(string[] args)
{
IWebHost webHost = CreateWebHostBuilder(args).Build();
using (var scope = webHost.Services.CreateScope())
{
// get the IpPolicyStore instance
var ipPolicyStore = scope.ServiceProvider.GetRequiredService<IIpPolicyStore>();
// seed IP data from appsettings
await ipPolicyStore.SeedAsync();
}
await webHost.RunAsync();
}A rule is composed of an endpoint, a period and a limit.
Endpoint format is {HTTP_Verb}:{PATH}, you can target any HTTP verb by using the asterix symbol.
Period format is {INT}{PERIOD_TYPE}, you can use one of the following period types: s, m, h, d.
Limit format is {LONG}.
Examples:
Rate limit all endpoints to 2 calls per second:
Wildcard:
{
"Endpoint": "*",
"Period": "1s",
"Limit": 2
}Regex:
{
"Endpoint": ".+",
"Period": "1s",
"Limit": 2
}If, from the same IP, in the same second, you'll make 3 GET calls to api/values, the last call will get blocked. But if in the same second you call PUT api/values too, the request will go through because it's a different endpoint. When endpoint rate limiting is enabled each call is rate limited based on {HTTP_Verb}{PATH}.
Rate limit calls with any HTTP Verb to /api/values to 5 calls per 15 minutes:
Wildcard:
{
"Endpoint": "*:/api/values",
"Period": "15m",
"Limit": 5
}Regex:
{
"Endpoint": ":/api/values",
"Period": "15m",
"Limit": 5
}Rate limit GET call to /api/values to 5 calls per hour:
{
"Endpoint": "get:/api/values",
"Period": "1h",
"Limit": 5
}Rate limit POST or PUT call to /api/values to 5 calls per hour:
{
"Endpoint": "((post)|(put)):/api/values",
"Period": "1h",
"Limit": 5
}If, from the same IP, in one hour, you'll make 6 GET calls to api/values, the last call will get blocked. But if in the same hour you call GET api/values/1 too, the request will go through because it's a different endpoint.
When a client makes a HTTP call, the IpRateLimitMiddleware : RateLimitMiddleware<IpRateLimitProcessor> does the following:
- extracts the IP, Client id, HTTP verb and URL from the request object, if you want to implement your own extraction logic you can override the
IpRateLimitMiddleware.ResolveIdentitymethod or implement custom ip/client resolvers:
public class CustomRateLimitConfiguration : RateLimitConfiguration
{
protected override void RegisterResolvers()
{
base.RegisterResolvers();
ClientResolvers.Add(new ClientQueryStringResolveContributor(HttpContextAccessor, ClientRateLimitOptions.ClientIdHeader));
}
}-
searches for the IP, Client id and URL in the white lists, and if it matches any, then no action is taken.
-
searches in the IP rules for a match, all rules that apply are grouped by period, for each period the most restrictive rule being used.
-
searches in the General rules for a match, if a general rule that matches has a defined period that is not present in the IP rules, then this general rule is also used.
-
for each matching rule the rate limit counter is incremented, if the counter value is greater then the rule limit, then the request gets blocked.
If the request gets blocked then the client receives a text response like this:
Status Code: 429
Retry-After: 58
Content: API calls quota exceeded! maximum admitted 2 per 1m.
You can customize the response by changing these options HttpStatusCode and QuotaExceededMessage, if you want to implement your own response you can override the IpRateLimitMiddleware.ReturnQuotaExceededResponse. The Retry-After header value is expressed in seconds.
If the request doesn't get rate limited then the longest period defined in the matching rules is used to compose the X-Rate-Limit headers, these headers are injected in the response:
X-Rate-Limit-Limit: the rate limit period (eg. 1m, 12h, 1d)
X-Rate-Limit-Remaining: number of request remaining
X-Rate-Limit-Reset: UTC date time (ISO 8601) when the limits resets
A client can parse the X-Rate-Limit-Reset like this:
DateTime resetDate = DateTime.ParseExact(resetHeader, "o", DateTimeFormatInfo.InvariantInfo);
The X-Rate-Limit and Retry-After headers can be disabled by setting the DisableRateLimitHeaders option to true in appsettings.json.
By default, blocked request are logged using Microsoft.Extensions.Logging.ILogger, if you want to implement your own logging you can override the IpRateLimitMiddleware.LogBlockedRequest.
The default logger emits the following information when a request gets rate limited:
info: AspNetCoreRateLimit.IpRateLimitMiddleware[0]
Request get:/api/values from IP 84.247.85.224 has been blocked, quota 2/1m exceeded by 3. Blocked by rule *:/api/value, TraceIdentifier 0HKTLISQQVV9D.
At application startup the IP rate limit rules defined in appsettings.json are loaded in cache by either MemoryCacheClientPolicyStore or DistributedCacheIpPolicyStore depending on what type of cache provider you are using. You can access the Ip policy store inside a controller and modify the IP rules like so:
public class IpRateLimitController : Controller
{
private readonly IpRateLimitOptions _options;
private readonly IIpPolicyStore _ipPolicyStore;
public IpRateLimitController(IOptions<IpRateLimitOptions> optionsAccessor, IIpPolicyStore ipPolicyStore)
{
_options = optionsAccessor.Value;
_ipPolicyStore = ipPolicyStore;
}
[HttpGet]
public IpRateLimitPolicies Get()
{
return _ipPolicyStore.Get(_options.IpPolicyPrefix);
}
[HttpPost]
public void Post()
{
var pol = _ipPolicyStore.Get(_options.IpPolicyPrefix);
pol.IpRules.Add(new IpRateLimitPolicy
{
Ip = "8.8.4.4",
Rules = new List<RateLimitRule>(new RateLimitRule[] {
new RateLimitRule {
Endpoint = "*:/api/testupdate",
Limit = 100,
Period = "1d" }
})
});
_ipPolicyStore.Set(_options.IpPolicyPrefix, pol);
}
}This way you can store the IP rate limits in a database and push them in cache after each app start.