Commit 0f25bfc2 authored by Maxime Besson's avatar Maxime Besson
Browse files

Document new Captcha API (#2692)

parent a941428e
Pipeline #21057 passed with stage
in 16 minutes and 15 seconds
......@@ -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
......
=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>. The following rules
must be applied:
=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
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment