Stephen Olander-Waters > Apache2-AuthTicketLDAP-0.02 > Apache2::AuthTicketLDAP

Download:
Apache2-AuthTicketLDAP-0.02.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.02   Source  

NAME ^

Apache2::AuthTicketLDAP - Cookie Ticketing with LDAP Authentication

VERSION ^

version 0.02

SYNOPSIS ^

 The documentation is largely the same as I<Apache2::AuthTicket>, however, with 
 a few addenda. A typical installation will look like:

 # in httpd.conf
 PerlModule Apache2::AuthTicketLDAP
 PerlSetVar AuthCookieDebug 3 #Useful for debugging
 PerlSetVar AuthTicketLDAPCacheDir "/var/cache/apache"
 PerlSetVar AuthTicketLDAPCacheSize "4m"
 PerlSetVar AuthTicketLDAPCachePageSize "4096"
 PerlSetVar AuthTicketLDAPCacheTTL "10m"
 PerlSetVar AuthTicketLDAPStmtCacheSize "4m"
 PerlSetVar AuthTicketLDAPStmtCachePageSize "4096"
 PerlSetVar AuthTicketLDAPStmtCacheTTL "1m"
 PerlSetVar FooCookieName "MyCookie"
 PerlSetVar FooSatisfy any
 PerlSetVar FooTicketDB dbi:mysql:database=mschout;host=testbed
 PerlSetVar FooTicketDBAutoCommit 0
 PerlSetVar FooTicketDBUser test
 PerlSetVar FooTicketDBPassword secret
 PerlSetVar FooTicketTable tickets:ticket_hash:ts
 PerlSetVar FooTicketSecretTable ticket_secrets:sec_data:sec_version
 PerlSetVar FooTicketExpires 45
 PerlSetVar FooTicketIdleTimeout 30
 PerlSetVar FooTicketThreshold 60
 PerlSetVar FooTicketLogoutURI /foo/index.html
 PerlSetVar FooTicketLoginHandler /foologin
 PerlSetVar FooLoginScript /foologinform
 PerlSetVar FooPath /
 PerlSetVar FooDomain .foo.com
 PerlSetVar FooSecure 1
 PerlSetVar FooLDAPURL "ldap://ldap.foo.com:389"
 PerlSetVar FooLDAPDN "dc=foo,dc=com"
 PerlSetVar FooLDAPScope "one"
 PerlSetVar FooLDAPFilter "uid=MYUSER"

 <Location /foo>
     AuthType Apache2::AuthTicketLDAP
     AuthName Foo
     PerlAuthenHandler Apache2::AuthTicketLDAP->authenticate
     PerlAuthzHandler Apache2::AuthTicketLDAP->authorize
     require ldap_attribute allowedFoo=Yes
     require valid-user
 </Location>
 
 <Location /foologinform>
     AuthType Apache2::AuthTicketLDAP
     AuthName Foo
     SetHandler perl-script
     PerlResponseHandler Apache2::AuthTicketLDAP->login_screen
 </Location>

 # Or for a mod_perl script to handle logins, store /foologinform in here and 
 # change:  PerlSetVar FooLoginScript /my/path/cgi-bin/foologinform
 <Directory /my/path/cgi-bin>
     Options ExecCGI
     SetHandler perl-script
     PerlResponseHandler ModPerl::Registry
     PerlOptions +ParseHeaders
     AllowOverride none
     Order allow,deny
     Allow from all
 </Directory>
 
 <Location /foologin>
     AuthType Apache2::AuthTicketLDAP
     AuthName Foo
     SetHandler perl-script
     PerlResponseHandler Apache2::AuthTicketLDAP->login
 </Location>
 
 <Location /foo/logout>
     AuthType Apache2::AuthTicketLDAP
     AuthName Foo
     SetHandler perl-script
     PerlResponseHandler Apache2::AuthTicketLDAP->logout
 </Location>

DESCRIPTION ^

This module builds upon the Apache2::AuthTicket database-backed, cookie ticketing system for websites. It provides for authentication and authorization against an LDAP database. It also implements CHI-based, mmap'd file caching of LDAP entries and SELECT queries.

Further differences between the two modules include: 1) Custom dbi_connect, supporting: a) passwordless local connections b) AutoCommit via TicketDBAutoCommit option c) a couple of Informix-specific options (ISOLATION and LOCK MODE) 2) Use SHA512 instead of MD5 for digests 3) Support "require ldap_attribute myAttrib=Foo" 4) TicketThreshold: Only update database when a ticket timestamp is at least X seconds old. Reduces database updates.

Keep in mind that the mmap caching will make apache processes look huge. It is an illusion -- cached files are only mapped into memory once.

