.\" -*- 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::Main::Plugin 3pm" .TH Lemonldap::NG::Portal::Main::Plugin 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::Main::Plugin \- Base class for Lemonldap::NG::Portal modules (plugins, authentication modules,...). .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 3 \& package Lemonldap::NG::Portal::My::Plugin; \& use Mouse; \& extends \*(AqLemonldap::NG::Portal::Main::Plugin\*(Aq; \& \& use constant beforeAuth => \*(AqverifyIP\*(Aq; \& \& sub init { \& my ($self) = @_; \& $self\->addUnauthRoute( mypath => \*(Aqhello\*(Aq, [ \*(AqGET\*(Aq, \*(AqPUT\*(Aq ] ); \& $self\->addAuthRoute( mypath => \*(Aqwelcome\*(Aq, [ \*(AqGET\*(Aq, \*(AqPUT\*(Aq ] ); \& return 1; \& } \& sub verifyIP { \& my ($self, $req) = @_; \& return PE_ERROR if($req\->address !~ /^10/); \& return PE_OK; \& } \& sub hello { \& my ($self, $req) = @_; \& ... \& return $self\->p\->sendJSONresponse($req, { hello => 1 }); \& } \& sub welcome { \& my ($self, $req) = @_; \& ... \& return $self\->p\->sendHtml($req, \*(Aqtemplate\*(Aq, params => { WELCOME => 1 }); \& } .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Lemonldap::NG::Portal::Main::Plugin provides many methods to easily write Lemonldap::NG addons. .PP \&\fBinit()\fR is called for each plugin. If a plugin initialization fails (\fBinit()\fR returns 0), the portal responds a 500 status code for each request. .SH "Writing plugins" .IX Header "Writing plugins" Custom plugins can be inserted in portal by declaring them in \&\f(CW\*(C`lemonldap\-ng.ini\*(C'\fR file, section \f(CW\*(C`[portal]\*(C'\fR, key \f(CW\*(C`customPlugins\*(C'\fR: .PP .Vb 2 \& [portal] \& customPlugins = ::My::Plugin1, ::My::Plugin2 .Ve .PP Plugins must be valid packages well found in \f(CW@INC\fR. .SS "Plugin entry points" .IX Subsection "Plugin entry points" \fIEntry point based on PATH_INFO\fR .IX Subsection "Entry point based on PATH_INFO" .PP Plugins can declare unauthRoutes/authRoutes during initialization (= /path/info). Methods declared in this way must be declared in the plugin class. They will be called with \f(CW$req\fR argument. \f(CW$req\fR is the HTTP request. (See Lemonldap::NG::Portal::Main::Request). These methods must return a valid PSGI response. You can also use \fBsendJSONresponse()\fR or \fBsendHtml()\fR methods (see Lemonldap::NG::Common::PSGI). .PP Example: .PP .Vb 10 \& sub init { \& my ($self) = @_; \& $self\->addUnauthRoute( mypath => \*(Aqhello\*(Aq, [ \*(AqGET\*(Aq, \*(AqPUT\*(Aq ] ); \& $self\->addAuthRoute( mypath => \*(Aqwelcome\*(Aq, [ \*(AqGET\*(Aq, \*(AqPUT\*(Aq ] ); \& return 1; \& } \& sub hello { \& my ($self, $req) = @_; \& ... \& return $self\->p\->sendJSONresponse($req, { hello => 1 }); \& } \& sub welcome { \& my ($self, $req) = @_; \& ... \& return $self\->p\->sendHtml($req, \*(Aqtemplate\*(Aq, params => { WELLCOME => 1 }); \& } .Ve .PP If you want to get a "protected application" behavior, you can use \&\fBaddAuthRouteWithRedirect\fR. This methods calls \fBaddAuthRoute\fR with given arguments and build a "unAuth" route that build a redirection after authentication. .PP \fIEntry point in auth process\fR .IX Subsection "Entry point in auth process" .PP A plugin which wants to be inserted in authentication process has to declare constants set with method name to run. Following entry points are available. .ie n .IP """beforeAuth"": method called before authentication process" 4 .el .IP "\f(CWbeforeAuth\fR: method called before authentication process" 4 .IX Item "beforeAuth: method called before authentication process" .PD 0 .ie n .IP """betweenAuthAndData"": method called after authentication and before setting ""sessionInfo"" provisionning" 4 .el .IP "\f(CWbetweenAuthAndData\fR: method called after authentication and before setting \f(CWsessionInfo\fR provisionning" 4 .IX Item "betweenAuthAndData: method called after authentication and before setting sessionInfo provisionning" .ie n .IP """afterData"": method called after ""sessionInfo"" provisionning \fI(macros, groups,...)\fR. This entry point is called after 'storeHistory' if login process fails and before 'validSession' if succeeds." 4 .el .IP "\f(CWafterData\fR: method called after \f(CWsessionInfo\fR provisionning \fI(macros, groups,...)\fR. This entry point is called after 'storeHistory' if login process fails and before 'validSession' if succeeds." 4 .IX Item "afterData: method called after sessionInfo provisionning (macros, groups,...). This entry point is called after 'storeHistory' if login process fails and before 'validSession' if succeeds." .ie n .IP """endAuth"": method called when session is validated (after cookie build)" 4 .el .IP "\f(CWendAuth\fR: method called when session is validated (after cookie build)" 4 .IX Item "endAuth: method called when session is validated (after cookie build)" .ie n .IP """authCancel"": method called when user click on ""cancel"" during auth process" 4 .el .IP "\f(CWauthCancel\fR: method called when user click on ""cancel"" during auth process" 4 .IX Item "authCancel: method called when user click on ""cancel"" during auth process" .ie n .IP """forAuthUser"": method called for already authenticated users" 4 .el .IP "\f(CWforAuthUser\fR: method called for already authenticated users" 4 .IX Item "forAuthUser: method called for already authenticated users" .ie n .IP """beforeLogout"": method called before logout" 4 .el .IP "\f(CWbeforeLogout\fR: method called before logout" 4 .IX Item "beforeLogout: method called before logout" .PD .PP \&\fBNote\fR: methods inserted so must return a PE_* constant. See Lemonldap::NG::Portal::Main::Constants. .PP Advanced entry points .IX Subsection "Advanced entry points" .PP These entry points are not stored in \f(CW\*(C`$req\->step\*(C'\fR but launched on the fly: .ie n .IP """afterSub"": hash ref that give methods to call after given main method is called. Example:" 4 .el .IP "\f(CWafterSub\fR: hash ref that give methods to call after given main method is called. Example:" 4 .IX Item "afterSub: hash ref that give methods to call after given main method is called. Example:" .Vb 8 \& use constant afterSub => { \& getUser => \*(Aqmysub\*(Aq, \& } \& sub mysub { \& my ( $self ,$req ) = @_; \& # Do something \& return PE_OK; \& } .Ve .ie n .IP """aroundSub"": hash ref that give methods to call instead of given main method. Example:" 4 .el .IP "\f(CWaroundSub\fR: hash ref that give methods to call instead of given main method. Example:" 4 .IX Item "aroundSub: hash ref that give methods to call instead of given main method. Example:" .Vb 10 \& use constant aroundSub => { \& getUser => \*(Aqmysub\*(Aq, \& }; \& sub mysub { \& my ( $self, $sub, $req ) = @_; \& # Do something before \& my $ret = $sub\->($req); \& # Do something after \& return $ret; \& } .Ve .Sp Do not launch "getUser" but use the given \f(CW$sub\fR. This permits multiple plugins to use "aroundSub" in the same time. .ie n .IP """hook"": hash ref that gives methods to call when a hook is triggered in the LemonLDAP::NG code. Example:" 4 .el .IP "\f(CWhook\fR: hash ref that gives methods to call when a hook is triggered in the LemonLDAP::NG code. Example:" 4 .IX Item "hook: hash ref that gives methods to call when a hook is triggered in the LemonLDAP::NG code. Example:" .Vb 3 \& use constant hook => { \& oidcGenerateIDToken => \*(AqaddClaimToIDToken\*(Aq \& }; \& \& sub addClaimToIDToken { \& my ( $self, $req, $payload, $rp ) = @_; \& $payload\->{"id_token_hook"} = 1; \& return PE_OK; \& } .Ve .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 "SEE ALSO" .IX Header "SEE ALSO" .SS "OTHER POD FILES" .IX Subsection "OTHER POD FILES" .IP "Writing an authentication module: Lemonldap::NG::Portal::Auth" 4 .IX Item "Writing an authentication module: Lemonldap::NG::Portal::Auth" .PD 0 .IP "Writing a UserDB module: Lemonldap::NG::Portal::UserDB" 4 .IX Item "Writing a UserDB module: Lemonldap::NG::Portal::UserDB" .IP "Writing a second factor module: Lemonldap::NG::Portal::Main::SecondFactor" 4 .IX Item "Writing a second factor module: Lemonldap::NG::Portal::Main::SecondFactor" .IP "Writing an issuer module: Lemonldap::NG::Portal::Main::Issuer" 4 .IX Item "Writing an issuer module: Lemonldap::NG::Portal::Main::Issuer" .IP "Writing another plugin: Lemonldap::NG::Portal::Main::Plugin" 4 .IX Item "Writing another plugin: Lemonldap::NG::Portal::Main::Plugin" .IP "Request object: Lemonldap::NG::Portal::Main::Request" 4 .IX Item "Request object: Lemonldap::NG::Portal::Main::Request" .IP "Adding parameters in the manager: Lemonldap::NG::Manager::Build" 4 .IX Item "Adding parameters in the manager: Lemonldap::NG::Manager::Build" .PD .SH AUTHORS .IX Header "AUTHORS" .IP "LemonLDAP::NG team " 4 .IX Item "LemonLDAP::NG team " .SH "BUG REPORT" .IX Header "BUG REPORT" Use OW2 system to report bug or ask for features: .SH DOWNLOAD .IX Header "DOWNLOAD" Lemonldap::NG is available at .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 .