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.

• An 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'.

• secret => 'a salt value'

  Used to create the nonce. Defaults to your application's secret, which means you must set your application's secret before loading this plugin. If you're using an array the first value in the array will be used.

  IMPORTANT: Changing this value will cause an HTTP 400 response to be returned to any clients with cached authentication credentials.

• 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 (skye.shaw AT gmail.com)

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.