Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

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

	   use Catalyst	qw/

	   __PACKAGE__->config(	authentication => {
	       default_realm =>	'example',
	       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({}, "example");
	       # either	user gets authenticated	or 401 is sent
	       # Note that the authentication realm sent to the	client (in the
	       # RFC 2617 sense) is overridden here, but this *does not*
	       # effect	the Catalyst::Authentication::Realm used for
	       # authentication	- to do	that, you need
	       # $c->authenticate({}, 'otherrealm')


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

       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.

	   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.

       new $config, $c,	$realm
	   Simple constructor.

	   Validates that $config is ok.

       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:

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

	       Array reference to domains used to build	the authorization

	       This list of domains defines the	protection space. If a domain
	       URI is an absolute path (starts with /),	it is relative to the
	       root URL	of the server being accessed.  An absolute URI in this
	       list may	refer to a different server than the one being

	       The client will use this	list to	determine the set of URIs for
	       which the same authentication information may be	sent.

	       If this is omitted or its value is empty, the client will
	       assume that the protection space	consists of all	URIs on	the
	       responding server.

	       Therefore, if your application is not hosted at the root	of
	       this domain, and	you want to prevent the	authentication
	       credentials for this application	being sent to any other
	       applications.  then you should use the use_uri_for
	       configuration option, and pass a	domain of /.

       authenticate_basic $c, $realm, \%auth_info
	   Performs HTTP basic authentication.

       authenticate_digest $c, $realm, \%auth_info
	   Performs HTTP digest	authentication.

	   The password_type must be clear for digest authentication to
	   succeed.  If	you do not want	to store your user passwords as	clear
	   text, you may instead store the MD5 digest in hex of	the string

	   Catalyst::Plugin::Cache is used for persistent storage of the nonce
	   values (see "Nonce").  It must be loaded in your application,
	   unless you override the "store_digest_authorization_nonce" and
	   "get_digest_authorization_nonce" methods as shown below.

	   Takes an additional parameter of algorithm, the possible values of
	   which are 'MD5' (the	default) and 'MD5-sess'. For more information
	   about 'MD5-sess', see section in RFC	2617.

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

	   Sets	the 401	response and calls "$ctx->detach".

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

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

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

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

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

	   The type of password	returned by the	user object. Same usage	as in

	   The name of accessor	used to	retrieve the value of the password
	   field from the user object. Same usage as in

	   The field name that the user's username is mapped into when finding
	   the user from the realm. Defaults to	'username'.

	   If this configuration key has a true	value, then the	domain(s) for
	   the authorization header will be run	through	$c->uri_for(). Use
	   this	configuration option if	your application is not	running	at the
	   root	of your	domain,	and you	want to	ensure that authentication
	   credentials from your application are not shared with other
	   applications	on the same server.

	   If this configuration key has a true	value then authentication will
	   be denied (and a 401	issued in normal circumstances)	unless the
	   request is via https.

	   Causes authentication to fail as normal modules do, without calling
	   "$c->detach". This means that the basic auth	credential can be used
	   as part of the progressive realm.

	   However use like this is probably not optimum it also means that
	   users in browsers ill never get a HTTP authenticate dialogue	box
	   (unless you manually	return a 401 response in your application),
	   and even some automated user	agents (for APIs) will not send	the
	   Authorization header	without	specific manipulation of the request

	   Enables support for .NET (or	other similarly	broken clients), which
	   fails to include the	query string in	the uri	in the digest
	   Authorization header, contrary to rfc2617.

	   This	option has no effect on	clients	that include the query string;
	   they	will continue to work as normal.

       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.

       Updated to current name space and currently maintained by: Tomas	Doran

       Original	module by:

       Yuval Kogman, ""
       Jess Robinson
       Sascha Kiefer ""

       Patches contributed by:

       Peter Corlett
       Devin Austin (dhoss) ""
       Ronald J	Kimball

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

	       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.

perl v5.24.1			 Catalyst::Authentication::Credential::HTTP(3)


Want to link to this manual page? Use this URL:

home | help