Document new Captcha API (#2692)
This commit is contained in:
Maxime Besson
parent
b4d0082e5c
commit
67ebefd137
|
|
@ -31,3 +31,18 @@ Go in ``General parameters`` > ``Portal`` > ``Captcha``:
|
|||
- **Activation in register form**: set to 1 to display captcha in
|
||||
register form
|
||||
- **Size**: length of captcha
|
||||
- **Captcha module**: allows you to use a custom Captcha module, see
|
||||
:ref:`below <customcaptcha>`. Leave it blank to use the default Captcha
|
||||
implementation
|
||||
- **Captcha module options**: options for the custom Captcha module
|
||||
|
||||
.. _customcaptcha:
|
||||
|
||||
Custom Captcha modules
|
||||
----------------------
|
||||
|
||||
.. versionadded:: 2.0.15
|
||||
|
||||
If the default Captcha does not meet your requirements, you can replace it with
|
||||
a different implementation. See the ``Lemonldap::NG::Portal::Captcha`` manual
|
||||
page for details on how to implement a Captcha module.
|
||||
|
|
|
|||
|
|
@ -26,6 +26,26 @@ Known regressions in the latest released version
|
|||
|
||||
None
|
||||
|
||||
2.0.15
|
||||
------
|
||||
|
||||
New Captcha API
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
It is now possible to create your own Captcha modules to replace the one provided by default.
|
||||
|
||||
In order for custom Captcha modules to work, you need to modify your custom ``standardform.tpl``, ``mail.tpl`` and ``register.tpl`` template files:
|
||||
|
||||
.. code:: diff
|
||||
|
||||
- <TMPL_IF NAME=CAPTCHA_SRC>
|
||||
- <TMPL_INCLUDE NAME="captcha.tpl">
|
||||
+ <TMPL_IF NAME=CAPTCHA_HTML>
|
||||
+ <TMPL_VAR NAME=CAPTCHA_HTML>
|
||||
</TMPL_IF>
|
||||
|
||||
If you are using the default templates from the ``bootstrap`` theme, you don't need to change anything.
|
||||
|
||||
2.0.14
|
||||
------
|
||||
|
||||
|
|
|
|||
|
|
@ -48,6 +48,7 @@ lib/Lemonldap/NG/Portal/Auth/Slave.pm
|
|||
lib/Lemonldap/NG/Portal/Auth/SSL.pm
|
||||
lib/Lemonldap/NG/Portal/Auth/Twitter.pm
|
||||
lib/Lemonldap/NG/Portal/Auth/WebID.pm
|
||||
lib/Lemonldap/NG/Portal/Captcha.pod
|
||||
lib/Lemonldap/NG/Portal/Captcha/SecurityImage.pm
|
||||
lib/Lemonldap/NG/Portal/CDC.pm
|
||||
lib/Lemonldap/NG/Portal/CertificateResetByMail/Custom.pm
|
||||
|
|
|
|||
|
|
@ -0,0 +1,153 @@
|
|||
=pod
|
||||
|
||||
=encoding utf8
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Lemonldap:NG::Portal::Captcha - Writing CAPTCHA modules for LemonLDAP::NG.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
package Lemonldap::NG::Portal::Captcha::My;
|
||||
|
||||
use strict;
|
||||
use Mouse;
|
||||
# Add constants used by this module
|
||||
|
||||
our $VERSION = '0.1';
|
||||
|
||||
extends 'Lemonldap::NG::Portal::Main::Plugin';
|
||||
|
||||
sub init {
|
||||
my $self = shift;
|
||||
return 1;
|
||||
}
|
||||
|
||||
sub init_captcha {
|
||||
my ( $self, $req ) = @_;
|
||||
|
||||
# Read option from the manager configuration
|
||||
my $option = $self->conf->{captchaOptions}->{option1};
|
||||
|
||||
# This can be used to inject custom JS code at the beginning
|
||||
# of the page
|
||||
my $script = <your html code>;
|
||||
$req->data->{customScript} .= $script;
|
||||
|
||||
# This will add your custom HTML code to the protected form
|
||||
my $html = <your html code>;
|
||||
$req->captchaHtml($html);
|
||||
}
|
||||
|
||||
sub check_captcha {
|
||||
my ( $self, $req ) = @_;
|
||||
|
||||
my $captcha_input = $req->param('some_post_param');
|
||||
my $is_captcha_valid = <your code here>;
|
||||
|
||||
if($is_captcha_valid) {
|
||||
return 1;
|
||||
} else {
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
1;
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Captcha modules only need to implement two methods: one for initializing the
|
||||
challenge, before the form is displayed, and the other to verify that the
|
||||
submitted response is correct.
|
||||
|
||||
=head1 METHODS
|
||||
|
||||
=head2 Accessors and methods provided by Lemonldap::NG::Portal::Main::Plugin
|
||||
|
||||
=over
|
||||
|
||||
=item p: portal object
|
||||
|
||||
=item conf: configuration hash (as reference)
|
||||
|
||||
=item logger alias for p->logger accessor
|
||||
|
||||
=item userLogger alias for p->userLogger accessor
|
||||
|
||||
=item error: alias for p->error method
|
||||
|
||||
=back
|
||||
|
||||
=head2 "Routes" management
|
||||
|
||||
Like each module that inherits from Lemonldap::NG::Portal::Plugin,
|
||||
you can define dedicated routes in a Captcha plugin.
|
||||
|
||||
=over
|
||||
|
||||
=item addAuthRoute: wrapper to L<Lemonldap::NG::Handler::PSGI::Try>
|
||||
addAuthRoute() method
|
||||
|
||||
=item addUnauthRoute: wrapper to L<Lemonldap::NG::Handler::PSGI::Try>
|
||||
addUnauthRoute() method
|
||||
|
||||
=back
|
||||
|
||||
=head2 Methods that must be provided by a Captcha module
|
||||
|
||||
=head3 init_captcha($req)
|
||||
|
||||
This method is called when the protected form is built by LemonLDAP::NG.
|
||||
Your responsibility is to do any preparatory step, and provide LemonLDAP::NG
|
||||
with the HTML code that it has to display in the form to enable the Captcha.
|
||||
|
||||
This is done by setting C<$req-E<gt>captchaHtml>
|
||||
|
||||
=head3 check_captcha($req)
|
||||
|
||||
This method is called after the user submitted the protected form. Your
|
||||
responibility is to check the user's response (usually provided as a POST
|
||||
field), and return 0 if the response is incorrect, 1 if the response is
|
||||
correct.
|
||||
|
||||
=head1 LOGGING
|
||||
|
||||
Logging is provided by C<$self-E<gt>logger> and C<$self-E<gt>userLogger>. See
|
||||
L<Lemonldap::NG::Portal::Main::Plugin> for a detailed description of logging levels.
|
||||
|
||||
=head1 AUTHORS
|
||||
|
||||
=over
|
||||
|
||||
=item LemonLDAP::NG team L<http://lemonldap-ng.org/team>
|
||||
|
||||
=back
|
||||
|
||||
=head1 BUG REPORT
|
||||
|
||||
Use OW2 system to report bug or ask for features:
|
||||
L<https://gitlab.ow2.org/lemonldap-ng/lemonldap-ng/issues>
|
||||
|
||||
=head1 DOWNLOAD
|
||||
|
||||
Lemonldap::NG is available at
|
||||
L<https://lemonldap-ng.org/download>
|
||||
|
||||
=head1 COPYRIGHT AND LICENSE
|
||||
|
||||
See COPYING file for details.
|
||||
|
||||
This library is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 2, or (at your option)
|
||||
any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program. If not, see L<http://www.gnu.org/licenses/>.
|
||||
|
||||
=cut
|
||||
Loading…
Reference in New Issue