NAME

Web::Authenticate::Session::Storage::Handler::SQL - Implementation of Web::Authenticate::Session::Storage::Handler::Role that can be used with MySQL or SQLite.

VERSION

version 0.013

DESCRIPTION

This Web::Authenticate::Session::Storage::Handler::Role is meant to be used with a very specific table structure:

    CREATE TABLE sessions (
        id INTEGER PRIMARY KEY AUTO_INCREMENT,
        user_id INTEGER NOT NULL UNIQUE,
        session_id VARCHAR(255) NOT NULL UNIQUE,
        expires INTEGER NOT NULL
    );

Other columns can exists, and the names of the table and column can change. But at least these columns must exist in order for this storage handler to work properly. Also, the primary key does not have to be an integer, and could even be the session_id. Also, the user_id does not need to be unique if you want to allow multiple sessions for a user by setting "allow_multiple_sessions_per_user" in Web::Authenticate to true.

METHODS

user_storage_handler

Sets the Web::Authenticate::User::Storage::Handler::Role to be used. This is required. Default is Web::Authenticate::User::Storage::Handler::SQL created with "dbix_raw".

sessions_table

Sets the name of the sessions table that will be used when querying the database. Default is 'sessions'.

session_id_field

Sets the name of the session id field that will be used when querying the database. Default is 'session_id'.

user_id_field

Sets the name of the user_id field that will be used when querying the database. Default is 'user_id'.

require_same_user_agent

A session id will only be valid from the user agent it was originally created on. If invalid, the session will be deleted in storage. If this is set to true, a user agent field is required in the table. It should be a varchar 255 like so:

    CREATE TABLE sessions (
        id INTEGER PRIMARY KEY AUTO_INCREMENT,
        user_id INTEGER NOT NULL UNIQUE,
        session_id VARCHAR(255) NOT NULL UNIQUE,
        user_agent VARCHAR(255),
        expires INTEGER NOT NULL
    );

See "user_agent_field" to change the default name of the field.

require_same_ip_address

A session id will only be valid from the ip address it was originally created from. If invalid, the session will be deleted in storage. If this is set to true, an ip address field is required in the table. It should be a varchar 255 like so:

    CREATE TABLE sessions (
        id INTEGER PRIMARY KEY AUTO_INCREMENT,
        user_id INTEGER NOT NULL UNIQUE,
        session_id VARCHAR(255) NOT NULL UNIQUE,
        ip_address VARCHAR(255),
        expires INTEGER NOT NULL
    );

See "ip_address_field" to change the default name of the field.

digest

Sets the Web::Authenticate::Digest::Role that is used for user agents if "require_same_user_agent" is set to true or ip addresses if "require_same_ip_address" is set to true. Default is Web::Authenticate::Digest.

user_agent_provider

Sets the object that does Web::Authenticate::UserAgentProvider::Role. Default is Web::Authenticate::UserAgentProvider::EnvUserAgentProvider.

ip_address_provider

Sets the object that does Web::Authenticate::IpAddressProvider::Role. Default is Web::Authenticate::IpAddressProvider::EnvIpAdderssProvider.

user_agent_field

Sets the name of the user agent field if "require_same_user_agent" is set to 1. Default is 'user_agent'.

ip_address_field

Sets the name of the ip address field if "require_same_ip_address" is set to 1. Default is 'ip_address'.

expires_field

Sets the name of the expires time field that will be used when querying the database. Default is 'expires'.

dbix_raw

Sets the DBIx::Raw object that will be used to query the database. This is required with no default.

columns

The columns to select. At a minimum, "session_id_field", "user_id_field", and "expires_field" will always be selected.

    $storage_handler->columns([qw/session_data/]);

Default is an empty array ref.

session_id_digest_hex

This is a subroutine reference to the digest hex that will be used when storing the session id. Default is Digest::SHA::sha512_hex.

store_session

Takes in user, session_id, expires, and any additional values for columns in a hash and a session with those values is created. Returns a Web::Authenticate::Session with any values from "columns" stored in "row" in Web::Authenticate::Session.

    my $session_values => {
        session_data => $session_data,
    };
    my $session = $session_storage_handler->store_session($user, $session_id, $expires, $session_values);

    # if you need no extra user values in the row
    my $session = $storage_handler->store_session($user, $session_id, $expires);

load_session

Loads a Web::Authenticate::Session by session_id. If the session exists, the session is returned. Otherwise, undef is returned. Undef will also be returned if the session is expires, or if the user agent or ip address don't match if "require_same_user_agent" or "require_same_ip_address" are set. Any additional "columns" will be stored in "row" in Web::Authenticate::Session.

    my $session = $session_storage_handler->load_session($session_id);

delete_session

Deletes a session from storage.

    $session_storage_handler->delete_session($session_id);

invalidate_user_sessions

Invalidates (deletes) any user sessions for user.

    $session_storage_handler->invalidate_user_sessions($user);

update_expires

Updates the expires time for the session with the session id session_id.

    $session_storage_handler->update_expires($session_id, $expires);

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.

cpanm Web::Authenticate

perl -MCPAN -e shell
install Web::Authenticate