                          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_bad_method            If set, login form submitted without POST
      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, 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).

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

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

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

  $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_SERVER

      A server that implements the kadmin-remctl interface for querying
      the time a principal has until password expiration (via the
      check_expire command).  Default: not set.

  $EXPIRING_PW_TGT

      The TGT file used to query against the kadmin-remctl interface used
      in $EXPIRING_PW_SERVER.  The TGT should be maintained by a process
      outside of webauth.  Default: not set.

  $EXPIRING_PW_PRINC

      The principal of the server used for authentication to the
      kadmin-remctl interface.  Usually this should be left as the default
      and not be set, where Net::Remctl will do the correct thing.  However,
      during the test suite we need to set this to test against a local
      remctl.  Default: empty string.

  $EXPIRING_PW_PORT

      The remctl port of the server used for authentication to the
      kadmin-remctl interface.  Usually this should be left as the default
      and not be set, where Net::Remctl will do the correct thing.  Default:
      0.

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

  $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.  When this is not set, we will create a CPW
      token from the initial failure using the old password already entered
      during the login attempt.  When this is set, we will instead require
      that the user retype their password at the same time they enter their
      new password.  Default: 1 (require the users to resend password).

  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.
