• NAME
• SYNOPSIS
• INTRODUCTION
• DESCRIPTION
• CONSTRUCTOR
• TICKET GENERATION
• BUGS
• AUTHOR
• COPYRIGHT

NAME

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

SYNOPSIS

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

    # 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();

    # 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. It requires the mod_auth_tkt shared secret (the TKTAuthSecret value) to use with the MD5 hash. The following alternatives are supported - supplying the secret explicitly:

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

or pointing to the apache config file containing the mod_auth_tkt TKTAuthSecret directive, from which Apache::AuthTkt will parse the secret:

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

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. Note that if you are using mod_auth_tkt 'TKTAuthIgnoreIP on', you must pass a false value for this parameter (e.g. undef). Default: $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!

Alternatively, 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

Cookie name. Should match the TKTAuthCookieName directive, if you're using it. Default: 'auth_tkt'.

cookie_domain

Cookie domain. Should match the TKTAuthDomain directive, if you're using it. Default: none.

cookie_path

Cookie path. Default: '/'.

cookie_secure

Flag whether to set the 'secure' cookie flag, so that the cookie is returned only in HTTPS contexts. Default: 0.

BUGS

We should be able to use the mod_auth_tkt Apache configuration directives for our ticket settings instead of forcing the user to pass them again as parameters.

AUTHOR

Gavin Carr <gavin@openfusion.com.au>

COPYRIGHT

Copyright 2001-2005 Open Fusion Pty Ltd. All Rights Reserved.

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