view release on metacpan or  search on metacpan

README  view on Meta::CPAN

                            }
                        },
                        admins => {
                            credential => {
                                class => 'Password',
                                password_field => 'password',
                                password_type => 'clear'
                            },
                            store => {
                                class => '+MyApp::Authentication::Store::NetAuth',
                                authserver => '192.168.10.17'
                            }
                        }
                    }
        );

    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

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

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

    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:
        Catalyst::Authentication::Store::storename.

METHODS
  $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

  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.

  find_realm_for_persisted_user()
    Private method, do not call from user code!

INTERNAL METHODS
    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 )

README  view on Meta::CPAN

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

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

  $c->setup_auth_realm( )
OVERRIDDEN METHODS
  $c->setup( )
SEE ALSO
    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.

  Realms
    Catalyst::Authentication::Realm

  User Storage Backends
    Catalyst::Authentication::Store::Minimal
    Catalyst::Authentication::Store::DBIx::Class
    Catalyst::Authentication::Store::LDAP
    Catalyst::Authentication::Store::RDBO
    Catalyst::Authentication::Store::Model::KiokuDB
    Catalyst::Authentication::Store::Jifty::DBI
    Catalyst::Authentication::Store::Htpasswd

  Credential verification
    Catalyst::Authentication::Credential::Password
    Catalyst::Authentication::Credential::HTTP
    Catalyst::Authentication::Credential::OpenID
    Catalyst::Authentication::Credential::Authen::Simple
    Catalyst::Authentication::Credential::Flickr
    Catalyst::Authentication::Credential::Testing
    Catalyst::Authentication::Credential::AuthTkt
    Catalyst::Authentication::Credential::Kerberos

  Authorization
    Catalyst::Plugin::Authorization::ACL,
    Catalyst::Plugin::Authorization::Roles

  Internals Documentation
    Catalyst::Plugin::Authentication::Internals

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

DON'T SEE ALSO
    This module along with its sub plugins deprecate a great number of other
    modules. These include Catalyst::Plugin::Authentication::Simple,
    Catalyst::Plugin::Authentication::CDBI.

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

COMPATIBILITY CONFIGURATION
    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.

COMPATIBILITY ROUTINES
    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
    only.

  $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/;