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

Xavier Guimard's avatar
Xavier Guimard committed
4
our $VERSION = '2.0.2';
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
=head1 DESCRIPTION

Lemonldap::NG is a modular Web-SSO based on Apache::Session modules. It
Christophe Maudoux's avatar
Christophe Maudoux committed
35 36
provides an easy way to build a secured area to protect applications with
very few changes.
37

Christophe Maudoux's avatar
Christophe Maudoux committed
38 39 40
Lemonldap::NG manages both authentication and authorization. Furthermore
it provides headers for accounting. So you can have a full AAA protection
for your web space as described below.
41

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

Xavier Guimard's avatar
Xavier Guimard committed
45 46 47
=head1 KINEMATICS

The portal object is based on L<Lemonldap::NG::Handler::Try>: underlying
Christophe Maudoux's avatar
Christophe Maudoux committed
48 49
handler tries to authenticate user and follows initialized auth / unauth
routes.
Xavier Guimard's avatar
Xavier Guimard committed
50 51 52

=head2 Initialization

Christophe Maudoux's avatar
Christophe Maudoux committed
53 54 55
Initialization process subscribes portal to handler configuration reload and
requests handler initialization (L<Lemonldap::NG::Portal::Main::Init>).
So configuration is read by handler at each reload.
Xavier Guimard's avatar
Xavier Guimard committed
56

Christophe Maudoux's avatar
Christophe Maudoux committed
57
During configuration reload, each enabled components are loaded as plugins:
Xavier Guimard's avatar
Xavier Guimard committed
58 59 60 61 62 63 64 65 66 67 68

=over

=item authentication module

=item userDB module

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

=back

Christophe Maudoux's avatar
Christophe Maudoux committed
69
init() is called for each plugin. If a plugin initialization fails (init()
Xavier Guimard's avatar
Xavier Guimard committed
70 71
returns 0), the portal responds a 500 status code for each request.

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

=head2 Main route

Xavier Guimard's avatar
Xavier Guimard committed
76
The "/" route is declared in L<Lemonldap::NG::Portal::Main::Init>. It points to
Christophe Maudoux's avatar
Christophe Maudoux committed
77
different methods in L<Lemonldap::NG::Portal::Main::Run>. Theses methods select
Xavier Guimard's avatar
Xavier Guimard committed
78 79 80 81
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
82
stored in $req->steps and launches it. If the result is PE_OK, process()
Xavier Guimard's avatar
Xavier Guimard committed
83 84
continues, else it returns the error code.

Christophe Maudoux's avatar
Christophe Maudoux committed
85
If it is an Ajax request, do() responds in JSON format else it manages
86
redirection if any. Else it calls
Christophe Maudoux's avatar
Christophe Maudoux committed
87 88
Lemonldap::NG::Portal::Main::Display::display() to load template and arguments,
and launches Lemonldap::NG::Common::PSGI::sendHtml() using them.
Xavier Guimard's avatar
Xavier Guimard committed
89 90 91 92

=head1 DEVELOPER INSTRUCTIONS

Portal main object is defined in Lemonldap::NG::Portal::Main::* classes. Other
Christophe Maudoux's avatar
Christophe Maudoux committed
93
components are plugins. Plugins do not have to store any hash key in main object.
Xavier Guimard's avatar
Xavier Guimard committed
94

Christophe Maudoux's avatar
Christophe Maudoux committed
95 96
Main and plugin keys must be set during initialization process. They must
be read-only during requests receiving.
Xavier Guimard's avatar
Xavier Guimard committed
97 98

The L<Lemonldap::NG::Portal::Main::Request> request has fixed keys. A plugin
Xavier Guimard's avatar
Xavier Guimard committed
99
that wants to store a temporary key must store it in C<$req-E<gt>data> or use
Xavier Guimard's avatar
Xavier Guimard committed
100 101 102 103
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
104 105
not be modified by any components even during initialization process or
receiving request (during initialization, copy the value in the plugin
Christophe Maudoux's avatar
Christophe Maudoux committed
106
namespace instead).
Xavier Guimard's avatar
Xavier Guimard committed
107

Christophe Maudoux's avatar
Christophe Maudoux committed
108
All plugins can access to portal methods using $self->p which points to
Xavier Guimard's avatar
Xavier Guimard committed
109 110 111 112
portal main object. Some main methods are mapped to the plugin namespace:

=over

113 114 115
=item logger() accessor to log

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

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

=back

Xavier Guimard's avatar
Xavier Guimard committed
121
=head1 SEE ALSO
Xavier Guimard's avatar
Xavier Guimard committed
122

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

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

=over

Xavier Guimard's avatar
Xavier Guimard committed
129
=item Writing an authentication module: L<Lemonldap::NG::Portal::Auth>
Xavier Guimard's avatar
Xavier Guimard committed
130

Xavier Guimard's avatar
Xavier Guimard committed
131 132 133
=item Writing a UserDB module: L<Lemonldap::NG::Portal::UserDB>

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

Xavier Guimard's avatar
Xavier Guimard committed
135 136
=item Writing an issuer module: L<Lemonldap::NG::Portal::Main::Issuer>

Xavier Guimard's avatar
Xavier Guimard committed
137
=item Writing another plugin: L<Lemonldap::NG::Portal::Main::Plugin>
Xavier Guimard's avatar
Xavier Guimard committed
138 139 140 141 142 143 144

=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
145
=head1 AUTHORS
146 147 148

=over

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

=back
152

153 154 155
=head1 BUG REPORT

Use OW2 system to report bug or ask for features:
Xavier Guimard's avatar
Xavier Guimard committed
156
L<https://gitlab.ow2.org/lemonldap-ng/lemonldap-ng/issues>
157 158 159 160 161 162

=head1 DOWNLOAD

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

163 164
=head1 COPYRIGHT AND LICENSE

Xavier Guimard's avatar
Xavier Guimard committed
165
See COPYING file for details.
166 167

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

=cut