♻️ A friction-less C# HTTP verification client for Google's reCAPTCHA API.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Build status Nuget Users

BitArmory.ReCaptcha for .NET and C#

Project Description

♻️ A minimal, no-drama, friction-less C# HTTP verification client for Google's reCAPTCHA API.

The problem with current ReCaptcha libraries in .NET is that all of them take a hard dependency on the underlying web framework like ASP.NET WebForms, ASP.NET MVC 5, ASP.NET Core, or ASP.NET Razor Pages.

Furthermore, current reCAPTCHA libraries for .NET are hard coded against the HttpContext.Request to retrieve the remote IP address of the visitor. Unfortunately, this method doesn't work if your website is behind a service like CloudFlare where the CF-Connecting-IP header value is the real IP address of the visitor on your site.

BitArmory.ReCaptcha is a minimal library that works across all .NET web frameworks without taking a hard dependency on any web framework. If you want to leverage platform specific features, like MVC Action Filters, you'll need to implement your own ActionFilter that leverages the functionality in this library.

Supported Platforms

  • .NET Standard 1.3 or later
  • .NET Framework 4.5 or later

Crypto Tip Jar

  • 🐕 Dogecoin: DGVC2drEMt41sEzEHSsiE3VTrgsQxGn5qe

Download & Install

Nuget Package BitArmory.ReCaptcha

Install-Package BitArmory.ReCaptcha


Getting Started

You'll need to create reCAPTCHA account. You can sign up here! After you sign up and setup your domain, you'll have two important pieces of information:

  1. Your site key
  2. Your secret key

Client-side Setup

Add the following <div class="g-recaptcha"> and <script> tags to your HTML form:

    <form method="POST">
        <div class="g-recaptcha" data-sitekey="your_site_key"></div>
        <input type="submit" value="Submit">

    <script src="https://www.google.com/recaptcha/api.js" async defer></script>

Verifying the POST Server-side

When the POST is received on the server:

  1. Get the client's IP address. If you're using CloudFlare, be sure to use the CF-Connecting-IP header value.
  2. Extract the g-recaptcha-response (Client Response) HTML form field.
  3. Use the ReCaptchaService to verify the client's reCAPTCHA is valid.

The following example shows how to verify the captcha during an HTTP POST back in ASP.NET Core: Razor Pages.

//1. Get the client IP address in your chosen web framework
string clientIp = this.HttpContext.Connection.RemoteIpAddress.ToString();
string captchaResponse = null;
string secret = "your_secret_key";

//2. Extract the `g-recaptcha-response` field from the HTML form in your chosen web framework
if( this.Request.Form.TryGetValue(Constants.ClientResponseKey, out var grr) )
   capthcaResponse = grr;

//3. Validate the reCAPTCHA with Google
var captchaApi = new ReCaptchaService();
var isValid = await captchaApi.VerifyAsync(capthcaResponse, clientIp, secret);
if( !isValid )
   this.ModelState.AddModelError("captcha", "The reCAPTCHA is not valid.");
   return new BadRequestResult();
   //continue processing, everything is okay!

That's it! Happy verifying! 🎉


  • Download the source code.
  • Run build.cmd.

Upon successful build, the results will be in the \__compile directory. If you want to build NuGet packages, run build.cmd pack and the NuGet packages will be in __package.