NAME
Mojolicious::Plugin::ReCAPTCHAv2 - use Googles "No CAPTCHA reCAPCTHA" (reCAPTCHA v2) service in Mojolicious apps
VERSION
version 1.06
SYNOPSIS
use Mojolicious::Plugin::ReCAPTCHAv2;
sub startup {
my $app = shift;
$app->plugin('ReCAPTCHAv2', {
sitekey => 'site-key-embedded-in-public-html', # required
secret => 'key-used-in-internal-verification-requests', # required
# api_timeout => 10, # optional
# api_url => 'https://www.google.com/recaptcha/api/siteverify', # optional
# size => 'normal', # optional
# tabindex => 0, # optional
# theme => 'light', # optional
# type => 'image', # optional
});
}
# later
# assembling website:
$c->stash( captcha => $app->recaptcha_get_html );
# now use stashed value in your HTML template, i.e.: <form..>...<% $captcha %>...</form>
# on incoming request
# synchronous
my ( $captcha_verified, $err ) = $c->recaptcha_verify;
if ( $captcha_verified ) {
# success: probably human
...
}
else {
# fail: probably bot, but may also be a processing error
if ( @{$err} ) {
# processing failed, inspect error codes
foreach my $e ( @{$err} ) {
...
}
}
else {
# bot
...
}
}
# asynchronous
Mojo::IOLoop->delay(
sub {
my $delay = shift;
$c->recaptcha_verify( $delay->begin(0) );
},
sub {
my ( $delay, $captcha_verified, $err ) = @_;
if ( $captcha_verified ) {
# success: probably human
...
}
else {
# fail: probably bot, but may also be a processing error
if ( @{$err} ) {
# processing failed, inspect error codes
foreach my $e ( @{$err} ) {
...
}
}
else {
# bot
...
}
}
}
)->wait;DESCRIPTION
Mojolicious::Plugin::ReCAPTCHAv2 allows you to protect your site against automated interaction by (potentially malicious) robots.
This is accomplished by injecting a extra javascript widget in your forms that requires human interaction. The interaction is evaluated on a server (via AJAX) and a dynamic parameter is injected in your form. When your users submit your form to your server you receive that parameter and can verify it by sending it to the captcha servers in the background. You should then stop further processing of the request you received if the captcha did not validate.
Please note that this module currently does not support some advanced usage models for the captcha like explicit rendering and AJAX callbacks. Therefore a few options listed in the official Google docs are not listed above. If you would like to see support for this kind of functionality, please get in touch with the author / maintainer of this module.
For a general overview of what a Captcha is and how the Google "No Captcha" reCaptcha (v2) service works, please refer to the official documentation.
OPTIONS
The following params can be provided to the plugin on registration:
sitekeysecretapi_timeoutapi_urlsizetabindexthemetype
sitekey and secret are required parameters, while all others are optional. The default values for the optional configuration params are shown in the synopsis.
For the meaning of these please refer to https://developers.google.com/recaptcha/docs/display#config.
METHODS
Mojolicious::Plugin::ReCAPTCHAv2 inherits all methods from Mojolicious::Plugin and implements no extra ones.
HELPERS
Mojolicious::Plugin::ReCAPTCHAv2 makes the following helpers available:
recaptcha_get_html
Returns a HTML fragment with the widget code; you will probably want to put this in the stash, since it has to be inserted in your HTML form element when processing the template.
recaptcha_verify( [ $callback ] )
Call this helper when receiving the request from your website after the user submitted the form. Sends your secret, the response token from the request your received and the users IP to the reCAPTCHA server to verify the token.
You should call this only once per incoming request.
It will return two values: a success indicator and a (usually empty) array reference with error codes.
The status indicator will be either a true or false value:
false(0)-
The reCAPTCHA service could not verify that the Captcha was solved by a human; either because it was a bot or because of some processing error.
You should check the second return value for processing errors. If there are none, the captcha was not solved correctly, probably indicating a bot.
In either case you should not continue processing the request but probably re-display the form with an approriate error message.
true(1)-
The data is valid and the reCAPTCHA service believes that the challenge was solved by a human. You may proceed with processing the incoming request.
The second return value may contain zero, one or more error codes. Possible values are listed below under "ERRORS".
ASYNC WITH PROMISES
You can also verify the reCAPTCHA non-blocking by using recaptcha_verify_p. This will only work on a Mojolicious version that includes Mojo::Promise promises, so v7.53 and newer.
recaptcha_verify_p
# on incoming request
sub form_handler {
my $c = shift;
$c->recaptcha_verify_p->then(
sub { # success, probably human
...
$c->render('success');
}
)->catch(
sub { # fail ...
my @errors = @{ @_[0] };
if (@errors) { # there was a processing error ...
$c->reply->exception(join "\n", @errors);
}
else { # it's probably a bot ...
$c->render(text => 'no bots allowed', status => 403);
}
}
)->wait;
}This helper returns a Mojo::Promise that will resolve if the reCAPTCHA service believes that the challenge was solved by a human, and it will reject if there was a failure. The failure can be caused either by an error or because the service believes the challenge was attempted by a bot.
In case of errors, those will be passed through the rejection. See "ERRORS" below for more details.
ERRORS
The following official API error codes can be returned by reCAPTCHA:
missing-input-secret-
The secret parameter is missing.
This should not happen, since registering the plugin requires a
secretconfiguration param which is then automatically included in the verification request. invalid-input-secret-
The secret parameter is invalid or malformed.
Please check your registration data and configuration!
missing-input-response-
The response parameter is missing.
Please check if the HTML code for the widget was included at the correct position in your template. Please check the request parameters that were transferred to your server after the user submitted your form.
invalid-input-response-
The response parameter is invalid or malformed.
Somebody tinkered with the request data somewhere.
Additionally the following error codes may be encountered which are defined internally by this module. Note: these codes start with "x-" to distinguish them from official error codes.
x-http-communication-failed-
Something went wrong while trying to talk to the reCAPTCHA server.
x-unparseable-data-received-
The http request was completed successfully but Mojo::JSON could not decode the response received from the reCAPTCHA server.
SEE ALSO
AUTHOR
Heiko Jansen <hjansen@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2020 by Heiko Jansen <hjansen@cpan.org>.
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007