https://github.com/pet-toys/cloudflare-turnstile-net
Cloudflare Turnstile for ASPNET.
https://github.com/pet-toys/cloudflare-turnstile-net
captcha cloudflare turnstile
Last synced: 3 months ago
JSON representation
Cloudflare Turnstile for ASPNET.
- Host: GitHub
- URL: https://github.com/pet-toys/cloudflare-turnstile-net
- Owner: pet-toys
- License: apache-2.0
- Created: 2024-04-15T17:35:52.000Z (over 1 year ago)
- Default Branch: dev
- Last Pushed: 2025-05-11T06:51:40.000Z (5 months ago)
- Last Synced: 2025-06-15T15:54:14.493Z (4 months ago)
- Topics: captcha, cloudflare, turnstile
- Language: C#
- Homepage:
- Size: 70.3 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
# Cloudflare Turnstile for NET
[![Unit Test][test-badge]][test-url] [![NuGet Version][nuget-v-badge]][nuget-url] [![NuGet Downloads][nuget-dt-badge]][nuget-url]
Based on the following [project](https://github.com/michaelvs97/AspNetCore.ReCaptcha)
Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html).
## Requirements
You must have a CloudFlare account. Create a Turnstile widget for your form or site. You will need the SiteKey and SecretKey.
## Installation
You can install this package using NuGet.
```powershell
# Package Manager
PM> Install-Package PetToys.CloudflareTurnstileNet
# .NET CLI
dotnet add package PetToys.CloudflareTurnstileNet
```
## Configuration
Create a new configuration section like this in your appsettings.json and update the SiteKey and SecretKey values from CloudFlare.
```json
{
"CloudflareTurnstileOptions": {
"SiteKey": "Site key from your CloudFlare dashboard",
"SecretKey": "Secret key from your CloudFlare dashboard",
"Enabled": true
},
}
```
## Usage
To use PetToys.CloudflareTurnstileNet in your project, you must add the CloudflareTurnstileNet services to the service container like so:
```c#
builder.Services.AddCloudflareTurnstile(builder.Configuration.GetSection("CloudflareTurnstileOptions"));
```
## Clientside Code
The cloudflare turnstile javascript must be added as well as the turnstile div. In automatic mode the `asp-validation-summary` is also required to show the validation error.
An example razor page:
```razor
@page
@namespace MyApp.Pages
@using Microsoft.Extensions.Options
@using PetToys.CloudflareTurnstileNet
@inject IOptions turnstileOptions
@model ContactModel
@if (turnstileOptions.Value.Enabled)
{
}
Contact Us
@if (turnstileOptions.Value.Enabled)
{
}
```
## Automatic Validation
Automatic verification can be applied by adding an attribute to your page model or controller. Here is a razor page example that uses `FormErrorMessage` to set a custom error message:
```c#
using PetToys.CloudflareTurnstileNet;
[ValidateCloudflareTurnstile(FormErrorMessage = "Cloudflare Turnstile verification failed")]
public class ContactModel : PageModel
{
```
For an MVC controller apply the attribute to the action method:
```c#
[HttpPost]
[ValidateCloudflareTurnstile(FormErrorMessage = "Cloudflare Turnstile verification failed")]
public IActionResult Submit(ContactViewModel model)
{
if (!ModelState.IsValid)
{
return View("Index");
}
```
In the handler method `ModelState.IsValid` must be checked as the attribute will add a model error if validation fails. An example:
```c#
public IActionResult OnPost()
{
if (!ModelState.IsValid)
{
// Turnstile verification or other verification failed
return Page();
}
// Turnstile verification succeeded...
}
```
## Manual Validation
If you want to manually validate the Turnstile token inject `ITurnstileService` and `IOptions`.
Example:
```c#
private readonly ITurnstileService _turnstileService;
private readonly IOptions _turnstileOptions;
public ContactModel(ITurnstileService turnstileService, IOptions turnstileOptions)
{
_turnstileService = turnstileService;
_turnstileOptions = turnstileOptions;
}
```
In your page handler, get the turnstile token from the form then call the turnstile service method `VerifyAsync` to verify the token with CloudFlare. If the returned value is `true` then the user passed validation.
```c#
public async Task OnPostAsync([FromForm(Name = "cf-turnstile-response")] string turnstileToken)
{
bool turnstileSuccess = true;
if (_turnstileOptions.Value.Enabled)
{
turnstileSuccess = await _turnstileService.VerifyAsync(turnstileToken);
}
// other custom validation
```
[nuget-v-badge]: https://img.shields.io/nuget/v/PetToys.CloudflareTurnstileNet?style=flat-square&logo=nuget&label=version
[nuget-dt-badge]: https://img.shields.io/nuget/dt/PetToys.CloudflareTurnstileNet?style=flat-square&logo=nuget
[nuget-url]: https://www.nuget.org/packages/PetToys.CloudflareTurnstileNet/
[test-badge]: https://img.shields.io/github/actions/workflow/status/pet-toys/cloudflare-turnstile-net/test.yml?branch=dev&style=flat-square&logo=github&label=test
[test-url]: https://github.com/pet-toys/cloudflare-turnstile-net/actions?query=workflow%3Atest+branch%3Adev