/ 
Web-Authenticate-0.013
River stage zero No dependents
/ Web::Authenticate

NAME

Web::Authenticate - Allows web authentication using cookies and a storage engine.

VERSION

version 0.013

SYNOPSIS

my $dbix_raw = DBIx::Raw->new(dsn => 'dbi:mysql:test:127.0.0.1:3306', user => 'user', password => 'password');
my $user_storage_handler = Web::Authenticate::User::Storage::Handler::SQL->new(dbix_raw => $dbix_raw);
my $storage_handler = Web::Authenticate::Session::Storage::Handler::SQL->new(dbix_raw => $dbix_raw, user_storage_handler => $user_storage_handler);
my $session_handler = Web::Authenticate::Session::Handler->new(session_storage_handler => $storage_handler);
my $web_authenticate = Web::Authenticate->new(
    user_storage_handler => $user_storage_handler,
    session_handler => $session_handler,
    after_login_url => 'http://www.google.com/account.cgi',
    after_logout_url => 'http://www.google.com/',
    login_url => 'http://www.google.com/login.cgi',
);  

# login user
my $login_result = $web_authenticate->login(login_args => [$username, $password]);

if ($login_result->success) {
    # success!
}

# authenticate a user to be on a page just with their session
my $authenticate_result = $web_authenticate->authenticate;

if ($authenticate_result->succes) {
    # success! allowed to access page
} 

# authenticate user with authenticators
my $authenticate_result = $web_authenticate->authenticate(authenticators => $authenticators);

if ($authenticate_result->succes) {
    # success! allowed to access page
} 


# create a user
my $create_user_result = $web_authenticate->create_user(username => $username, password => $password);

if ($create_user_result->success) {
    print "Created user " . $create_user_result->user->id . "\n";
}

# create a user and verify username and password meet requirements
my $create_user_result = $web_authenticate->create_user(username => $username, password => $password, username_verifiers => $username_verifiers, password_verifiers => $password_verifiers);

if ($create_user_result->success) {
    print "Created user " . $create_user_result->user->id . "\n";
} else {
    print "username errors: \n";
    for my $verifier (@{$create_user_result->failed_username_verifiers}) {
        print "\t" . $verifier->error_msg . "\n";
    }

    print "password errors: \n";
    for my $verifier (@{$create_user_result->failed_password_verifiers}) {
        print "\t" . $verifier->error_msg . "\n";
    }
}

# create a user with additional values
my $user_values => {
    age => 22,
    address => '123 Hopper Ln, Austin TX 78705',
};
my $create_user_result = $web_authenticate->create_user(username => $username, password => $password, user_values => $user_values);

if ($create_user_result->success) {
    print "Created user " . $create_user_result->user->id . "\n";
    print "user age " . $create_user_result->user->row->{age} . "\n";
    print "user address " . $create_user_result->user->row->{address} . "\n";
}

DESCRIPTION

This modules allows easy management of user authentication via cookies, redirects, a storage engine, a session handler, and cookie handler. It is flexible so you can rewrite any of those pieces for your applications' needs.

METHODS

user_storage_handler

Sets the Web::Authenticate::User::Storage::Handler::Role to be used. This is required with no default.

session_handler

Sets the Web::Authenticate::Session::Handler::Role to be used. This is required with no default.

Sets the object that does Web::Authenticate::Cookie::Handler::Role to be used. The default is the default Web::Authenticate::Cookie::Handler.

redirect_handler

Sets the object that does Web::Authenticate::RedirectHandler::Role to be used. The default is the default Web::Authenticate::RedirectHandler.

request_url_provider

Sets the object that does Web::Authenticate::RequestUrlProvider::Role to get the url for the current request (used to store the current url if "allow_after_login_redirect_override" is set to true and "authenticate" fails). Default is Web::Authenticate::RequestUrlProvider::CgiRequestUrlProvider.

login_url

Sets the login url that a user will be redirected to if they need to login. This is required with no default.

my $web_auth = Web::Authenticate->new(login_url => "http://www.google.com/login");

OR

$web_auth->login_url("http://www.google.com/login");

after_login_url

The url the user will be redirected to after a successful login.

after_logout_url

The url the user will be redirected to after a successful logout. This is required with no default.

authenticate_fail_url

The url the user will be redirected to if they are logged in, but fail to pass all authenticators in the authenticators arrayref for "authenticate".

update_expires_on_authenticate

If set to true (1), updates the expires time for the session upon successful authentication. Default is true.

allow_after_login_redirect_override

If a user requests a page that requires authentication and is redirected to login, if allow_after_login_redirect_override is set to true (1), then the user will be redirected to that url after a successful login. If set to false, then the user will be redirected to "after_login_url".

