Griesoft.AspNetCore.ReCaptcha 2.3.0

dotnet add package Griesoft.AspNetCore.ReCaptcha --version 2.3.0
NuGet\Install-Package Griesoft.AspNetCore.ReCaptcha -Version 2.3.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Griesoft.AspNetCore.ReCaptcha" Version="2.3.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Griesoft.AspNetCore.ReCaptcha --version 2.3.0
#r "nuget: Griesoft.AspNetCore.ReCaptcha, 2.3.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Griesoft.AspNetCore.ReCaptcha as a Cake Addin
#addin nuget:?package=Griesoft.AspNetCore.ReCaptcha&version=2.3.0

// Install Griesoft.AspNetCore.ReCaptcha as a Cake Tool
#tool nuget:?package=Griesoft.AspNetCore.ReCaptcha&version=2.3.0

ASP.NET Core reCAPTCHA

A Google reCAPTCHA service for ASP.NET Core. Keep bots away from submitting forms or other actions in just a few steps.

The service supports V2 and V3 and comes with tag helpers that make it easy to add challenges to your forms. Also, backend validation is made easy and requires only the use of an attribute in your controllers or actions that should get validated.

Build Status Build Status License NuGet GitHub Release

Installation

Install via NuGet using:

PM> Install-Package Griesoft.AspNetCore.ReCaptcha

Quickstart

Prequisites

You will need an API key pair which can be acquired by signing up here. For assistance or other questions regarding that topic, refer to Google's guide.

After sign-up, you should have a Site key and a Secret key. You will need those to configure the service in your app.

Configuration

Settings

Open your appsettings.json and add the following lines:

"RecaptchaSettings": {
    "SiteKey": "<Your site key goes here>",
    "SecretKey": "<Your secret key goes here>"
}

Important: The SiteKey will be exposed to the public, so make sure you don't accidentally swap it with the SecretKey.

Service Registration

Register this service by calling the AddRecaptchaService() method which is an extension method of IServiceCollection. For example:

.NET 6
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRecaptchaService();
Prior to .NET 6
public void ConfigureServices(IServiceCollection services)
{
    services.AddRecaptchaService();
}

Adding a reCAPTCHA element to your view

First, import the tag helpers. Open your _ViewImports.cshtml file and add the following lines:

@using Griesoft.AspNetCore.ReCaptcha
@addTagHelper *, Griesoft.AspNetCore.ReCaptcha

Next, you need to add the <recaptcha-script> to every view you intend to use the reCAPTCHA. That will render the API script. Preferably you would add this somewhere close to the bottom of your body element.

Now you may add a reCAPTCHA challenge to your view where ever you need it. Using the <recaptcha /> tag in your form will render a reCAPTCHA V2 checkbox inside it.

For invisible reCAPTCHA use:

<button re-invisible form-id="yourFormId">Submit</button>

For reCAPTCHA V3 use:

<recaptcha-v3 form-id="yourFormId" action="submit">Submit</recaptcha-v3>

Adding backend validation to an action

Validation is done by decorating your controller or action with [ValidateRecaptcha].

For example:

using Griesoft.AspNetCore.ReCaptcha;
using Microsoft.AspNetCore.Mvc;

namespace ReCaptcha.Sample.Controllers
{
    public class ExampleController : Controller
    {
        [ValidateRecaptcha]
        public IActionResult FormSubmit(SomeModel model)
        {
            // Will hit the next line only if validation was successful
            return View("FormSubmitSuccessView");
        }
    }
}

Now each incoming request to that action will be validated for a valid reCAPTCHA token.

The default behavior for invalid tokens is a 404 (BadRequest) response. But this behavior is configurable, and you may also instead request the validation result as an argument to your action.

This can be achieved like this:

[ValidateRecaptcha(ValidationFailedAction = ValidationFailedAction.ContinueRequest)]
public IActionResult FormSubmit(SomeModel model, ValidationResponse recaptchaResponse)
{
    if (!recaptchaResponse.Success)
    {
        return BadRequest();
    }

    return View("FormSubmitSuccessView");
}

In case you are validating a reCAPTCHA V3 token, make sure you also add an action name to your validator.

For example:

[ValidateRecaptcha(Action = "submit")]
public IActionResult FormSubmit(SomeModel model)
{
    return View("FormSubmitSuccessView");
}

Options & Customization

There are global defaults that you may modify on your application startup. Also, the appearance and position of V2 tags may be modified. Either globally or each tag individually.

All options from the official reCAPTCHA docs are available to you in this package.

Proxy Server

If your environment requires to use forward proxy server, this can be done by specifying two additional parameters in the configuration file

"RecaptchaSettings": {
    "UseProxy": true,
    "ProxyAddress": "http://10.1.2.3:80"
}

The address should contain port and protocol, as required by the System.Net.WebProxy class.

Detailed Documentation

Is on it's way...

Contributing

Contributing is heavily encouraged. 💪 The best way of doing so is by first starting a discussion about new features or improvements you would like to make. Or, in case of a bug, report it first by creating a new issue. From there, you may volunteer to fix it if you like. 😄

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Framework net462 is compatible.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Griesoft.AspNetCore.ReCaptcha:

Package Downloads
Griesoft.OrchardCore.ReCaptcha

A Google reCAPTCHA Orchard Core module based on the Griesoft.AspNetCore.Griesoft package. Supports reCAPTCHA V2 and V3.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.3.0 635 1/23/2024
2.2.0 11,595 9/25/2022
2.1.2 383 9/25/2022
2.1.1 1,309 8/14/2022
2.1.0 511 8/14/2022
2.0.7 1,159 5/2/2022
2.0.6 687 5/1/2022
2.0.1 504 4/23/2022
2.0.0 498 4/22/2022
1.0.0 2,796 2/29/2020