=pod

=encoding utf8

=head1 NAME

Lemonldap:NG::Portal::Password - Writing password modification modules for LemonLDAP::NG.

=head1 SYNOPSIS

    package Lemonldap::NG::Portal::Password::My;

    use strict;
    use Mouse;

    # Add constants used by this module
    use Lemonldap::NG::Portal::Main::Constants qw(PE_OK);

    our $VERSION = '0.1';

    extends 'Lemonldap::NG::Portal::Password::Base';

    sub init {
        my ($self) = @_;
        ...
    }

    sub confirm {
        my ( $self, $req, $old_password ) = @_;
        ...
    }

    sub modifyPassword {
        my ( $self, $req, $new_password, %args ) = @_;
        ...
    }

  

=head1 DESCRIPTION

Password modules are used to modify the user's password in regular password
change operations or password reset operations. Password modules are
independent objects that are instantiated by Lemonldap::NG portal. They must
provide methods described below.

=head1 METHODS

=head2 Accessors and methods provided by Lemonldap::NG::Common::Module

=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

=back

=head2 Methods that must be provided by a Password module

=head3 init()

Method launched after object creation (after each configuration reload). It
must return a true value if initialization was successful.

=head3 Methods called on demand

All these methods must return a Lemonldap::NG::Portal::Main::Constants value.
They are called with one argument: a L<Lemonldap::NG::Portal::Main::Request>
object.

=head4 confirm($req, $old_password)

This method is called to validate that the supplied old password is correct.
This is slightly different from authentication in the sense that an expired old
password cannot be used to login but can be used to set a new password.

=head4 modifyPassword($req, $new_password, %args)

This method is called to perform the actual password change.

Possible args:

=over

=item passwordReset: set in the case of a password reset (old password is not known)
=item useMail: set if $req->user contains the user's email

=back

=head1 LOGGING

Logging is provided by $self->logger and $self->userLogger. The following rules
must be applied:

=over

=item logger->debug: technical debugging messages

=item logger->info: simple technical information

=item logger->notice: technical information that could interest administrators

=item logger->warn: technical warning

=item logger->error: error that must be reported to administrator

=item userLogger->info: simple information about user's action

=item userLogger->notice: information that may be registered (auth success,...)

=item userLogger->warn: bad action of a user (auth failure). Auth/Combination
transform it to "info" when another authentication scheme is available

=item userLogger->error: bad action of a user that must be reported, (even if
another backend is available with Combination)

=back

=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
