You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A Google reCPATCHA validation wrapper service for ASP.NET Core. With only a few simple setup steps you are ready to block bots from filling in and submitting forms on your website.
1
+
# ASP.NET Core reCAPTCHA
2
+
A Google reCAPTCHA validation wrapper service for ASP.NET Core. In only a few simple steps, you are ready to block bots from filling in and submitting forms on your website with reCAPTCHA.
3
3
4
-
This package also supports reCAPTCHA V3, but at the moment does not provide any frontend tag helpers for that. So only backend validation is supported at the moment.
4
+
The package 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.
The first thing you need to do is to sign up for a new API key-pair for your project. You can follow [Google's guide](https://developers.google.com/recaptcha/intro#overview), if you haven't done that yet.
20
+
### Prequisites
21
+
You will need an API key pair which can be acquired by [signing up here](http://www.google.com/recaptcha/admin). For assistance or other questions regarding that topic, refer to [Google's guide](https://developers.google.com/recaptcha/intro#overview).
21
22
22
-
After sign-up you should now have a **Site key** and a **Secret key**. Make note of those, you will need them for the next step.
23
+
After sign-up, you should have a **Site key** and a **Secret key**. You will need those to configure the service in your app.
23
24
24
25
### Configuration
25
26
27
+
#### Settings
28
+
26
29
Open your `appsettings.json` and add the following lines:
27
30
28
31
```json
@@ -31,41 +34,57 @@ Open your `appsettings.json` and add the following lines:
31
34
"SecretKey": "<Your secret key goes here>"
32
35
}
33
36
```
37
+
**Important:** The `SiteKey` will be exposed to the public, so make sure you don't accidentally swap it with the `SecretKey`.
34
38
35
-
Make sure to place your site & secret key in the right spot. You risk to expose your secret key to the public if you switch it with the site key.
39
+
#### Service Registration
36
40
37
-
For more inforamtion about ASP.NET Core configuration check out the [Microsoft docs](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1).
41
+
Register this service by calling the `AddRecaptchaService()` method which is an extension method of `IServiceCollection`. For example:
38
42
39
-
In your `Startup.cs` you now need to add the service. Add the following line `services.AddRecaptchaService();` into the `ConfigureServices(IServiceCollection services)` method, like this for excample.
First you will need to import the tag helpers. Open your `_ViewImports.cshtml` file and add the following lines:
62
+
First, import the tag helpers. Open your `_ViewImports.cshtml` file and add the following lines:
55
63
56
64
```razor
57
65
@using Griesoft.AspNetCore.ReCaptcha
58
-
59
66
@addTagHelper *, Griesoft.AspNetCore.ReCaptcha
60
67
```
61
68
62
-
Now you are ready to use the tag helpers in your views. Always add the `<recaptcha-script>`tag on the bottom of your view. This will render the script tag which will load the reCAPTCHA.js API.
69
+
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.
63
70
64
-
Next you only need to add a `<recaptcha>` tag in your form and you are all set. This is the most simplest way of adding reCAPTCHA to your views. Now you only need to add backend validation to the controller of your view.
71
+
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.
Add a using statement to `Griesoft.AspNetCore.ReCaptcha` in your controller. Next you just need to the `[ValidateRecaptcha]` attribute to the action which is triggered by your form.
85
+
Validation is done by decorating your controller or action with `[ValidateRecaptcha]`.
// Will hit the next line only if validation was successfull
100
+
// Will hit the next line only if validation was successful
87
101
returnView("FormSubmitSuccessView");
88
102
}
89
103
}
90
104
}
91
105
```
106
+
Now each incoming request to that action will be validated for a valid reCAPTCHA token.
107
+
108
+
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.
In case you are validating a reCAPTCHA V3 token, make sure you also add an action name to your validator.
126
+
127
+
For example:
128
+
129
+
```csharp
130
+
[ValidateRecaptcha(Action="submit")]
131
+
publicIActionResultFormSubmit(SomeModelmodel)
132
+
{
133
+
returnView("FormSubmitSuccessView");
134
+
}
135
+
```
136
+
137
+
## Options & Customization
92
138
93
-
Now if validation would fail, the action method would never get called.
139
+
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.
94
140
95
-
You can configure that behaviour and a lot of other stuff globally at startup or even just seperatly for each controller or action.
141
+
All options from the [official reCAPTCHA docs](https://developers.google.com/recaptcha/intro) are available to you in this package.
96
142
97
-
### Addition information
143
+
## Detailed Documentation
144
+
Is on it's way...
98
145
99
-
For more detailed usage guides check out the wiki. You can find guides about additional configuration options, response validation behaviour, explicit rendering of tags, invisible reCAPTCHA elements and the usage of reCAPTCHA V3.
146
+
## Contributing
147
+
Contributing is heavily encouraged. :muscle: 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. 😄
0 commit comments