/ 
Apache-AuthTkt-0.07
River stage one • 1 direct dependent • 1 total dependent
/ Apache::AuthTkt

NAME

Apache::AuthTkt - module to generate authentication tickets for mod_auth_tkt apache module.

SYNOPSIS

# Constructor - either (preferred):
$at = Apache::AuthTkt->new(
    conf => '/etc/httpd/conf.d/auth_tkt.conf',
);
# OR:
$at = Apache::AuthTkt->new(
    secret => '818f9c9d-91ed-4b74-9f48-ff99cfe00a0e',
);

# Generate ticket
$ticket = $at->ticket(uid => $username, ip_addr => $ip_addr);

# Or generate cookie containing ticket
$cookie = $at->cookie(
    uid => $username, 
    cookie_name => 'auth_tkt',
    cookie_domain => 'www.openfusion.com.au',
);

# Access the shared secret
$secret = $at->secret();
# If using the 'conf' constructor above, all other TKTAuth attributes 
#   are also available e.g.:
print $at->cookie_name(), $at->ignore_ip(), $at->request_ssl();

# Report error string
print $at->errstr;

INTRODUCTION

Apache::AuthTkt is a module for generating authentication tickets for use with the 'mod_auth_tkt' apache module. Tickets are typically generated by a CGI/mod_perl page when a user has been authenticated. The ticket contains a username/uid for the authenticated user, and often also the IP address they authenticated from, a set of authorisation tokens, and any other user data required. The ticket also includes an MD5 hash of all the included user data plus a shared secret, so that tickets can be validated by mod_auth_tkt without requiring access to the user repository.

See http://www.openfusion.com.au/labs/mod_auth_tkt for mod_auth_tkt itself.

DESCRIPTION

CONSTRUCTOR

An Apache::AuthTkt object is created via a standard constructor with named arguments. The preferred form is to point the constructor to the apache config file containing the mod_auth_tkt TKTAuthSecret directive, from which Apache::AuthTkt will parse the shared secret it needs, as well as any additional TKTAuth* directives it finds:

$at = Apache::Tkt->new(
    conf => '/etc/httpd/conf/auth_tkt.conf',
);

Alternatively, you can pass the mod_auth_tkt shared secret (the TKTAuthSecret value) explicitly to the constructor:

$at = Apache::AuthTkt->new(
    secret => '818f9c9d-91ed-4b74-9f48-ff99cfe00a0e',
);

ACCESSORS

If the 'conf' form of the constructor is used, Apache::AuthTkt parses all additional TKTAuth* directives it finds there and stores them in additional internal attributes. Those values are available via accessors named after the relevant TKTAuth directive (with the 'TKTAuth' prefix dropped and converted to lowercase underscore format) i.e.

$at->secret()
$at->cookie_name()
$at->back_cookie_name()
$at->back_arg_name()
$at->domain()
$at->cookie_expires()
$at->login_url()
$at->timeout_url()
$at->unauth_url()
$at->timeout()
$at->timeout_refresh()
$at->token ()
$at->guest_login()
$at->ignore_ip()
$at->require_ssl()

TICKET GENERATION

Tickets are generated using the ticket() method with named parameters:

# Generate ticket
$ticket = $at->ticket(uid => $username);

Ticket returns undef on error, with error information available via the errstr() method:

$ticket = $at->ticket or die $at->errstr;

ticket() accepts the following arguments, all optional:

uid

uid, username, or other user identifier for this ticket. There is no requirement that this be unique per-user. Default: 'guest'.

ip_addr

IP address associated with this ticket. Default: if $at->ignore_ip is true, then '0.0.0.0', otherwise $ENV{REMOTE_ADDR};

tokens

A comma-separated list of tokens associated with this user. Typically only used if you are using the mod_auth_tkt TKTAuthToken directive. Default: none.

data

Arbitrary user data to be stored for this ticket. This data is included in the MD5 hash check. Default: none.

base64

Flag used to indicate whether to base64-encode the ticket. Default: 1.

ts

Explicitly set the timestamp to use for this ticket. Only for testing!

As an alternative to ticket(), the cookie() method can be used to return the generated ticket in cookie format. cookie() returns undef on error, with error information available via the errstr() method:

$cookie = $at->cookie or die $at->errstr;

cookie() supports all the same arguments as ticket(), plus the following:

Cookie name. Should match the TKTAuthCookieName directive, if you're using it. Default: $at->cookie_name, or 'auth_tkt'.

Cookie domain. Should match the TKTAuthDomain directive, if you're using it. Default: $at->domain.

Cookie path. Default: '/'.

Flag whether to set the 'secure' cookie flag, so that the cookie is returned only in HTTPS contexts. Default: $at->require_ssl, or 0.

TICKET VALIDATION

You may validate a ticket with the parse_ticket() method. parse_ticket() takes one parameter (a ticket value) and returns a hashref with the following key/value pairs:

ts
uid
tokens
data

parse_ticket() will return undef if any errors with the ticket value are encountered.

The parse_ticket() method algorithm is analogous to the function with the same name in the mod_auth_tkt C module.

AUTHOR

Gavin Carr <gavin@openfusion.com.au>

Contributors:

Peter Karman <peter@peknet.com>

COPYRIGHT

Copyright 2001-2008 Open Fusion Pty Ltd.

This program is free software. You may copy or redistribute it under the same terms as perl itself.