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/

cpanm WWW::Suffit::Plugin::FileAuth

perl -MCPAN -e shell
install WWW::Suffit::Plugin::FileAuth