Edi.Captcha 5.0.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
using Edi.Captcha.SampleApp.Models;
using Microsoft.AspNetCore.Mvc;
using System;
using System.Diagnostics;
namespace Edi.Captcha.SampleApp.Controllers;
public class StatelessController(IStatelessCaptcha captcha) : Controller
{
public IActionResult Index()
{
return View(new StatelessHomeModel());
}
[HttpPost]
public IActionResult Index(StatelessHomeModel model)
{
if (ModelState.IsValid)
{
bool isValidCaptcha = captcha.Validate(model.CaptchaCode, model.CaptchaToken);
return Content(isValidCaptcha ? "Success - Stateless captcha validated!" : "Invalid captcha code");
}
return BadRequest();
}
[Route("get-stateless-captcha")]
public IActionResult GetStatelessCaptcha()
{
var result = captcha.GenerateCaptcha(100, 36);
return Json(new {
token = result.Token,
imageBase64 = Convert.ToBase64String(result.ImageBytes)
});
}
[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
public IActionResult Error()
{
return View(new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
}
}
4. Example View
@model StatelessHomeModel
@{
ViewData["Title"] = "Stateless Captcha Example";
}
<div class="text-center">
<h1 class="display-4">Stateless Captcha Example</h1>
<p>This example shows how to use stateless captcha that works in clustered environments.</p>
</div>
<div class="row">
<div class="col-md-6 offset-md-3">
<div class="card">
<div class="card-header">
<h5>Stateless Captcha Form</h5>
</div>
<div class="card-body">
<form asp-action="Index" method="post" id="stateless-form">
<div class="form-group mb-3">
<label>Captcha Image:</label>
<div class="d-flex align-items-center">
<img id="captcha-image" src="" alt="Captcha" class="me-2" style="border: 1px solid #ccc;" />
<button type="button" class="btn btn-sm btn-outline-secondary" onclick="refreshCaptcha()">
🔄 Refresh
</button>
</div>
<small class="form-text text-muted">Click refresh to get a new captcha</small>
</div>
<div class="form-group mb-3">
<label asp-for="CaptchaCode">Enter Captcha Code:</label>
<input asp-for="CaptchaCode" class="form-control" placeholder="Enter the code from image" autocomplete="off" />
<span asp-validation-for="CaptchaCode" class="text-danger"></span>
</div>
<input type="hidden" asp-for="CaptchaToken" id="captcha-token" />
<div class="form-group">
<button type="submit" class="btn btn-primary">Submit</button>
<a asp-controller="Home" asp-action="Index" class="btn btn-secondary">Session-based Example</a>
</div>
</form>
<div class="mt-4">
<h6>Advantages of Stateless Captcha:</h6>
<ul class="small">
<li>✅ Works in clustered/load-balanced environments</li>
<li>✅ No server-side session storage required</li>
<li>✅ Built-in expiration through encryption</li>
<li>✅ Secure token-based validation</li>
<li>✅ Better scalability</li>
<li>✅ Single API call for both token and image</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<script>
async function refreshCaptcha() {
try {
const response = await fetch('/get-stateless-captcha');
const data = await response.json();
// Set the token for validation
document.getElementById('captcha-token').value = data.token;
// Set the image source using base64 data
document.getElementById('captcha-image').src = `data:image/png;base64,${data.imageBase64}`;
// Clear the input
document.getElementById('CaptchaCode').value = '';
} catch (error) {
console.error('Error refreshing captcha:', error);
alert('Failed to load captcha. Please try again.');
}
}
// Initialize captcha on page load
document.addEventListener('DOMContentLoaded', function() {
refreshCaptcha();
});
</script>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}