WebLogin(3pm)
NAME
WebLogin - Central login service for the WebAuth authentication system
SYNOPSIS
use WebLogin;
my $weblogin = WebLogin->new (PARAMS => { pages => \%pages },
QUERY => $q);
$weblogin->run;
DESCRIPTION
The WebLogin module implements a CGI service using the CGI::Application framework that provides central login services for the WebAuth authentication system. For its entry points and constructor options, see "Instance Script Methods" in CGI::Application. This module is normally only called from the login.fcgi, logout.fcgi, and pwchange.cgi scripts that come with WebAuth and comprise, with this module, the WebLogin service. It is not currently designed to be used by any other scripts and does not currently have a documented API.
FUNCTIONS
setup
Overridden CGI::Application setup function. This is used for all
initialization of data needed for our WebLogin object. It sets
various defaults, sets up our Template Toolkit options, creates
memcached caches, and other needed setup items to prepare.
cgiapp_prerun
Overridden CGI::Application function that is called before the
processing of each individual query. This does further setup
that's meant to be query-specific, since we're potentially being
wrapped up in FastCGI or other methods that will cache the WebLogin
object.
This includes clearing any parameters or template parameters from
previous runs, creating fresh objects for handling current query
and responses, and storing other query-specific data.
krb5_escape (PRINCIPAL)
Escape special characters in a principal name to match the escaping
done by krb5_unparse_name. Returns the escaped principal name.
fix_token (TOKEN)
Encode a token for URL usage.
expire_cookie (NAME, SECURE)
Create and return a CGI::Cookie object that will expire an existing
cookie. The cookie has the given NAME set, and includes the given
flag as to whether or not it uses SSL.
is_factor_set
Uses the cookies set on the WebKDC::WebResponse object to determine
if we have a factor token passed back from the WebKDC. Returns 1
if so, 0 if not.
template_params (SETTINGS_REF)
Interface used to wrap up and save various parameters that we are
storing to later be used in the template files. Takes a hashref to
settings we wish to add/override, and returns the ending hashref of
all current parameters.
get_pagename (PAGETYPE)
Takes the type of page we want, then returns the file name of the
template that is used to display that page type.
print_headers (ARGS_REF)
Sets the headers for a page. This handles setting or removing any
cookies, then setting the headers. If a return URL was set, add a
redirect to that URL into the headers.
pretty_return_uri (URI)
Takes a URI object and uses it to create a 'pretty' return URI, one
that's more readable by users for display on the configuration
page. Returns a string containing that URI.
parse_uri
Parses the return URL from the web response and either sets the
pretty URI (via petty_return_uri) or flags an error to the template
if there was something wrong with the URL.
token_rights
Parses the token.acl file, using that to return an arrayref of the
credentials that the requesting WAS is permitted to obtain. This
is used in cases where a specific WAS might have access to request
delegated credentials.
get_login_cancel_url
Checks to see if there is a login canceled token, and if so, sets
template parameters to offer a login canceled URL with that token.
print_login_page
View for the user login page. This is the view that allows a user
to attempt to login, offering fields for username and password,
possibly a URL for remote user authentication, and any errors from
previous failed logins.
print_error_page
View for the generic error page. This will pass along any
previously set error types for the template, and make sure that the
error page itself isn't cached.
print_error_fatal
View for a fatal error. This is something normally only used on an
error to print out a template, meant as an emergency fallback to
display something when things are very messed up.
print_confirm_page
View for the confirmation page post-login. This potentially
includes a password expiration warning, a warning for expiring
device factor cookies, and a notice for delegated credentials. If
none of those are set, then we may (on WebKDC::Config settings)
bypass the confirmation page entirely and just send a redirect to
the login destination.
redisplay_confirm_page
View to redisplay the confirmation page after a change in the
REMOTE_USER cookie. This is a much more simple version of
print_confirm_page, as it doesn't have to do most of the checking
for warnings and whether or not to bypass the page.
print_pwchange_page
View to print out the password change page. Pass along any needed
user information, such as their login information and any change
password token.
print_pwchange_confirm_page
View to print out a confirmation after a successful password
change. This is only accessed when the user is going to the
password change page via the URL just for that, rather than as a
part of the normal login flow.
print_multifactor_page
View to print out a page prompting the user to enter their
multifactor one-time password. We pass along user information, the
factors needed for login, and the factors the user has.
print_remuser_redirect
Redirect a user to the REMOTE_USER enabled login URL. This passes
the request token and service token on to the URL, then returns it
as a redirect page for CGI::Application to print.
add_generic_proxy_token (ARGS_REFERENCE)
Create and add a generic token to the set of tokens passed to the
WebKDC via the web request. Read the ARGS_REFERENCE for any non-
default arguments we wish to create the proxy token with, then
create a new WebAuth::Token::WebKDCProxy object. Encode it with
the keyring and add it to the proxy cookies on the web request.
add_kerberos_proxy_token
Create a proxy token using forwarded Kerberos credentials and pass
into the web request.
add_remuser_token
Create a proxy token with the REMOTE_USER identity and pass into
the web request. This does validation against the REMOTE_USER
setting, then passes along to add_generic_proxy_token if it passes
our requirements.
add_changepw_token
Create a kadmin/changepw token using the username and password of a
user after successful login. This will create a ticket, put it
into a WebAuth::Token::Cred object, and use the keyring to encode
it. The token is passed back as the CPT parameter on the WebLogin
object. Returns 1 on success.
change_user_password
Attempt to change a user's password using a previously created
change password token. Validate that the token is correct for the
given user, then attempt to change the user's password, returning a
status and any exception objects that may have been created during
failures.
error_if_no_cookies
Tests to make sure that cookies are enabled in the user's browser.
If a test cookie is not set, we reload the page with an attempt to
set that cookie and a flag showing that we're making the attempt.
If we find the flag set and no cookie, then the user does not have
cookies set, and we display an error page.
error_password_no_post
Tests to make sure that if a password was sent, the request method
was POST. This is done in order to avoid the password potentially
showing up in referrer strings sent to a remote site. If the
method was not POST, we display an error page.
error_no_request_token
Tests to make sure that we have a request token and service token
defined in the submitted CGI query. If not, we will display an
error page.
error_invalid_pwchange_fields
Tests the requirements for a password change request page to be
successfully entered. This does not actually try to change the
password or check that it is successful, but only checks to make
sure that the user has entered all of the needed data. If not, we
will display the password change page again, with error flags for
the missing or incorrect fields.
is_replay (RT)
Checks against memcached to see if the given request token has been
recently used, in order to detect a replay attack. Returns 1 if
the request token was found.
is_rate_limited (USERNAME)
Checks against memcached to see if the given user has exceeded a
certain number of failed logins. Returns 1 if the user has
exceeded the number (set in WebKDC::Config).
register_auth (RT, USERNAME)
Registers a successful authentication for the given user in
memcached, with the request token for the authentication. This is
used to detect replay attacks.
register_auth_fail (USERNAME)
Registers a failed authentication for the given user in memcached.
This is used for rate limiting users on failed logins.
setup_kdc_request (COOKIES)
Takes the WebKDC::WebRequest object already created, and fills that
object with data from the user/browser. This includes current
cookies passed to us, and also any relevant data sent via the CGI
query. The latter can include username and password, for two
examples.
Returns the status from the request. This is usually WK_SUCCESS as
we are not actually contacting the WebKDC at this point, but can be
error statuses in cases such as the user not filling in their
username, or if replay or rate limited checks were triggered.
handle_login_error (STATUS, ERROR)
This is a catch-all handler for any error during the normal user
login process. This uses the given error status to decide what
needs to be done to handle this error case, often simply printing
out a screen to request additional information or the user to re-
enter correct information. In some cases, this will have to throw
up an unrecoverable error page that the user can do nothing with.
index
The default run mode, handling the basic attempt to log in, whether
via plain username and password, SPNEGO, or other method.
This is called if no other run mode is set by the main login URL,
or on any regular failure to successfully log in (such as invalid
password).
logout
Run mode to handle a request by the user to log out, blowing away
all proxy cookies.
This is only called via the logout URL.
pwchange()
Run mode to handle an attempt by the user to change their current
password. This handles the attempt to change the user password,
either passing the user on to the confirmation page or bringing the
user back to this page on a problem with changing the password.
This is called by either the user clicking a link from the confirm
page warning that their password is soon to expire, or by the user
being forced to here after logging in with an expired password.
pwchange_display
Run mode to handle a direct access to the password change display
screen.
This is called only by the user visiting the password change URL
from outside the normal program flow.
multifactor
Run mode to handle an attempted multifactor login. The username
and one-time password are passed to the WebKDC in order to validate
whether or not there was a successful login, and the user is then
sent to either the confirm page on success, or the multifactor page
again on failure.
This is called from the multifactor entry screen, when the user
submits their one-time password.
multifactor_sendauth
Run mode to handle the request from a user to send a multifactor
authentication token somewhere via a remctl command. The command
itself is configured in WebKDC::Config. The normal case would be
sending out a OTP over SMS to a user.
This is called from the multifactor entry screen, in the case of a
user having a multifactor method that requires the user be sent a
token.
edit_authz_identity
Run mode to handle the request from a user to change their
authorization identity.
This is called from the config screen.
edit_remoteuser
Run mode to handle the request from a user to change their
REMOTE_USER setting.
This is called from the config screen.
AUTHORS
Roland Schemers, Russ Allbery <eagle@eyrie.org>, and Jon Robertson <jonrober@stanford.edu>.
SEE ALSO
WebAuth(3), WebKDC(3), WebKDC::Config(3) This module is part of WebAuth. The current version is available from <http://webauth.stanford.edu/>.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
