Choosing a Driver

If you need to authenticate against a source that is not provided, you can use the Generic driver which will accept either a hash of username/password pairs, or an array of arrays of credentials, or a subroutine reference that can verify the credentials. So through the Generic driver you should be able to write your own verification system. There is also a Dummy driver, which blindly accepts any credentials (useful for testing). See the CGI::Application::Plugin::Authentication::Driver::Generic, CGI::Application::Plugin::Authentication::Driver::DBI and, CGI::Application::Plugin::Authentication::Driver::Dummy docs for more information on how to use these drivers. And see the Authen::Simple suite of modules for information on those drivers.

Choosing a Store

If you do not specify which Store module you wish to use, the plugin will try to determine the best one for you.

Login page

Ticket based authentication

authen

  __PACKAGE__->authen->config(
        LOGIN_RUNMODE => 'login',
  );

- or -

  $self->authen->protected_runmodes(qw(one two));

config

The following parameters are accepted:

DRIVER

Here you can choose which authentication module(s) you want to use to perform the authentication. For simplicity, you can leave off the CGI::Application::Plugin::Authentication::Driver:: part when specifying the DRIVER name If this module requires extra parameters, you can pass an array reference that contains as the first parameter the name of the module, and the rest of the values in the array will be considered options for the driver. You can provide multiple drivers which will be used, in order, to check the credentials until a valid response is received.

     DRIVER => 'Dummy' # let anyone in regardless of the password

  - or -

     DRIVER => [ 'DBI',
         DBH         => $self->dbh,
         TABLE       => 'user',
         CONSTRAINTS => {
             'user.name'         => '__CREDENTIAL_1__',
             'MD5:user.password' => '__CREDENTIAL_2__'
         },
     ],

  - or -

     DRIVER => [
         [ 'Generic', { user1 => '123' } ],
         [ 'Generic', sub { my ($u, $p) = @_; is_prime($p) ? 1 : 0 } ]
     ],

  - or -

     DRIVER => [ 'Authen::Simple::LDAP',
         host   => 'ldap.company.com',
         basedn => 'ou=People,dc=company,dc=net'
     ],
    

STORE

Here you can choose how we store the authenticated information after a user has successfully logged in. We need to store the username so that on the next request we can tell the user has already logged in, and we do not have to present them with another login form. If you do not provide the STORE option, then the plugin will look to see if you are using the CGI::Application::Plugin::Session module and based on that info use either the Session module, or fall back on the Cookie module. If the module requires extra parameters, you can pass an array reference that contains as the first parameter the name of the module, and the rest of the array should contain key value pairs of options for this module. These storage modules generally live under the CGI::Application::Plugin::Authentication::Store:: name-space, and this part of the package name can be left off when specifying the STORE parameter.

    STORE => 'Session'

  - or -

    STORE => ['Cookie',
        NAME   => 'MYAuthCookie',
        SECRET => 'FortyTwo',
        EXPIRY => '1d',
    ]
    

POST_LOGIN_RUNMODE

Here you can specify a runmode that the user will be redirected to if they successfully login.

  POST_LOGIN_RUNMODE => 'welcome'
    

POST_LOGIN_URL

Here you can specify a URL that the user will be redirected to if they successfully login. If both POST_LOGIN_URL and POST_LOGIN_RUNMODE are specified, then the latter will take precedence.

  POST_LOGIN_URL => 'http://example.com/start.cgi'
    

POST_LOGIN_CALLBACK

A code reference that is executed after login processing but before POST_LOGIN_RUNMODE or redirecting to POST_LOGIN_URL. This is normally a method in your CGI::Application application and as such the CGI::Application object is passed as a parameter.

  POST_LOGIN_CALLBACK => \&update_login_date
    

and later in your code:

  sub update_login_date {
    my $self = shift;

    return unless($self->authen->is_authenticated);

    ...
  }
    

LOGIN_RUNMODE

Here you can specify a runmode that the user will be redirected to if they need to login.

  LOGIN_RUNMODE => 'login'
    

LOGIN_URL

If your login page is external to this module, then you can use this option to specify a URL that the user will be redirected to when they need to login. If both LOGIN_URL and LOGIN_RUNMODE are specified, then the latter will take precedence.

  LOGIN_URL => 'http://example.com/login.cgi'
    

LOGOUT_RUNMODE

Here you can specify a runmode that the user will be redirected to if they ask to logout.

  LOGOUT_RUNMODE => 'logout'
    

LOGOUT_URL

If your logout page is external to this module, then you can use this option to specify a URL that the user will be redirected to when they ask to logout. If both LOGOUT_URL and LOGOUT_RUNMODE are specified, then the latter will take precedence.

  LOGIN_URL => 'http://example.com/logout.html'
    

DETAINT_URL_REGEXP

