Manual

Introduction

What is AuthTkt

AuthTkt is three different things:

• a sign in handler - a piece of software to handle user sign ins and set a special signed cookie

• a ticket checker - a piece of software which on each request looks at the special signed cookie to determine:

  • if the user has signed in
  • if the user is still at the same IP address they signed in from
  • if the cookie is still valid
  • the username of the user
  • any tokens and user data associated with the user

• A flows service (flows is a new framework I’m writing) to expose the things above to the developer in an easy way

AuthTkt is designed so that the ticket checking can be handled by Apache mod_auth_tkt rather than the AuthTkt package itself so that for production deployment you can delegate this work to Apache. AuthTkt doesn’t aim to be a copy of mod_auth_tkt, rather it aims to ensure that where functionality overlaps, behaviour is identical to mod_auth_tkt. This might change in the future if I decide to implement SHA hashes instead of MD5 for example.

Of course if you don’t want to use Apache you can use AuthTkt’s implementation instead.

How does it work?

First of all you write a function called validate_sub() to determine whether the username and password a user enters on the sign in screen generated by the sign in handler is correct.

When the user enters a correct username and password your validate_sub() handler can also optionally set two things:

• The user tokens
• The user data

The user tokens are a list of strings which you should restrict to the characters A-Z, a-z, 0-9, - and _. The , character is not allowed. These strings are usually used to represent the roles of the signed in user.

The user data is a single string which is sometimes used to represent the group.

The username, tokens and data, as well as other information such as the time, are all concatentated together in a special way and an MD5 checksum representing the concatentated string is generated and appended to it too. The entire string is then Base64 encoded and set as the value of a cookie. This value is known as the ticket.

On future requests by the same user the ticket is read from the cookie and Base64 decoded. An MD5 checksum is generatated from it again with the same salt and compared with the MD5 checksum found in the cookie value. If they are the same it is assumed the data in the cookie has not been tampered with.

Depending on settings the data is checked to verify the IP address of the user and that the ticket hasn’t expired. If everything is OK, the username, tokens and data are added to the environ (as the REMOTE_USER, REMOTE_USER_DATA and REMOTE_USER_TOKENS environment variables). Otherwise nothing is added.

If you are using the flows service, the data is then read out of the environment and placed into a flow.ticket data structure ready for you to use.

Your application can then determine if a user is signed in and do permission checks based on the data.

What is the benefit of an auth ticket approach?

The benefit of the ticket approach is that it is extremely scalable for one very important reason:

• All group and role data is stored in the cookie so you never need to do any server-side lookups against the username which means no database connections, no sessions to track etc. All nice and easy.

What is the disadvantage?

There are two disadvantages to this though:

• All the username, group and role data is stored in an easily-decodable format in the cookie so anyone intercepting the cookie find out any information about the user stored in the username, user tokens or user data.
• There is no way to track sign-outs. If a user signs out their cookie gets removed but if someone else were to send that same cookie the system would think they were signed in again.
• If someone could guess your salt or crack MD5 they could modify the data in the ticket to pretend to be someone else or change their roles.

In practice these often aren’t a big deal.

For the first problem:

• Never store sensitive data in the cookie to start with
• If things are really that sensitive, make sure every request is over HTTPS rather than HTTP so that the connection is always encrypted anyway

For the second problem:

• Enable IP address checking so the cookie will only be accepted from the IP at which it was created.

For the third problem:

• Always keep the salt you use top secret.
• There isn’t much you can do if people can correctly generate MD5 hashes without the salt, but it might be wise for your implementation to check if lots of bad tickets are coming from the same IP or with similar data as it could indicate a brute-force attack

What parts of mod_auth_tkt are not supported by AuthTkt?

• Single sign on (neither provider nor consumer)
• Guest logins

Using AuthTkt

See the Flows documentation.

Related Software

AuthTkt is usually used in conjunction with the following packages, but can be used standaplone too:

UserManager

A PostgreSQL driver for managing users, groups and roles in a PostgreSQL database. Can be used in the validate_sub() function to get information about a user and check usernames and passwords.

PermissionKit

A set of simple tools for checking permissions. Can be used to check the group and roles stored in the user data and user tokens of a cookie ticket.

Apache Options

Caution

At the moment, only the options described in the Using AuthTkt section actually work in AuthTkt. The others are best ignored for the time being.

Server Directives

mod_auth_tkt requires one apache server-level directive - the shared secret used for MD5 hashing. May be global or specific to a virtual host.

TKTAuthSecret <secret>

String - the secret used for MD5 hashing. This should be kept secret and changed periodically. e.g.

TKTAuthSecret "w b@5b15#664038f.f9d8U19b7e25 664eY9ad2%4393e,a2ef"

