Document new Captcha API (#2692)
This commit is contained in:
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
|
- **Activation in register form**: set to 1 to display captcha in
|
||||||
register form
|
register form
|
||||||
- **Size**: length of captcha
|
- **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
|
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
|
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/SSL.pm
|
||||||
lib/Lemonldap/NG/Portal/Auth/Twitter.pm
|
lib/Lemonldap/NG/Portal/Auth/Twitter.pm
|
||||||
lib/Lemonldap/NG/Portal/Auth/WebID.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/Captcha/SecurityImage.pm
|
||||||
lib/Lemonldap/NG/Portal/CDC.pm
|
lib/Lemonldap/NG/Portal/CDC.pm
|
||||||
lib/Lemonldap/NG/Portal/CertificateResetByMail/Custom.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