Lemonldap::NG::Portal::Main::Plugin(3pm)

1Lemonldap::NG::Portal::UMsaeirn:C:oPnlturgiibnu(t3e)d PeLrelmoDnolcduampe:n:tNaGt:i:oPnortal::Main::Plugin(3)
2
3
4

NAME

6       Lemonldap::NG::Portal::Main::Plugin - Base class for
7       Lemonldap::NG::Portal modules (plugins, authentication modules,...).
8

SYNOPSIS

10         package Lemonldap::NG::Portal::My::Plugin;
11         use Mouse;
12         extends 'Lemonldap::NG::Portal::Main::Plugin';
13
14         use constant beforeAuth => 'verifyIP';
15
16         sub init {
17             my ($self) = @_;
18             $self->addUnauthRoute( mypath => 'hello', [ 'GET', 'PUT' ] );
19             $self->addAuthRoute( mypath => 'welcome', [ 'GET', 'PUT' ] );
20             return 1;
21         }
22         sub verifyIP {
23             my ($self, $req) = @_;
24             return PE_ERROR if($req->address !~ /^10/);
25             return PE_OK;
26         }
27         sub hello {
28             my ($self, $req) = @_;
29             ...
30             return $self->p->sendJSONresponse($req, { hello => 1 });
31         }
32         sub welcome {
33             my ($self, $req) = @_;
34             ...
35             return $self->p->sendHtml($req, 'template', params => { WELCOME => 1 });
36         }
37

DESCRIPTION

39       Lemonldap::NG::Portal::Main::Plugin provides many methods to easily
40       write Lemonldap::NG addons.
41
42       init() is called for each plugin. If a plugin initialization fails
43       (init() returns 0), the portal responds a 500 status code for each
44       request.
45

Writing plugins

47       Custom plugins can be inserted in portal by declaring them in
48       "lemonldap-ng.ini" file, section "[portal]", key "customPlugins":
49
50         [portal]
51         customPlugins = ::My::Plugin1, ::My::Plugin2
52
53       Plugins must be valid packages well found in @INC.
54
55   Plugin entry points
56       Entry point based on PATH_INFO
57
58       Plugins can declare unauthRoutes/authRoutes during initialization (=
59       /path/info). Methods declared in this way must be declared in the
60       plugin class.  They will be called with $req argument. $req is the HTTP
61       request.  (See Lemonldap::NG::Portal::Main::Request). These methods
62       must return a valid PSGI response. You can also use sendJSONresponse()
63       or sendHtml() methods (see Lemonldap::NG::Common::PSGI).
64
65       Example:
66
67         sub init {
68             my ($self) = @_;
69             $self->addUnauthRoute( mypath => 'hello', [ 'GET', 'PUT' ] );
70             $self->addAuthRoute( mypath => 'welcome', [ 'GET', 'PUT' ] );
71             return 1;
72         }
73         sub hello {
74             my ($self, $req) = @_;
75             ...
76             return $self->p->sendJSONresponse($req, { hello => 1 });
77         }
78         sub welcome {
79             my ($self, $req) = @_;
80             ...
81             return $self->p->sendHtml($req, 'template', params => { WELLCOME => 1 });
82         }
83
84       If you want to get a "protected application" behavior, you can use
85       addAuthRouteWithRedirect. This methods calls addAuthRoute with given
86       arguments and build a "unAuth" route that build a redirection after
87       authentication.
88
89       Entry point in auth process
90
91       A plugin which wants to be inserted in authentication process has to
92       declare constants set with method name to run. Following entry points
93       are available.
94
95       "beforeAuth": method called before authentication process
96       "betweenAuthAndData": method called after authentication and before
97       setting "sessionInfo" provisionning
98       "afterData": method called after "sessionInfo" provisionning (macros,
99       groups,...). This entry point is called after 'storeHistory' if login
100       process fails and before 'validSession' if succeeds.
101       "endAuth": method called when session is validated (after cookie build)
102       "authCancel": method called when user click on "cancel" during auth
103       process
104       "forAuthUser": method called for already authenticated users
105       "beforeLogout": method called before logout
106
107       Note: methods inserted so must return a PE_* constant. See
108       Lemonldap::NG::Portal::Main::Constants.
109
110       Advanced entry points
111
112       These entry points are not stored in "$req->step" but launched on the
113       fly:
114
115       "afterSub": hash ref that give methods to call after given main method
116       is called. Example:
117             use constant afterSub => {
118                 getUser => 'mysub',
119             }
120             sub mysub {
121                 my ( $self ,$req ) = @_;
122                 # Do something
123                 return PE_OK;
124             }
125
126       "aroundSub": hash ref that give methods to call instead of given main
127       method. Example:
128             use constant aroundSub => {
129                 getUser => 'mysub',
130             };
131             sub mysub {
132                 my ( $self, $sub, $req ) = @_;
133                 # Do something before
134                 my $ret = $sub->($req);
135                 # Do something after
136                 return $ret;
137             }
138
139           Do not launch "getUser" but use the given $sub. This permits
140           multiple plugins to use "aroundSub" in the same time.
141
142       "hook": hash ref that gives methods to call when a hook is triggered in
143       the LemonLDAP::NG code. Example:
144             use constant hook => {
145                 oidcGenerateIDToken          => 'addClaimToIDToken'
146             };
147
148             sub addClaimToIDToken {
149               my ( $self, $req, $payload, $rp ) = @_;
150               $payload->{"id_token_hook"} = 1;
151               return PE_OK;
152             }
153

LOGGING

155       Logging is provided by $self->logger and $self->userLogger. The
156       following rules must be applied:
157
158       logger->debug: technical debugging messages
159       logger->info: simple technical information
160       logger->notice: technical information that could interest
161       administrators
162       logger->warn: technical warning
163       logger->error: error that must be reported to administrator
164       userLogger->info: simple information about user's action
165       userLogger->notice: information that may be registered (auth
166       success,...)
167       userLogger->warn: bad action of a user (auth failure). Auth/Combination
168       transform it to "info" when another authentication scheme is available
169       userLogger->error: bad action of a user that must be reported, (even if
170       another backend is available with Combination)
171

AUTHORS

186       LemonLDAP::NG team <http://lemonldap-ng.org/team>
187

BUG REPORT

189       Use OW2 system to report bug or ask for features:
190       <https://gitlab.ow2.org/lemonldap-ng/lemonldap-ng/issues>
191

DOWNLOAD

193       Lemonldap::NG is available at <https://lemonldap-ng.org/download>
194

COPYRIGHT AND LICENSE

196       See COPYING file for details.
197
198       This library is free software; you can redistribute it and/or modify it
199       under the terms of the GNU General Public License as published by the
200       Free Software Foundation; either version 2, or (at your option) any
201       later version.
202
203       This program is distributed in the hope that it will be useful, but
204       WITHOUT ANY WARRANTY; without even the implied warranty of
205       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
206       General Public License for more details.
207
208       You should have received a copy of the GNU General Public License along
209       with this program.  If not, see <http://www.gnu.org/licenses/>.
210
211
212
213perl v5.38.0                      2023-11L-e1m4onldap::NG::Portal::Main::Plugin(3)