Directory Directives

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.

Apache Setup

AuthType Basic / require <users>

mod_auth_tkt requires the following standard apache authentication directives to trigger authentication:

AuthType Basic
require valid-user      # or require user1, user2, etc.

AuthTkt Setup

TKTAuthLoginURL <url>

Standard URL to which unauthenticated users are redirected. This is a required directive unless you are using guest mode via ‘TKTAuthGuestLogin on’. e.g.

TKTAuthLoginURL https://www.example.com/auth/login.cgi

TKTAuthTimeoutURL <url>

URL to which users are redirected in the event their ticket times out. Default: TKTAuthLoginURL. e.g.

TKTAuthTimeoutURL https://www.example.com/auth/login.cgi?timeout=1

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.

TKTAuthPostTimeoutURL https://www.example.com/auth/login.cgi?posttimeout=1

TKTAuthUnauthURL <url>

URL to which users are redirected in the event that they are not authorised for a particular area e.g. incorrect tokens.

TKTAuthUnauthURL https://www.example.com/auth/login.cgi?unauth=1

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. e.g.

TKTAuthGuestLogin on

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.

TKTAuthGuestCookie on

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 (but not on apache 1.3.x, as yet), 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:

TKTAuthGuestUser visitor
TKTAuthGuestUser guest-%12U

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.

Default: off.

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 86400
TKTAuthTimeout 1w
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.

TKTAuthTimeoutRefresh 0.66

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 course).

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. Examples:

TKTAuthCookieExpires 86400
TKTAuthCookieExpires 1w
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:

back=http%3A%2F%2Fwww.example.com%2Findex.html

to the TKTAuthLoginURL it redirects to, allowing your login script to redirect back to the requested page upon successful login. Default: ‘back’. 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). Default: none. 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 are ORed.

Default: none. e.g.

TKTAuthToken finance
TKTAuthToken admin

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. e.g.

TKTAuthIgnoreIP on

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.

TKTAuthRequireSSL on

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.

TKTAuthCookieSecure on

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 SSL).

Example Apache Configurations

Minimal config using logins:

<Location /secret1>
  AuthType Basic
  require valid-user
  TKTAuthLoginURL https://www.example.com/auth/login.cgi
</Location>

Minimal config using guest logins (users can still login explicitly, of course):

<Location /secret2>
  AuthType Basic
  require valid-user
  TKTAuthGuestLogin on
</Location>

Example internet configuration:

<Location /secret3>
  AuthType Basic
  require valid-user
  TKTAuthLoginURL https://www.example.com/auth/login.cgi
  TKTAuthTimeoutURL https://www.example.com/auth/login.cgi?timeout=1
  TKTAuthPostTimeoutURL https://www.example.com/auth/login.cgi?timeout=1&post=1
  TKTAuthIgnoreIP on
  TKTAuthTimeout 2h
  TKTAuthCookieExpires 2h
</Location>

Example intranet configuration:

<Location /secret4>
  AuthType Basic
  require valid-user
  TKTAuthGuestLogin on
  TKTAuthLoginURL https://www.example.com/auth/login.cgi
  TKTAuthTimeoutURL https://www.example.com/auth/login.cgi?timeout=1
  TKTAuthPostTimeoutURL https://www.example.com/auth/login.cgi?timeout=1&post=1
  TKTAuthTimeout 4h
  TKTAuthCookieExpires 4h
</Location>

Support

Support for mod_auth_tkt itself is available on the mod_auth_tkt mailing list, courtesy of sourceforge:

List

modauthtkt-users@lists.sourceforge.net

List Page and Signup

https://lists.sourceforge.net/lists/listinfo/modauthtkt-users

List Archive

http://sourceforge.net/mailarchive/forum.php?forum=modauthtkt-users

There is no support for this Python AuthTkt package though.

Internal Code

The internal code is a bit of a mess because it half tries to implement the mod_auth_tkt code and reflect its Perl structure and half tries to be its own thing.

Important sections of the code are:

authtkt.AuthTkt()

This holds the options used to create new cookies when a user successfully authenticates and is also used for creating cookie tickets and checking existing tickets are valid.

authtkt.service

A service which is exposes the data stored in the ticket if it has been successfully checked

Arguments for the service include:

secret

This must be the same secret used in the configuration file under the TKTAuthSecret option.

cookie_name

The name of the cookie. Usually should be the string "auth_tkt".

ignore_ip

Can be True or False and should match the value specified in TKTAuthIgnoreIP

authtkt.ext

A Flows extension for handling sign in and sign out in a Flows application.

Relies on:

conf

Options describing how the handler itself functions. Internally the validate_sub() is confgured via this object.