Google reCAPTCHA

The Google reCAPTCHA module integrates Google's reCAPTCHA service into the application, providing an additional layer of security to prevent spam and abuse.

Overview

This module protects your application forms from automated bots and spam submissions by implementing Google's reCAPTCHA verification. It supports both reCAPTCHA v2 (checkbox and invisible) and reCAPTCHA v3 (score-based) to provide flexible security options for different use cases.

Features

• reCAPTCHA v2 Checkbox: Traditional "I'm not a robot" checkbox verification
• reCAPTCHA v2 Invisible: Background verification without user interaction
• reCAPTCHA v3 Score-Based: Advanced bot detection with risk scoring
• Form Protection: Protect login, registration, contact, and custom forms
• Bot Prevention: Block automated submissions and credential stuffing attacks
• Configurable Thresholds: Set custom score thresholds for v3 verification
• Bypass for Trusted Users: Option to skip verification for logged-in users

Requirements

• Open Core Business Suite (Base System)
• Google reCAPTCHA API keys (Site Key and Secret Key)
• No additional module dependencies

Installation

1. Enable the module in your module configuration:

// config/modules.php or via admin panel
'GoogleRecaptcha' => true,

2. Run the module migrations:

php artisan module:migrate GoogleRecaptcha

3. Publish the module configuration:

php artisan module:publish GoogleRecaptcha

Configuration

Obtaining API Keys

1. Visit the Google reCAPTCHA Admin Console
2. Click + to create a new site
3. Enter a label for your site
4. Select reCAPTCHA type (v2 or v3)
5. Add your domain(s)
6. Accept the terms of service
7. Copy the Site Key and Secret Key

Module Settings

Access reCAPTCHA settings through Settings > Google reCAPTCHA:

Setting	Description	Default
Enable reCAPTCHA	Enable/disable reCAPTCHA protection	Disabled
Site Key	Your Google reCAPTCHA site key	-
Secret Key	Your Google reCAPTCHA secret key	-
reCAPTCHA Version	v2 Checkbox, v2 Invisible, or v3	v2 Checkbox
Score Threshold (v3)	Minimum score to pass (0.0-1.0)	0.5
Protected Forms	Select forms to protect	Login, Register

Environment Variables

You can also configure reCAPTCHA via environment variables:

RECAPTCHA_ENABLED=true
RECAPTCHA_SITE_KEY=your_site_key_here
RECAPTCHA_SECRET_KEY=your_secret_key_here
RECAPTCHA_VERSION=v2  # v2, v2_invisible, or v3
RECAPTCHA_SCORE_THRESHOLD=0.5

Usage

Protected Forms

By default, reCAPTCHA can protect:

• Login Form: Prevent brute force attacks
• Registration Form: Block spam account creation
• Password Reset: Protect password reset requests
• Contact Forms: Prevent spam submissions
• Custom Forms: Any form you designate

Adding reCAPTCHA to Custom Forms

Blade Template (v2 Checkbox)

<form method="POST" action="/your-endpoint">
    @csrf

    <!-- Your form fields -->

    @if(config('recaptcha.enabled'))
        <div class="g-recaptcha" data-sitekey="{{ config('recaptcha.site_key') }}"></div>
        @error('g-recaptcha-response')
            <span class="error">{{ $message }}</span>
        @enderror
    @endif

    <button type="submit">Submit</button>
</form>

@push('scripts')
    <script src="https://www.google.com/recaptcha/api.js" async defer></script>
@endpush

Blade Template (v3)

<form method="POST" action="/your-endpoint" id="myForm">
    @csrf
    <input type="hidden" name="g-recaptcha-response" id="recaptchaResponse">

    <!-- Your form fields -->

    <button type="submit">Submit</button>
</form>

@push('scripts')
    <script src="https://www.google.com/recaptcha/api.js?render={{ config('recaptcha.site_key') }}"></script>
    <script>
        document.getElementById('myForm').addEventListener('submit', function(e) {
            e.preventDefault();
            grecaptcha.ready(function() {
                grecaptcha.execute('{{ config('recaptcha.site_key') }}', {action: 'submit'})
                    .then(function(token) {
                        document.getElementById('recaptchaResponse').value = token;
                        e.target.submit();
                    });
            });
        });
    </script>
@endpush

Server-Side Validation

Using Form Request

use Modules\GoogleRecaptcha\Rules\RecaptchaRule;

public function rules(): array
{
    return [
        'email' => 'required|email',
        'password' => 'required',
        'g-recaptcha-response' => ['required', new RecaptchaRule()],
    ];
}

Inline Validation

use Modules\GoogleRecaptcha\Services\RecaptchaService;

public function store(Request $request, RecaptchaService $recaptcha)
{
    if (!$recaptcha->verify($request->input('g-recaptcha-response'))) {
        return back()->withErrors(['captcha' => 'reCAPTCHA verification failed']);
    }

    // Process form...
}

API Integration

For API endpoints, include the reCAPTCHA token in your request:

POST /api/V1/contact
Content-Type: application/json

{
    "name": "John Doe",
    "email": "[email protected]",
    "message": "Hello!",
    "recaptcha_token": "03AGdBq24..."
}

reCAPTCHA Version Comparison

Feature	v2 Checkbox	v2 Invisible	v3
User Interaction	Click checkbox	None (automatic)	None (automatic)
Challenge	May show image challenge	May show image challenge	No challenge
Score	Pass/Fail	Pass/Fail	0.0 - 1.0
Best For	High-security forms	Streamlined UX	Continuous protection

Best Practices

1. Choose Appropriate Version: Use v3 for seamless UX, v2 for high-risk forms
2. Set Reasonable Thresholds: Start with 0.5 for v3 and adjust based on results
3. Monitor Scores: Review v3 scores to fine-tune threshold
4. Fallback Options: Provide alternative verification for accessibility
5. Test Thoroughly: Verify reCAPTCHA works in all browsers

Troubleshooting

reCAPTCHA Not Displaying

• Verify Site Key is correct
• Check domain is registered in Google Console
• Ensure JavaScript is enabled and loading

Verification Always Failing

• Verify Secret Key is correct
• Check server can reach Google's API
• Review score threshold for v3 (may be too high)

localhost Development

• Register localhost in Google Console
• Use test keys provided by Google for development:
  • Site Key: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
  • Secret Key: 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

Score Too Low (v3)

• Ensure user behavior appears human
• Check for VPN/proxy usage
• Review page load and form submission patterns