Edi.Captcha 5.1.1
Edi.Captcha.AspNetCore
The Captcha module used in my blog
Install
NuGet Package Manager
Install-Package Edi.Captcha
or .NET CLI
dotnet add package Edi.Captcha
Session-Based Captcha (Traditional Approach)
1. Register in DI
services.AddSession(options =>
{
options.IdleTimeout = TimeSpan.FromMinutes(20);
options.Cookie.HttpOnly = true;
});
services.AddSessionBasedCaptcha();
// Don't forget to add this line in your `Configure` method.
app.UseSession();
or you can customize the options
services.AddSessionBasedCaptcha(option =>
{
option.Letters = "2346789ABCDEFGHJKLMNPRTUVWXYZ";
option.SessionName = "CaptchaCode";
option.CodeLength = 4;
});
2. Generate Image
Using MVC Controller
private readonly ISessionBasedCaptcha _captcha;
public SomeController(ISessionBasedCaptcha captcha)
{
_captcha = captcha;
}
[Route("get-captcha-image")]
public IActionResult GetCaptchaImage()
{
var s = _captcha.GenerateCaptchaImageFileStream(
HttpContext.Session,
100,
36
);
return s;
}
Using Middleware
app.UseSession().UseCaptchaImage(options =>
{
options.RequestPath = "/captcha-image";
options.ImageHeight = 36;
options.ImageWidth = 100;
});
3. Add CaptchaCode Property to Model
[Required]
[StringLength(4)]
public string CaptchaCode { get; set; }
5. View
<div class="col">
<div class="input-group">
<div class="input-group-prepend">
<img id="img-captcha" src="~/captcha-image" />
</div>
<input type="text"
asp-for="CommentPostModel.CaptchaCode"
class="form-control"
placeholder="Captcha Code"
autocomplete="off"
minlength="4"
maxlength="4" />
</div>
<span asp-validation-for="CommentPostModel.CaptchaCode" class="text-danger"></span>
</div>
6. Validate Input
_captcha.ValidateCaptchaCode(model.CommentPostModel.CaptchaCode, HttpContext.Session)
To make your code look more cool, you can also write an Action Filter like this:
public class ValidateCaptcha : ActionFilterAttribute
{
private readonly ISessionBasedCaptcha _captcha;
public ValidateCaptcha(ISessionBasedCaptcha captcha)
{
_captcha = captcha;
}
public override void OnActionExecuting(ActionExecutingContext context)
{
var captchaedModel =
context.ActionArguments.Where(p => p.Value is ICaptchable)
.Select(x => x.Value as ICaptchable)
.FirstOrDefault();
if (null == captchaedModel)
{
context.ModelState.AddModelError(nameof(captchaedModel.CaptchaCode), "Captcha Code is required");
context.Result = new BadRequestObjectResult(context.ModelState);
}
else
{
if (!_captcha.Validate(captchaedModel.CaptchaCode, context.HttpContext.Session))
{
context.ModelState.AddModelError(nameof(captchaedModel.CaptchaCode), "Wrong Captcha Code");
context.Result = new ConflictObjectResult(context.ModelState);
}
else
{
base.OnActionExecuting(context);
}
}
}
}
and then
services.AddScoped<ValidateCaptcha>();
and then
public class YourModelWithCaptchaCode : ICaptchable
{
public string YourProperty { get; set; }
[Required]
[StringLength(4)]
public string CaptchaCode { get; set; }
}
[ServiceFilter(typeof(ValidateCaptcha))]
public async Task<IActionResult> SomeAction(YourModelWithCaptchaCode model)
{
// ....
}
Stateless Captcha (Recommended for Scalable Applications)
Advantages of Stateless Captcha:
- ✅ Works in clustered/load-balanced environments
- ✅ No server-side session storage required
- ✅ Built-in expiration through encryption
- ✅ Secure token-based validation
- ✅ Better scalability
- ✅ Single API call for both token and image
1. Register in DI
services.AddStatelessCaptcha();
or with custom options:
services.AddStatelessCaptcha(options =>
{
options.Letters = "2346789ABCDGHKMNPRUVWXYZ";
options.CodeLength = 4;
options.TokenExpiration = TimeSpan.FromMinutes(5);
});
2. Create Model with Token Support
public class StatelessHomeModel
{
[Required]
[StringLength(4)]
public string CaptchaCode { get; set; }
public string CaptchaToken { get; set; }
}
3. Example Controller and View
See: src\Edi.Captcha.SampleApp\Controllers\StatelessController.cs and src\Edi.Captcha.SampleApp\Views\Stateless\Index.cshtml for a complete example.
Cluster/Load Balancer Configuration
⚠️ Important for Production Deployments: The stateless captcha uses ASP.NET Core's Data Protection API for token encryption. In clustered environments or behind load balancers, you must configure shared data protection keys to ensure captcha tokens can be validated on any server.
Option 1: File System (Network Share)
public void ConfigureServices(IServiceCollection services)
{
services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\shared-network-path\keys"))
.SetApplicationName("YourAppName"); // Must be consistent across all instances
services.AddStatelessCaptcha(options =>
{
// Your captcha configuration
});
}
Option 2: Azure Blob Storage
public void ConfigureServices(IServiceCollection services)
{
services.AddDataProtection()
.PersistKeysToAzureBlobStorage("DefaultEndpointsProtocol=https;AccountName=...", "keys-container", "dataprotection-keys.xml")
.SetApplicationName("YourAppName");
services.AddStatelessCaptcha(options =>
{
// Your captcha configuration
});
}
Option 3: Redis
public void ConfigureServices(IServiceCollection services)
{
services.AddDataProtection()
.PersistKeysToStackExchangeRedis(ConnectionMultiplexer.Connect("your-redis-connection"), "DataProtection-Keys")
.SetApplicationName("YourAppName");
services.AddStatelessCaptcha(options =>
{
// Your captcha configuration
});
}
Option 4: SQL Server
public void ConfigureServices(IServiceCollection services)
{
services.AddDataProtection()
.PersistKeysToDbContext<YourDbContext>()
.SetApplicationName("YourAppName");
services.AddStatelessCaptcha(options =>
{
// Your captcha configuration
});
}
Single Server Deployment
For single server deployments, no additional configuration is required. The default Data Protection configuration will work correctly.
Testing Cluster Configuration
To verify your cluster configuration is working:
- Generate a captcha on Server A
- Submit the form to Server B (or any other server)
- Validation should succeed
If validation fails with properly entered captcha codes, check your Data Protection configuration.
Shared Key Stateless Captcha (Recommended for Scalable Applications without DPAPI)
When to use Shared Key Stateless Captcha:
- ✅ Full control over encryption keys
- ✅ Works without ASP.NET Core Data Protection API
- ✅ Simpler cluster configuration
- ✅ Custom key rotation strategies
- ✅ Works across different application frameworks
- ✅ No dependency on external storage for keys
1. Register in DI with Shared Key
services.AddSharedKeyStatelessCaptcha(options =>
{
options.SharedKey = "your-32-byte-base64-encoded-key"; // Generate securely
options.FontStyle = FontStyle.Bold;
options.DrawLines = true;
options.TokenExpiration = TimeSpan.FromMinutes(5);
});
2. Generate Secure Shared Key
Important: Use a cryptographically secure random key. Here's how to generate one:
// Generate a secure 256-bit key (one-time setup)
using (var rng = RandomNumberGenerator.Create())
{
var keyBytes = new byte[32]; // 256 bits
rng.GetBytes(keyBytes);
var base64Key = Convert.ToBase64String(keyBytes);
Console.WriteLine($"Shared Key: {base64Key}");
}
3. Configuration Options
Configuration File (appsettings.json)
{
"CaptchaSettings": {
"SharedKey": "your-generated-base64-key-here",
"TokenExpirationMinutes": 5
}
}
public void ConfigureServices(IServiceCollection services)
{
var captchaKey = Configuration["CaptchaSettings:SharedKey"];
var expirationMinutes = Configuration.GetValue<int>("CaptchaSettings:TokenExpirationMinutes", 5);
services.AddSharedKeyStatelessCaptcha(options =>
{
options.SharedKey = captchaKey;
options.TokenExpiration = TimeSpan.FromMinutes(expirationMinutes);
// Other options...
});
}
4. Example Controller and View
See: src\Edi.Captcha.SampleApp\Controllers\SharedKeyStatelessController.cs and src\Edi.Captcha.SampleApp\Views\SharedKeyStateless\Index.cshtml for a complete example.