Enhance Security in Laravel with Google reCAPTCHA V3

Google reCAPTCHA V3 is a powerful tool to protect your website from spam and abuse without interrupting user experience. Unlike reCAPTCHA V2, which requires user interaction (like clicking a checkbox), reCAPTCHA V3 works invisibly in the background, assigning a score to each request based on user behavior. This makes it ideal for forms, login pages, and other sensitive areas of your application.

In this blog post, I’ll show you how to integrate Google reCAPTCHA V3 into your Laravel application using the josiasmontag/laravel-recaptchav3 package. This lightweight package focuses on backend validation, making it easy to secure your forms and endpoints.

Why Use Google reCAPTCHA V3?

• Invisible Protection: No user interaction is required, ensuring a smooth experience.

• Behavioral Analysis: Assigns a score to each request based on user activity.

• Customizable Actions: Define specific actions (e.g., login, register) to monitor.

• Easy Integration: Simple setup and configuration with Laravel.

Step 1: Install the Package

To get started, install the josiasmontag/laravel-recaptchav3 package via Composer:

composer require josiasmontag/laravel-recaptchav3

Step 2: Configure reCAPTCHA V3

1. Add reCAPTCHA Keys:
   Obtain your reCAPTCHA V3 site key and secret key from the Google reCAPTCHA Admin Console. Add them to your .env file:

   RECAPTCHAV3_SITEKEY=your-site-key
   RECAPTCHAV3_SECRET=your-secret-key

2. Publish the Config File (Optional):
   If you want to customize the package configuration, publish the config file:

php artisan vendor:publish --provider="Lunaweb\RecaptchaV3\Providers\RecaptchaV3ServiceProvider"

This will create a recaptchav3.php file in the config directory.

Step 3: Initialize reCAPTCHA JavaScript

reCAPTCHA V3 works best when it’s loaded on every page to gather context about user interactions. Add the following code to your header or footer template:

{!! RecaptchaV3::initJs() !!}

This script initializes reCAPTCHA V3 and generates tokens for your forms.

Step 4: Add reCAPTCHA to Forms

Use the RecaptchaV3::field() method to add an invisible reCAPTCHA field to your forms. This field will automatically be populated with a reCAPTCHA token.

<form method="post" action="/contact-us">
    {!! RecaptchaV3::field('contact') !!}
    <input type="submit" value="contact">
</form>

Here, register is the action name, which you can customize based on the form’s purpose.

Step 5: Validate reCAPTCHA Responses

To validate the reCAPTCHA token, add the recaptchav3 rule to your validation logic. The rule accepts two parameters: the action name and the minimum required score (default is 0.5).

use Illuminate\Support\Facades\Validator;

$validate = Validator::make($request->all(), [
    'g-recaptcha-response' => 'required|recaptchav3:register,0.5'
]);

If the score is below the threshold, the validation will fail.

Step 6: Handle Scores Programmatically

You can also verify the reCAPTCHA score manually and take custom actions based on the result. For example:

use Lunaweb\RecaptchaV3\Facades\RecaptchaV3;

$score = RecaptchaV3::verify($request->get('g-recaptcha-response'), 'register');

if ($score > 0.7) {
    // High score: Likely a human
} elseif ($score > 0.3) {
    // Medium score: Require additional verification
} else {
    // Low score: Likely a bot
    return abort(400, 'You are most likely a bot');
}

Step 7: Customize Validation Messages

To provide a custom error message for reCAPTCHA validation failures, add the following to your validation.php language file:

'custom' => [
    'g-recaptcha-response' => [
        'recaptchav3' => 'Captcha error message',
    ],
],

Step 8: Hide the reCAPTCHA Badge

By default, reCAPTCHA V3 displays a badge on your site. To hide it, add the following CSS:

.grecaptcha-badge { visibility: hidden !important; }

Step 9: Localization

The package follows the default application locale defined in config/app.php. To override this, specify a locale in your .env file:

RECAPTCHAV3_LOCALE=ar

Step 10: Testing

To make your forms testable, you can mock the RecaptchaV3 facade in your tests:

RecaptchaV3::shouldReceive('verify')
    ->once()
    ->andReturn(1.0);

This ensures your tests don’t rely on external reCAPTCHA validation.

Conclusion

By integrating Google reCAPTCHA V3 into your Laravel application, you can significantly enhance security and protect your forms from spam and abuse. The josiasmontag/laravel-recaptchav3 package makes it easy to implement and validate reCAPTCHA tokens, ensuring a seamless experience for your users.

Give it a try in your next project, and let me know how it works for you! 🚀