Use hCaptcha with dotnet and ASP.NET Core

Many websites protect themselves from automated access with reCaptcha, a Google company.

The top dog can be found on almost every website.

About hCaptcha

What few people know is that there are real alternatives to reCaptcha: hCaptcha.

hCaptcha is a company of Intuition Machines. Intuition Machines itself is a company that says about itself that it is an absolute specialist in deep learning. The company is located in California, USA.

They also say of themselves that they are superior to reCaptcha, especially in terms of privacy and data protection - with identical results in terms of bot checking.

Developer perspective

hCaptcha itself is still relatively young, so the documentation is not as good as reCaptcha. The documentation really only covers the essentials, which is sufficient for the basic setup.
Integration is currently only focused in web applications or applications based on HTML and JavaScript. There is no other possibility - right now.

hCaptcha currently offers two different types of bot verification:

• By selecting images, requires interaction with the user
• Automated, invisible and without user interaction in the background

Both variants are implemented with the help of JavaScript. The APIs are currently not quite as flexible as reCaptcha.

Otherwise the functionality is relatively similar:
The client receives an Id which is sent to the server. On the server, the captcha API must then be addressed to get the result of the check.

ASP.NET Core

Currently there is no documentation how hCaptcha can be integrated into .NET or ASP.NET core applications. The documentation here is really limited to the basics of HTML and HTTP.

hCaptcha has now received some data to create a list of community contributions:
https://github.com/hCaptcha/hcaptcha-integrations-list

I contributed the example of .NET and ASP.NET Core: https://github.com/BenjaminAbt/hcaptcha

ASP.NET Core Usage

For the use in .NET and ASP.NET Core I have created two NuGet packages:

• which covers the basic, technology neutral functions
• for integration into ASP.NET core applications

HCaptcha is registered via the services, whereby the necessary configuration is also registered here.

1public void ConfigureServices(IServiceCollection services)
2{
3   // HCaptcha
4   services.AddHCaptcha(Configuration.GetSection("HCaptcha"));
5   ...

The configuration is limited to the most necessary: The hCaptcha SiteKey and the Secret. Both information are part of the site registration in the hCaptcha dashbaord.

1"HCaptcha": {
2   "SiteKey": "", // Overwrite them with yours
3   "Secret": "" // Overwrite them with yours
4}

In case of use I have primarily decided to use a model binder.
Even if a ModelBinder is not the primary way to use it, it is a very convenient way to validate a captcha.

 1public void ConfigureServices(IServiceCollection services)
 2{
 3    // HCaptcha
 4    services.AddHCaptcha(Configuration.GetSection("HCaptcha"));
 5
 6    // Mvc
 7    services.AddControllersWithViews(mvcOptions =>
 8        // add model binder
 9        mvcOptions.AddHCaptchaModelBinder());
10}

A model binder is called in ASP.NET Core when a specific data type is part of the parameter list of an action.
For this I created the HCaptchaVerifyResponse type.

Once this type is part of the action, the captcha is automatically validated in the background before the action is called. The result is then part of the instance.

 1public class HomeController : Controller
 2{
 3    [HttpGet, Route("")]
 4    public IActionResult Index()
 5    {
 6        return View(new IndexViewModel());
 7    }
 8
 9    [HttpPost, Route("")]
10    public IActionResult Index(HCaptchaVerifyResponse hCaptcha)
11    {
12        return View(new IndexViewModel(hCaptcha));
13    }
14}

The alternative would be a corresponding service filter.