Mojolicious::Plugin::DigestAuth - HTTP Digest Authentication for Mojolicious
$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 can be done globally when loading the plugin
$self->plugin('digest_auth', %options)
or locally when calling digest_auth
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".
By default MD5/auth authentication is performed. This is configurable, see "digest_auth".
Authentication information is given via the allow option and can be retrieved from a variety of sources:
allow
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.
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' });
A htdigest style file
$self->plugin('digest_auth', allow => '/home/sshaw/www_users');
An object with a get() method that returns hashed passwords
get()
$self->plugin('digest_auth', allow => $db);
Arguments are passed to get() in the following order: realm, username.
realm, username
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.
undef
HTTP 401: Unauthorized
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.
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:
mod_rewrite
RewriteEngine On RewriteRule ^ - [E=X-HTTP_AUTHORIZATION:%{HTTP:Authorization}]
Loads the plugin and sets up the defaults given by %options.
%options
See "digest_auth".
This method will croak if if any of the options are invalid or if there is an error loading the password database.
croak
$self->digest_auth(%options) $routes = $self->digest_auth($url, %options)
$url
Optional. If provided authentication will be performed for all routes defined under $url. See "PERFORMING AUTHENTICATION".
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.
'MD5'
'MD5-sess'
qop
domain => '/path' | 'your.domain.com'
Authentication domain. Defaults to '/'.
'/'
expires => seconds
Nonce lifetime. Defaults to 300 seconds (5 minutes).
300
qop => 'auth' | ''
Quality of protection. Defaults to 'auth'. auth-int is not supported.
'auth'
auth-int
realm => 'Your Realm'
Authentication realm. Defaults to 'WWW'.
'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.
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.
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".
Will croak if any of the options are invalid.
Mojolicious, Mojolicious::Plugin::BasicAuth, http://en.wikipedia.org/wiki/Digest_access_authentication
Skye Shaw (sshaw AT lucas.cis.temple.edu)
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.
To install Mojolicious::Plugin::DigestAuth, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious::Plugin::DigestAuth
CPAN shell
perl -MCPAN -e shell install Mojolicious::Plugin::DigestAuth
For more information on module installation, please visit the detailed CPAN module installation guide.