.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CatalystX::SimpleLogin::Manual 3pm"
.TH CatalystX::SimpleLogin::Manual 3pm "2022-08-28" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CatalystX::SimpleLogin::Manual \- How to use and customise CatalystX::SimpleLogin.
.SS "Tutorial"
.IX Subsection "Tutorial"
We're using a sample application here, to make the instructions a little
easier. This assumes that you have Catalyst, Catalyst::Devel,
Template Toolkit, and the Catalyst authentication and session plugins
installed.
.PP
.Vb 3
\&    catalyst.pl MyApp
\&    cd MyApp
\&    script/myapp_create.pl view HTML TT
.Ve
.PP
Edit lib/MyApp.pm and add CatalystX::SimpleLogin,  Authenticate, and the
Session plugins to the use Catalyst plugin list:
.PP
.Vb 8
\&    use Catalyst qw/\-Debug
\&                    ConfigLoader
\&                    +CatalystX::SimpleLogin
\&                    Authentication
\&                    Session
\&                    Session::Store::File
\&                    Session::State::Cookie
\&                    Static::Simple/;
.Ve
.PP
Add the following config for authentication, including two sample users:
.PP
.Vb 10
\&    _\|_PACKAGE_\|_\->config(
\&        \*(AqPlugin::Authentication\*(Aq => {
\&            default => {
\&                credential => {
\&                    class => \*(AqPassword\*(Aq,
\&                    password_field => \*(Aqpassword\*(Aq,
\&                    password_type => \*(Aqclear\*(Aq
\&                },
\&                store => {
\&                    class => \*(AqMinimal\*(Aq,
\&                    users => {
\&                        bob => {
\&                            password => "bobpw",
\&                        },
\&                        william => {
\&                            password => "billpw",
\&                        },
\&                    },
\&                },
\&            },
\&        },
\&    );
.Ve
.PP
Execute \f(CW\*(C` script/myapp_server.pl \*(C'\fR and, as part of the debug output, you should see:
.PP
.Vb 7
\&    [debug] Loaded Chained actions:
\&    .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-.
\&    | Path Spec                           | Private                              |
\&    +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&    | /login                              | /login/login                         |
\&    | /logout                             | /login/logout                        |
\&    \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
.Ve
.PP
Go to \f(CW\*(C` localhost:3000 \*(C'\fR and you should see the Catalyst welcome screen. Go to
\&\f(CW\*(C` localhost:3000/login \*(C'\fR and you should get a login screen containing username and
password text fields, a 'Remember' checkbox, and a 'Login' button. Enter 'bob' and
\&'bobpw'. You should be logged in and taken to the welcome screen. If you execute
\&\f(CW\*(C` localhost:3000/logout \*(C'\fR you will be logged out, and should see this in the
debug output (the welcome screen will stay the same).
.PP
Now go to \f(CW\*(C` lib/MyApp/Controller/Root.pm \*(C'\fR and remove the lines saying:
.PP
.Vb 3
\&    use strict;
\&    use warnings;
\&    use parent \*(AqCatalyst::Controller\*(Aq;
.Ve
.PP
and add the following lines:
.PP
.Vb 3
\&    use Moose;
\&    use namespace::autoclean;
\&    BEGIN { extends \*(AqCatalyst::Controller\*(Aq }
.Ve
.PP
Now add a new action to \f(CW\*(C` lib/MyApp/Controller/Root.pm \*(C'\fR and include
\&\f(CW\*(C` Does(\*(AqNeedsLogin\*(Aq) \*(C'\fR to use the Catalyst ActionRole that is part of SimpleLogin:
.PP
.Vb 4
\&    sub hello_user : Local Does(\*(AqNeedsLogin\*(Aq) {
\&        my ( $self, $c ) = @_;
\&        $c\->res\->body(\*(Aq<h2>Hello, user!</h2>\*(Aq);
\&    }
.Ve
.PP
Restart the server and you can see the new action. Go to \f(CW\*(C`htp://localhost:3000/hello_user\*(C'\fR
and you'll get the 'Hello, user!' page. Now execute \f(CW\*(C`http://localhost:3000/logout\*(C'\fR and try
\&\f(CW\*(C`http://localhost:3000/hello_user\*(C'\fR again. You will be presented with a login screen.
.PP
\fIAuthorization\fR
.IX Subsection "Authorization"
.PP
CatalystX::SimpleLogin also provides /login/required and /login/not_required for easy
chaining off of for actions which should only be available to authenticated users.
.PP
.Vb 1
\&    package MyApp::Controller::Secure;
\&
\&    sub setup : Chained(\*(Aq/login/required\*(Aq) PathPart(\*(Aq\*(Aq) CaptureArgs(1) {
\&        my ( $self, $c, $id ) = @_;
\&        # setup actions for authenticated\-user\-only access
\&        $c\->stash\->{id} = $id;
\&    }
\&
\&    sub something_secure : Chained(\*(Aqsetup\*(Aq) PathPart Args(0) {
\&        my ( $self, $c ) = @_;
\&        # only authenticated users will have access to this action
\&    }
\&
\&    sub open_to_all : Chained(\*(Aq/login/not_required\*(Aq) PathPart Args(0) {
\&        my ( $self, $c ) = @_;
\&        # this is available to everyone
\&    }
.Ve
.PP
For more fine-grained control, you can use \s-1ACL\s0 checks to refine access 
control policies. This functionality is provided via Catalyst::ActionRole::ACL. 
Please consult the \s-1ACL\s0 documentation for steps to setup your application.
The \s-1ACL\s0 checks work by allowing you to add additional attributes on your
actions which control the particular role(s) required or allowed.
.PP
.Vb 10
\&    package MyApp;
\&    _\|_PACKAGE_\|_\->config(
\&        \*(AqController::Login\*(Aq => {
\&            actions => {
\&                required => {
\&                    Does => [\*(AqACL\*(Aq],
\&                    AllowedRole => [\*(Aqadmin\*(Aq, \*(Aqpoweruser\*(Aq], # ANY of these
\&                    # RequiresRole => [\*(Aqextranet\*(Aq], # ALL of these
\&                    ACLDetachTo => \*(Aqlogin\*(Aq,
\&                },
\&            },
\&        },
\&    );
\&
\&    package MyApp::Controller::Foo;
\&    BEGIN { extends \*(AqCatalyst::Controller\*(Aq }
\&
\&    sub do_something : Chained(\*(Aq/login/required\*(Aq)
\&                     : Does(\*(AqACL\*(Aq) RequiresRole(\*(Aqcreateinvoice\*(Aq) ACLDetachTo(\*(Aq/login\*(Aq) {}
.Ve
.PP
You can also add a message, which will be put into the flash key 'error_msg'. Add
the following to the hello_user action:
.PP
.Vb 1
\&  : LoginRedirectMessage(\*(AqPlease Login to view this Action\*(Aq)
.Ve
.PP
Now we'll create a Template Toolkit template that can be customized. Create a
\&\f(CW\*(C` root/login/login.tt \*(C'\fR file with the following lines.
.PP
.Vb 2
\&  [% error_msg %]
\&  [% render_login_form %]
.Ve
.PP
Now edit \f(CW\*(C` lib/MyApp.pm \*(C'\fR and add the config shown below
to remove the 'RenderAsTTTemplate' trait, and add
\&'flash_to_stash' for Catalyst::Plugin::Session
(to allow the error message to be passed to the next request):
.PP
.Vb 9
\&    _\|_PACKAGE_\|_\->config(
\&        \*(AqPlugin::Session\*(Aq => {
\&            flash_to_stash => 1
\&        },
\&        \*(AqController::Login\*(Aq => {
\&            traits => [\*(Aq\-RenderAsTTTemplate\*(Aq],
\&        },
\&        # Other config..
\&    );
.Ve
.PP
Restart the server and try to view the hello_user page without being logged in.
You should be redireced to the login page with the error message displayed at
the top.
.PP
You can replace \f(CW\*(C` [% render_login_form %] \*(C'\fR with your own html, and customize
it as you please.
.PP
.Vb 6
\&    <div class="error">[% error_msg %]</div>
\&    <form id="login_form" method="post" >
\&    <fieldset class="main_fieldset">
\&    <div><label class="label" for="username">Username:
\&    </label><input type="text" name="username" id="username" value="" />
\&    </div>
\&
\&    <div><label class="label" for="password">Password: </label>
\&    <input type="password" name="password" id="password" value="" />
\&    </div>
\&
\&    <div><label class="label" for="remember">Remember: </label>
\&    <input type="checkbox" name="remember" id="remember" value="1" />
\&    </div>
\&
\&    <div><input type="submit" name="submit" id="submit" value="Login" />
\&    </div>
\&    </fieldset></form>
.Ve
.PP
Or you can customize it using HTML::FormHandler \s-1HTML\s0 rendering features, and
the 'login_form_args' config key.
.PP
To alter the amount the remember me extends the session by alter the \f(CW\*(C`remember_me_expiry\*(C'\fR
configuration setting.
.PP
.Vb 6
\&    _\|_PACKAGE_\|_\->config(
\&        \*(AqController::Login\*(Aq => {
\&            remember_me_expiry => 999999999, # the default is about 32 years.
\&        },
\&        # Other config..
\&    );
.Ve