Portal.pm 5.07 KB
Newer Older
Xavier Guimard's avatar
Xavier Guimard committed
1
# Alias for Lemonldap::NG::Portal::Main
2 3
package Lemonldap::NG::Portal;

4
our $VERSION = '2.0.0';
Xavier Guimard's avatar
Xavier Guimard committed
5 6
use Lemonldap::NG::Portal::Main;
use base 'Lemonldap::NG::Portal::Main';
7 8 9 10 11 12 13

1;

__END__

=pod

Xavier Guimard's avatar
Xavier Guimard committed
14 15
=encoding utf8

16 17 18 19 20
=head1 NAME

Lemonldap::NG::Portal - The authentication portal part of Lemonldap::NG Web-SSO
system.

Xavier Guimard's avatar
Xavier Guimard committed
21 22 23 24 25 26 27 28
=head1 SYNOPSIS

Use any of Plack launcher. Example:

  #!/usr/bin/env plackup
  
  use Lemonldap::NG::Portal;
  
Xavier Guimard's avatar
Xavier Guimard committed
29
  # This must be the last instruction! See PSGI for more
Xavier Guimard's avatar
Xavier Guimard committed
30 31
  Lemonldap::NG::Portal->run($opts);

32 33 34 35 36 37 38 39 40
=head1 DESCRIPTION

Lemonldap::NG is a modular Web-SSO based on Apache::Session modules. It
simplifies the build of a protected area with a few changes in the application.

It manages both authentication and authorization and provides headers for
accounting. So you can have a full AAA protection for your web space as
described below.

Xavier Guimard's avatar
Xavier Guimard committed
41 42
Lemonldap::NG::Portal provides portal components. See
L<http://lemonldap-ng.org> for more.
43

Xavier Guimard's avatar
Xavier Guimard committed
44 45 46 47 48 49 50 51
=head1 KINEMATICS

The portal object is based on L<Lemonldap::NG::Handler::Try>: underlying
handler tries to authenticate user and then follow the routes (auth/unauth)
declared during initialization.

=head2 Initialization

Xavier Guimard's avatar
Xavier Guimard committed
52
The initialisation process subscribes portal to handler configuration reload and
Xavier Guimard's avatar
Xavier Guimard committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
ask for handler initialization (L<Lemonldap::NG::Portal::Main::Init>).
So configuration read is triggered by handler at each reload.

During configuration reload, every enabled components are loaded as plugins:

=over

=item authentication module

=item userDB module

=item other enabled plugins (issuers,...)

=back

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

Xavier Guimard's avatar
Xavier Guimard committed
71
See L<Lemonldap::NG::Portal::Main::Plugin> to see how to write modules.
Xavier Guimard's avatar
Xavier Guimard committed
72 73 74

=head2 Main route

Xavier Guimard's avatar
Xavier Guimard committed
75
The "/" route is declared in L<Lemonldap::NG::Portal::Main::Init>. It points to
Xavier Guimard's avatar
Xavier Guimard committed
76 77 78 79 80
different methods in L<Lemonldap::NG::Portal::Main::Run>. Theses methods choose
methods to call in the process and call do().

do() stores methods to call in $req->steps and launches
Lemonldap::NG::Portal::Main::Process::process(). This method removes each method
Xavier Guimard's avatar
Xavier Guimard committed
81
stored in $req->steps and launches it. If the result is PE_OK, process()
Xavier Guimard's avatar
Xavier Guimard committed
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105
continues, else it returns the error code.

If the request was an Ajax one, do() responds in JSON format else it manages
redirection if any. Else it calls
Lemonldap::NG::Portal::Main::Display::display() to have template and arguments,
then it launch Lemonldap::NG::Common::PSGI::sendHtml() with them.

=head1 DEVELOPER INSTRUCTIONS

Portal main object is defined in Lemonldap::NG::Portal::Main::* classes. Other
components are plugins. Plugins must not store any hash key in the main object.

Main and plugin keys must be initializated during initialization. They must
be read-only during receiving requests.

The L<Lemonldap::NG::Portal::Main::Request> request has fixed keys. A plugin
that wants to store a temporary key must store it in $req->datas or use
defined keys, but it must never create a root key. Plugin keys may have
explicit names to avoid conflicts.

Whole configuration is always available. It is stored in $self->conf. It must
not be modified by anyone even during initialization or receiving request
(during initialization, copy the value in the plugin namespace instead).

Xavier Guimard's avatar
Xavier Guimard committed
106
All plugins can dial with the portal methods using $self->p which points to
Xavier Guimard's avatar
Xavier Guimard committed
107 108 109 110
portal main object. Some main methods are mapped to the plugin namespace:

=over

111 112 113
=item logger() accessor to log

=item userLogger() accessor to log user actions
Xavier Guimard's avatar
Xavier Guimard committed
114 115 116 117 118

=item error() accessor (use it to store error during initialization)

=back

Xavier Guimard's avatar
Xavier Guimard committed
119
=head1 SEE ALSO
Xavier Guimard's avatar
Xavier Guimard committed
120 121

Most of the documentation is available on the website
Xavier Guimard's avatar
Xavier Guimard committed
122 123 124
L<http://lemonldap-ng.org>

=head2 OTHER POD FILES
Xavier Guimard's avatar
Xavier Guimard committed
125 126 127 128 129

=over

=item Writing an authentication module: L<Lemonldap::NG::Portal::Auth::Base>

Xavier Guimard's avatar
Xavier Guimard committed
130 131 132
=item Writing a second authentication factor module:
L<Lemonldap::NG::Portal::Main::SecondFactor>

Xavier Guimard's avatar
Xavier Guimard committed
133 134 135 136 137 138 139 140 141 142
=item Writing an issuer module: L<Lemonldap::NG::Portal::Main::Issuer>

=item Writing another type of plugin: L<Lemonldap::NG::Portal::Main::Plugin>

=item Request object: L<Lemonldap::NG::Portal::Main::Request>

=item Adding parameters in the manager: L<Lemonldap::NG::Manager::Build>

=back

Xavier Guimard's avatar
Xavier Guimard committed
143
=head1 AUTHORS
144 145 146

=over

Xavier Guimard's avatar
Xavier Guimard committed
147
=item LemonLDAP::NG team L<http://lemonldap-ng.org/team>
148 149

=back
150

Xavier Guimard's avatar
Xavier Guimard committed
151 152 153
=head1 BUG REPORT

Use OW2 system to report bug or ask for features:
Xavier Guimard's avatar
Xavier Guimard committed
154
L<http://jira.ow2.org>
Xavier Guimard's avatar
Xavier Guimard committed
155 156 157 158 159 160

=head1 DOWNLOAD

Lemonldap::NG is available at
L<http://forge.objectweb.org/project/showfiles.php?group_id=274>

161 162
=head1 COPYRIGHT AND LICENSE

Xavier Guimard's avatar
Xavier Guimard committed
163
See COPYING file for details.
164 165

This library is free software; you can redistribute it and/or modify
166 167 168 169 170 171 172 173 174 175 176
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/>.
177 178

=cut