Guide Home
POD Home

Sloop::Client::TokenAuth

DESCRIPTION

Implements client authentication using cookies. A TokenAuth object is associated with a single cookie name. TokenAuth provides a random base 62 token for each client to be used as the cookie value; it does not actually set the cookie as this must be done in an HTTP response. It can do subsequent validation of a Sloop::Client object.

SYNOPSIS

 use Sloop::Client::TokenAuth;
 my $auth = Sloop::Client::TokenAuth->new (
        cookieName => [REQUIRED] string
        duration => [REQUIRED] integer
        attributes => [optional] hash ref
        checkIP => [optional] 0/undef or non-zero/defined
        tokenSize => [optional] integer
 );
cookieName

The name to use to identify cookies. There should be no whitespace or any of the following characters: ( ) < > @ , ; : \ / " { } [ ] ? =

Those will be pruned out; you can check post construction in the cookieName attribute.

duration

How long a cookie remains valid for, in minutes.

attributes

A hash ref with the following (all optional) fields. For more information, see RFC 6265.

domain

To be used as the value of a cookie's Domain attribute.

path

To be used as the value of a cookie's Path attribute.

secure

If true, the Secure attribute will be added to cookies. Make sure you use this if you are using Sloop::Client::Secure.

httpOnly

If true, the HttpOnly attribute will be added to cookies.

checkIP

If defined validate() calls will confirm that the IP address of the client is the same as when the cookie was set; if not, validation fails. The default is to not do this.

This does not mean there can only be one client per IP address, just that a token associated with a given IP address cannot be used from a different address.

tokenSize

The length of the base 62 token; the default is 6, which is ~57 billion possible combinations.

ATTRIBUTES

Referring to object and not cookie attributes.

The cookieName, tokenSize and checkIP parameters from the constructor may be accessed as attributes of the same name.

cookieAttr

This only exists if an 'attributes' hash was defined in the constructor call. It is an array of strings used when setting cookies.

duration

This is the same as the constructor argument but in seconds. It is modifiable.

validTokens

This is a hash ref keyed by token. Generally you should not have to make use of it, but if you want to, e.g., suddenly invalidate everyone, you can $auth->{validTokens}={}.

METHODS

$auth->add($ip, $sessionData)

Creates a new token and returns it. The token should be submitted to the client (e.g., via a "Set-Cookie:" header line) as the value half of the cookie. For example, if the cookie name (given to the constructor) is "Chocolate" and the token returned is "ABC123", the basic cookie would be "Chocolate=ABC123". The cookie() method can be used to construct a complete header cookie line with attributes.

$ip is a string IP address to associate the cookie with. If $auth->{checkIP} is not set, this doesn't matter -- just don't change that later.

$sessionData is an optional scalar or reference (to anything) to attach to each token. This can be retrieved via fetch().

An example:

 my $token = $auth->add($client->{ip});
 my $cookie = $auth->cookie($token);
 $client->reply(\$page, cookies => [ $cookie ]);

$auth->cookie($token, $suffix)

This is a wrapper around Sloop::Lib::makeCookie(), and returns a line suitable for setting a cookie via the HTTP "Set-Cookie" header, etc. This is the cookie required by and checked for by TokenAuth. See the 'cookies' parameter to Sloop::Client::reply() for an easy way to use this.

$token should be the value returned by add() for the client in question.

$suffix is an optional suffix to append to the cookie name to facilitate the use of multiple tokens on the same client browser (e.g., for logins as a different user).

Any cookie attributes passed to the TokenAuth constructor are included.

$auth->fetch($token)

Returns whatever was submitted as the $sessionData arg to add(), for the record associated with $token.

$auth->delete($client, $suffix)

Removes a cookie record; attempts to authenticate with the associated token will subsequently fail.

$client is a Sloop::Client derived object with an associated Sloop::Client::Request object object attached.

$suffix should be the same as was used for this client with cookie().

$auth->update($token, $suffix)

This updates the valid duration of $token by setting its timestamp to now; i.e., increasing it by the value of the duration attribute of $auth.

In order for this to be effective, the new duration must be returned to the client or the cookie will be removed by the browser. To that end, this method returns the same thing as auth->cookie($token), and $suffix has the same significance as there.

Note that the validity of $token is not checked, and if you haven't called $auth->validate($token) yet, it may have expired already. However, if $token was previously purged, it will return undef. This is guaranteed not to happen between calls of validate() and update() in the same handler.

$auth->validate($client, $suffix)

Checks a client request to see it if includes our cookie. If so, and the cookie is still valid, it returns the associated unique token for this client (the same one returned by add(), which you can use with fetch()). If not, it returns 0.

$client is a Sloop::Client derived object. This should have a Sloop::Request object attached to it that has not been responded to yet.

$suffix has the purpose and significance described for the cookie() method.