diff --git a/doc/sources/admin/captcha.rst b/doc/sources/admin/captcha.rst index 849e3bedd..deeeea7da 100644 --- a/doc/sources/admin/captcha.rst +++ b/doc/sources/admin/captcha.rst @@ -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 `. 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. diff --git a/doc/sources/admin/upgrade_2_0_x.rst b/doc/sources/admin/upgrade_2_0_x.rst index 1c8ecb3de..8aafad2e4 100644 --- a/doc/sources/admin/upgrade_2_0_x.rst +++ b/doc/sources/admin/upgrade_2_0_x.rst @@ -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 + + - + - + + + + + + +If you are using the default templates from the ``bootstrap`` theme, you don't need to change anything. + 2.0.14 ------ diff --git a/lemonldap-ng-portal/MANIFEST b/lemonldap-ng-portal/MANIFEST index 9f00afd89..b98e66b0c 100644 --- a/lemonldap-ng-portal/MANIFEST +++ b/lemonldap-ng-portal/MANIFEST @@ -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 diff --git a/lemonldap-ng-portal/lib/Lemonldap/NG/Portal/Captcha.pod b/lemonldap-ng-portal/lib/Lemonldap/NG/Portal/Captcha.pod new file mode 100644 index 000000000..f239e7c93 --- /dev/null +++ b/lemonldap-ng-portal/lib/Lemonldap/NG/Portal/Captcha.pod @@ -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 = ; + $req->data->{customScript} .= $script; + + # This will add your custom HTML code to the protected form + my $html = ; + $req->captchaHtml($html); + } + + sub check_captcha { + my ( $self, $req ) = @_; + + my $captcha_input = $req->param('some_post_param'); + my $is_captcha_valid = ; + + 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 +addAuthRoute() method + +=item addUnauthRoute: wrapper to L +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-EcaptchaHtml> + +=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-Elogger> and C<$self-EuserLogger>. See +L for a detailed description of logging levels. + +=head1 AUTHORS + +=over + +=item LemonLDAP::NG team L + +=back + +=head1 BUG REPORT + +Use OW2 system to report bug or ask for features: +L + +=head1 DOWNLOAD + +Lemonldap::NG is available at +L + +=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. + +=cut