view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Catalyst::Authentication::Credential::RemoteHTTP - Authenticate against
    remote HTTP server

VERSION
    version 0.05

SYNOPSIS
        package MyApp::Controller::Auth;

        use Catalyst qw/
          Authentication
          /;

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

            $c->authenticate( { username => $c->req->param('username'),
                                password => $c->req->param('password') });
        }

DESCRIPTION
    This authentication credential checker takes authentication information
    (most often a username) and a password, and attempts to validate the
    username and password provided against a remote http server - ie against
    another web server.

    This is useful for environments where you want to have a single source
    of authentication information, but are not able to conveniently use a
    networked authentication mechanism such as LDAP.

CONFIGURATION
        # example
        __PACKAGE__->config(
            'Plugin::Authentication' => {
                        default_realm => 'members',
                        realms => {
                            members => {
                                credential => {
                                    class => 'RemoteHTTP',
                                    url => 'http://intranet.company.com/authenticated.html',
                                    password_field => 'password',
                                    username_prefix => 'MYDOMAIN\\',
                                    http_keep_alive => 1,
                                    defer_find_user => 1,
                                },
                                ...
                        },
            },
        );

    class
        The classname used for Credential. This is part of
        Catalyst::Plugin::Authentication and is the method by which
        Catalyst::Authentication::Credential::RemoteHTTP is loaded as the
        credential validator. For this module to be used, this must be set
        to 'RemoteHTTP'.

    url The URL that is used to authenticate the user. The module attempts
        to fetch this URL using a HEAD request (to prevent dragging a large
        page across the network) with the credentials given. If this fails
        then the authentication fails. If no URL is supplied in the config,
        then an exception is thrown on startup.

    username_field
        The field in the authentication hash that contains the username.
        This may vary, but is most likely 'username'. In fact, this is so
        common that if this is left out of the config, it defaults to
        'username'.

    password_field
        The field in the authentication hash that contains the password.
        This may vary, but is most likely 'password'. In fact, this is so
        common that if this is left out of the config, it defaults to
        'password'.

    username_prefix
        This is an optional prefix to the username, which is added to the
        username before it is used for authenticating to the remote http
        server. It may be used (for example) to apply a domain to the
        authenticated username.

    username_suffix
        This is an optional suffix to the username, which is added to the
        username before it is used for authenticating to the remote http
        server. It may be used (for example) to apply a domain to the
        authenticated username.

    http_keep_alive
        If "http_keep_alive" is set then keep_alive is set on the
        connections to the remote http server. This is required if you are
        using NTLM authentication (since an additional encryption nonce is
        passed in the http negotiation). It is optional, but normally
        harmless, for other forms of authentication.

    defer_find_user
        Normally the associated user store is queried for user information
        before the remote http authentication takes place.

        However if, for example, you are using a
        Catalyst::Authentication::Store::DBIx::Class store with the
        "auto_create_user" option, then you can end up with invalid users
        added to the store. If "defer_find_user" is set true then the remote
        http authentication occurs before the user is queried against the
        store, ensuring that any users passed to the store are known to be
        valid to the remote http server.

METHODS
    There are no publicly exported routines in the RemoteHTTP module (or
    indeed in most credential modules.) However, below is a description of
    the routines required by Catalyst::Plugin::Authentication for all
    credential modules.

  new( $config, $app, $realm )
    Instantiate a new RemoteHTTP object using the configuration hash
    provided in $config. A reference to the application is provided as the
    second argument.

  authenticate( $authinfo, $c )
    Try to log a user in, receives a hashref containing authentication
    information as the first argument, and the current context as the