Portal.pm 4.96 KB
Newer Older
1 2 3 4 5
## @file
# Alias for Lemonldap::NG::SharedConf

## @class
# Alias for Lemonldap::NG::SharedConf
6 7
package Lemonldap::NG::Portal;

8
our $VERSION = '2.0.0';
Xavier Guimard's avatar
Xavier Guimard committed
9 10
use Lemonldap::NG::Portal::Main;
use base 'Lemonldap::NG::Portal::Main';
11 12 13 14 15 16 17

1;

__END__

=pod

Xavier Guimard's avatar
Xavier Guimard committed
18 19
=encoding utf8

20 21 22 23 24
=head1 NAME

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

Xavier Guimard's avatar
Xavier Guimard committed
25 26 27 28 29 30 31 32
=head1 SYNOPSIS

Use any of Plack launcher. Example:

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

36 37 38 39 40 41 42 43 44
=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
45 46
Lemonldap::NG::Portal provides portal components. See
L<http://lemonldap-ng.org> for more.
47

Xavier Guimard's avatar
Xavier Guimard committed
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
=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

The intialisation process subscribes portal to handler configuration reload and
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
75
See L<Lemonldap::NG::Portal::Main::Plugin> to see how to write modules.
Xavier Guimard's avatar
Xavier Guimard committed
76 77 78

=head2 Main route

Xavier Guimard's avatar
Xavier Guimard committed
79
The "/" route is declared in L<Lemonldap::NG::Portal::Main::Init>. It points to
Xavier Guimard's avatar
Xavier Guimard committed
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
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
stored in $req->steps and launches it. If the result is PE_OK, proces()
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
110
All plugins can dial with the portal methods using $self->p which points to
Xavier Guimard's avatar
Xavier Guimard committed
111 112 113 114 115 116 117 118 119 120
portal main object. Some main methods are mapped to the plugin namespace:

=over

=item lmLog()

=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 123

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

=head2 OTHER POD FILES
Xavier Guimard's avatar
Xavier Guimard committed
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141

=over

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

=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
142
=head1 AUTHORS
143 144 145

=over

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

=back
149

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

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

=head1 DOWNLOAD

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

160 161
=head1 COPYRIGHT AND LICENSE

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

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

=cut