LDAP authentication processing works similarly to mod_ldap/mod_authnz_ldap. 1) An anonymous search looks up a user on the LDAP server. Returns 403 if unsuccessful. Otherwise, the entry is cached. 2) That user's LDAP entry DN and password is used to bind to the server. Returns 403 if unsuccessful, OK if successful.

On the database side, everything works the same as Apache2::AuthTicket except that users are authenticated and authorized with LDAP instead.

Authorization works similarly to mod_ldap/mod_authnz_ldap. 1) require valid-user works as usual. 2) require ldap-attribute was changed to require ldap_attribute (note the underscore). a) The cache is checked for an LDAP entry for the user. b) If it exists and is not expired, that entry is used. c) Otherwise, a new anonymous search is performed and cached. d) If the attribute value does not match, return 403. Otherwise, OK.

CONFIGURATION ^

These are the things you must do in order to configure this module:

 1) Configure your mod_perl apache server.
 2) Create the necessary database tables.
 3) Add a secret to the secrets table.
 4) Ensure the cache directory exists and is read/write for the forked apache 
    user or group.

Apache Configuration - httpd.conf

There are a number of additional configuration variables required by this module. Otherwise, configuration is largely the same as with Apache2::AuthTicket.

Additional per-AuthName variables supported by the Apache2::AuthTicket configuration mechanism: * PerlSetVar SEULDAPURL "ldap://ldap.foo.com:389" * PerlSetVar SEULDAPDN "dc=foo,dc=com" * PerlSetVar SEULDAPScope "one" * PerlSetVar SEULDAPFilter "uid=MYUSER" * PerlSetVar SEUTicketDBAutoCommit 0

Additional variables that are defined once in httpd.conf and are global for all AuthNames and are not configurable through configure(): * PerlSetVar AuthTicketLDAPCacheDir "/var/cache/apache" * PerlSetVar AuthTicketLDAPCacheSize "4m" * PerlSetVar AuthTicketLDAPCachePageSize "4096" * PerlSetVar AuthTicketLDAPCacheTTL "10m" * PerlSetVar AuthTicketLDAPStmtCacheSize "4m" * PerlSetVar AuthTicketLDAPStmtCachePageSize "4096" * PerlSetVar AuthTicketLDAPStmtCacheTTL "1m"

There are four blocks that need to be entered into httpd.conf. The first of these is the block specifying your access restrictions. This block should look somrthing like this:

 <Location /foo>
     AuthType Apache2::AuthTicketLDAP
     AuthName Foo
     PerlAuthenHandler Apache2::AuthTicketLDAP->authenticate
     PerlAuthzHandler Apache2::AuthTicketLDAP->authorize
     require valid-user
     require ldap_attribute myAttrib=Foo
 </Location>

The remaining blocks control how to display the login form, and the login and logout URLs. These blocks should look similar to this:

 <Location /foologinform>
     AuthType Apache2::AuthTicketLDAP
     AuthName Foo
     SetHandler perl-script
     PerlResponseHandler Apache2::AuthTicketLDAP->login_screen
 </Location>
 
 # Or for a mod_perl script to handle logins, store /foologinform in here and 
 # change:  PerlSetVar FooLoginScript /my/path/cgi-bin/foologinform
 <Directory /my/path/cgi-bin>
     Options ExecCGI
     SetHandler perl-script
     PerlResponseHandler ModPerl::Registry
     PerlOptions +ParseHeaders
     AllowOverride none
     Order allow,deny
     Allow from all
 </Directory>

 <Location /foologin>
     AuthType    Apache2::AuthTicketLDAP
     AuthName    Foo
     SetHandler  perl-script
     PerlResponseHandler Apache2::AuthTicketLDAP->login
 </Location>
 
 <Location /foo/logout>
     AuthType Apache2::AuthTicketLDAP
     AuthName Foo
     SetHandler perl-script
     PerlResponseHandler Apache2::AuthTicketLDAP->logout
 </Location>

Apache Configuration - startup.pl

Any non-global Apache2::AuthTicketLDAP configuration items can be set in startup.pl. You can configure an AuthName like this:

 Apache2::AuthTicketLDAP->configure(String auth_name, *Hash config)

When configuring this way, you don't prefix the configuration items with the AuthName value like you do when using PerlSetVar directives.

You must still include Apache2::AuthCookie configuration directives and Apache2::AuthTicketLDAP global variables in httpd.conf when configuring the server this way. These items include:

  * PerlSetVar FooPath /
  * PerlSetVar FooDomain .foo.com
  * PerlSetVar FooSecure 1
  * PerlSetVar FooLoginScript /foologinform
  * PerlSetVar AuthTicketLDAPCacheDir "/var/cache/apache"
  * PerlSetVar AuthTicketLDAPCacheSize "4m"
  * PerlSetVar AuthTicketLDAPCachePageSize "4096"
  * PerlSetVar AuthTicketLDAPCacheTTL "10m"
  * PerlSetVar AuthTicketLDAPStmtCacheSize "4m"
  * PerlSetVar AuthTicketLDAPStmtCachePageSize "4096"
  * PerlSetVar AuthTicketLDAPStmtCacheTTL "1m"

