sshaw > Mojolicious-Plugin-DigestAuth-0.04 > Mojolicious::Plugin::DigestAuth

Download:
Mojolicious-Plugin-DigestAuth-0.04.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.04   Source   Latest Release: Mojolicious-Plugin-DigestAuth-0.08

NAME ^

Mojolicious::Plugin::DigestAuth - HTTP Digest Authentication for Mojolicious

SYNOPSIS ^

   $self->plugin('digest_auth');

   # In your action
   return unless $self->digest_auth(allow => { sshaw => 'password' });

   # Or, in startup()
   my $r = $self->digest_auth('/admin', allow => { sshaw => 'password' });
   $r->route('/new')->to('users#new');

CONFIGURATION ^

SETUP

Configuration can be done globally when loading the plugin

    $self->plugin('digest_auth', %options)

or locally when calling digest_auth

    $self->digest_auth(%options);

Local options override their global counterparts. For example, the following will apply to all authentication requests

   # setup()
   $self->plugin('digest_auth', realm   => 'Thangz',
                                expires => 120,
                                allow   => '/path/to/htdigest_file');


   # controller
   sub show
   {
       my $self = shift;
       return unless $self->digest_auth;

       # ...
   }

But can be overridden within an action

   sub edit
   {
       my $self = shift;
       return unless $self->digest_auth(realm   => 'RealmX',
                                        expires => 24*3600,
                                        allow   => { sshaw => 'Ay3Br4h_!' });
       # ...
   }

For a full list of options see "digest_auth".

AUTHENTICATION

By default MD5/auth authentication is performed. This is configurable, see "digest_auth".

DB

Authentication information is given via the allow option and can be retrieved from a variety of sources:

PERFORMING AUTHENTICATION

Authentication can be performed by calling the digest_auth method from within the action you'd like to protect:

   sub some_action
   {
       my $self = shift;
       return unless $self->digest_auth;

       # Authenticated users get here
   }

If authentication is successful digest_auth returns true, otherwise undef is returned and a HTTP 401 status code and the message: HTTP 401: Unauthorized are sent to the client. Currently this message cannot be changed.

Authentication can also be performed for a set of routes by calling digest_auth from within your application's startup function. This form performs authentication automatically for all of the routes defined under the given URL:

   package YourWebApp;

   use Mojo::Base 'Mojolicious';

   sub startup
   {
     my $self = shift;
     $self->plugin('digest_auth', %options);

     # ...

     my $admin = $self->digest_auth('/admin');
     $admin->route('/new')->to('users#new');
     $admin->route('/edit/:id')->to('users#edit');
   }

In this case authentication is performed via a bridge with a callback.

WEB SERVERS

Authentication will fail if your application is sitting behind a web server does not pass the Authorization header to your application. In Apache this can be achieved with mod_rewrite:

   RewriteEngine On
   RewriteRule ^ - [E=X-HTTP_AUTHORIZATION:%{HTTP:Authorization}]

METHODS ^

plugin

     $self->plugin('digest_auth', %options)

Loads the plugin and sets up the defaults given by %options.

Arguments

%options

See "digest_auth".

Errors

This method will croak if if any of the options are invalid or if there is an error loading the password database.

digest_auth

     $self->digest_auth(%options)
     $routes = $self->digest_auth($url, %options)

Arguments

$url

Optional. If provided authentication will be performed for all routes defined under $url. See "PERFORMING AUTHENTICATION".

%options

Returns

Without a URL prefix:

True if authentication was successful, undef otherwise. If unsuccessful a HTTP 401 status code and message are sent to the client.

With a URL prefix:

An instance of Mojolicious::Routes. See "PERFORMING AUTHENTICATION".

Errors

Will croak if any of the options are invalid.

SEE ALSO ^

Mojolicious, Mojolicious::Plugin::BasicAuth, http://en.wikipedia.org/wiki/Digest_access_authentication

AUTHOR ^

Skye Shaw (sshaw AT lucas.cis.temple.edu)

LICENSE ^

Copyright (c) 2011 Skye Shaw. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: