README

   1 NAME
   2     Catalyst::Plugin::Authentication - Infrastructure plugin for the
   3     Catalyst authentication framework.
   4
   5 SYNOPSIS
   6         use Catalyst qw/
   7             Authentication
   8         /;
   9
  10         # later on ...
  11         $c->authenticate({ username => 'myusername',
  12                            password => 'mypassword' });
  13         my $age = $c->user->get('age');
  14         $c->logout;
  15
  16 DESCRIPTION
  17     The authentication plugin provides generic user support for Catalyst
  18     apps. It is the basis for both authentication (checking the user is who
  19     they claim to be), and authorization (allowing the user to do what the
  20     system authorises them to do).
  21
  22     Using authentication is split into two parts. A Store is used to
  23     actually store the user information, and can store any amount of data
  24     related to the user. Credentials are used to verify users, using
  25     information from the store, given data from the frontend. A Credential
  26     and a Store are paired to form a 'Realm'. A Catalyst application using
  27     the authentication framework must have at least one realm, and may have
  28     several.
  29
  30     To implement authentication in a Catalyst application you need to add
  31     this module, and specify at least one realm in the configuration.
  32
  33     Authentication data can also be stored in a session, if the application
  34     is using the Catalyst::Plugin::Session module.
  35
  36     NOTE in version 0.10 of this module, the interface to this module
  37     changed. Please see "COMPATIBILITY ROUTINES" for more information.
  38
  39 INTRODUCTION
  40   The Authentication/Authorization Process
  41     Web applications typically need to identify a user - to tell the user
  42     apart from other users. This is usually done in order to display private
  43     information that is only that user's business, or to limit access to the
  44     application so that only certain entities can access certain parts.
  45
  46     This process is split up into several steps. First you ask the user to
  47     identify themselves. At this point you can't be sure that the user is
  48     really who they claim to be.
  49
  50     Then the user tells you who they are, and backs this claim with some
  51     piece of information that only the real user could give you. For
  52     example, a password is a secret that is known to both the user and you.
  53     When the user tells you this password you can assume they're in on the
  54     secret and can be trusted (ignore identity theft for now). Checking the
  55     password, or any other proof is called credential verification.
  56
  57     By this time you know exactly who the user is - the user's identity is
  58     authenticated. This is where this module's job stops, and your
  59     application or other plugins step in.
  60
  61     The next logical step is authorization, the process of deciding what a
  62     user is (or isn't) allowed to do. For example, say your users are split
  63     into two main groups - regular users and administrators. You want to
  64     verify that the currently logged in user is indeed an administrator
  65     before performing the actions in an administrative part of your
  66     application. These decisions may be made within your application code
  67     using just the information available after authentication, or it may be
  68     facilitated by a number of plugins.
  69
  70   The Components In This Framework
  71    Realms
  72     Configuration of the Catalyst::Plugin::Authentication framework is done
  73     in terms of realms. In simplest terms, a realm is a pairing of a
  74     Credential verifier and a User storage (Store) backend.
  75
  76     An application can have any number of Realms, each of which operates
  77     independant of the others. Each realm has a name, which is used to
  78     identify it as the target of an authentication request. This name can be
  79     anything, such as 'users' or 'members'. One realm must be defined as the
  80     default_realm, which is used when no realm name is specified. More
  81     information about configuring realms is available in the configuration
  82     section.
  83
  84    Credential Verifiers
  85     When user input is transferred to the Catalyst application (typically
  86     via form inputs) the application may pass this information into the
  87     authentication system through the $c->authenticate() method. From there,
  88     it is passed to the appropriate Credential verifier.
  89
  90     These plugins check the data, and ensure that it really proves the user
  91     is who they claim to be.
  92
  93    Storage Backends
  94     The authentication data also identifies a user, and the Storage backend
  95     modules use this data to locate and return a standardized
  96     object-oriented representation of a user.
  97
  98     When a user is retrieved from a store it is not necessarily
  99     authenticated. Credential verifiers accept a set of authentication data
 100     and use this information to retrieve the user from the store they are
 101     paired with.
 102
 103    The Core Plugin
 104     This plugin on its own is the glue, providing realm configuration,
 105     session integration, and other goodness for the other plugins.
 106
 107    Other Plugins
 108     More layers of plugins can be stacked on top of the authentication code.
 109     For example, Catalyst::Plugin::Session::PerUser provides an abstraction
 110     of browser sessions that is more persistent per users.
 111     Catalyst::Plugin::Authorization::Roles provides an accepted way to
 112     separate and group users into categories, and then check which
 113     categories the current user belongs to.
 114
 115 EXAMPLE
 116     Let's say we were storing users in a simple perl hash. Users are
 117     verified by supplying a password which is matched within the hash.
 118
 119     This means that our application will begin like this:
 120
 121         package MyApp;
 122
 123         use Catalyst qw/
 124             Authentication
 125         /;
 126
 127         __PACKAGE__->config->{authentication} =
 128                     {
 129                         default_realm => 'members',
 130                         realms => {
 131                             members => {
 132                                 credential => {
 133                                     class => 'Password',
 134                                     password_field => 'password',
 135                                     password_type => 'clear'
 136                                 },
 137                                 store => {
 138                                     class => 'Minimal',
 139                                     users = {
 140                                         bob => {
 141                                             password => "s00p3r",
 142                                             editor => 'yes',
 143                                             roles => [qw/edit delete/],
 144                                         },
 145                                         william => {
 146                                             password => "s3cr3t",
 147                                             roles => [qw/comment/],
 148                                         }
 149                                     }
 150                                 }
 151                             }
 152                             }
 153                     };
 154
 155     This tells the authentication plugin what realms are available, which
 156     credential and store modules are used, and the configuration of each.
 157     With this code loaded, we can now attempt to authenticate users.
 158
 159     To show an example of this, let's create an authentication controller:
 160
 161         package MyApp::Controller::Auth;
 162
 163         sub login : Local {
 164             my ( $self, $c ) = @_;
 165
 166             if (    my $user = $c->req->param("user")
 167                 and my $password = $c->req->param("password") )
 168             {
 169                 if ( $c->authenticate( { username => $user,
 170                                          password => $password } ) ) {
 171                     $c->res->body( "hello " . $c->user->get("name") );
 172                 } else {
 173                     # login incorrect
 174                 }
 175             }
 176             else {
 177                 # invalid form input
 178             }
 179         }
 180
 181     This code should be very readable. If all the necessary fields are
 182     supplied, call the "authenticate" method from the controller. If it
 183     succeeds the user is logged in.
 184
 185     The credential verifier will attempt to retrieve the user whose details
 186     match the authentication information provided to $c->authenticate().
 187     Once it fetches the user the password is checked and if it matches the
 188     user will be authenticated and "$c->user" will contain the user object
 189     retrieved from the store.
 190
 191     In the above case, the default realm is checked, but we could just as
 192     easily check an alternate realm. If this were an admin login, for
 193     example, we could authenticate on the admin realm by simply changing the
 194     $c->authenticate() call:
 195
 196         if ( $c->authenticate( { username => $user,
 197                                  password => $password }, 'admin' )l ) {
 198             $c->res->body( "hello " . $c->user->get("name") );
 199         } ...
 200
 201     Now suppose we want to restrict the ability to edit to a user with an
 202     'editor' value of yes.
 203
 204     The restricted action might look like this:
 205
 206         sub edit : Local {
 207             my ( $self, $c ) = @_;
 208
 209             $c->detach("unauthorized")
 210               unless $c->user_exists
 211               and $c->user->get('editor') eq 'yes';
 212
 213             # do something restricted here
 214         }
 215
 216     (Note that if you have multiple realms, you can use
 217     $c->user_in_realm('realmname') in place of $c->user_exists(); This will
 218     essentially perform the same verification as user_exists, with the added
 219     requirement that if there is a user, it must have come from the realm
 220     specified.)
 221
 222     The above example is somewhat similar to role based access control.
 223     Catalyst::Plugin::Authentication::Store::Minimal treats the roles field
 224     as an array of role names. Let's leverage this. Add the role
 225     authorization plugin:
 226
 227         use Catalyst qw/
 228             ...
 229             Authorization::Roles
 230         /;
 231
 232         sub edit : Local {
 233             my ( $self, $c ) = @_;
 234
 235             $c->detach("unauthorized") unless $c->check_roles("edit");
 236
 237             # do something restricted here
 238         }
 239
 240     This is somewhat simpler and will work if you change your store, too,
 241     since the role interface is consistent.
 242
 243     Let's say your app grew, and you now have 10000 users. It's no longer
 244     efficient to maintain a hash of users, so you move this data to a
 245     database. You can accomplish this simply by installing the DBIx::Class
 246     Store and changing your config:
 247
 248         __PACKAGE__->config->{authentication} =
 249                         {
 250                             default_realm => 'members',
 251                             realms => {
 252                                 members => {
 253                                     credential => {
 254                                         class => 'Password',
 255                                         password_field => 'password',
 256                                         password_type => 'clear'
 257                                     },
 258                                     store => {
 259                                         class => 'DBIx::Class',
 260                                         user_class => 'MyApp::Users',
 261                                         role_column => 'roles'
 262                                     }
 263                                     }
 264                             }
 265                         };
 266
 267     The authentication system works behind the scenes to load your data from
 268     the new source. The rest of your application is completely unchanged.
 269
 270 CONFIGURATION
 271             # example
 272             __PACKAGE__->config->{authentication} =
 273                         {
 274                             default_realm => 'members',
 275                             realms => {
 276                                 members => {
 277                                     credential => {
 278                                         class => 'Password',
 279                                         password_field => 'password',
 280                                         password_type => 'clear'
 281                                     },
 282                                     store => {
 283                                         class => 'DBIx::Class',
 284                                             user_class => 'MyApp::Users',
 285                                             role_column => 'roles'
 286                                         }
 287                                 },
 288                                 admins => {
 289                                     credential => {
 290                                         class => 'Password',
 291                                         password_field => 'password',
 292                                         password_type => 'clear'
 293                                     },
 294                                     store => {
 295                                         class => '+MyApp::Authentication::Store::NetAuth',
 296                                         authserver => '192.168.10.17'
 297                                     }
 298                                 }
 299
 300                         }
 301                         };
 302
 303         use_session
 304
 305         Whether or not to store the user's logged in state in the session,
 306         if the application is also using Catalyst::Plugin::Session. This
 307         value is set to true per default.
 308
 309         default_realm
 310
 311         This defines which realm should be used as when no realm is provided
 312         to methods that require a realm such as authenticate or find_user.
 313
 314         realms
 315
 316         This contains the series of realm configurations you want to use for
 317         your app. The only rule here is that there must be at least one. A
 318         realm consists of a name, which is used to reference the realm, a
 319         credential and a store.
 320
 321         Each realm config contains two hashes, one called 'credential' and
 322         one called 'store', each of which provide configuration details to
 323         the respective modules. The contents of these hashes is specific to
 324         the module being used, with the exception of the 'class' element,
 325         which tells the core Authentication module the classname to
 326         instantiate.
 327
 328         The 'class' element follows the standard Catalyst mechanism of class
 329         specification. If a class is prefixed with a +, it is assumed to be
 330         a complete class name. Otherwise it is considered to be a portion of
 331         the class name. For credentials, the classname 'Password', for
 332         example, is expanded to
 333         Catalyst::Plugin::Authentication::Credential::Password. For stores,
 334         the classname 'storename' is expanded to:
 335         Catalyst::Plugin::Authentication::Store::storename.
 336
 337 METHODS
 338     authenticate( $userinfo, $realm )
 339         Attempts to authenticate the user using the information in the
 340         $userinfo hash reference using the realm $realm. $realm may be
 341         omitted, in which case the default realm is checked.
 342
 343     user
 344         Returns the currently logged in user or undef if there is none.
 345
 346     user_exists
 347         Returns true if a user is logged in right now. The difference
 348         between user_exists and user is that user_exists will return true if
 349         a user is logged in, even if it has not been yet retrieved from the
 350         storage backend. If you only need to know if the user is logged in,
 351         depending on the storage mechanism this can be much more efficient.
 352
 353     user_in_realm ( $realm )
 354         Works like user_exists, except that it only returns true if a user
 355         is both logged in right now and was retrieved from the realm
 356         provided.
 357
 358     logout
 359         Logs the user out, Deletes the currently logged in user from
 360         $c->user and the session.
 361
 362     find_user( $userinfo, $realm )
 363         Fetch a particular users details, matching the provided user info,
 364         from the realm specified in $realm.
 365
 366 INTERNAL METHODS
 367     These methods are for Catalyst::Plugin::Authentication INTERNAL USE
 368     only. Please do not use them in your own code, whether application or
 369     credential / store modules. If you do, you will very likely get the
 370     nasty shock of having to fix / rewrite your code when things change.
 371     They are documented here only for reference.
 372
 373     set_authenticated ( $user, $realmname )
 374         Marks a user as authenticated. This is called from within the
 375         authenticate routine when a credential returns a user. $realmname
 376         defaults to 'default'
 377
 378     auth_restore_user ( $user, $realmname )
 379         Used to restore a user from the session. In most cases this is
 380         called without arguments to restore the user via the session. Can be
 381         called with arguments when restoring a user from some other method.
 382         Currently not used in this way.
 383
 384     save_user_in_session ( $user, $realmname )
 385         Used to save the user in a session. Saves $user in session, marked
 386         as originating in $realmname. Both arguments are required.
 387
 388     auth_realms
 389         Returns a hashref containing realmname -> realm instance pairs.
 390         Realm instances contain an instantiated store and credential object
 391         as the 'store' and 'credential' elements, respectively
 392
 393     get_auth_realm ( $realmname )
 394         Retrieves the realm instance for the realmname provided.
 395
 396
 397
 398 SEE ALSO
 399     This list might not be up to date. Below are modules known to work with
 400     the updated API of 0.10 and are therefore compatible with realms.
 401
 402   User Storage Backends
 403     Catalyst::Plugin::Authentication::Store::Minimal,
 404     Catalyst::Plugin::Authentication::Store::DBIx::Class,
 405
 406   Credential verification
 407     Catalyst::Plugin::Authentication::Credential::Password,
 408
 409   Authorization
 410     Catalyst::Plugin::Authorization::ACL,
 411     Catalyst::Plugin::Authorization::Roles
 412
 413   Internals Documentation
 414     Catalyst::Plugin::Authentication::Internals
 415
 416   Misc
 417     Catalyst::Plugin::Session, Catalyst::Plugin::Session::PerUser
 418
 419 DON'T SEE ALSO
 420     This module along with its sub plugins deprecate a great number of other
 421     modules. These include Catalyst::Plugin::Authentication::Simple,
 422     Catalyst::Plugin::Authentication::CDBI.
 423
 424     At the time of writing these plugins have not yet been replaced or
 425     updated, but should be eventually:
 426     Catalyst::Plugin::Authentication::OpenID,
 427     Catalyst::Plugin::Authentication::LDAP,
 428     Catalyst::Plugin::Authentication::CDBI::Basic,
 429     Catalyst::Plugin::Authentication::Basic::Remote.
 430
 431 INCOMPATABILITIES
 432     The realms based configuration and functionality of the 0.10 update of
 433     Catalyst::Plugin::Authentication required a change in the API used by
 434     credentials and stores. It has a compatibility mode which allows use of
 435     modules that have not yet been updated. This, however, completely mimics
 436     the older api and disables the new realm-based features. In other words
 437     you can not mix the older credential and store modules with realms, or
 438     realm-based configs. The changes required to update modules are
 439     relatively minor and are covered in
 440     Catalyst::Plugin::Authentication::Internals. We hope that most modules
 441     will move to the compatible list above very quickly.
 442
 443 COMPATIBILITY ROUTINES
 444     In version 0.10 of Catalyst::Plugin::Authentication, the API changed.
 445     For app developers, this change is fairly minor, but for Credential and
 446     Store authors, the changes are significant.
 447
 448     Please see the documentation in version 0.09 of
 449     Catalyst::Plugin::Authentication for a better understanding of how the
 450     old API functioned.
 451
 452     The items below are still present in the plugin, though using them is
 453     deprecated. They remain only as a transition tool, for those sites which
 454     can not yet be upgraded to use the new system due to local
 455     customizations or use of Credential / Store modules that have not yet
 456     been updated to work with the new API.
 457
 458     These routines should not be used in any application using realms
 459     functionality or any of the methods described above. These are for
 460     reference purposes only.
 461
 462     login
 463         This method is used to initiate authentication and user retrieval.
 464         Technically this is part of the old Password credential module and
 465         it still resides in the Password class. It is included here for
 466         reference only.
 467
 468     default_auth_store
 469         Return the store whose name is 'default'.
 470
 471         This is set to "$c->config->{authentication}{store}" if that value
 472         exists, or by using a Store plugin:
 473
 474             # load the Minimal authentication store.
 475                 use Catalyst qw/Authentication Authentication::Store::Minimal/;
 476
 477         Sets the default store to
 478         Catalyst::Plugin::Authentication::Store::Minimal.
 479
 480     get_auth_store $name
 481         Return the store whose name is $name.
 482
 483     get_auth_store_name $store
 484         Return the name of the store $store.
 485
 486     auth_stores
 487         A hash keyed by name, with the stores registered in the app.
 488
 489     register_auth_stores %stores_by_name
 490         Register stores into the application.
 491
 492 AUTHORS
 493     Yuval Kogman, "nothingmuch@woobling.org"
 494
 495     Jay Kuri, "jayk@cpan.org"
 496
 497     Jess Robinson
 498
 499     David Kamholz
 500
 501 COPYRIGHT & LICENSE
 502             Copyright (c) 2005 the aforementioned authors. All rights
 503             reserved. This program is free software; you can redistribute
 504             it and/or modify it under the same terms as Perl itself.
 505
 506 POD ERRORS
 507     Hey! The above document had some coding errors, which are explained
 508     below:
 509
 510     Around line 672:
 511         You can't have =items (as at line 706) unless the first thing after
 512         the =over is an =item
 513