allow_after_login_redirect_time_seconds

The url of the page the user tried to load is set to a cookie if they are redirected to login from "authenticate". This sets the amount of time (in seconds) for the cookie to be valid. Default is 5 minutes.

allow_multiple_sessions_per_user

A bool (1 or undef) whether or not to allow multiple sessions per user. If set to true, when "invalidate_user_sessions" in Web::Authenticate::Session::Handler::Role will not be called. Default is false.

login

Verifies the arguments required by Web::Authenticate::User::Storage::Handler::Role in "user_storage_handler". If they are correct, if "allow_after_login_redirect_override" is set to 1 and the user has a cookie set for this, the user will be redirected to that url. If not, the user is redirected to the first the "url" in Web::Authenticate::Authenticator::Redirect::Role of the first succesful Web::Authenticate::Authenticator::Redirect::Role in auth_redirects. If auth_redirects is empty or none authenticate, then the user is redirected to "after_login_url" Returns a Web::Authenticate::Result::Login object.

my $login_result = $web_auth->login(login_args => [$username, $password]);

if ($login_result->success) {
    log("user id is " . $login_result->user->id);
    exit; # already set to redirect to appropriate page
} else {
    # handle login failure
    if ($login_result->authenticator) {
        # this authenticator caused the failure
    }
}

logout

Logs a user out of their current session by deleting their session cookie and their storage-backed session.

$web_authenticate->logout;

authenticate

First makes sure that the user authenticates as being logged in with a session. If the user is not, the user is redirected to "login_url". Then, the method tries to authenticate all authenticators. If any authenticator fails, the user is redirected to "authenticate_fail_url". Then, all auth_redirects are checked. If any auth_redirect fails to authenticate, the user will be redirected to the "url" in Web::Authenticate::Authenticator::Redirect::Role for that auth_redirect. auth_redirects are processed in order. This method returns a Web::Authenticate::Result::Authenticate object.

my $authenticate_result = $web_auth->authenticate;

# OR
my $authenticate_result = $web_auth->authenticate(authenticators => $authenticators, auth_redirects => $auth_redirects);

if ($authenticate_result->success) {
    print "User " . $authenticate_result->user->id . " successfully authenticated\n";
} else {
    # failed to authenticate user.
    if ($authenticate_result->failed_authenticator) {
        # this authenticator caused the failure
    }
}

is_authenticated

First makes sure that the user authenticates as being logged in with a session. If the user is not, the user is redirected to "login_url" if redirect is set to 1. Then, the method tries to authenticate all authenticators. If any authenticator fails, the user is redirected to "authenticate_fail_url" if redirect is set to 1. This method returns a Web::Authenticate::Result::IsAuthenticated object.

my $is_authenticated_result = $web_auth->is_authenticated;

# OR
my $is_authenticated_result = $web_auth->is_authenticated(authenticators => $authenticators);

if ($is_authenticated_result->success) {
    print "User " . $is_authenticated_result->user->id . " successfully authenticated\n";
} else {
    # failed to authenticate user.
    if ($is_authenticated_result->failed_authenticator) {
        # this authenticator caused the failure
    }
}

This method does not update the expires time for the session. It does however respect "allow_after_login_redirect_override".

check_for_session

This is meant to be used on the login page if you do not want users to be able to login if they are already authenticated.

$web_authenticate->check_for_session;

# or with auth redirects
$web_authenticate->check_for_session(auth_redirects => $auth_redirects);

Returns Web::Authenticate::Result::CheckForSession.

create_user

This is a convenience method that can be used if the Web::Authenticate::User::Storage::Handler::Role you are using accepts its "store_user" in Web::Authenticate::User::Storage::Handler::Role arguments as:

store_user($username, $password, $user_values)

Such as Web::Authenticate::User::Storage::Handler::SQL.

my $create_user_result = $web_authenticate->create_user(
    username => $username, 
    password => $password, 
    username_verifiers => $username_verifiers, 
    password_verifiers => $password_verifiers,
    user_values => {
        age => $age,
        insert_time => \'NOW()',
    },
);

if ($create_user_result->success) {
    print "User " . $create_user_result->user->id . " created\n";
} else {
    print "username errors: \n";
    for my $verifier (@{$create_user_result->failed_username_verifiers}) {
        print "\t" . $verifier->error_msg . "\n";
    }

    print "password errors: \n";
    for my $verifier (@{$create_user_result->failed_password_verifiers}) {
        print "\t" . $verifier->error_msg . "\n";
    }
}

AUTHOR

Adam Hopkins <srchulo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Adam Hopkins.

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