mod_auth_tkt - apache ticket authentication module
mod_auth_tkt is a lightweight cookie-based authentication module, written in C,
for apache versions 1.3.x, 2.0.x, and 2.2.x It implements a single-signon
framework that works across multiple apache instances, different apache
versions, and multiple machines.
mod_auth_tkt itself is completely repository-agnostic, as the actual
authentication is done by a user-supplied CGI or script in your language of
choice (examples are provided in Perl, with contrib libraries for use with
python and PHP). This allows authentication against virtually any kind of user
repository you can imagine (password files, ldap directories, databases, etc.)
mod_auth_tkt supports inactivity timeouts (including the ability to control how
aggressively the ticket is refreshed), the ability to include arbitrary user
data within the cookie, configurable cookie names and domains, token-based
access to subsections of a site, and optional 'guest' access for
mod_auth_tkt is configured in your apache configuration files using the
following set of directives (all mod_auth_tkt directives begin with
mod_auth_tkt supports two apache server-level directives, one required -
TKTAuthDigest, the shared secret used for digest hashing - and one optional -
TKTAuthDigestType, the type of digest to use in ticket hashes. Both may be
global or specific to a virtual host.
- TKTAuthSecret <secret>
- String - the secret used for digest hashing. This should be kept secret
and changed periodically. e.g.
TKTAuthSecret "w b@5b15#664038f.f9d8U19b7e25 664eY9ad2%4393e,a2ef"
- TKTAuthDigestType [ MD5 | SHA256 | SHA512 ]
- String, one of MD5 | SHA256 | SHA512. The digest/hash type to use in
tickets. The default is MD5, which is faster, but has now been shown to be
vulnerable to collision attacks. Such attacks are not directly applicable
to mod_auth_tkt, which primarily relies on the security of the shared
secret rather than the strength of the hashing scheme. More paranoid users
will probably prefer to use one of the SHA digest types, however.
The default is likely to change in a future version, so setting the digest
type explicitly is encouraged.
Note that using one of the SHA digest types with the perl CGI scripts
requires a version of Apache::AuthTkt >= 2.1.
All directory-level directives are optional, except that either TKTAuthLoginURL
or TKTAuthGuestLogin (or both) must be set to cause mod_auth_tkt to be invoked
for a particular directory. As usual, directory-level directives may be set in
Directory or Location sections, or in .htaccess files.
- AuthType None / require <users>
- mod_auth_tkt requires the following standard apache authentication
directives to trigger authentication:
require valid-user # or require user1, user2, etc.
- TKTAuthLoginURL <url>
- Standard URL to which unauthenticated users are redirected. This is a
required directive unless you are using guest mode via 'TKTAuthGuestLogin
- TKTAuthTimeoutURL <url>
- URL to which users are redirected in the event their ticket times out.
Default: TKTAuthLoginURL. e.g.
- TKTAuthPostTimeoutURL <url>
- URL to which users are redirected in the event their ticket times out
during a POST operation. This case is distinguished to allow you to handle
such cases specially - you probably don't want to redirect back to the
referrer after login, for instance. Default: TKTAuthTImeoutURL. e.g.
- TKTAuthUnauthURL <url>
- URL to which users are redirected in the event that they are not
authorised for a particular area e.g. incorrect tokens.
- TKTAuthGuestLogin <boolean>
- Flag to turn on 'guest' mode, which means that any user without a valid
ticket is authenticated anyway as the TKTAuthGuestUser user. This is
useful for allowing public access for guests and robots, while allowing
more personalised or privileged access for users who login. Default: off.
- TKTAuthGuestCookie <boolean>
- Flag to indicate whether or not to issue a ticket cookie for guest users.
Issuing a cookie is primarily useful where you are using UUID-ed guest
users where you want them to keep the initial guest username you issue
them for tracking purposes. e.g.
Default is 'off', unless you use a TKTAuthGuestUser with a UUID (see next),
in which case it's 'on'. Setting explicitly is recommended, however.
- TKTAuthGuestUser <string>
- Username to be used for the guest user (in the ticket uid, REMOTE_USER
environment variable, etc).
On apache 2.0.x and 2.2.x (but not on apache 1.3.x), the TKTAuthGuestUser
may also contain a special sprintf-like pattern '%U', which is expanded to
36-character UUID, allowing individualised guest usernames. The %U may
also include an integer <= 36 to limit the number of characters used in
the UUID e.g. %12U, %20U etc.
Default: 'guest'. Examples:
- TKTAuthGuestFallback <boolean>
- Flag to indicate that a timed out user ticket should automatically
fallback to 'guest' status, and issue a new guest ticket, instead of
redirecting to the TKTAuthTimeoutURL. Only makes sense with
TKTAuthGuestLogin on, of course.
- TKTAuthTimeout <seconds>
- The ticket timeout period, in seconds. After this period, the ticket is
considered stale, and the user is redirected to the TKTAuthTimeoutURL (if
set, else to the TKTAuthLoginURL). Note that the ticket can be
automatically refreshed, however, using the next setting.
The following units can also be specified on the timeout (with no spaces
between timeout and unit): y/years, M/months, w/weeks, d/days, h/hours,
m/minutes, and s/seconds.
This timeout is protected by the ticket hashing, so cannot be trivially
modified, unlike the TKTAuthCookieExpires setting below.
Setting TKTAuthTimeout to 0 means never timeout, but this is strongly
discouraged, as it allows for trivial replay attacks. Set it to a week or
two if you really don't want timeouts.
Default: 2h. Examples:
TKTAuthTimeout 1w 4d 3h
- TKTAuthTimeoutRefresh <decimal>
- A number between 0 and 1 indicating whether and how to refresh ticket
timestamps. 0 means never refresh (hard timeouts). 1 means refresh tickets
every time. .33 (for example) means refresh if less than .33 of the
timeout period remains.
This is a politeness setting for those paranoid types who have their
browsers set to confirm all cookies - refreshing every time quickly
becomes VERY tedious. Default: 0.5. e.g.
- TKTAuthCookieName <name>
- The name used for the ticket cookie. Default: 'auth_tkt'.
- TKTAuthDomain <domain>
- The domain to use in ticket cookies, which defines the hosts for which the
browser will submit this cookie. Default: the apache ServerName (either
global or for a specific virtual host).
- TKTAuthCookieExpires <seconds>
- NB: This directive is not currently supported on apache 1.3.x!
The period until the cookie expires, used to set the 'expires' field on the
ticket cookie, in seconds. This is useful if you want cookies to persist
across browser sessions (and your login script must support it too, of
The following units can also be specified on the expiry period (with no
spaces between period and unit): y/years, M/months, w/weeks, d/days,
h/hours, m/minutes, and s/seconds.
Note that his is a client-side setting and is not protected by the
ticket hashing, so you should always set a TKTAuthTimeout in addition to
using an expiry. Cookie expiries are refreshed with tickets if
TKTAuthTimeoutRefresh is set.
Default: none (not used).
TKTAuthCookieExpires 1w 3d 4h
- TKTAuthBackArgName <name>
- The name used for the back GET parameter. If this is set, mod_auth_tkt
will add a GET parameter to all redirect URLs containing a URI-escaped
version of the current requested page e.g. if the requested page is
http://www.example.com/index.html and TKTAuthBackArgName is set to 'back',
mod_auth_tkt will add a parameter like:
to the TKTAuthLoginURL it redirects to, allowing your login script to
redirect back to the requested page upon successful login.
To omit altogether, set to the string None i.e.
- TKTAuthBackCookieName <name>
- The cookie name to use for the back cookie. If this is set, mod_auth_tkt
will set a back cookie containing a URI-escaped version of current
requested page when redirecting (see TKTAuthBackArgName above), instead of
using a GET parameter.
Default: none (not used).
- TKTAuthToken <token>
- String indicating a required token for the given location, implementing a
simple form of token-based access control. If the user's ticket does not
contain one or more of the required tokens in the ticket token list then
mod_auth_tkt will redirect to the TKTAuthUnauthURL location (or
TKTAuthLoginURL if not set). Your login script is expected to set the
appropriate token list up at login time, of course.
Note that this directive can be repeated, and the semantics are that
any of the required tokens is sufficient for access i.e. the tokens
Default: none (not used).
- TKTAuthIgnoreIP <boolean>
- Flag indicating that mod_auth_tkt should ignore the client IP address in
authenticating tickets (your login script must support this as well,
setting the client IP address to 0.0.0.0). This is often required out on
the open internet, especially if you are using an HTTPS login page (as you
should) and are dealing with more than a handful of users (the typical
problem being transparent HTTP proxies at ISPs).
Default: 'off' i.e. ticket is only valid from the originating IP address.
- TKTAuthRequireSSL <boolean>
- Flag used to indicate that tickets should be refused except in SSL/HTTPS
protected contexts (redirects to TKTAuthLoginURL if not, which presumably
would be using HTTPS). Default: 'off' ( don't require SSL). e.g.
See also TKTAuthCookieSecure below.
- TKTAuthCookieSecure <boolean>
- Flag used to set the 'secure' flag on all ticket cookies issued,
indicating to the browser that they should only be sent in SSL/HTTPS
protected contexts. Default: 'off' ( don't set 'secure' flag). e.g.
TKTAuthRequireSSL and TKTAuthCookieSecure are normally used together. One
case where it makes sense to use them separately is where you are proxying
through a separate SSL-equipped reverse proxy, where you would want to use
TKTAuthCookieSecure by itself (since the proxied request will never be via
- TKTAuthDebug <integer>
- Turn on mod_auth_tkt debug output messages in your error log, with
verbosity increasing with higher integer values. Current range: 1-3.
Note that you will also require apache 'LogLevel debug' set to see these
Minimal config using logins:
Minimal config using guest logins (users can still login explicitly, of course):
Example internet configuration:
Example intranet configuration:
Support is available on the mod_auth_tkt mailing list, courtesy of sourceforge:
- List Page and Signup
- List Archive
Ticket payload should include IP address, to make debugging IP address problems
Gavin Carr <firstname.lastname@example.org>
mod_auth_tkt is licensed under the terms of the Apache Licence.