view release on metacpan or  search on metacpan

lib/Gantry/Docs/Cookbook.pod  view on Meta::CPAN

    }

These stubs are filled inside C<Gantry::Samples::AuthCookie>.  They
are not particularly interesting, but here they are:

    sub do_open {
        my ( $self ) = @_;

        return( "you're in" );

    } # END do_open

    sub do_closed {
        my ( $self ) = @_;

        my @lines;
        push( @lines, "you're in: " . $self->user );
        push( @lines,
            ht_br(), ht_br(),
            ht_a(
                ( $self->app_rootp . "/login?logout=1" ),
                ('logout ' . $self->user),
            ),
        );
        return( join( "", @lines ) );

    } # END do_closed

Some pages display differently for logged in users than they do for
others.  For instance the front page of perlmonks always shows the
Seekers of Perl Wisdom section for anyone not logged in, but a page
of the user's choice for those logged in.  This requires looking at
the cookie, to find out who is logged in, without denying access.
These modules in the samples demonstrate this:

    Gantry::Samples::AuthCookie::SQLite
    Gantry::Samples::TablePermissions
    Gantry::Samples::TablePermCRUD

They do this by setting:

    auth_optional yes => no_accessor;

in their controller level config blocks.  This sets the C<user_row>
attribute of the site object, without keeping anyone out of the page
for failure to have a valid cookie.  Now that the config tells the
auth cookie plugin where to look for user data and which pages to
restrict, we must have database tables for that user data.

=head2 Authentication Database

For C<Gantry::Plugins::AuthCookie> to work, you need to set up a
database for it to use, or add tables to your app's existing database.
Using a separate database is good in a corporate setting where users
have various access to many different apps.  Combining the auth
tables into an existing database is better for self standing sites.
The samples use a single database, so I'll show that approach first.

There are three essential columns in the user table needed for
authentication: id, user name, and pass word.  The id is for the benifit
of the ORM.  The other fields hold the user's credentials.  The names
of these columns is not fixed by the AuthCookie plugin.  The defaults
are ident and password.  We'll see how to control the names the plugin
uses below.

You are welcome to put additional information in the user rows.  The
user table from the samples has this schema (which was generated by bigtop):

    CREATE TABLE user (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        active INTEGER,
        username varchar,
        password varchar,
        email varchar,
        fname varchar,
        lname varchar,
        created datetime,
        modified datetime
    );

When you use authentication, with either auth_require or auth_optional, you
can get the ORM row for the logged in user by calling C<user_row> on your
Gantry site object.  If auth is optional, and the user is not logged in,
you will still get a user row, but it won't have data in it.

To tell the plugin about the table, the samples use these variables
in the app level config block:

    config {
        dbconn `dbi:SQLite:dbname=app.db` => no_accessor;
        auth_table user => no_accessor;
        auth_user_field username;
        #...
    }

To use a separate database for auth, set C<auth_dbconn> like dbconn, but
pointing to the other database.  We need to tell the plugin the name
of our user table with the C<auth_table> config parameter.  Since sqlite
allows us to, we call it C<user>.  Since our user names are stored in
the C<username> column, and not in C<ident>, we must set the
C<auth_user_field> config parameter to C<username>.  To change the pass word
column away from C<password>, we would use C<auth_password_field>, but we
don't need to in this case.

That's all you need to set up cookie base user log-ins.  If you want
to further restrict pages to subsets of logged-in users, see the next
question.

=head1 How do I authorize users?

Once you have mastered authenticating users, it is usually a short step
to wanting to divide them into groups with different access rights.
For instance, a message board like slashdot needs special access for
editors.

As with authentication, there are two parts to authorization.  First, you
need to change the config info (or code).  Then, you need to include
the groups and their member lists in the database.  I'll take them in
that order.

Note well, that the samples do not use group authorization at the