The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


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


    # 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 => '',

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


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 for mod_auth_tkt itself.



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


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->token ()


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, username, or other user identifier for this ticket. There is no requirement that this be unique per-user. Default: 'guest'.


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


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.


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


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


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.


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:


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.


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


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


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.


Gavin Carr <>


Peter Karman <>

Ton Voon <>

Jose Luis Martinez <>


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.