The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache-AuthTkt-2.1
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',
        digest_type => 'MD5',
    );

    # 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 and validating authentication tickets used with the 'mod_auth_tkt' apache module. Tickets are typically generated by a login web page of some kind 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) and the digest_type to use (default is 'MD5') explicitly to the constructor:

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

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->secret_old()
    $at->digest_type()
    $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 PARSING AND VALIDATION

You may parse and validate existing tickets with the validate_ticket() method. It takes as its first parameter the ticket to be validated, and then an optional list of named parameter overrides (e.g. ip_addr => 'x.x.x.x'). If the ticket is valid, validate_ticket returns a hashref with the following key/value pairs:

digest
ts
uid
tokens
data

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

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

There is also a parse_ticket() method available that parses the ticket without running it through the validation phase, and returns the same data as validate_ticket(). This is only safe to use where you are certain that the ticket has been validated elsewhere. In general it's considerably safer to just use validate_ticket.

DIGEST TYPES

As of version 2.1.0, mod_auth_tkt supports multiple digest types. The following digest_types are currently supported:

MD5

The current default, for backwards compatibility. Requires the Digest::MD5 perl module.

SHA256

Requires the Digest::SHA perl module.

These can be set either via your config (the TKTAuthDigestType directive) or by passing a 'digest_type' parameter to the AuthTkt constructor.

AUTHOR

Gavin Carr <gavin@openfusion.com.au>

Contributors:

Peter Karman <peter@peknet.com>

Ton Voon <ton.voon@altinity.com>

Jose Luis Martinez <jlmartinez@capside.com>

COPYRIGHT

Copyright 2001-2009 Gavin Carr and contributors.

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