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.

AUTHOR

Stephen Olander-Waters <stephenw@stedwards.edu>

COPYRIGHT AND LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)