Ubuntu Manpage: WebLogin - Central login service for the WebAuth authentication system

Provided by: libwebkdc-perl_4.7.0-7build1_all

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.