.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Lemonldap::NG::Portal::UserDB 3pm"
.TH Lemonldap::NG::Portal::UserDB 3pm 2024-02-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Lemonldap:NG::Portal::UserDB \- Writing authentication modules for LemonLDAP::NG.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  package Lemonldap::NG::Portal::UserDB::My;
\&  
\&  use strict;
\&  use Mouse;
\&  # Add constants used by this module
\&  use Lemonldap::NG::Portal::Main::Constants qw(PE_OK);
\&  
\&  our $VERSION = \*(Aq0.1\*(Aq;
\&  
\&  extends \*(AqLemonldap::NG::Common::Module\*(Aq;
\&
\&  sub init {
\&      ...
\&  }
\&  
\&  sub getUser {
\&      my ( $self, $req, %args ) = @_;
\&      ...
\&  }
\&  
\&  sub setSessionInfo {
\&      my ( $self, $req ) = @_;
\&      ...
\&  }
\&  
\&  sub setGroups {
\&      my ( $self, $req ) = @_;
\&      ...
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
UserDB modules are used to search a user in user database. UserDB modules are
independent objects that are instantiated by Lemonldap::NG portal. They must
provide methods described below.
.SH METHODS
.IX Header "METHODS"
.SS "Accessors and methods provided by Lemonldap::NG::Common::Module"
.IX Subsection "Accessors and methods provided by Lemonldap::NG::Common::Module"
.IP "p: portal object" 4
.IX Item "p: portal object"
.PD 0
.IP "conf: configuration hash (as reference)" 4
.IX Item "conf: configuration hash (as reference)"
.IP "logger alias for p\->logger accessor" 4
.IX Item "logger alias for p->logger accessor"
.IP "userLogger alias for p\->userLogger accessor" 4
.IX Item "userLogger alias for p->userLogger accessor"
.IP "error: alias for p\->error method" 4
.IX Item "error: alias for p->error method"
.PD
.PP
\fI"Routes" management\fR
.IX Subsection """Routes"" management"
.PP
Like any module that inherits from Lemonldap::NG::Portal::Plugin,
Lemonldap::NG::Portal::Main::Auth provides URI path functions:
.IP "addAuthRoute: wrapper to Lemonldap::NG::Handler::PSGI::Try \fBaddAuthRoute()\fR method" 4
.IX Item "addAuthRoute: wrapper to Lemonldap::NG::Handler::PSGI::Try addAuthRoute() method"
.PD 0
.IP "addUnauthRoute: wrapper to Lemonldap::NG::Handler::PSGI::Try \fBaddUnauthRoute()\fR method" 4
.IX Item "addUnauthRoute: wrapper to Lemonldap::NG::Handler::PSGI::Try addUnauthRoute() method"
.PD
.PP
Example:
.PP
.Vb 11
\&  sub init {
\&      ...
\&      $self\->addAuthRoute( saml => { proxy => "proxySub" }, [ \*(AqGET\*(Aq, \*(AqPOST\*(Aq ] );
\&      ...
\&  }
\&  sub proxySub {
\&      my ( $self, $req ) = @_;
\&      ...
\&      # This sub must return a PSGI response. Example
\&      return [ 302, [ Location => \*(Aqhttp://x.y/\*(Aq ], [] ];
\&  }
.Ve
.PP
This means that requests http://auth.../saml/proxy will be given to \fBproxySub()\fR
method.
.SS "Methods that must be provided by a UserDB module"
.IX Subsection "Methods that must be provided by a UserDB module"
\fR\f(BIinit()\fR\fI\fR
.IX Subsection "init()"
.PP
Method launched after object creation (after each configuration reload). It
must return a true value if authentication module is ready, false else.
.PP
\fIMethods called at each request\fR
.IX Subsection "Methods called at each request"
.PP
All these methods must return a Lemonldap::NG::Portal::Main::Constants value.
They are called with one argument: a Lemonldap::NG::Portal::Main::Request
object.
.PP
Note: if you want to change \fBprocess()\fR next steps, you just have to change
\&\f(CW$req\fR\->steps array.
.PP
getUser($req,%args)
.IX Subsection "getUser($req,%args)"
.PP
First method called to search user in database. If \f(CW$args\fR{useMail} is set then
\&\f(CW$req\fR\->{user} contains a mail address.
.PP
setSessionInfo($req)
.IX Subsection "setSessionInfo($req)"
.PP
This method is called after authentication process. It must populate
\&\f(CW$req\fR\->sessionInfo.
.PP
setGroups($req)
.IX Subsection "setGroups($req)"
.PP
This method populates \f(CW$req\fR\->{sessionInfo}\->{groups} if backend is able to
provide groups \fI(Like LDAP)\fR. Else, it juste return PE_OK.
.SH LOGGING
.IX Header "LOGGING"
Logging is provided by \f(CW$self\fR\->logger and \f(CW$self\fR\->userLogger. The following rules
must be applied:
.IP "logger\->debug: technical debugging messages" 4
.IX Item "logger->debug: technical debugging messages"
.PD 0
.IP "logger\->info: simple technical information" 4
.IX Item "logger->info: simple technical information"
.IP "logger\->notice: technical information that could interest administrators" 4
.IX Item "logger->notice: technical information that could interest administrators"
.IP "logger\->warn: technical warning" 4
.IX Item "logger->warn: technical warning"
.IP "logger\->error: error that must be reported to administrator" 4
.IX Item "logger->error: error that must be reported to administrator"
.IP "userLogger\->info: simple information about user's action" 4
.IX Item "userLogger->info: simple information about user's action"
.IP "userLogger\->notice: information that may be registered (auth success,...)" 4
.IX Item "userLogger->notice: information that may be registered (auth success,...)"
.IP "userLogger\->warn: bad action of a user (auth failure). Auth/Combination transform it to ""info"" when another authentication scheme is available" 4
.IX Item "userLogger->warn: bad action of a user (auth failure). Auth/Combination transform it to ""info"" when another authentication scheme is available"
.IP "userLogger\->error: bad action of a user that must be reported, (even if another backend is available with Combination)" 4
.IX Item "userLogger->error: bad action of a user that must be reported, (even if another backend is available with Combination)"
.PD
.SH AUTHORS
.IX Header "AUTHORS"
.IP "LemonLDAP::NG team <http://lemonldap\-ng.org/team>" 4
.IX Item "LemonLDAP::NG team <http://lemonldap-ng.org/team>"
.SH "BUG REPORT"
.IX Header "BUG REPORT"
Use OW2 system to report bug or ask for features:
<https://gitlab.ow2.org/lemonldap\-ng/lemonldap\-ng/issues>
.SH DOWNLOAD
.IX Header "DOWNLOAD"
Lemonldap::NG is available at
<https://lemonldap\-ng.org/download>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
See COPYING file for details.
.PP
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.
.PP
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.
.PP
You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.