NAME

Apache::AuthTypeKey - Apache authorization handler using TypeKey

SYNOPSIS

## In httpd.conf or .htaccess:
PerlModule Apache::AuthTypeKey
PerlSetVar TypeKeyPath /
PerlSetVar TypeKeyLoginScript /login.pl

## These documents require user to be logged in.
<Location /protected>
AuthType Apache::AuthTypeKey
AuthName TypeKey
PerlAuthenHandler Apache::AuthTypeKey->authenticate
require valid-user
PerlSetVar TypeKeyToken your_token
</Location>

## This is the _return URL that the login.pl script should point to.
<Location /login-protected>
AuthType Apache::AuthTypeKey
AuthName TypeKey
SetHandler perl-script
PerlHandler Apache::AuthTypeKey->login
PerlSetVar TypeKeyToken your_token
</Location>

DESCRIPTION

Apache::AuthTypeKey implements Apache authentication and authorization handling using the TypeKey authentication service (http://typekey.com/). TypeKey is Six Apart's free, open service providing a central login for people to comment on weblogs, get access to protected information, etc.

To use Apache::AuthTypeKey, you'll need a TypeKey token that identifies your site. So you'll need to sign up for a TypeKey account at https://www.typekey.com/t/typekey/register, then fill out the Preferences form to include the URI of your application. Specifically, this URI should be the URI for the /login-protected area above, because that's the URI that TypeKey will return to after a user logs in.

Apache::AuthTypeKey is a subclass of Apache::AuthCookie, so it inherits all of that module's cookie-handling and authorization code. It also inherits all of that module's configuration settings and options.

Authentication

Authentication is handled for you through TypeKey, and cookie handling is handled by Apache::AuthCookie. The value of the cookie will be the string returned from TypeKey, including the username, email address, name, and a DSA signature on those values, preventing users from forging the cookie.

Login Screen

The actual login form is on http://www.typekey.com/; the login screen that you'll be providing should be just a simple page linking people to that login screen, along with your TypeKey token and return URI. An example login screen is in eg/login.pl, but you'll probably wish to customize the HTML, as it's fairly plain.

The login script functionality is inherited from Apache::AuthCookie, so it's implemented as a script that you must configure in your httpd.conf or .htaccess. For example:

PerlSetVar TypeKeyLoginScript /login.pl

If you'd rather use a different mechanism for your login screen, you can subclass Apache::AuthTypeKey and override the login_form method. See the Apache::AuthCookie documentation for more details.

Authorization

Apache::AuthTypeKey--coupled with TypeKey--will handle all of the authentication for you, telling you whether someone is a valid TypeKey user. For authorization, you have a couple of options:

• Allow any TypeKey user

  If you'd like to allow any valid TypeKey user, just use

  require valid-user

  as in the SYNOPSIS above.

• Allow only certain TypeKey users

  If you'd like to allow only certain TypeKey users, you can specify their TypeKey usernames in standard require statements. For example:

  require user foo
  require user bar

  This will allow only the TypeKey users foo and bar.

• Override the authorization phase and handle it yourself

  If you'd like to do something more complex, like look up valid TypeKey usernames in a database listing authorized users, you can subclass Apache::AuthTypeKey and override the authorize method. Note that Apache::AuthTypeKey doesn't actually provide its own authorize method anyway--it merely inherits Apache::AuthCookie->authorize.

LICENSE

Apache::AuthTypeKey is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR & COPYRIGHT

Except where otherwise noted, Apache::AuthTypeKey is Copyright 2004 Six Apart Ltd, cpan@sixapart.com. All rights reserved.

SEE ALSO

Apache::AuthCookie, Authen::TypeKey