1CatalystX::SimpleLogin:U:sMearnuCaoln(t3r)ibuted Perl DoCcautmaelnytsattXi:o:nSimpleLogin::Manual(3)
2
3
4
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.38.0 2023-07-20 CatalystX::SimpleLogin::Manual(3)