A plugin for Payload to protect collection's operations using Google reCAPTCHA v3.
Please install the plugin version according to the Payload version. The major version of the plugin must match the major version of the Payload.
yarn add payload-recaptcha-v3
# OR
npm i payload-recaptcha-v3
In the plugins
array of your Payload config, call the plugin with options:
import { buildConfig } from 'payload/config';
import reCAPTCHAv3 from 'payload-recaptcha-v3';
const config = buildConfig({
// ... rest of your config
plugins: [
reCAPTCHAv3({
secret: process.env.GOOGLE_RECAPTCHA_SECRET,
}),
],
});
export default config;
-
secret
: stringRequired. Your Google reCAPTCHA v3 secret key.
-
errorHandler
: reCAPTCHAErrorHandlerOptional. The function that throws the exception. By default, it throws Forbidden when the response from Google is not a success.
To protect a collection's operation, you have to add in the Collection Config the property recaptcha
into the custom
.
The recaptcha
property has to be an array of strings containing the operation name according to Available Collection operations.
import { CollectionConfig } from 'payload/types';
export const Orders: CollectionConfig = {
slug: 'orders',
fields: [],
// ... rest of your config
custom: {
recaptcha: [
{
name: 'create',
action: 'submit',
},
{
name: 'update',
action: 'modify',
},
],
},
};
export default Orders;
Then, when you make an HTTP Request to the Payload API, include the header X-reCAPTCHA-V3
with the token received from Google:
<script>
function onClick(e) {
e.preventDefault();
grecaptcha.ready(function() {
grecaptcha.execute('reCAPTCHA_site_key', {action: 'submit'}).then(function(token) {
fetch('/api/orders', {
method: 'POST',
headers: {
'X-reCAPTCHA-V3': token
},
body: JSON.stringify({...})
})
});
});
}
</script>
Tests are using Jest, to run the tests use:
npm test
A function that has the purpose of throwing an exception depending on the response received from Google.
type reCAPTCHAErrorHandler = (response?: reCAPTCHAResponse) => void;
The response received from Google when verifying the token.
Properties
Name | Description |
---|---|
success: boolean | whether this request was a valid reCAPTCHA token for your site |
score: number | the score for this request (0.0 - 1.0) |
action: string | the action name for this request (important to verify) |
challenge_ts: number | timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ) |
hostname: string | the hostname of the site where the reCAPTCHA was solved |
'error-codes'?: reCAPTCHAErrorCode[] | optional |
Error code | Description |
---|---|
missing-input-secret | The secret parameter is missing. |
invalid-input-secret | The secret parameter is invalid or malformed. |
missing-input-response | The response parameter is missing. |
invalid-input-response | The response parameter is invalid or malformed. |
bad-request | The request is invalid or malformed. |
timeout-or-duplicate | The response is no longer valid: either is too old or has been used previously. |
invalid-keys | Unknown |