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

FreeBSD Manual Pages


home | help
Catalyst::Plugin::AuthUsercContributed PerlCatalyst::Plugin::Authentication(3)

       Catalyst::Plugin::Authentication	- Infrastructure plugin	for the
       Catalyst	authentication framework.

	   use Catalyst	qw/

	   # later on ...
	   $c->authenticate({ username => 'myusername',
			      password => 'mypassword' });
	   my $age = $c->user->get('age');

       The authentication plugin provides generic user support for Catalyst
       apps. It	is the basis for both authentication (checking the user	is who
       they claim to be), and authorization (allowing the user to do what the
       system authorises them to do).

       Using authentication is split into two parts. A Store is	used to
       actually	store the user information, and	can store any amount of	data
       related to the user. Credentials	are used to verify users, using
       information from	the store, given data from the frontend. A Credential
       and a Store are paired to form a	'Realm'. A Catalyst application	using
       the authentication framework must have at least one realm, and may have

       To implement authentication in a	Catalyst application you need to add
       this module, and	specify	at least one realm in the configuration.

       Authentication data can also be stored in a session, if the application
       is using	the Catalyst::Plugin::Session module.

       NOTE in version 0.10 of this module, the	interface to this module
       changed.	 Please	see "COMPATIBILITY ROUTINES" for more information.

   The Authentication/Authorization Process
       Web applications	typically need to identify a user - to tell the	user
       apart from other	users. This is usually done in order to	display
       private information that	is only	that user's business, or to limit
       access to the application so that only certain entities can access
       certain parts.

       This process is split up	into several steps. First you ask the user to
       identify	themselves. At this point you can't be sure that the user is
       really who they claim to	be.

       Then the	user tells you who they	are, and backs this claim with some
       piece of	information that only the real user could give you. For
       example,	a password is a	secret that is known to	both the user and you.
       When the	user tells you this password you can assume they're in on the
       secret and can be trusted (ignore identity theft	for now). Checking the
       password, or any	other proof is called credential verification.

       By this time you	know exactly who the user is - the user's identity is
       authenticated. This is where this module's job stops, and your
       application or other plugins step in.

       The next	logical	step is	authorization, the process of deciding what a
       user is (or isn't) allowed to do. For example, say your users are split
       into two	main groups - regular users and	administrators.	You want to
       verify that the currently logged	in user	is indeed an administrator
       before performing the actions in	an administrative part of your
       application. These decisions may	be made	within your application	code
       using just the information available after authentication, or it	may be
       facilitated by a	number of plugins.

   The Components In This Framework

       Configuration of	the Catalyst::Plugin::Authentication framework is done
       in terms	of realms. In simplest terms, a	realm is a pairing of a
       Credential verifier and a User storage (Store) backend. As of version
       0.10003,	realms are now objects that you	can create and customize.

       An application can have any number of Realms, each of which operates
       independent of the others. Each realm has a name, which is used to
       identify	it as the target of an authentication request. This name can
       be anything, such as 'users' or 'members'. One realm must be defined as
       the default_realm, which	is used	when no	realm name is specified. More
       information about configuring realms is available in the	configuration

       Credential Verifiers

       When user input is transferred to the Catalyst application (typically
       via form	inputs)	the application	may pass this information into the
       authentication system through the "$c->authenticate()" method.  From
       there, it is passed to the appropriate Credential verifier.

       These plugins check the data, and ensure	that it	really proves the user
       is who they claim to be.

       Credential verifiers compatible with versions of	this module 0.10x and
       upwards should be in the	namespace

       Storage Backends

       The authentication data also identifies a user, and the Storage backend
       modules use this	data to	locate and return a standardized object-
       oriented	representation of a user.

       When a user is retrieved	from a store it	is not necessarily
       authenticated.  Credential verifiers accept a set of authentication
       data and	use this information to	retrieve the user from the store they
       are paired with.

       Storage backends	compatible with	versions of this module	0.10x and
       upwards should be in the	namespace "Catalyst::Authentication::Store".

       The Core	Plugin

       This plugin on its own is the glue, providing realm configuration,
       session integration, and	other goodness for the other plugins.

       Other Plugins

       More layers of plugins can be stacked on	top of the authentication
       code. For example, Catalyst::Plugin::Session::PerUser provides an
       abstraction of browser sessions that is more persistent per user.
       Catalyst::Plugin::Authorization::Roles provides an accepted way to
       separate	and group users	into categories, and then check	which
       categories the current user belongs to.

       Let's say we were storing users in a simple Perl	hash. Users are
       verified	by supplying a password	which is matched within	the hash.

       This means that our application will begin like this:

	   package MyApp;

	   use Catalyst	qw/

	   __PACKAGE__->config(	'Plugin::Authentication' =>
			   default => {
			       credential => {
				   class => 'Password',
				   password_field => 'password',
				   password_type => 'clear'
			       store =>	{
				   class => 'Minimal',
				   users => {
				       bob => {
					   password => "s00p3r",
					   editor => 'yes',
					   roles => [qw/edit delete/],
				       william => {
					   password => "s3cr3t",
					   roles => [qw/comment/],

       This tells the authentication plugin what realms	are available, which
       credential and store modules are	used, and the configuration of each.
       With this code loaded, we can now attempt to authenticate users.

       To show an example of this, let's create	an authentication controller:

	   package MyApp::Controller::Auth;

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

	       if (    my $user	    = $c->req->params->{user}
		   and my $password = $c->req->params->{password} )
		   if (	$c->authenticate( { username =>	$user,
					    password =>	$password } ) )	{
		       $c->res->body( "hello " . $c->user->get("name") );
		   } else {
		       # login incorrect
	       else {
		   # invalid form input

       This code should	be self-explanatory. If	all the	necessary fields are
       supplied, call the "authenticate" method	on the context object. If it
       succeeds	the user is logged in.

       The credential verifier will attempt to retrieve	the user whose details
       match the authentication	information provided to	"$c->authenticate()".
       Once it fetches the user	the password is	checked	and if it matches the
       user will be authenticated and "$c->user" will contain the user object
       retrieved from the store.

       In the above case, the default realm is checked,	but we could just as
       easily check an alternate realm.	If this	were an	admin login, for
       example,	we could authenticate on the admin realm by simply changing
       the "$c->authenticate()"	call:

	   if (	$c->authenticate( { username =>	$user,
				    password =>	$password }, 'admin' ) ) {
	       $c->res->body( "hello " . $c->user->get("name") );
	   } ...

       Now suppose we want to restrict the ability to edit to a	user with an
       'editor'	value of yes.

       The restricted action might look	like this:

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

		 unless	$c->user_exists
		 and $c->user->get('editor') eq	'yes';

	       # do something restricted here

       (Note that if you have multiple realms, you can use
       "$c->user_in_realm('realmname')"	in place of "$c->user_exists();" This
       will essentially	perform	the same verification as user_exists, with the
       added requirement that if there is a user, it must have come from the
       realm specified.)

       The above example is somewhat similar to	role based access control.
       Catalyst::Authentication::Store::Minimal	treats the roles field as an
       array of	role names. Let's leverage this. Add the role authorization

	   use Catalyst	qw/

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

	       $c->detach("unauthorized") unless $c->check_user_roles("edit");

	       # do something restricted here

       This is somewhat	simpler	and will work if you change your store,	too,
       since the role interface	is consistent.

       Let's say your app grows, and you now have 10,000 users.	It's no	longer
       efficient to maintain a hash of users, so you move this data to a
       database.  You can accomplish this simply by installing the DBIx::Class
       Store and changing your config:

	   __PACKAGE__->config(	'Plugin::Authentication' =>
			       default_realm =>	'members',
			       members => {
				   credential => {
				       class =>	'Password',
				       password_field => 'password',
				       password_type =>	'clear'
				   store => {
				       class =>	'DBIx::Class',
				       user_model => 'MyApp::Users',
				       role_column => 'roles',

       The authentication system works behind the scenes to load your data
       from the	new source. The	rest of	your application is completely

	   # example
	   __PACKAGE__->config(	'Plugin::Authentication' =>
			   default_realm => 'members',

			   members => {
			       credential => {
				   class => 'Password',
				   password_field => 'password',
				   password_type => 'clear'
			       store =>	{
				   class => 'DBIx::Class',
				   user_model => 'MyApp::Users',
				   role_column => 'roles',
			   admins => {
			       credential => {
				   class => 'Password',
				   password_field => 'password',
				   password_type => 'clear'
			       store =>	{
				   class => '+MyApp::Authentication::Store::NetAuth',
				   authserver => ''

       NOTE: Until version 0.10008 of this module, you would need to put all
       the realms inside a "realms" key	in the configuration. Please see
       "COMPATIBILITY CONFIGURATION" for more information

	   Whether or not to store the user's logged in	state in the session,
	   if the application is also using Catalyst::Plugin::Session. This
	   value is set	to true	per default.

	   However, even if use_session	is disabled, if	any code touches
	   $c->session,	a session object will be auto-vivified and session
	   Cookies will	be sent	in the headers.	To prevent accidental session
	   creation, check if a	session	already	exists with if ($c->sessionid)
	   { ... }. If the session doesn't exist, then don't place anything in
	   the session to prevent an unecessary	session	from being created.

	   This	defines	which realm should be used as when no realm is
	   provided to methods that require a realm such as authenticate or

       realm refs
	   The Plugin::Authentication config hash contains the series of realm
	   configurations you want to use for your app.	The only rule here is
	   that	there must be at least one. A realm consists of	a name,	which
	   is used to reference	the realm, a credential	and a store.  You may
	   also	put your realm configurations within a subelement called
	   'realms' if you desire to separate them from	the remainder of your
	   configuration.  Note	that if	you use	a 'realms' subelement, you
	   must	put ALL	of your	realms within it.

	   You can also	specify	a realm	class to instantiate instead of	the
	   default Catalyst::Authentication::Realm class using the 'class'
	   element within the realm config.

	   Each	realm config contains two hashes, one called 'credential' and
	   one called 'store', each of which provide configuration details to
	   the respective modules.  The	contents of these hashes is specific
	   to the module being used, with the exception	of the 'class'
	   element, which tells	the core Authentication	module the classname
	   to instantiate.

	   The 'class' element follows the standard Catalyst mechanism of
	   class specification.	If a class is prefixed with a +, it is assumed
	   to be a complete class name.	Otherwise it is	considered to be a
	   portion of the class	name. For credentials, the classname
	   'Password', for example, is expanded	to
	   Catalyst::Authentication::Credential::Password. For stores, the
	   classname 'storename' is expanded to:

   $c->authenticate( $userinfo [, $realm ])
       Attempts	to authenticate	the user using the information in the
       $userinfo hash reference	using the realm	$realm.	$realm may be omitted,
       in which	case the default realm is checked.

   $c->user( )
       Returns the currently logged in user, or	undef if there is none.
       Normally	the user is re-retrieved from the store.  For
       Catalyst::Authentication::Store::DBIx::Class the	user is	re-restored
       using the primary key of	the user table.	 Thus user can throw an	error
       even though user_exists returned	true.

   $c->user_exists( )
       Returns true if a user is logged	in right now. The difference between
       user_exists and user is that user_exists	will return true if a user is
       logged in, even if it has not been yet retrieved	from the storage
       backend.	If you only need to know if the	user is	logged in, depending
       on the storage mechanism	this can be much more efficient.  user_exists
       only looks into the session while user is trying	to restore the user.

   $c->user_in_realm( $realm )
       Works like user_exists, except that it only returns true	if a user is
       both logged in right now	and was	retrieved from the realm provided.

   $c->logout( )
       Logs the	user out. Deletes the currently	logged in user from "$c->user"
       and the session.	 It does not delete the	session.

   $c->find_user( $userinfo, $realm )
       Fetch a particular users	details, matching the provided user info, from
       the realm specified in $realm.

	   $user = $c->find_user({ id => $id });
	   $c->set_authenticated($user); # logs	the user in and	calls persist_user

       Under normal circumstances the user data	is only	saved to the session
       during initial authentication.  This call causes	the auth system	to
       save the	currently authenticated	user's data across requests.  Useful
       if you have changed the user data and want to ensure that future
       requests	reflect	the most current data.	Assumes	that at	the time of
       this call, $c->user contains the	most current data.

       Private method, do not call from	user code!

       These methods are for Catalyst::Plugin::Authentication INTERNAL USE
       only.  Please do	not use	them in	your own code, whether application or
       credential / store modules. If you do, you will very likely get the
       nasty shock of having to	fix / rewrite your code	when things change.
       They are	documented here	only for reference.

   $c->set_authenticated( $user, $realmname )
       Marks a user as authenticated. This is called from within the
       authenticate routine when a credential returns a	user. $realmname
       defaults	to 'default'.  You can use find_user to	get $user

   $c->auth_restore_user( $user, $realmname )
       Used to restore a user from the session.	In most	cases this is called
       without arguments to restore the	user via the session. Can be called
       with arguments when restoring a user from some other method.  Currently
       not used	in this	way.

   $c->auth_realms( )
       Returns a hashref containing realmname -> realm instance	pairs. Realm
       instances contain an instantiated store and credential object as	the
       'store' and 'credential'	elements, respectively

   $c->get_auth_realm( $realmname )
       Retrieves the realm instance for	the realmname provided.

       This was	a short-lived method to	update user information	- you should
       use persist_user	instead.

   $c->setup_auth_realm( )
   $c->setup( )
       This list might not be up to date.  Below are modules known to work
       with the	updated	API of 0.10 and	are therefore compatible with realms.


   User	Storage	Backends

   Credential verification


   Internals Documentation

       Catalyst::Plugin::Session, Catalyst::Plugin::Session::PerUser

       This module along with its sub plugins deprecate	a great	number of
       other modules. These include Catalyst::Plugin::Authentication::Simple,

       The realms-based	configuration and functionality	of the 0.10 update of
       Catalyst::Plugin::Authentication	required a change in the API used by
       credentials and stores.	It has a compatibility mode which allows use
       of modules that have not	yet been updated. This,	however, completely
       mimics the older	api and	disables the new realm-based features. In
       other words you cannot mix the older credential and store modules with
       realms, or realm-based configs. The changes required to update modules
       are relatively minor and	are covered in
       Catalyst::Plugin::Authentication::Internals.  We	hope that most modules
       will move to the	compatible list	above very quickly.

       Until version 0.10008 of	this module, you needed	to put all the realms
       inside a	"realms" key in	the configuration.

	   # example
	   __PACKAGE__->config(	'Plugin::Authentication' =>
			   default_realm => 'members',
			   realms => {
			       members => {

       If you use the old, deprecated "__PACKAGE__->config( 'authentication'
       )" configuration	key, then the realms key is still required.

       In version 0.10 of Catalyst::Plugin::Authentication, the	API changed.
       For app developers, this	change is fairly minor,	but for	Credential and
       Store authors, the changes are significant.

       Please see the documentation in version 0.09 of
       Catalyst::Plugin::Authentication	for a better understanding of how the
       old API functioned.

       The items below are still present in the	plugin,	though using them is
       deprecated. They	remain only as a transition tool, for those sites
       which can not yet be upgraded to	use the	new system due to local
       customizations or use of	Credential / Store modules that	have not yet
       been updated to work with the new API.

       These routines should not be used in any	application using realms
       functionality or	any of the methods described above. These are for
       reference purposes only.

   $c->login( )
       This method is used to initiate authentication and user retrieval.
       Technically this	is part	of the old Password credential module and it
       still resides in	the Password class. It is included here	for reference

   $c->default_auth_store( )
       Return the store	whose name is 'default'.

       This is set to "$c->config( 'Plugin::Authentication' => { store => #
       Store} )" if that value exists, or by using a Store plugin:

	   # load the Minimal authentication store.
	   use Catalyst	qw/Authentication Authentication::Store::Minimal/;

       Sets the	default	store to

   $c->get_auth_store( $name )
       Return the store	whose name is $name.

   $c->get_auth_store_name( $store )
       Return the name of the store $store.

   $c->auth_stores( )
       A hash keyed by name, with the stores registered	in the app.

   $c->register_auth_stores( %stores_by_name )
       Register	stores into the	application.

   $c->auth_store_names( )
   $c->get_user( )
       Please use the bug tracker, and git patches are wecome.

       Questions on usage should be directed to	the Catalyst mailing list or
       the #catalyst irc channel.

       Yuval Kogman, ""	- original author

       Jay Kuri, "" - Large rewrite

       Tomas Doran (t0m), ""

       Jess Robinson
       David Kamholz
       Nigel Metheringham
       Florian Ragwitz ""
       Stephan Jauernick ""
       Oskari Ojala (Okko), ""
       John Napiorkowski (jnap)	""

       Copyright (c) 2005 - 2012 the Catalyst::Plugin::Authentication

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.24.1			  2013-04-1Catalyst::Plugin::Authentication(3)


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

home | help