Example of configure(): Apache2::AuthTicketLDAP->configure('Foo', { TicketDB => 'DBI:mysql:database=test;host=foo', TicketDBUser => 'mschout', TicketDBPassword => 'secret', TicketTable => 'tickets:ticket_hash:ts', TicketSecretTable => 'ticket_secrets:sec_data:sec_version', TicketExpires => '15', TicketLogoutURI => '/foo/index.html', TicketLoginHandler => '/foologin', TicketIdleTimeout => 5, TicketThreshold => 60, LDAPURL => 'ldap://ldap.foo.com:389', LDAPDN => 'dc=foo,dc=com', LDAPScope => 'one', LDAPFilter => 'uid=MYUSER', TicketDBAutoCommit => 0, });

Configuration is the same as with Apache2::AuthTicket and Apache2::AuthCookie, though TicketUserTable and TicketPasswordStyle are ignored.

The following directives are added by this module:

TicketThreshold

This directive tells the module to only update the database when a ticket timestamp is at least X seconds old. Reduces database updates.

 Example: 60
 Default: 0 (always update)
 Required: No
TicketDBAutoCommit

This directive tells whether to start the database connection in AutoCommit mode or not.

 Example: 0
 Default: 1
 Required: No
AuthTicketLDAPCacheDir

Set the file path of the cache directory to be used by CHI. It is the same for both the statement and LDAP entry caches.

 Example: /var/cache/apache
 Default: <none>
 Required: Yes
AuthTicketLDAPCacheSize

Set the size of the LDAP entry cache. You can use 1k or 1m for kilobytes or megabytes, respectively.

 Example: 4m
 Default: <none>
 Required: Yes
AuthTicketLDAPCachePageSize

Set the page size of the LDAP entry cache. In bytes.

 Example: 4096
 Default: <none>
 Required: Yes
AuthTicketLDAPCacheTTL

Set the maximum time a cached LDAP entry is considered "good". You can use 1m, 1h, or 1d for minutes, hours, days, respectively. N.b., expired entries remain in the cache. They are ignored until their space is needed.

 Example: 10m
 Default: <none>
 Required: Yes
AuthTicketLDAPStmtCacheSize

Set the size of the SELECT statement cache. You can use 1k or 1m for kilobytes or megabytes, respectively.

 Example: 4m
 Default: <none>
 Required: Yes
AuthTicketLDAPStmtCachePageSize

Set the page size of the SELECT statement cache. In bytes.

 Example: 4096
 Default: <none>
 Required: Yes
AuthTicketLDAPStmtCacheTTL

Set the maximum time a cached SELECT result is considered "good". You can use 1m, 1h, or 1d for minutes, hours, days, respectively. N.b., expired entries remain in the cache. They are ignored until their space is needed.

 Example: 1m
 Default: <none>
 Required: Yes
LDAPURL

Set the URL for the LDAP server. The default is there to comply with Apache2::AuthTicket's admittedly weird standard of providing unlikely defaults for things which should be overridden.

 Example: ldap://ldap.example.com:389
 Default: ldap://ldap.example.com:389
 Required: No, but really Yes
LDAPDN

Set the LDAP Distinguished Name for searching.

 Example: dc=example,dc=com
 Default: dc=example,dc=com
 Required: No, but really Yes
LDAPScope

Set the LDAP scope for searching. Valid: one, sub, base.

 Example: one
 Default: sub
 Required: No
LDAPFilter

Set the LDAP filter for searching. The text MYUSER will be replaced with the supplied login name.

 Example: uid=MYUSER
 Default: uid=MYUSER
 Required: No

Database Configuration

Only the tickets and secrets tables from Apache2::AuthTicket are needed for this module. Please refer to that module's documentation for detailed implementation details.

One important difference is that due to this module's usage of SHA512, the ticket size is 128.

The following is just a summary:

tickets table
 Example:

 CREATE TABLE tickets (
    ticket_hash CHAR(128) NOT NULL,
    ts          INT NOT NULL,
    PRIMARY KEY (ticket_hash)
 );
secrets table
 Example:

 CREATE TABLE ticketsecrets (
     sec_version  SERIAL,
     sec_data     TEXT NOT NULL
 );

METHODS ^

CREDITS ^

Many thanks to Michael Schout for writing Apache2::AuthTicket. Additional thanks to St. Edward's University for providing the resources to write this module.

SEE ALSO ^

Apache2::AuthTicket, Apache2::AuthCookie, Net::LDAP, CHI, CHI::Driver::FastMmap

AUTHOR ^

Stephen Olander-Waters <stephenw@stedwards.edu>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2012 by St. Edward's University.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: