reCAPTCHA Validator

reCAPTCHA Validator makes it easy to include Google's reCAPTCHA v2 (Checkbox) in ASP.NET pages.

Installation

Component	Package
JereckNET.Web.ReCaptcha

Install reCAPTCHA Validator by searching for reCAPTCHA in Visual Studio's Package Manager or by using the Package Manager Console :

PM > Install-Package JereckNET.Web.ReCaptcha

User Guide

Register for Google reCAPTCHA

To start using reCAPTCHA, you need to sign up for an API key pair for your site. The key pair consists of a site key and secret key. The site key is used to invoke reCAPTCHA service on your site. The secret key authorizes communication between your application backend and the reCAPTCHA server to verify the user's response. The secret key needs to be kept safe for security purposes.

This library is currently compatible only with the reCAPTCHA v2 Checkbox mode.

For more information, please refer to Google's reCAPTCHA website.

Use in your ASP.NET project

In the ASPX front-end

From the Designer toolbox, drop the ReCaptchaValidator control on your designer surface, or add the following code to your ASPX header markup :

<%@ Register Assembly="JereckNET.Web.ReCaptcha" Namespace="JereckNET.Web.UI" TagPrefix="jcw" %>

and this control wherever you want your reCAPTCHA to be located :

<jcw:ReCaptchaValidator ID="captchaValidator" runat="server" 
    SecretKey="your_secret_key" 
    SiteKey="your_site_key" />

In your code back-end

The ReCaptchaValidator control implements theIValidator interface. To check the validity of the user's response, a simple call to Page.IsValid will trigger the check with the reCAPTCHA's API :

protected void Button1_Click(object sender, EventArgs e) {
    if (Page.IsValid) {
        /* ... */
    }
}

Public properties

The ReCaptchaValidator class derives from WebControl and has the following additional public properties :

Property	Description
Callback	The name of your client-side callback function, executed when the user submits a successful response. The g-recaptcha-response token is passed to your callback.
ErrorCallback	The name of your client-side callback function, executed when reCAPTCHA encounters an error.
Errors¹	The errors returned from reCAPTCHA's API as a RecaptchaErrors enum.
ExpiredCallback	The name of your client-side callback function, executed when the reCAPTCHA response expires and the user needs to re-verify.
LoadedCallback	The name of your client-side callback function, executed when the reCAPTCHA control is created.
PrefersColorSchemeAware	Instruct the control to select the theme to use based on the client's browser preference. If the browser is not compatible with the prefers-color-scheme media query, or is configured with no-preference, the theme configured with the Theme property is used. Defaults to true.
SecretKey	The secret key as configured in reCAPTCHA Administration Console. Defaults to your_secret_key (and will not work as is).
SiteKey	The site key as configured in reCAPTCHA Administration Console. Defaults to your_site_key (and will not work as is).
Size	The size of the widget. Defaults to Normal
TestMode²	This enables the reCAPTCHA validation to pass without check (for test purposes only). Defaults to false
Theme	The color theme of the widget. Defaults to Light

¹ The enumeration returned is decorated with the [Flags] attribute and can contain multiple values.

² The test mode is designed to be used for automatic testing (which, by itself is contrary the the very principle of CAPTCHA validation). The verification requests will always pass.
This uses a special set of SiteKey/SecretKey provided by Google, and displays a warning message to ensure it's not used for production traffic.

RecaptchaErrors enum values

• MissingInputSecret : The secret parameter is missing.
• InvalidInputSecret : The secret parameter is invalid or malformed.
• MissingInputResponse : The response parameter is missing.
• InvalidInputResponse : The response parameter is invalid or malformed.
• BadRequest : The request is invalid or malformed.
• TimeoutOrDuplicate : The response is no longer valid: either is too old or has been used previously.
• UnknownError : Self-explanatory

License

reCAPTCHA Validator is licensed under the MIT License - the details are at LICENSE.txt