=head1 NAME

Mojolicious::Plugin::BasicAuthPlus - Basic HTTP Auth Helper Plus

=head1 VERSION

version 0.02

=head1 SYNOPSIS

  use Mojolicious::Lite;

  plugin 'basic_auth_plus';

  # Inline callback
  get '/' => sub {
      my $self = shift;

      return $self->render_text('ok')
          if $self->basic_auth(
              realm => sub { return 1 if "@_" eq 'username password' }
          );
  };

  # Explicit username and password
  get '/foo' => sub {
      my $self = shift;

      $self->render_text('ok')
        if $self->basic_auth(
          "Realm Name" => {
              username => 'username',
              password => 'password'
          }
      );
  };

  # With encrypted password
  get '/' => sub {
      my $self = shift;

      $self->render_text('ok')
        if $self->basic_auth(
          "Realm Name" => {
              username => 'username',
              password => 'MlQ8OC3xHPIi.'
          }
      );
  };

  # Passwd file authentication
  get '/' => sub {
      my $self = shift;

      $self->render_text('ok')
        if $self->basic_auth(
          "Realm Name" => {
              path => '/path/to/passwd/file.txt'
          }
      );
  };

  # LDAP authentication (with anonymous bind)
  get '/' => sub {
      my $self = shift;

      $self->render_text('ok')
        if $self->basic_auth(
          "Realm Name" => {
              host   => 'ldap.company.com',
              basedn => 'ou=People,dc=company,dc=com'
          }
      );
  };

  # Active Directory authentication (with authenticated bind)
  get '/' => sub {
      my $self = shift;

      $self->render_text('ok')
        if $self->basic_auth(
          "Realm Name" => {
              host   => 'ldap.company.com',
              basedn => 'dc=company,dc=com',
              binddn => 'ou=People,dc=company,dc=com',
              bindpw => 'secret'
          }
      );
  };

  app->start;

=head1 DESCRIPTION

L<Mojolicious::Plugin::BasicAuthPlus> is a helper for basic HTTP
authentication that supports multiple authentication schemes, including
an inline callback, hard-coded username and password, a passwd file, LDAP,
or Active Directory.

=head1 METHODS

=head2 basic_auth

Configure specific auth method (see CONFIGURATION).  Returns 1 on success,
0 on failure.

=head1 CONFIGURATION

The basic_auth method takes an HTTP Basic Auth realm name that either
designates a subroutine with which to do the authentication check, or a named
hash, where the realm is the hash name.  When the realm represents a named
hash, the key/value pairs specify the source of user credentials on
which to match and other related parameters.

Realm names may contain whitespace.

The username and password may be defined explicitly, or authentication can be
against a passwd file, LDAP, or Active Directory.  The following options may
be set in the hash:

=over 5

=item B<username>

Specify the username to match.

=item B<password>

Specify the password to match.  The string may be plaintext or use any of the
formats noted in L<Authen::Simple::Password>.

=item B<path>

The location of a password file holding user credentials.  Per
L<Authen::Simple::Passwd>, "Any standard passwd file that has records seperated
with newline and fields seperated by ":" is supported.  First field is expected
to be username and second field, plain or encrypted password.  Required."

=item B<host>

The hostname or IP address of an LDAP or Active Directory server.

=item B<basedn>

The base DN to use with LDAP or Active Directory.

=item B<binddn>

The bind DN to use when doing an authenticated bind against LDAP or Active
Directory.

=item B<bindpw>

The password to use when doing an authenticated bind to LDAP or Active
Directory.

=back

If username and password are defined, then other options pertaining to a
passwd file or LDAP/ActiveDirectory authentication will be ignored, because it
it assumed you intend to compare the defined username and password against
those supplied by the user.

=head1 SEE ALSO

L<Mojolicious>, L<Mojolicious::Guides>, L<http://mojolicio.us>,
L<Authen::Simple::Password>, L<Authen::Simple::LDAP>, L<Authen::Simple::Passwd>

=head1 DEVELOPMENT

L<http://github.com/stregone/mojolicious-plugin-basicauthplus>

=head1 ACKNOWLEDGEMENTS

Based on Mojolicious::Plugin::BasicAuth, by Glen Hinkle <tempire@cpan.org>.

=head1 AUTHOR

Brad Robertson <blr@cpan.org>

=head1 BUGS

Please report any bugs or feature requests to
C<bug-mojolicious-plugin-basicauthplus at rt.cpan.org>, or through the web
interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mojolicious-Plugin-BasicAuthPlus>.  I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Mojolicious::Plugin::BasicAuthPlus

You can also look for information at:

=over 4 

=item * RT: CPAN's request tracker (report bugs here)

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mojolicious-Plugin-BasicAuthPlus>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Mojolicious-Plugin-BasicAuthPlus>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Mojolicious-Plugin-BasicAuthPlus>

item * Search CPAN

L<http://search.cpan.org/dist/Mojolicious-Plugin-BasicAuthPlus/>

=back

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2013 by Brad Robertson.

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.


=cut

