=encoding utf8

=head1 NAME

Mojolicious::Plugin::HttpBasicAuth - Http-Basic-Authentication implementation

=head1 SYNOPSIS

  # in your startup
  $self->plugin(
      'http_basic_auth', {
          validate => sub {
              my $c         = shift;
              my $loginname = shift;
              my $password  = shift;
              return 1 if($loginname eq 'Homer' && $password eq 'Marge');
              return 0;
          },
          realm => 'Homers Home'
      }
  );

  # in your routes
  sub index {
      my $self = shift;
      return unless $self->basic_auth(\%options);
      $self->render();
  }


=head1 DESCRIPTION

L<Mojolicious::Plugin::HttpBasicAuth> is a implemntation of the Http-Basic-Authentication

=head1 OPTIONS

L<Mojolicious::Plugin::HttpBasicAuth> supports the following options.

=head2 realm

  $self->plugin('http_basic_auth', {realm => 'My Castle!'});

HTTP-Realm, defaults to 'WWW'

=head2 validate

  $self->plugin('http_basic_auth', {
      validate => sub {
            my $c          = shift;
            my $loginname  = shift;
            my $password   = shift;
            return 1 if($loginname eq 'Homer' && $password eq 'Marge');
            return 0;
      }
  });

Validation callback to verify user. This option is B<mandatory>.

=head2 invalid

  $self->plugin('http_basic_auth', {
      invalid => sub {
          my $controller = shift;
          return (
              json => { json     => { error => 'HTTP 401: Unauthorized' } },
              html => { template => 'auth/basic' },
              any  => { data     => 'HTTP 401: Unauthorized' }
          );
      }
  });

Callback vor invalid requests, default can be seen here. Return values are dispatched to L<Mojolicious::Controller/"respond_to">

=head1 HELPERS

L<Mojolicious::Plugin::HttpBasicAuth> implements the following helpers.

=head2 basic_auth

  return unless $self->basic_auth({realm => 'Marges Kitchen'});

All default options can be overwritten in every call.

=head1 METHODS

L<Mojolicious::Plugin::HttpBasicAuth> inherits all methods from
L<Mojolicious::Plugin> and implements the following new ones.

=head2 register

  my $route = $plugin->register(Mojolicious->new);
  my $route = $plugin->register(Mojolicious->new, {realm => 'Fort Knox'});

Register renderer and helper in L<Mojolicious> application.

=head1 SEE ALSO

L<Mojolicious>, L<Mojolicious::Guides>, L<http://mojolicio.us>.

=head1 AUTHOR

Patrick Grämer, L<http://graemer.org>.

=cut