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:

• A hash reference without a realm

  $self->plugin('digest_auth', allow => { sshaw => 'my_pAzw3rD',
                                          admin => '->fofinha!' });

  In this case users will either be placed into the realm given by the realm option or the default realm, WWW.

  Passwords must be given in plain text.

• A hash reference with realm(s)

  $self->plugin('digest_auth', allow => { 'Admin Realm' => { sshaw => 'my_pAzw3rD' },
                                          'WWW Users'   => { tony  => 'vrooooooom' });

  Passwords must be given in plain text.

• A htdigest style file

  $self->plugin('digest_auth', allow => '/home/sshaw/www_users');

• An object with a get() method that returns hashed passwords

  $self->plugin('digest_auth', allow => $db);

  Arguments are passed to get() in the following order: realm, username.

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

• allow => { user => password }

• allow => { realm => { user => password }}

• allow => 'htdigest_file'

• allow => $obj

  See "DB".

• algorithm => 'MD5' | 'MD5-sess'

  Digest algorithm, either 'MD5' or 'MD5-sess'. Defaults to 'MD5', 'MD5-sess' requires a qop.

• domain => '/path' | 'your.domain.com'

  Authentication domain. Defaults to '/'.

• expires => seconds

  Nonce lifetime. Defaults to 300 seconds (5 minutes).

• qop => 'auth' | ''

  Quality of protection. Defaults to 'auth'. auth-int is not supported.

• realm => 'Your Realm'

  Authentication realm. Defaults to 'WWW'.

• support_broken_browsers => 1 | 0

  When processing requests from certain browsers skip steps that would otherwise result in a HTTP 400 response. Defaults to 1.

  Currently only applies to IE 5 and 6. These two browsers fail to append the query string to the URI included in the Authorization header and, after authenticating, fail to include the opaque value.

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.

cpanm Mojolicious::Plugin::DigestAuth

perl -MCPAN -e shell
install Mojolicious::Plugin::DigestAuth