NAME

Catalyst::Authentication::Credential::HTTP - HTTP Basic and Digest authentication for Catalyst.

SYNOPSIS

use Catalyst qw/
    Authentication
/;

__PACKAGE__->config( authentication => {
    realms => { 
        example => { 
            credential => { 
                class => 'HTTP',
                type  => 'any', # or 'digest' or 'basic'
                password_type  => 'clear',
                password_field => 'password'
            },
            store => {
                class => 'Minimal',
                users => {
                    Mufasa => { password => "Circle Of Life", },
                },
            },
        },
    }
});

sub foo : Local {
    my ( $self, $c ) = @_;

    $c->authenticate({ realm => "example" }); 
    # either user gets authenticated or 401 is sent
    # Note that the authentication realm sent to the client is overridden
    # here, but this does not affect the Catalyst::Authentication::Realm
    # used for authentication.

    do_stuff();
}

sub always_auth : Local {
    my ( $self, $c ) = @_;
    
    # Force authorization headers onto the response so that the user
    # is asked again for authentication, even if they successfully
    # authenticated.
    my $realm = $c->get_auth_realm('example');
    $realm->credential->authorization_required_response($c, $realm);
}

# with ACL plugin
__PACKAGE__->deny_access_unless("/path", sub { $_[0]->authenticate });

DESCRIPTION

This module lets you use HTTP authentication with Catalyst::Plugin::Authentication. Both basic and digest authentication are currently supported.

When authentication is required, this module sets a status of 401, and the body of the response to 'Authorization required.'. To override this and set your own content, check for the $c->res->status == 401 in your end action, and change the body accordingly.

TERMS

Nonce

A nonce is a one-time value sent with each digest authentication request header. The value must always be unique, so per default the last value of the nonce is kept using Catalyst::Plugin::Cache. To change this behaviour, override the store_digest_authorization_nonce and get_digest_authorization_nonce methods as shown below.

METHODS

new $config, $c, $realm

Simple constructor.

authenticate $c, $realm, \%auth_info

Tries to authenticate the user, and if that fails calls authorization_required_response and detaches the current action call stack.

Looks inside $c->request->headers and processes the digest and basic (badly named) authorization header.

This will only try the methods set in the configuration. First digest, then basic.

The %auth_info hash can contain a number of keys which control the authentication behaviour:

realm

Sets the HTTP authentication realm presented to the client. Note this does not alter the Catalyst::Authentication::Realm object used for the authentication.

domain

Array reference to domains used to build the authorization headers.

authenticate_basic $c, $realm, \%auth_info

Performs HTTP basic authentication.

authenticate_digest $c, $realm, \%auth_info

Performs HTTP digest authentication. Note that the password_type must by clear for digest authentication to succeed, and you must have Catalyst::Plugin::Session in your application as digest authentication needs to store persistent data.

Note - if you do not want to store your user passwords as clear text, then it is possible to store instead the MD5 digest in hex of the string '$username:$realm:$password'

authorization_required_response $c, $realm, \%auth_info

Sets $c->response to the correct status code, and adds the correct header to demand authentication data from the user agent.

Typically used by authenticate, but may be invoked manually.

%opts can contain domain and algorithm, which are used to build %the digest header.

store_digest_authorization_nonce $c, $key, $nonce

get_digest_authorization_nonce $c, $key

Set or get the $nonce object used by the digest auth mode.

You may override these methods. By default they will call get and set on $c->cache.

CONFIGURATION

All configuration is stored in YourApp->config(authentication => { yourrealm => { credential => { class => 'HTTP', %config } } }.

This should be a hash, and it can contain the following entries:

type

Can be either any (the default), basic or digest.

This controls authorization_required_response and authenticate, but not the "manual" methods.

authorization_required_message

Set this to a string to override the default body content "Authorization required.", or set to undef to suppress body content being generated.

password_type

The type of password returned by the user object. Same usage as in Catalyst::Authentication::Credential::Password

password_field

The name of accessor used to retrieve the value of the password field from the user object. Same usage as in Catalyst::Authentication::Credential::Password

use_uri_for

If this configuration key has a true value, then the domain(s) for the authorization header will be run through $c->uri_for()

RESTRICTIONS

When using digest authentication, this module will only work together with authentication stores whose User objects have a password method that returns the plain-text password. It will not work together with Catalyst::Authentication::Store::Htpasswd, or Catalyst::Authentication::Store::DBIC stores whose password methods return a hashed or salted version of the password.

AUTHORS

Updated to current name space and currently maintained by: Tomas Doran bobtfish@bobtfish.net.

Original module by:

Yuval Kogman, nothingmuch@woobling.org

Jess Robinson

Sascha Kiefer esskar@cpan.org

SEE ALSO

RFC 2617 (or its successors), Catalyst::Plugin::Cache, Catalyst::Plugin::Authentication

COPYRIGHT & LICENSE

Copyright (c) 2005-2008 the aforementioned authors. All rights
reserved. This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.