The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Web-Authenticate-0.003
River stage zero No dependents
++
/ Web::Authenticate

NAME

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

VERSION

version 0.003

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.

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

  • authenticators (optional) - An arrayref of Web::Authenticate::Authenticator::Role. If any of the authenticators does not authenticate, then the user will be redirected to "authenticate_fail_url".

  • redirect (optional) - If set to true, this method will redirect appropriately if the user does not 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" 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".

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.