Apache2::AuthTicketLDAP - Cookie Ticketing with LDAP Authentication
version 0.02
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>
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.
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.
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>
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:
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
This directive tells whether to start the database connection in AutoCommit mode or not.
Example: 0 Default: 1 Required: No
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
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
Set the page size of the LDAP entry cache. In bytes.
Example: 4096 Default: <none> Required: Yes
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
Set the size of the SELECT statement cache. You can use 1k or 1m for kilobytes or megabytes, respectively.
Set the page size of the SELECT statement cache. In bytes.
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
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
Set the LDAP Distinguished Name for searching.
Example: dc=example,dc=com Default: dc=example,dc=com Required: No, but really Yes
Set the LDAP scope for searching. Valid: one, sub, base.
Example: one Default: sub Required: No
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
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:
Example: CREATE TABLE tickets ( ticket_hash CHAR(128) NOT NULL, ts INT NOT NULL, PRIMARY KEY (ticket_hash) );
Example: CREATE TABLE ticketsecrets ( sec_version SERIAL, sec_data TEXT NOT NULL );
Many thanks to Michael Schout for writing Apache2::AuthTicket. Additional thanks to St. Edward's University for providing the resources to write this module.
Apache2::AuthTicket, Apache2::AuthCookie, Net::LDAP, CHI, CHI::Driver::FastMmap
Stephen Olander-Waters <stephenw@stedwards.edu>
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.
To install Apache2::AuthTicketLDAP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache2::AuthTicketLDAP
CPAN shell
perl -MCPAN -e shell install Apache2::AuthTicketLDAP
For more information on module installation, please visit the detailed CPAN module installation guide.