++ed by:
Author image sshaw
and 1 contributors


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



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

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



Configuration can be done globally when loading the plugin

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

or locally when calling digest_auth


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:

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


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');

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:

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



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

Loads the plugin and sets up the defaults given by %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.


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



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.

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


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.