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/>.