/ 
WWW-Suffit-Plugin-FileAuth-1.00
River stage zero No dependents
/ WWW::Suffit::Plugin::FileAuth

NAME

WWW::Suffit::Plugin::FileAuth - The Suffit plugin for authentication and authorization by password file

SYNOPSIS

sub startup {
    my $self = shift->SUPER::startup();
    $self->plugin('FileAuth', {
        configsection => 'auth',
    });

    # . . .
}

... configuration:

# FileAuth configuration
<Auth>
    AuthUserFile /etc/myapp/passwd.db
</Auth>

DESCRIPTION

This plugin provides authentication and authorization by looking up users in plain text password files

The AuthUserFile configuration directive sets the path to the user file of a textual file containing the list of users and passwords for user authentication.

If it is not absolute, it is treated as relative to the project data directory.

By default use passwd.db file name

Each line of the user file contains a username followed by a colon, followed by the encrypted password. If the same user ID is defined multiple times, plugin will use the first occurrence to verify the password. Try to avoid such cases!

The encrypted password format depends on which length of this encrypted-string and character-set:

md5     32 hex digits and chars
sha1    40 hex digits and chars
sha224  56 hex digits and chars
sha256  64 hex digits and chars
sha384  96 hex digits and chars
sha512  128 hex digits and chars
unsafe plain text otherwise

Also, each line of the user file can contain parameters in the Query of URL format (RFC 3986), which must be placed at the end of the line with a leading colon character, which is the delimiter

For example:

admin:5f4dcc3b5aa765d61d8327deb882cf99
test:5f4dcc3b5aa765d61d8327deb882cf99:uid=1&name=Test%20user
anonymous:password

OPTIONS

This plugin supports the following options

configsection

configsection => 'auth'

This option sets a section name of the config file for define namespace of configuration directives for this plugin

Default: none (without section)

HELPERS

This plugin provides the following helpers

fileauth.init

my $init = $self->fileauth->init;

This method returns the init object (Mojo::JSON::Pointer) that contains data of initialization:

{
    error       => '...',       # Error message
    status      => 500,         # HTTP status code
    code        => 'E7000',     # The Suffit error code
}

For example (in your controller):

# Check init status
my $init = $self->fileauth->init;
if (my $err = $init->get('/error')) {
    $self->reply->error($init->get('/status'),
        $init->get('/code'), $err);
    return;
}

fileauth.authenticate

my $auth = $self->fileauth->authenticate({
    username    => $username,
    password    => $password,
    loginpage   => 'login', # -- To login-page!!
    expiration  => $remember ? SESSION_EXPIRE_MAX : SESSION_EXPIRATION,
    realm       => "Test zone",
});
if (my $err = $auth->get('/error')) {
    if (my $location = $auth->get('/location')) { # Redirect
        $self->flash(message => $err);
        $self->redirect_to($location); # 'login' -- To login-page!!
    } elsif ($auth->get('/status') >= 500) { # Fatal server errors
        $self->reply->error($auth->get('/status'), $auth->get('/code'), $err);
    } else { # User errors (show on login page)
        $self->stash(error => $err);
        return $self->render;
    }
    return;
}

This helper performs authentication backend subprocess and returns result object (Mojo::JSON::Pointer) that contains data structure:

{
    error       => '',          # Error message
    status      => 200,         # HTTP status code
    code        => 'E0000',     # The Suffit error code
    username    => $username,   # User name
    referer     => $referer,    # Referer
    loginpage   => $loginpage,  # Login page for redirects (location)
    location    => undef,       # Location URL for redirects
}

fileauth.authorize

my $auth = $self->fileauth->authorize({
    referer     => $referer,
    username    => $username,
    loginpage   => 'login', # -- To login-page!!
});
if (my $err = $auth->get('/error')) {
    if (my $location = $auth->get('/location')) {
        $self->flash(message => $err);
        $self->redirect_to($location); # 'login' -- To login-page!!
    } else {
        $self->reply->error($auth->get('/status'), $auth->get('/code'), $err);
    }
    return;
}

This helper performs authorization backend subprocess and returns result object (Mojo::JSON::Pointer) that contains data structure:

{
    error       => '',          # Error message
    status      => 200,         # HTTP status code
    code        => 'E0000',     # The Suffit error code
    username    => $username,   # User name
    referer     => $referer,    # Referer
    loginpage   => $loginpage,  # Login page for redirects (location)
    location    => undef,       # Location URL for redirects
    user    => {        # User data
        address     => "127.0.0.1", # User (client) IP address
        base        => "http://localhost:8080", # Base URL of request
        comment     => "No comments", # Comment
        email       => 'test@example.com', # Email address
        email_md5   => "a84450...366", # MD5 hash of email address
        method      => "ANY", # Current method of request
        name        => "Bob Smith", # Full user name
        path        => "/", # Current query-path of request
        role        => "Regular user", # User role
        status      => true, # User status in JSON::PP::Boolean notation
        uid         => 1, # User ID
        username    => $username, # User name
    },
}

METHODS

Internal methods

register

This method register the plugin and helpers in Mojolicious application

SEE ALSO

Mojolicious, WWW::Suffit::Server

AUTHOR

Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>

COPYRIGHT

Copyright (C) 1998-2024 D&D Corporation. All Rights Reserved

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See LICENSE file and https://dev.perl.org/licenses/