NAME

       Catalyst::Authentication::Realm - Base class for realm objects.

DESCRIPTION

CONFIGURATION

       class
           By default this class is used by Catalyst::Plugin::Authentication for all realms. The class parameter
           allows  you  to  choose a different class to use for this realm. Creating a new Realm class can allow
           for authentication methods that fall outside the normal credential/store methodology.

       auto_create_user
           Set this to true if you wish this realm to auto-create user accounts  when  the  user  doesn't  exist
           (most useful for remote authentication schemes).

       auto_update_user
           Set  this  to  true  if  you  wish this realm to auto-update user accounts after authentication (most
           useful for remote authentication schemes).

       use_session
           Sets session usage for this particular realm - overriding the global use_sesion setting.

METHODS

   new( $realmname, $config, $app )
       Instantiantes this realm, plus the specified store and credential classes.

   store( )
       Returns an instance of the store object for this realm.

   credential( )
       Returns an instance of the credential object for this realm.

   find_user( $authinfo, $c )
       Retrieves the user given the authentication information provided.  This is most  often  called  from  the
       credential.   The  default  realm  class  simply delegates this call the store object.  If enabled, auto-
       creation and auto-updating of users is also handled here.

   authenticate( $c, $authinfo)
       Performs the authentication process for the current realm.  The default realm class simply delegates this
       to the credential and sets the authenticated user on success.  Returns the authenticated user object;

USER PERSISTENCE

       The Realm class allows complete control over the persistance of users between requests.  By  default  the
       realm attempts to use the Catalyst session system to accomplish this.  By overriding the methods below in
       a custom Realm class, however, you can handle user persistance in any way you see fit.

   persist_user($c, $user)
       persist_user  is  the  entry  point  for saving user information between requests in most cases this will
       utilize the session.  By default this uses the catalyst session system  to  store  the  user  by  calling
       for_session  on  the active store.  The user object must be a subclass of Catalyst::Authentication::User.
       If you have updated the user object, you must call persist_user again to ensure that the  persisted  user
       object reflects your updates.

   remove_persisted_user($c)
       Removes any persisted user data.  By default, removes the user from the session.

   user_is_restorable( $c )
       Returns  whether  there  is  a  persisted user that may be restored.  Returns a token used to restore the
       user.  With the default session persistance it returns the raw frozen user information.

   restore_user($c, [$frozen_user])
       Restores the user from the given frozen_user parameter, or if  not  provided,  using  the  response  from
       $self->user_is_restorable();  Uses $self->from_session() to decode the frozen user.

   failed_user_restore($c)
       If  there  is a session to restore, but the restore fails for any reason then this method is called. This
       method supplied just removes the persisted user, but can be overridden if required to have  more  complex
       logic (e.g. finding a the user by their 'old' username).

   from_session($c, $frozenuser )
       Decodes  the  frozenuser  information provided and returns an instantiated user object.  By default, this
       call is delegated to $store->from_session().

   save_user_in_session($c, $user)
       DEPRECATED.  Use persist_user instead.  (this simply calls persist_user)

perl v5.40.0                                       2024-10-28               Catalyst::Authentication::Realm(3pm)