This is a regular expression used to detaint URLs used in the login form. By default it will be set to

  ^([\w\_\%\?\&\;\-\/\@\.\+\$\=\#\:\!\*\"\'\(\)\,]+)$
    

This regular expression is based upon the document http://www.w3.org/Addressing/URL/url-spec.txt. You could set it to a more specific regular expression to limit the domains to which users could be directed.

DETAINT_USERNAME_REGEXP

This is a regular expression used to detaint the username parameter used in the login form. By default it will be set to

  ^([\w\_]+)$
    

CREDENTIALS

Set this to the list of form fields where the user will type in their username and password. By default this is set to ['authen_username', 'authen_password']. The form field names should be set to a value that you are not likely to use in any other forms. This is important because this plugin will automatically look for query parameters that match these values on every request to see if a user is trying to log in. So if you use the same parameter names on a user management page, you may inadvertently perform a login when that was not intended. Most of the Driver modules will return the first CREDENTIAL as the username, so make sure that you list the username field first. This option can be ignored if you use the built in login box

  CREDENTIALS => 'authen_password'

  - or -

  CREDENTIALS => [ 'authen_username', 'authen_domain', 'authen_password' ]
    

LOGIN_SESSION_TIMEOUT

This option can be used to tell the system when to force the user to re-authenticate. There are a few different possibilities that can all be used concurrently:

  # force re-authentication if idle for more than 15 minutes
  LOGIN_SESSION_TIMEOUT => '15m'

  # Everyone must re-authentication if idle for more than 30 minutes
  # also, everyone must re-authentication at least once a day
  # and root must re-authentication if idle for more than 5 minutes
  LOGIN_SESSION_TIMEOUT => {
        IDLE_FOR => '30m',
        EVERY    => '1d',
        CUSTOM   => sub {
          my $authen = shift;
          return ($authen->username eq 'root' && (time() - $authen->last_access) > 300) ? 1 : 0;
        }
  }

RENDER_LOGIN

This value can be set to a subroutine reference that returns the HTML of a login form. The subroutine reference overrides the default call to login_box. The subroutine is normally a method in your CGI::Application application and as such the CGI::Application object is passed as the first parameter.

  RENDER_LOGIN => \&login_form
    

and later in your code:

  sub login_form {
    my $self = shift;

    ...
    return $html
  }
    

LOGIN_FORM

You can set this option to customize the login form that is created when a user needs to be authenticated. If you wish to replace the entire login form with a completely custom version, then just set LOGIN_RUNMODE to point to your custom runmode.

All of the parameters listed below are optional, and a reasonable default will be used if left blank:

protected_runmodes

:all - All runmodes in this module will require authentication

  # match all runmodes
  __PACKAGE__->authen->protected_runmodes(':all');

  # only protect runmodes one two and three
  __PACKAGE__->authen->protected_runmodes(qw(one two three));

  # protect only runmodes that start with auth_
  __PACKAGE__->authen->protected_runmodes(qr/^auth_/);

  # protect all runmodes that *do not* start with public_
  __PACKAGE__->authen->protected_runmodes(qr/^(?!public_)/);

is_protected_runmode

redirect_after_login

POST_LOGIN_RUNMODE

If the POST_LOGIN_RUNMODE config parameter is set, that run mode will be the chosen location.

POST_LOGIN_URL

If the above fails and the POST_LOGIN_URL config parameter is set, then there will be a 302 redirection to that location.

destination

If the above fails and there is a destination query parameter, which must a taint check against the DETAINT_URL_REGEXP config parameter, then there will be a 302 redirection to that location.

original destination

If all the above fail then there the originally requested page will be delivered.

redirect_to_login

redirect_to_logout

setup_runmodes

last_login

  my $last_login = $self->authen->last_login;

This function will initiate a session or cookie if one has not been created already.

last_access

  my $last_access = $self->authen->last_access;

This function will initiate a session or cookie if one has not been created already.

is_login_timeout

  $self->add_message('login session timed out') if $self->authen->is_login_timeout;

This function will initiate a session or cookie if one has not been created already.

is_authenticated

  assert($self->authen->is_authenticated); # The user should be logged in if we got here

This function will initiate a session or cookie if one has not been created already.

login_attempts

username

  my $username = $self->authen->username;

This function will initiate a session or cookie if one has not been created already.

is_new_login

  $self->log->info("New Login") if $self->authen->is_new_login;

This function will initiate a session or cookie if one has not been created already.

credentials

logout

  $self->authen->logout();

This function will initiate a session or cookie if one has not been created already.

drivers

store

initialize

The user will be logged out by calling the "logout()" method if the login session has been idle for too long, if it has been too long since the last login, or if the login has timed out. If you need to know if a user was logged out because of a time out, you can call the "is_login_timeout" method.

If all goes well, a true value will be returned, although it is usually not necessary to check.

This function will initiate a session or cookie if one has not been created already.

display

login_box

This function will initiate a session or cookie if one has not been created already.

new

instance

prerun_callback

 sub cgiapp_prerun {
    my $self = shift;

    $self->CGI::Application::Plugin::Authentication::prerun_callback();
 }

authen_login_runmode

authen_dummy_redirect