view release on metacpan or  search on metacpan

lib/Authen/Simple/IMAP.pm  view on Meta::CPAN

=head1 DESCRIPTION

Authenticate against IMAP or IMAPS services. 

Requires Net::IMAP::Simple for IMAP and Net::IMAP::Simple::SSL for IMAPS.
These modules are loaded when the object is created, not at compile time.

=head1 METHODS 

=over 4

=item  * new

This method takes a hash of parameters. The following options are
valid:

=over 8

=item * host

The hostname of the IMAP server

=item * protocol

Either 'IMAP' or 'IMAPS'.  Any other value causes an exception.
Selecting 'IMAPS' will cause an exception if Net::IMAP::Simple::SSL 
is not installed.

=item * log   

Any object that supports "debug", "info", "error" and "warn".

	log => Log::Log4perl->get_logger('Authen::Simple::PAM')

=item * escape_slash 

In some environments, a password containing a slash will fail unless the slash
is escaped. Set escape_slash to true to escape slashes in passwords, or false
to leave them unescaped.  This is true by default.

=item * imap

Any object that supports "login" and "errstr" methods.  The obvious choice
being a Net::IMAP::Simple object, but if you want to use something else, here's
how you can do it.  This is how I use a mock imap object for the unit tests.  

=back

=item * authenticate( $username, $password ) 

Returns true on success and false on failure.

=back

=head1 DEPENDENCIES

Net::IMAP::Simple is required, and Net::IMAP::Simple::SSL is required for IMAPS.
Net::IMAP::Simple::Plus adds some patches to the otherwise abandoned and broken Net::IMAP::Simple, so I recommend it.   

=head1 BUGS AND LIMITATIONS

=over 4

=item *

I've never tried this in mod_perl, so including the mod_perl example in 
the synopsis is pure hubris on my part.

=item *

The unit tests are pretty sparse.  They don't include any tests against real 
IMAP servers.  They just do a successful and failed password against a mock
imap server object.

=item * 

This module uses Net::IMAP::Simple, which is broken and abandoned.  I should
either use something else or implement the IMAP stuff myself.  I wound up
wrapping the Net::IMAP::Simple stuff in an alarm+eval block to get it to behave.

=back

=head1 SEE ALSO

=over 4

=item Authen::Simple

=item Authen::Simple::Adapter

=item Net::IMAP::Simple

=item Net::IMAP::Simple::SSL

=back

=head1 CREDITS

=over 4

=item *

I pretty much ripped the best parts of this doc out of Christian Hansen's 
Authen::Simple::PAM and replaced "pam" with "imap" in a few places.  The 
lousy parts are my own.

=back

=head1 AUTHOR

Dylan Martin  C<< <dmartin@sccd.ctc.edu> >>

=head1 LICENCE AND COPYRIGHT

Copyright (c) 2009, Dylan Martin C<< <dmartin@sccd.ctc.edu> >> and Seattle
Central Community College.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.