Dodanie skutecznej ochrony przed automatycznymi atakami botów na formularze to jeden z kluczowych elementów zwiększania bezpieczeństwo aplikacji webowych. Jednym z najpopularniejszych rozwiązań jest reCAPTCHA od Google, który w prosty sposób pozwala odróżnić prawdziwego użytkownika od zautomatyzowanego skryptu. Poniższy artykuł omawia krok po kroku proces implementacja tej technologii, obejmując rejestrację, konfigurację na frontendie oraz weryfikację po stronie backendu, a także praktyczne wskazówki dotyczące API i dalszej rozbudowy.
Podstawy działania reCAPTCHA v2 i v3
Usługa reCAPTCHA udostępnia dwa główne warianty: tradycyjną wersję v2, w której użytkownik klika pole „Nie jestem robotem” lub rozwiązuje zadania graficzne, oraz nowszą v3, opartą na analizie zachowania, która działa w tle, przyznając każdemu żądaniu ocenę ryzyka. Wybór odpowiedniej wersji zależy od poziomu wygody użytkownika i stopnia zabezpieczenia, którego potrzebujemy:
- reCAPTCHA v2 – wyświetlanie widgetu, wymaganie interakcji, większa widoczność mechanizmu, idealna dla formularzy o podwyższonym ryzyku.
- reCAPTCHA v3 – brak bezpośredniej interakcji, oceny w skali 0.0–1.0, możliwość analizowania zgłoszeń i blokowania podejrzanych aktywności.
Zarówno wersja v2, jak i v3 korzysta z tego samego API oraz wymaga uzyskania pary kluczy: Site Key i Secret Key.
Rejestracja i pobranie kluczy
Aby uzyskać dostęp do usługi, należy zarejestrować domenę w panelu administracyjnym Google:
- Wejdź na stronę rejestracji reCAPTCHA: https://www.google.com/recaptcha/admin
- Zaloguj się na konto Google, na którym chcesz zarządzać kluczami.
- Dodaj nową witrynę, określając nazwę, typ reCAPTCHA (v2 lub v3) i domeny, na których będzie działać.
- Otrzymasz dwa ciągi znaków: klucz publiczny (Site Key) oraz Secret Key, służący do weryfikacji po stronie serwera.
Warto zaimportować obie wartości do pliku konfiguracyjnego aplikacji lub przechowywać w zmiennych środowiskowych, aby nie wyciekły do repozytorium kodu.
Integracja po stronie frontend
Na warstwie klienta musimy załadować bibliotekę reCAPTCHA i wstawić widget w odpowiednie miejsce:
1. W sekcji nagłówka dokumentu dołącz skrypt:
<script src=”https://www.google.com/recaptcha/api.js” async defer></script>
2. W kodzie HTML formularza umieść kontener widgetu:
<div class=”g-recaptcha” data-sitekey=”TWÓJ_SITE_KEY”></div>
Konfiguracja widgetu
Możesz dodatkowo dopasować widget za pomocą parametrów:
- data-theme – motyw (light lub dark).
- data-size – wielkość (normal lub compact).
- data-badge – pozycjonowanie badge (bottomright, bottomleft, inline; w reCAPTCHA v3).
Obsługa tokena
Po poprawnym przejściu weryfikacji skrypt generuje token, który trafia do pola input:
<input type=”hidden” name=”g-recaptcha-response” value=”GENEROWANY_TOKEN”>
Następnie ten token musi być przekazany razem z pozostałymi danymi formularza do Twojego serwera.
Weryfikacja po stronie backend
Klient przesyła token w parametrze g-recaptcha-response. Twoja aplikacja powinna wykonać żądanie HTTP POST do endpointu Google:
- URL: https://www.google.com/recaptcha/api/siteverify
- Parametry:
- secret = TWÓJ_SECRET_KEY
- response = token_otrzymany_z_frontendu
- remoteip = opcjonalnie adres IP klienta
Przykładowe wywołanie w PHP można zaimplementować tak:
$response = file_get_contents(’https://www.google.com/recaptcha/api/siteverify?secret=’.SECRET_KEY.’&response=’.$_POST[’g-recaptcha-response’]);
$data = json_decode($response, true);
if ($data[’success’] === true) {
// walidacja zakończona sukcesem
} else {
// odrzuć formularz, podejrzane żądanie
}
W Node.js z użyciem fetch może to wyglądać następująco:
const res = await fetch(’https://www.google.com/recaptcha/api/siteverify’, { method: 'POST’,
headers: { 'Content-Type’: 'application/x-www-form-urlencoded’ },
body: `secret=${SECRET_KEY}&response=${token}`
});
const json = await res.json();
Zwróć uwagę na właściwą obsługę sytuacji błędnych i logowanie odpowiedzi, zwłaszcza gdy reCAPTCHA zwraca błąd spowodowany nieprawidłowym tokenem lub przekroczeniem limitów.
Dodatkowe wskazówki i częste problemy
Wdrożenie reCAPTCHA zazwyczaj przebiega sprawnie, ale warto pamiętać o kilku aspektach:
- Aktualizuj bibliotekę – choć kod reCAPTCHA ładuje się z zewnętrznego serwera, dokumentacja i zalecenia Google mogą się zmieniać.
- Zadbaj o czytelne komunikaty – w razie odrzucenia żądania poinformuj użytkownika o konieczności ponownej weryfikacji.
- Monitoruj statystyki – w panelu Google reCAPTCHA sprawdzisz liczbę zgłoszeń i współczynnik odrzuceń.
- Ochrona przed FRM bruteforce – w połączeniu z limitem prób logowania i blokadą IP zwiększysz poziom zabezpieczeń.
- Wersja mobilna – widget automatycznie dostosowuje się do rozmiaru ekranu, ale warto przetestować wygląd.
Dbając o poprawne zaimplementowanie reCAPTCHA, minimalizujesz ryzyko ataków automatycznych, jednocześnie zachowując komfort użytkowników. Dzięki prostemu połączeniu frontendu z odpowiednią logiką po stronie backendu oraz stałej walidacja tokenów możesz skutecznie chronić swoje formularze przed nadużyciami.
