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' });
An 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'
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.
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 (skye.shaw AT gmail.com)
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.