| < WebKDC Multifactor | Russ Allbery > Software > Orphaned Software > WebAuth |
WebLogin is the name for the component of WebAuth that handles user authentication interaction. It is a CGI service that runs on the WebKDC and presents HTML login forms, status pages, and handles translating browser cookies into XML requests to the WebKDC and vice versa. It passes its data to the WebKDC via a localhost HTTPS connection, but otherwise uses the same URL as application servers use to talk to the WebKDC.
For a detailed description of the user interactions and page flow in weblogin, see doc/weblogin-flow. This document describes the configuration and customization of the weblogin interface.
WebLogin uses a set of template HTML pages to display the login, logout, confirmation, and error pages. Internally, it uses the Template Perl module to process these templates. For detailed information about the supported syntax, install that module and then run:
perldoc Template
You can probably figure out the details you need by looking at the existing templates, though. WebLogin doesn't use any advanced features. The only key feature to be aware of is that any variable which is interpolated into the template needs to have "FILTER html" added to the directive to prevent any possible cross-site scripting attacks.
You will almost certainly want to customize these templates for your site to match your local page look and feel. The provided templates are functional and simple, but not particularly pretty.
There are four templates used by the weblogin scripts. The following documents all of the variables that are set by WebLogin. These variables don't have to be used if they're not of interest to your site or involve flows that you're not using.
The primary two templates are:
login.tmpl
error If set, some error happened
err_missinginput If set, user didn't supply username and password
err_username If set, user didn't supply username
err_password If set, user didn't supply password
err_loginfailed If set, login was invalid
err_forced If set, username/password login is forced
err_rejected If set, user was rejected by WebKDC
remuser_failed If set, REMOTE_USER was tried and failed
script_name Relative URL to which form should be posted
username Username, if already known
RT Request token (must be included in form)
ST Service token (must be included in form)
login_cancel If set, application provided a cancel URL
cancel_url The cancel URL (return URL plus cancel token)
show_remuser If set, show the option to try REMOTE_USER
remuser_uri URL to which to send the user for REMOTE_USER
confirm.tmpl
username Authenticated username
authz_subject Authorization identity of the user (may be empty)
return_url Return URL, including response tokens
pretty_return_url Anchor text for return URL (usually just host)
RT Original request token
ST Original service token
login_cancel If set, application provided a cancel URL
cancel_url The cancel URL (return URL plus cancel token)
remember_login If not set, delete SSO cookies at end of login
warn_expire If set, show warning for upcoming password expiration
expire_timestamp Epoch seconds for time password will expire
pwchange_url URL for the password change form
device_expiring Epoch seconds for time device factor will expire
show_remuser If set, show the REMOTE_USER cookie configuration
remuser If set, the REMOTE_USER cookie is set
script_name Relative URL to which cookie change should be posted
token_rights List (for FOREACH) of credentials WAS may request
type Type of credential (e.g. krb5)
name Credential (e.g. afs/example.com@EXAMPLE.COM)
principal First part of principal (e.g. afs)
instance Remaining part of principal (e.g. example.com)
realm Realm of credential (e.g. EXAMPLE.COM)
history List (for FOREACH) of previous login hosts/IPs
ip Originating IP (required)
hostname Originating hostname (optional)
timestamp Timestamp (required)
permitted_authz List (for FOREACH) of possible authorization ids
user_message Raw HTML returned by the user information service
token_rights will be a list, each member of which is a hash. The keys of the hash are listed under token_rights above. principal, instance, and realm will only be set if type is "krb5". See the WebKDC manual under WebKdcTokenAcl and the WebAuth protocol documentation for more information about the type of credentials that can be delegated.
A different template is used when the user doesn't have cookies enabled or in the event of some other WebKDC error. It takes the following Template variables:
error.tmpl
err_html If set, the entire HTML to display
err_bad_method If set, login form submitted without POST
err_confirm If set, incomplete data for confirm page
err_cookies_disabled If set, user doesn't have cookies enabled
err_insufficient_mfactor If set, user multifactor below requested level
err_insufficient_loa If set, user LoA below requested level
err_lockout If set, locked out due to excessive failures
err_no_mfactor If set, user has no configured multifactor
err_no_request_token If set, user had no request token
err_replay If set, authentication was a replay
err_sendauth If set, error running sendauth program
err_webkdc If set, the WebKDC reported an error
err_msg WebKDC error message
multifactor_required List (for FOREACH) of factors required
multifactor_configured List (for FOREACH) of factors user can have
login_cancel If set, application provided a cancel URL
cancel_url The cancel URL (return URL plus cancel token)
When encountering a login that requires multifactor, we send the user to a page that will prompt them for entering a multifactor one-time password, and potentially allow them to send those passwords via an external mechanism. It takes the following Template variables:
multifactor.tmpl
factor_type Type of multifactor being used (o1, o2, etc)
username The authenticated identity of the user
login_cancel If set, application provided a cancel URL
cancel_url The cancel URL (return URL plus cancel token)
multifactor_sentauth If set, we have run the sendauth function
error If set, some error happened
err_multifactor_missing If set, form was submitted without an OTP
err_multifactor_invalid If set, could not validate a submitted OTP
multifactor_required Set to site-required mf when user mf too low
multifactor_configured Set to user mf when user mf too low for site
user_message Raw HTML from the user information service
Finally, the logout script uses a simple template with only one variable:
logout.tmpl
cookies_flag If set, found a single sign-on cookie to delete
When customizing the templates for your site, carefully note the form elements set by the existing templates and make sure that your templates include the same form elements with the same names. Otherwise, the WebLogin scripts will not work as expected.
The behavior of the weblogin script is configured using the WebKDC::Config Perl module. That module sets some defaults and then loads /etc/webkdc/webkdc.conf to override those defaults or set any other configuration. /etc/webkdc/webkdc.conf must be valid Perl code, but don't let that scare you; you don't need to be a Perl programmer to configure it.
To change any of the configuration variables, put a line like the following into /etc/webkdc/webkdc.conf:
$VARIABLE = "value";
or
$VARIABLE = 10;
The former is for variables that take strings, and the latter is for variables that take numbers. The following variables are recognized. In some cases, the preferred name of the variable has changed, but the old version is supported for backward compatibility; this is noted in parens after the variable name.
The path of the configuration file can be overridden by setting the WEBKDC_CONFIG environment variable to point to some other path. This can be done inside Apache with mod_env.
Supported configuration variables are:
$BYPASS_CONFIRM
By default, a confirmation page is always shown to the user and they have to follow the link to continue to wherever they were trying to go. This page serves to warn the user that they're entering an authenticated site, to tell them what site they're authenticating to, and to give them an opportunity to cancel logging on to that site.
When this variable is set to a true value (1 is a good true value), the confirmation page is suppressed and the user is silently redirected to the destination page. For REMOTE_USER authentication or authentication using a single sign-on cookie, this is done with a 302 redirect page. After username/password login, this is done with a 303 redirect, but only if SERVER_PROTOCOL is set in the environment to HTTP/1.1. Otherwise, the regular confirmation page is displayed. When the 303 redirect is used, the page body is the normal redirect page.
When this variable is set to the special value "id", the confirmation page is suppressed as described above unless the WAS requests a proxy token instead of an id token (which would allow it to later request delegated credentials to act on behalf of the user). If the site requests a proxy token, the confirmation page will be displayed so that the user can be shown what credentials the WAS will be able to request.
Default: false.
$DEFAULT_REALM
A default Kerberos realm to append to the provided username if the username doesn't contain a "@". This is primarily useful if users should be authenticated in a different Kerberos realm than the default realm for the system on which the WebKDC is running. (Note that principals containing embedded escaped "@" characters will not have $DEFAULT_REALM appended.)
Default: not set.
$EXPIRING_PW_RESEND_PASSWORD
Whether or not to require the user to retype their password after having their login fail for an expired password and being prompted to change their password. If set to a false value (such as 0), WebLogin will create a CPW token from the initial failure using the old password already entered during the login attempt. When this is set to a true value (such as 1), WebLogin will instead require that the user retype their password at the same time they enter their new password.
Default: true (require the users to resend password).
$EXPIRING_PW_URL
The location for the password redirect form, used to redirect users with expiring or expired passwords to update those passwords. If this is not set, then the check to see if the user's password is expiring soon is disabled and expired passwords will result in an error message rather than a password change dialog.
Default: not set.
$EXPIRING_PW_WARNING
The time period in seconds that we check against for password expirations. Any password with an expiration time less than this number of seconds should bring up a warning on the login confirmation screen.
Default: not set.
$FACTOR_WARNING
The seconds until we start to warn a user that their long-lived device factor is about to expire. This will force the confirmation page, and so should be kept small for any sites that have the confirmation page disabled by default.
Default: 172800 (2 days).
$FATAL_PAGE
In case of an error in trying to generate a page from a template, we will print out a 500 page. If this is not set, we simply die with an error for logs and let Apache handle the page. If this is set, we load the file given as an error page and display it on template errors.
Default: not set.
$KEYRING_PATH
The path to the WebKDC keyring. This is used to encrypt some communications with the WebKDC, particularly when allowing authentication to the WebLogin server via a native Apache method such as Negotiate-Auth.
Default: "../conf/webkdc/keyring" (which works for the default installation paths inside the Apache configuration directory).
$LOGIN_STATE_UNSERIALIZE
If using the multifactor callout services "userinfo" and "validate", this can be assigned a function reference to unserialize the login-state value returned from those calls. This function should be customized to match the serialization implemented within the "userinfo" and "validate" handlers. Once unserialized, the object can be used within the WebLogin templates.
An example deserialization function is provided that returns a native perl object serialized by Storable::nfreeze, and encoded with base64:
$LOGIN_STATE_UNSERIALIZE = sub { use Storable qw( thaw ); use MIME::Base64 qw( decode_base64 ); my ($login_state) = @_; if ( ! eval { $login_state = Storable::thaw(decode_base64($login_state)); } ) { warn ("Unable to deserialize object. ", $@); } return $login_state; };Default: not set.
$LOGIN_URL
The URL used to log in to the site. This is used only with the password change feature, and only when $REMUSER_REDIRECT is also used. In that case, this is required in order to know which page to direct the form action back to after using the password change page.
Default: not set.
@MEMCACHED_SERVERS
WebLogin can support replay caching of successful logins and rate limiting of failed logins. Both require a memcached server to use for storage. Setting this variable will allow replay rejection ($REPLAY_TIMEOUT) and rate limiting ($RATE_LIMIT_THRESHOLD and $RATE_LIMIT_INTERVAL) to be configured.
The value should be a list of memcached servers of the form <ip>:<port>. A common value will be:
@MEMCACHED_SERVERS = ('127.0.0.1:11211');which will use a memcached on localhost on the default port. Note that a pool of WebLogin servers should all share the same memcached server correct behavior. WebLogin will dynamically disable replay caching and rate limiting if the memcached server is not available.
More complex settings are possible. This variable may actually be set to any list of values that are accepted by the servers option of the Cache::Memcached constructor. See its documentation for more information.
Default: not set.
$MULTIFACTOR_COMMAND
The command to pass through to the remctl interface for sending OTPs. This will probably be a string of at least two words, for command and sub-command. WebLogin will split on whitespace and then append the username before sending to the server specified in $MULTIFACTOR_SERVER.
Default: not set.
$MULTIFACTOR_PORT
The remctl port of the server used for authentication to the remctl interface for sending OTPs. Usually this should be left as the default and not be set, in which case WebLogin will use the default remctl port.
Default: not set.
$MULTIFACTOR_PRINC
The principal of the server used for authentication to the remctl interface for sending OTPs. Usually this should be left as the default and not be set, in which case the host principal for the server set in $MULTIFACTOR_SERVER will be used. However, if your remctl server is using a different Kerberos principal than the default, you may need to set this.
Default: not set.
$MULTIFACTOR_SERVER
A server that implements a remctl interface for sending one-time passwords via some external mechanism, such as SMS. This will only be called if a custom template has been set up for the multifactor page.
Default: not set.
$MULTIFACTOR_TGT
The TGT file used to query against the remctl interface used in $MULTIFACTOR_SERVER. The TGT should be maintained by a process outside of WebLogin.
Default: not set.
$PASSWORD_CHANGE_COMMAND
$PASSWORD_CHANGE_PORT
$PASSWORD_CHANGE_PRINC
$PASSWORD_CHANGE_SERVER
$PASSWORD_CHANGE_SUBCOMMAND
Configuration to use remctl to do password changes instead of using kpasswd. By default, the normal kpasswd protocol is used for password change, but this is a UDP-based protocol with some known problems and poor behavior if password changes are slow. If $PASSWORD_CHANGE_SERVER is set, password changes will be done via a remctl protocol instead. (WebAuth must be built with remctl support.)
The remaining options configure the service principal to which to authenticate when sending the command (_PRINC), the port to use if not the remctl default (_PORT), and the remctl command and subcommand to send (_COMMAND and _SUBCOMMAND). The only remaining argument will be the new password. _COMMAND and _SUBCOMMAND must be set; the other options are all optional and will use remctl defaults if not set.
Default: not set.
$RATE_LIMIT_INTERVAL
How long failed login attempts are remembered in seconds. This setting is only used if $RATE_LIMIT_THRESHOLD and @MEMCACHED_SERVERS are set. It controls how long a failed login attempt is remembered. After this interval, any failures are discarded (whether or not the user was locked out).
Default: 300 (5 minutes).
$RATE_LIMIT_THRESHOLD
If set, configures the threshold for failed login attempts. After this many failed attempts to authenticate as a user, all subsequent password authentications for that user will be rejected, valid or not, until $RATE_LIMIT_INTERVAL seconds have passed.
This also requires @MEMCACHED_SERVERS be set. If not, this setting is ignored.
Default: not set.
$REMEMBER_FALLBACK
The fallback position for whether or not to store webkdc-proxy tokens and any webkdc-factor tokens in cookies following a successful login; in other words, the fallback position for whether to do single sign-on. This value is used if the remember_login form parameter is not set.
This is not necessarily the default value; the template may send the parameter by default (and, in fact, the default template does). Rather, it's whatever happens if no value is sent. Assuming the form uses a checkbox, it's the behavior that should happen if the checkbox is not checked.
The value should be either 'yes' or 'no'.
Default: no (default template sends yes via a checkbox that's selected by default)
$REMUSER_ENABLED (was $HONOR_REMOTE_USER)
Whether to honor Apache authentication. If this variable is set to a true value (1 is a good true value) and REMOTE_USER is set in the environment when the login script runs, it will create temporary credentials for the user given in REMOTE_USER and log the user in with those credentials automatically. (Those credentials will only work for sites that have not requested forced login and have not requested a Kerberos authenticator.) Do not set this variable to true unless you really trust your Apache authentication and you know exactly which Apache authentication methods would be used for running the login.fcgi script. See install-spnego for more details.
Default: false.
$REMUSER_EXPIRES
Only used when $REMUSER_ENABLED is set. The credentials generated from REMOTE_USER will expire after this many seconds (given as a number).
Default: 28800 (eight hours).
@REMUSER_LOCAL_REALMS
Only used when $REMUSER_ENABLED is set. If the realm matches any of the listed realms, the realm information will be stripped off. By default, this list is empty, so all principal names will be passed on fully qualified.
This setting is semantically similar to WebKdcLocalRealms in the mod_webkdc configuration.
An example setting:
@REMUSER_LOCAL_REALMS = ("stanford.edu", "WIN.STANFORD.EDU");Default: not set.
@REMUSER_PERMITTED_REALMS
Only used when $REMUSER_ENABLED is set. If set, then authentication is only permitted if the realm is a member of this list (that is, everything after the @ sign in REMOTE_USER must match one of the values in this list). If unset, there is no restriction on which realms are permitted.
This setting is semantically similar to WebKdcPermittedRealms in the mod_webkdc configuration.
"" (the empty realm) is an allowable value and says to permit REMOTE_USER settings that contain no realm information (i.e., do not contain a @-sign).
If @REMUSER_PERMITTED_REALMS is unset, the possible authentication realms is determined by the underlying Kerberos service, including any cross-realm relationships that exist.
An example setting:
@REMUSER_PERMITTED_REALMS = ("EXAMPLE.COM", "");Default: not set.
@REMUSER_REALMS (was @REALMS)
Convenience (and backwards compatibility) setting to allow both @REMUSER_LOCAL_REALMS and @REMUSER_PERMITTED_REALMS to be set to the same value.
An example setting:
@REMUSER_REALMS = ("stanford.edu", "WIN.STANFORD.EDU", "");Default: not set.
$REMUSER_REDIRECT (was $REMOTE_USER_REDIRECT)
The URL to redirect users to when trying to authenticate them with Apache authentication. Setting this variable enables the optional REMOTE_USER support. Users who go to the login page will be given an option to try Apache authentication, and if they select that option, they will be sent to this URL instead. This should be another URL for the same login.fcgi script, but one protected by your Apache authentication mechanism of choice. Setting this variable also causes login.fcgi to redirect the user automatically if a weblogin_remuser cookie is set to a true value, and to add an option to the confirm page to manage that cookie if the user used Apache authentication or if the cookie is already present.
If using this option, you must also set $REMUSER_ENABLED (otherwise there would be no point).
Default: false.
$REPLAY_TIMEOUT
If set, configures how long request tokens are remembered to detect and reject replays (in seconds). By default, replay rejection is not done.
If replay rejection is enabled, only one successful authentication using a given request token is permitted within the time interval defined by this setting. This prevents the user from successfully authenticating to a site and then using the back button on the browser to go back to the login form and replay that authentication. It provides some security against attackers with access to the browser history, although the WebLogin server also attempts to tell browsers to not cache the login page. If this is enabled, users have to return to the original WebAuth-protected site if they want to restart the authentication process.
When replay rejection is in use, this configuration option should be set to the same timeout that the WebKDC uses for request tokens (the WebkdcTokenMaxTTL Apache directive). The default value of that directive is 300 (five minutes).
This also requires @MEMCACHED_SERVERS be set. If not, this setting is ignored.
Default: not set.
@SHIBBOLETH_IDPS
This setting is mostly obsolete and probably will not work as desired with Shibboleth 2.x or later. It only works when the target site is present in the URL, which is no longer the common case.
The hostnames (as used in URLs) of a local Shibboleth IdP protected by WebAuth. An example setting:
@SHIBBOLETH_IDP = ("idp.stanford.edu", "idp-dev.stanford.edu");If this variable is set and the return URL for a given WebLogin invocation points to one of the listed hosts, the URL is parsed looking for a setting matching the regular expression:
[?&]target=([^&]+)If such a setting is found and the value is parsable as an escaped URL, the hostname is extracted from that URL and is used for the display text on the confirmation page instead of the hostname of the IdP. This further hides from the user the underlying mechanics of Shibboleth and shows them the final destination host instead of the intermediate IdP host. This setting only affects the text on the page; the underlying links are left unchanged.
Default: not set.
$TEMPLATE_COMPILE_PATH
The path to the directory that Template Toolkit will use to create compiled versions of the template for speed.
Default: "/usr/local/share/weblogin/generic/templates/ttc" (which works for the default installation paths).
$TEMPLATE_PATH
The path to the directory containing the confirm.tmpl, error.tmpl, login.tmpl, logout.tmpl, multifactor.tmpl, and pwchange.tmpl templates.
Default: "/usr/local/share/weblogin/generic/templates" (which works for the default installation paths).
$TOKEN_ACL
The path to the token.acl file used by mod_webkdc. This variable must be set if you wish to include a summary of the delegated credentials that a WAS may request in the confirmation page.
Default: not set.
$URL
URL to use to contact the WebKDC. This should always point to localhost. It probably doesn't have to use SSL, given that it's using localhost, but the performance impact isn't high and being paranoid is nice.
Default: "https://localhost/webkdc-service/". You generally only want to change the local part of the URL, and then only if you want to use a non-standard URL for the WebKDC.
$WEBKDC_PRINCIPAL
The Kerberos principal used by the WebKDC. Currently, this configuration variable is only used with Apache REMOTE_USER support and ticket delegation to generate a proxy token based on a forwarded ticket, but it must be set in that case.
Default: not set.
Obsolete configuration options:
$REALM
Equivalent to setting @REMUSER_REALMS to the single realm set here. Use @REMUSER_REALMS instead.
In addition to the above variable settings, the configuration file may define Perl functions. If these functions are defined, they're called by the WebLogin scripts where appropriate.
authenticate
If defined, this function is called for every user visit to WebLogin (so it shouldn't do anything particularly expensive). It has available the environment of the WebLogin process and can, from that, make decisions about whether the user has already authenticated. Consider this the generalization of REMOTE_USER support, but allowing the local callback to examine other environment variables, such as ones indicating that a client-side certificate was used.
If the user is not authenticated, this function should return the empty list.
If the user is already authenticated, this function should return a list of four values. The first should be the authenticated identity of the user, the second the initial authentication factors, the third the session authentication factors, and the fourth the level of assurance. All four values must be present; use "u" for the authentication factors and 0 for level of assurance to convey no information about those values.
If this function returns authentication information, normal REMOTE_USER processing will not be done, even if it is enabled. So this can be used to override normal processing, but still fall back on normal REMOTE_USER processing if the separation authentication callback doesn't work for some reason.
map_username
If defined, this function is called with the user-provided username as its only argument. It is called before any qualification using $DEFAULT_REALM, and is not called if REMOTE_USER is set and Apache authentication is being honored.
This function should return the string to pass to the WebKDC as the username. It may perform arbitrary transformations of the username into the Kerberos principal to use for authentication. For example, it might accept an e-mail address and look up the corresponding Kerberos principal in a database.
record_login
If defined, this function is called after any successful login, regardless of the authentication mechanism used. It's called even if the user was authenticated via an existing single sign-on cookie. The only argument passed to the function is the username (as passed to the WebKDC, not as entered by the user), and the return value (if any) is ignored.
remuser_factors
If defined, this function is called whenever a user is authenticated via Apache authentication instead of via a password or other authentication information sent to the WebKDC. The only argument passed to the function is the username, but it's run within the context of the WebLogin application and can examine the environment for additional information about the Apache authentication as desired.
This function should return a list of three values: the initial authentication factors, the session authentication factors, and the level of assurance. The factors should be comma-separated lists of factor codes (see the WebAuth protocol documentation for valid factors). The level of assurance should be an integer number reflecting the site-defined levels of assurance for authentications and identity binding. Return 0 for the level of assurance if nothing is known about it.
If this function is not provided, WebLogin will use "u" (unknown) as the initial and session factor for Apache authentications and will not provide level of assurance information.
The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
| < WebKDC Multifactor | Russ Allbery > Software > Orphaned Software > WebAuth |