1CatalystX::SimpleLogin:U:sMearnuCaoln(t3r)ibuted Perl DoCcautmaelnytsattXi:o:nSimpleLogin::Manual(3)
2
3
4

NAME

6       CatalystX::SimpleLogin::Manual - How to use and customise
7       CatalystX::SimpleLogin.
8
9   Tutorial
10       We're using a sample application here, to make the instructions a
11       little easier. This assumes that you have Catalyst, Catalyst::Devel,
12       Template Toolkit, and the Catalyst authentication and session plugins
13       installed.
14
15           catalyst.pl MyApp
16           cd MyApp
17           script/myapp_create.pl view HTML TT
18
19       Edit lib/MyApp.pm and add CatalystX::SimpleLogin,  Authenticate, and
20       the Session plugins to the use Catalyst plugin list:
21
22           use Catalyst qw/-Debug
23                           ConfigLoader
24                           +CatalystX::SimpleLogin
25                           Authentication
26                           Session
27                           Session::Store::File
28                           Session::State::Cookie
29                           Static::Simple/;
30
31       Add the following config for authentication, including two sample
32       users:
33
34           __PACKAGE__->config(
35               'Plugin::Authentication' => {
36                   default => {
37                       credential => {
38                           class => 'Password',
39                           password_field => 'password',
40                           password_type => 'clear'
41                       },
42                       store => {
43                           class => 'Minimal',
44                           users => {
45                               bob => {
46                                   password => "bobpw",
47                               },
48                               william => {
49                                   password => "billpw",
50                               },
51                           },
52                       },
53                   },
54               },
55           );
56
57       Execute " script/myapp_server.pl " and, as part of the debug output,
58       you should see:
59
60           [debug] Loaded Chained actions:
61           .-------------------------------------+--------------------------------------.
62           | Path Spec                           | Private                              |
63           +-------------------------------------+--------------------------------------+
64           | /login                              | /login/login                         |
65           | /logout                             | /login/logout                        |
66           '-------------------------------------+--------------------------------------'
67
68       Go to " localhost:3000 " and you should see the Catalyst welcome
69       screen. Go to " localhost:3000/login " and you should get a login
70       screen containing username and password text fields, a 'Remember'
71       checkbox, and a 'Login' button. Enter 'bob' and 'bobpw'. You should be
72       logged in and taken to the welcome screen. If you execute "
73       localhost:3000/logout " you will be logged out, and should see this in
74       the debug output (the welcome screen will stay the same).
75
76       Now go to " lib/MyApp/Controller/Root.pm " and remove the lines saying:
77
78           use strict;
79           use warnings;
80           use parent 'Catalyst::Controller';
81
82       and add the following lines:
83
84           use Moose;
85           use namespace::autoclean;
86           BEGIN { extends 'Catalyst::Controller' }
87
88       Now add a new action to " lib/MyApp/Controller/Root.pm " and include "
89       Does('NeedsLogin') " to use the Catalyst ActionRole that is part of
90       SimpleLogin:
91
92           sub hello_user : Local Does('NeedsLogin') {
93               my ( $self, $c ) = @_;
94               $c->res->body('<h2>Hello, user!</h2>');
95           }
96
97       Restart the server and you can see the new action. Go to
98       "htp://localhost:3000/hello_user" and you'll get the 'Hello, user!'
99       page. Now execute "http://localhost:3000/logout" and try
100       "http://localhost:3000/hello_user" again. You will be presented with a
101       login screen.
102
103       Authorization
104
105       CatalystX::SimpleLogin also provides /login/required and
106       /login/not_required for easy chaining off of for actions which should
107       only be available to authenticated users.
108
109           package MyApp::Controller::Secure;
110
111           sub setup : Chained('/login/required') PathPart('') CaptureArgs(1) {
112               my ( $self, $c, $id ) = @_;
113               # setup actions for authenticated-user-only access
114               $c->stash->{id} = $id;
115           }
116
117           sub something_secure : Chained('setup') PathPart Args(0) {
118               my ( $self, $c ) = @_;
119               # only authenticated users will have access to this action
120           }
121
122           sub open_to_all : Chained('/login/not_required') PathPart Args(0) {
123               my ( $self, $c ) = @_;
124               # this is available to everyone
125           }
126
127       For more fine-grained control, you can use ACL checks to refine access
128       control policies. This functionality is provided via
129       Catalyst::ActionRole::ACL.  Please consult the ACL documentation for
130       steps to setup your application.  The ACL checks work by allowing you
131       to add additional attributes on your actions which control the
132       particular role(s) required or allowed.
133
134           package MyApp;
135           __PACKAGE__->config(
136               'Controller::Login' => {
137                   actions => {
138                       required => {
139                           Does => ['ACL'],
140                           AllowedRole => ['admin', 'poweruser'], # ANY of these
141                           # RequiresRole => ['extranet'], # ALL of these
142                           ACLDetachTo => 'login',
143                       },
144                   },
145               },
146           );
147
148           package MyApp::Controller::Foo;
149           BEGIN { extends 'Catalyst::Controller' }
150
151           sub do_something : Chained('/login/required')
152                            : Does('ACL') RequiresRole('createinvoice') ACLDetachTo('/login') {}
153
154       You can also add a message, which will be put into the flash key
155       'error_msg'. Add the following to the hello_user action:
156
157         : LoginRedirectMessage('Please Login to view this Action')
158
159       Now we'll create a Template Toolkit template that can be customized.
160       Create a " root/login/login.tt " file with the following lines.
161
162         [% error_msg %]
163         [% render_login_form %]
164
165       Now edit " lib/MyApp.pm " and add the config shown below to remove the
166       'RenderAsTTTemplate' trait, and add 'flash_to_stash' for
167       Catalyst::Plugin::Session (to allow the error message to be passed to
168       the next request):
169
170           __PACKAGE__->config(
171               'Plugin::Session' => {
172                   flash_to_stash => 1
173               },
174               'Controller::Login' => {
175                   traits => ['-RenderAsTTTemplate'],
176               },
177               # Other config..
178           );
179
180       Restart the server and try to view the hello_user page without being
181       logged in.  You should be redireced to the login page with the error
182       message displayed at the top.
183
184       You can replace " [% render_login_form %] " with your own html, and
185       customize it as you please.
186
187           <div class="error">[% error_msg %]</div>
188           <form id="login_form" method="post" >
189           <fieldset class="main_fieldset">
190           <div><label class="label" for="username">Username:
191           </label><input type="text" name="username" id="username" value="" />
192           </div>
193
194           <div><label class="label" for="password">Password: </label>
195           <input type="password" name="password" id="password" value="" />
196           </div>
197
198           <div><label class="label" for="remember">Remember: </label>
199           <input type="checkbox" name="remember" id="remember" value="1" />
200           </div>
201
202           <div><input type="submit" name="submit" id="submit" value="Login" />
203           </div>
204           </fieldset></form>
205
206       Or you can customize it using HTML::FormHandler HTML rendering
207       features, and the 'login_form_args' config key.
208
209       To alter the amount the remember me extends the session by alter the
210       "remember_me_expiry" configuration setting.
211
212           __PACKAGE__->config(
213               'Controller::Login' => {
214                   remember_me_expiry => 999999999, # the default is about 32 years.
215               },
216               # Other config..
217           );
218
219
220
221perl v5.30.1                      2020-01-29 CatalystX::SimpleLogin::Manual(3)
Impressum