Weblogin Configuration
Introduction
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.
Templates
WebLogin uses a set of template HTML pages to display the login, logout, confirmation, and error pages. Internally, it uses the HTML::Template Perl module to process these templates. For detailed information about the supported syntax, install that module and then run:
perldoc HTML::Template
You can probably figure out the details you need by looking at the existing templates, though. WebLogin doesn't use any advanced features.
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. They must support the following HTML::Template variables, which means that all of these variables must be mentioned in the templates even if you don't want to use them (otherwise, HTML::Template will throw errors).
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
script_name Relative URL to which form should be posted
username Username, if already known
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
remuser_failed If set, REMOTE_USER was tried and failed
confirm.tmpl
username Authenticated username
return_url Return URL, including response tokens
pretty_return_url Anchor text for return URL (usually just host)
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 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 TMPL_LOOP) 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)
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 HTML::Template variables:
error.tmpl
err_cookies_disabled If set, user doesn't have cookies enabled
err_no_request_token If set, user had no request token
err_confirm If set, incomplete data for confirm page
err_webkdc If set, the WebKDC reported an error
err_msg WebKDC error message
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.
Configuration
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.
$KEYRING_PATH
The path to the WebKDC keyring. This is used to encrypt some communications with the WebKDC. Default: "../conf/webkdc/keyring" (which works for the default installation paths inside the Apache configuration directory).
$TEMPLATE_PATH
The path to the directory containing the login.tmpl, confirm.tmpl, error.tmpl, and logout.tmpl templates. Default: "/usr/local/share/weblogin/generic/templates" (which works for the default installation paths).
$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.
$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.
$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_REALMS (was @REALMS)
Only used when $REMUSER_ENABLED is set. If this variable is set, everything after the @ sign in REMOTE_USER must match one of the values in this list and is stripped before creating the authenticated user identity. This variable is equivalent to the combination of WebKdcLocalRealms and WebKdcPermittedRealms in the mod_webkdc configuration but must be set separately due to how Apache authentication is supported.
An example setting:
@REALMS = ("stanford.edu", "WIN.STANFORD.EDU", "");As demonstrated in this example, realms should be listed in parentheses and separated by commas. "" (the empty realm) is an allowable value and means to allow REMOTE_USER settings that contain no realm information (do not contain a @-sign). If the realm matches any of the allowable realms, the realm information will be stripped off.
If this variable is not set, the REMOTE_USER information must not contain an @. If it does, it will be ignored and login will proceed as if it weren't set.
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.
$REALM
Equivalent to setting @REMUSER_REALMS to the single realm set here. Use @REMUSER_REALMS instead. Default: not set.
@SHIBBOLETH_IDPS
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.
$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.
$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.
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.
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.
