Constructor. Takes a hashref of properties as arguments.
Many of the methods which may be overridden in a subclass, or may be passed as properties to the new constuctor such as in the following:
The following methods will look for properties of the same name. Each of these will be described separately.
Takes either an auth_data object from a auth_data returned by verify_token,
or a hashref of arguments.
Possible arguments are:
The following are types of tokens that can be generated by generate_token. Each type includes pseudocode and a sample of a generated that token.
Performs the core logic. Returns an auth object on successful login.
Returns false on errored login (with the details of the error stored in
$@). If a false value is returned, execution of the CGI should be halted.
get_valid_auth WILL NOT automatically stop execution.
Optionally, the class and a list of arguments may be passed. This will create a new object using the passed arguments, and then run get_valid_auth.
|check_valid_auth||Runs get_valid_auth with login_print and location_bounce set to do nothing. This allows for obtaining login data without forcing an html login page to appear.|
Called if login errored. Defaults to printing a very basic (but
adequate) page loaded from login_template..
You will want to override it with a template from your own system. The hook that is called will be passed the step to print (currently only get_login_info and no_cookies), and a hash containing the form variables as well as the following:
Passed to the template swapped during login_print.
|bounce_on_logout||Default 0. If true, will location bounce to script returned by logout_redirect passing the key key_logout. If false, will simply show the login screen.|
|key_loggedout||Key to bounce with in the form during a logout should bounce_on_logout return true. Default is loggedout.|
|key_logout||If the form hash contains a true value in this field name, the current user will be logged out. Default is cea_logout.|
|key_cookie||The name of the auth cookie. Default is cea_user.|
|key_verify||A field name used during a bounce to see if cookies exist. Default is cea_verify.|
|key_user||The form field name used to pass the username. Default is cea_user.|
|key_pass||The form field name used to pass the password. Default is cea_pass.|
Works in conjunction with key_expires_min. If key_save is true, then
the cookie will be set to be saved for longer than the current session
(If it is a plaintext variety it will be given a 20 year life rather
than being a session cookie. If it is a cram variety, the expires_min
portion of the cram will be set to -1). If it is set to false, the cookie
will be available only for the session (If it is a plaintext variety, the cookie
will be session based and will be removed on the next loggout. If it is
a cram variety then the cookie will only be good for expires_min minutes.
Default is cea_save.
The name of the form field that contains how long cram type cookies will be valid
if key_save contains a false value.
Default key name is cea_expires_min. Default field value is 6 * 60 (six hours).
This value will have no effect when use_plaintext or use_crypt is set.
A value of -1 means no expiration.
|failed_sleep||Number of seconds to sleep if the passed tokens are invalid. Does not apply if validation failed because of expired tokens. Default value is 0. Setting to 0 disables any sleeping.|
|verify_token||This method verifies the token that was passed either via the form or via cookies. It will accept plaintext or crammed tokens (A listing of the available algorithms for creating tokes is listed below). It also allows for armoring the token with base64 encoding, or using blowfish encryption. A listing of creating these tokens can be found under generate_token.|
|parse_token||Used by verify_token to remove armor from the passed tokens and split the token into its parts. Returns true if it was able to parse the passed token.|
|cleanup_user||Called by verify_token. Default is to do no modification. Allows for usernames to be lowercased, or canonized in some other way. Should return the cleaned username.|
|verify_user||Called by verify_token. Single argument is the username. May or may not be an initial check to see if the username is ok. The username will already be cleaned at this point. Default return is true.|
Called by verify_token. Given the cleaned, verified username, should return a
valid password for the user. It can always return plaintext. If use_crypt is
enabled, it should return the crypted password. If use_plaintext and use_crypt
are not enabled, it may return the md5 sum of the password.
Alternately, get_pass_by_user may return a hashref of data items that will be added to the data object if the token is valid. The hashref must also contain a key named real_pass or password that contains the password. Note that keys passed back in the hashref that are already in the data object will override those in the data object.
|verify_password||Called by verify_token. Passed the password to check as well as the auth data object. Should return true if the password matches. Default method can handle md5, crypt, cram, secure_hash_cram, and plaintext (all of the default types supported by generate_token). If a property named verify_password exists, it will be used and called as a coderef rather than using the default method.|
|verify_payload||Called by verify_token. Passed the password to check as well as the auth data object. Should return true if the payload is valid. Default method returns true without performing any checks on the payload. If a property named verify_password exists, it will be used and called as a coderef rather than using the default method.|
|cgix||Returns a CGI::Ex object.|
|form||A hash of passed form info. Defaults to CGI::Ex::get_form.|
|cookies||The current cookies. Defaults to CGI::Ex::get_cookies.|
Should return either a template filename to use for the login template, or it
should return a reference to a string that contains the template. The contents
will be used in login_print and passed to the template engine.
Default login_template is the values of login_header, login_form, login_script, and login_script concatenated together.
Values from login_hash_common will be passed to the template engine, and will also be used to fill in the form.
The basic values are capable of handling most needs so long as appropriate headers and css styles are used.
Should return a header to use in the default login_template. The default
value will try to PROCESS a file called login_header.tt that should be
located in directory specified by the template_include_path method.
It should ideally supply css styles that format the login_form as desired.
|login_footer||Same as login_header - but for the footer. Will look for login_footer.tt by default.|
|login_form||An html chunk that contains the necessary form fields to login the user. The basic chunk has a username text entry, password text entry, save password checkbox, and submit button, and any hidden fields necessary for logging in the user.|
|text_user, text_pass, text_save||
The text items shown in the default login template. The default values are:
Disables simple cram type from being an available type. Default is
false. If set, then one of use_plaintext, use_crypt, or
secure_hash_keys should be set. Setting this option allows for
payloads to be generated by the server only - otherwise a user who
understands the algorithm could generate a valid simple_cram cookie
with a custom payload.
Another option would be to only accept payloads from tokens if use_blowfish is set and armor was equal to blowfish.
This module may be distributed under the same terms as Perl itself.
Paul Seamons <perl at seamons dot com>
|perl v5.20.3||CGI::EX::AUTH (3)||2015-10-07|