Scroll to navigation

Lemonldap::NG::Portal::Main::Plugin(3pm) User Contributed Perl Documentation Lemonldap::NG::Portal::Main::Plugin(3pm)

NAME

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

SYNOPSIS

  package Lemonldap::NG::Portal::My::Plugin;
  use Mouse;
  extends 'Lemonldap::NG::Portal::Main::Plugin';
  
  use constant beforeAuth => 'verifyIP';
  
  sub init {
      my ($self) = @_;
      $self->addUnauthRoute( mypath => 'hello', [ 'GET', 'PUT' ] );
      $self->addAuthRoute( mypath => 'welcome', [ 'GET', 'PUT' ] );
      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, 'template', params => { WELCOME => 1 });
  }

DESCRIPTION

Lemonldap::NG::Portal::Main::Plugin provides many methods to easily write Lemonldap::NG addons.

init() is called for each plugin. If a plugin initialization fails (init() returns 0), the portal responds a 500 status code for each request.

Writing plugins

Custom plugins can be inserted in portal by declaring them in "lemonldap-ng.ini" file, section "[portal]", key "customPlugins":

  [portal]
  customPlugins = ::My::Plugin1, ::My::Plugin2

Plugins must be valid packages well found in @INC.

Plugin entry points

Entry point based on PATH_INFO

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 $req argument. $req is the HTTP request. (See Lemonldap::NG::Portal::Main::Request). These methods must return a valid PSGI response. You can also use sendJSONresponse() or sendHtml() methods (see Lemonldap::NG::Common::PSGI).

Example:

  sub init {
      my ($self) = @_;
      $self->addUnauthRoute( mypath => 'hello', [ 'GET', 'PUT' ] );
      $self->addAuthRoute( mypath => 'welcome', [ 'GET', 'PUT' ] );
      return 1;
  }
  sub hello {
      my ($self, $req) = @_;
      ...
      return $self->p->sendJSONresponse($req, { hello => 1 });
  }
  sub welcome {
      my ($self, $req) = @_;
      ...
      return $self->p->sendHtml($req, 'template', params => { WELLCOME => 1 });
  }

If you want to get a "protected application" behavior, you can use addAuthRouteWithRedirect. This methods calls addAuthRoute with given arguments and build a "unAuth" route that build a redirection after authentication.

Entry point in auth process

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.

"beforeAuth": method called before authentication process
"betweenAuthAndData": method called after authentication and before setting "sessionInfo" provisionning
"afterData": method called after "sessionInfo" provisionning (macros, groups,...)
"endAuth": method called when session is validated (after cookie build)
"authCancel": method called when user click on "cancel" during auth process
"forAuthUser": method called for already authenticated users
"beforeLogout": method called before logout

Note: methods inserted so must return a PE_* constant. See Lemonldap::NG::Portal::Main::Constants.

Advanced entry points

These entry points are not stored in "$req->step" but launched on the fly:

"afterSub": hash ref that give methods to call after given main method is called. Example:
  use constant afterSub => {
      getUser => 'mysub',
  }
  sub mysub {
      my ( $self ,$req ) = @_;
      # Do something
      return PE_OK;
  }
    
"aroundSub": hash ref that give methods to call instead of given main method. Example:
  use constant aroundSub => {
      getUser => 'mysub',
  };
  sub mysub {
      my ( $self, $sub, $req ) = @_;
      # Do something before
      my $ret = $sub->($req);
      # Do something after
      return $ret;
  }
    

Do not launch "getUser" but use the given $sub. This permits multiple plugins to use "aroundSub" in the same time.

"hook": hash ref that gives methods to call when a hook is triggered in the LemonLDAP::NG code. Example:
  use constant hook => {
      oidcGenerateIDToken          => 'addClaimToIDToken'
  };
  sub addClaimToIDToken {
    my ( $self, $req, $payload, $rp ) = @_;
    $payload->{"id_token_hook"} = 1;
    return PE_OK;
  }
    

LOGGING

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

SEE ALSO

<http://lemonldap-ng.org>

OTHER POD FILES

AUTHORS

http://lemonldap-ng.org/team>

BUG REPORT

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

DOWNLOAD

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

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 <http://www.gnu.org/licenses/>.

2021-10-11 perl v5.32.1