install-multifactor

               Configuration of WebKDC Multifactor Support

Introduction

  In addition to the default support for password and web server
  authentication, WebAuth also supports multifactor authentication:
  requiring users accessing all or some WebAuth-protected sites to
  authenticate with multiple forms of authentication.  Generally, a
  combination of a password equivalent and some sort of cryptographic code
  generated by a device carried by the user is used, but WebAuth is
  agnostic about how the multifactor authentication is done.

  This document provides an overview of the multifactor authentication
  philosophy in WebAuth and supplemental information about how to deploy
  it.

  There are some pieces of the multifactor authentication support in
  WebAuth that can be used "out of the box" with only the software
  included in the WebAuth source package.  However, most features,
  including OTP (one-time password) support, will require an additional
  piece of site-specific middleware that currently you will need to write
  yourself.  This is described below under "User Information Service,"
  including the protocol that the WebKDC expects it to speak.  The future
  intention is to provide a simple sample implementation adequate for
  small sites to serve as a basis for customization.

Definitions

  The WebAuth documentation and code uses the following terms to describe
  multifactor authentication and related information:

  factor
      A factor is either a method of authentication (password, OTP) or
      information about authentication derived from the other factors
      (multifactor, which indicates the user authenticated with more than
      one general type of factor).  Factors are one- or two-letter codes,
      with multiple factors shown by separating them with commas.  The
      definition of all the factor codes is in the protocol specification.
      Note that authentication by presenting a WebLogin single sign-on
      cookie is itself a factor (the "c" or cookie factor).

  initial factors
      The initial factors are the factors the user used to do initial
      authentication: the authentication they performed to get their
      single sign-on cookie, having no previous authentication tokens (or
      after having been forced to reauthenticate).  A user will retain the
      same initial factors through the life of their single sign-on
      cookies.

  session factors
      The session factors are the factors that the user used to
      authenticate to a specific web site.  If the user was prompted for
      initial authentication to reach that web site, they will be the same
      as the initial factors.  However, they may be something else, such
      as "c" (cookie) if the user used a single sign-on cookie, or "k"
      (Kerberos) if the user authenticated to WebLogin using Kerberos with
      Negotiate-Auth.  In the latter case, the initial factors should be
      whatever methods the user used to obtain their initial Kerberos
      ticket-granting ticket on their local system.

  persistent factor
      This is a factor stored in a separate cookie in the user's browser
      that persists for longer than the expiration time of their single
      sign-on credentials.  It is used, for example, to set a cookie in a
      browser that has been vetted by some means (such as a previous
      multifactor authentication) that will add an additional
      authentication factor to subsequent authentications from that
      browser.

  level of assurance
      This is a site-defined numeric value that is intended to encapsulate
      in one number a combination of the identity proofing of the user (how
      much confirmation the organization has that the person is who they
      say they are) and the strength of their authentication method.  It's
      primarily intended for use with applications subject to regulatory
      requirements for particular levels of assurance.  For example, see
      NIST Special Publication 800-63 at:

      <http://csrc.nist.gov/publications/nistpubs/800-63-1/SP-800-63-1.pdf>

      which provides recommendations by the US government.  How (or
      whether) to use level of assurance numbers and what the numbers mean
      is entirely up to each site, except that higher numbers must be
      stronger than lower numbers.  WebAuth only passes the numbers around
      and does not originate them.

  random multifactor
      WebAuth supports a mechanism in which a given WebAuth-protected site
      can require multifactor authentication occasionally but not all the
      time.  This is called "random multifactor."  The frequency of the
      random requirement is determined by the site-provided user
      information service; WebAuth only tells it that random multifactor
      was requested and leaves it to the information service to decide
      whether that means multifactor authentication should be required.

  WebAuth currently recognizes three major types of initial authentication
  factors: password ("p"), OTP ("o"), and X.509 ("x").  However, both OTP
  and X.509 authentication may be done via different methods with varying
  levels of security.  For example, a tamper-resistant hardware smart card
  with a PIN and a certificate installed in the user's browser may both
  show up as X.509, but the former is much more secure than the latter.

  WebAuth therefore supports any number of site-defined variants of both
  OTP and X.509 factors formed by adding a number after "o" or "x".  For
  example, "o1" may be a printed list of one-time authentication codes,
  and "o3" may be Google Authenticator running on a smart phone.  The
  meaning of these factors are entirely site-defined, except that they
  should be in order of ascending strength ("o3" should be stronger, or at
  least equally strong, as "o2").

Authentication Interfaces

  There are multiple places within a deployed WebAuth system where a user
  may authenticate.  Each one needs to be separately configured for
  multifactor support to make a complete and coherent system.

  The primary authentication interface used by most sites is the WebLogin
  service, where the user is prompted for a username and password via an
  HTML form.  The WebKDC understands that authentication method and gives
  it initial factors of "p" (password) by default.  By default, no level
  of assurance is expressed for those logins.  This method can support an
  additional prompt for a one-time password if the WebKDC has been
  configured with an appropriate user information service that knows how
  to validate an OTP.  For more information on that, see "User Information
  Service" and "OTP Validation" below.

  There are two other authentication interfaces provided by WebAuth,
  however, and these can be made multifactor-aware without requiring a
  user information service.  Some sites may be able to deploy multifactor
  using just these interfaces and not have to create a user information
  service.

  The first is the support in WebLogin for trusting and reusing
  authentication information provided by the web server.  This is the
  support used to allow authentication via Negotiate-Auth and is described
  in docs/install-spnego.  By default, such authentications are given
  initial and session authentication factors of "u" (unknown).  However,
  WebLogin allows one to provide a (Perl) callback function named
  remuser_factors in the WebLogin configuration, which is passed the
  username of the user authenticating and has access to the full web
  server environment (including, for example, the environment variables
  set by a web server that has performed a successful client-side
  certificate authentication).  This function returns the initial and
  session factors and level of assurance.  Using this function, sites can
  map authentications done by the web server, which is the easiest way to
  implement X.509 authentication, to appropriate factors and level of
  assurance for their site.  For more information, see the description of
  the remuser_factors function in docs/weblogin-config.

  The second is the WebKDC interface that allows obtaining a webkdc-proxy
  token (the contents of a single sign-on cookie) directly using Kerberos
  authentication.  Here too, the default initial authentication factor is
  "u" (unknown), but the WebKdcKerberosFactors Apache directive can be
  used to set the initial factors for this method of authentication.
  Unlike with WebLogin's use of web server authentication, there is no way
  to programmatically map different users to different factors or to set a
  level of assurance for this method of authentication.

User Information Service

  The WebLogin callback and WebKdcKerberosFactors Apache directive will
  not be sufficient for most sites deploying multifactor authentication.
  Sites that want more flexibility, or that want to add OTP verification
  to the WebLogin flow, will need to provide a user information service.

  There are two components to the user information service: a "userinfo"
  call that returns general information about the user, including their
  configured factors and level of assurance, and a "validate" call that is
  used for OTP validation.  The second will be described in the next
  section.

  Currently, the only supported protocol for contacting the user
  information service is via remctl.  remctl is a Kerberos-authenticated
  protocol for executing remote commands and is available as free
  software.  For more information see the remctl distribution page:

      <http://www.eyrie.org/~eagle/software/remctl/>

  The location of the user information service is configured with the
  WebKDC Apache configuration directives WebKdcUserInfoURL and
  WebKdcUserInfoPrincipal.  A typical WebKdcUserInfoURL setting would be:

      WebKdcUserInfoURL remctl://userdb.example.com/user

  The protocol currently must be remctl.  The host and port of the service
  can be specified in the normal URL syntax.  The part after the slash is
  the remctl command name to use.

  The WebKdcUserInfoPrincipal directive can normally be omitted and is
  used only if the remctl server uses an authentication Kerberos principal
  other than the host principal for the system on which it's running.

  The user information service must provide a remctl command with a
  subcommand of "webkdc-userinfo" that takes the following arguments in
  order:

  username
      The username of the user attempting to authenticate.

  ip
      The IP address from which the user is coming (generally the IP
      address that is accessing the WebLogin server).  127.0.0.1 will be
      sent as the IP address if the WebKDC cannot determine the client's
      IP address for some reason.

  timestamp
      The timestamp of the authentication in seconds since UNIX epoch.
      This will currently always be the current time.

  random-multifactor
      A flag that will be 0 if random multifactor was not requested and 1
      if it was requested.

  url
      The URL to which the user would go after successful authentication.
      This is the return URL parameter from the WebAuth request token, so
      it may not match the URL to which the user went to trigger the
      authentication attempt.  This parameter will be ommitted if the
      WebKDC has no URL information (usually not the case).  If there is
      no URL information but factors (the next parameter) are present, it
      will be the empty string.

  factors
      A comma-separated list of initial authentication factor codes that
      the user has already established with the WebLogin server at the
      time of the call.  This parameter was added in WebAuth 4.5.0; older
      versions of the WebKDC will not send it.

  If the remctl command exits with a non-zero status, this will be taken
  as a fatal error and the user's authentication will be aborted.  The
  error can be reported on standard error.  If it exits with a zero
  status, it must provide an XML document on standard output with
  something like the following contents:

      <authdata user="{username}">
        <!-- List of authentication factors the user has available. -->
        <factors>
          <factor>p</factor>
          <factor>m</factor>
          <factor>o</factor>
          <factor>o3</factor>
        </factors>

        <!-- Optional. List of additional factors to add to successful
             logins. -->
        <additional-factors>
          <factor>h</factor>
        </additional-factors>

        <!-- Optional.  Present if specific factors should be required
             regardless of whether they were requested by the destination
             site. -->
        <required-factors>
          <factor>o3</factor>
        </required-factors>

        <!-- Optional.  Present if any persistent factors with a creation
             date prior to the timestamp should be invalidated.  If the
             WebKDC invalidates any factor information based on this
             cutoff, it should then retry the userinfo call with a
             modified factors parameter reflecting that change.  {time} is
             seconds since epoch. -->
        <persistent-factors>
          <valid-threshold>{time}</valid-threshold>
        </persistent-factors>

        <!-- Optional.  If present, contains possibly suspicious recent
             logins that the user should be notified of.  name and
             timestamp may be omitted.  If present, {time} is the seconds
             since epoch timestamp of the last login from that
             location. -->
        <login-history>
          <host name="{host}" timestamp="{time}">{ip}</host>
          <host name="{host}" timestamp="{time}">{ip}</host>
        </#-history>

        <!-- Optional.  If present, indicates that the user will not be
             able to assert a level of assurance higher than this
             number. -->
        <max-loa>{max-loa-value}</max-loa>

        <!-- Optional.  Contains the expiration time of the user's
             password in seconds since epoch, used to prompt the user
             to change their password. -->
        <password-expires>{expiration-time}</password-expires>

        <!-- Optional.  May contain a message for the user to display on
             the first load of the multifactor authentication page.
        <user-message>{message-for-user}</user-message>

        <!-- Optional.  May contain a string-serialized object that
             will be returned on a subsequent request to the
             validate service.  May be deserilized in WebLogin and
             used to change WebLogin behavior, for example - display
             a custom message to the user. -->
        <login-state>{custom-state-object}</#-state>
      </authdata>

  {username} should match the user for which the information is being
  retrieved.

  All elements are optional except for <factors>, which should list all
  factors that the user is capable of providing (based on local knowledge
  of user configuration).  The list of factors should normally always
  include "p" (password).  If the user is capable of multifactor, be sure
  to include "m" (multifactor) in the list of factors.  Do not include
  "rm" (random multifactor); this is handled specially.

  If <additional-factors> is present, those factors will be added to any
  successful authentication.  This is primarily intended as a mechanism to
  add the "h" (human-verified) factor temporarily for a user after local
  support staff have confirmed their identity as a way of giving that user
  a multifactor factor when they've lost their multifactor authentication
  method.  However, it can be used for any scenario where the user
  information service knows, via some external means, that a successful
  authentication (either password or OTP) for that user should add some
  additional factors besides the normal ones.

  If <required-factors> is present, the WebKDC will add the factors
  present to those required by the WebAuth-protected site.  This can be
  used to force multifactor authentication even if the WebAuth-protected
  site doesn't require it.  This is how random multifactor should be
  implemented by the user information service.  If the random multifactor
  flag is 1 and the user is selected, include a required factor (generally
  the m factor) within this tag.  The user information service should also
  remember that the user was selected for random multifactor and continue
  to require it every time the random multifactor flag is true until the
  user successfully authenticates with multifactor, since otherwise the
  user may just reload the login page until they get lucky again.

  For backward compatibility, the <multifactor-required /> tag, if present
  without <required-factors>, is treated as equivalent to a required
  factor of m.

  The optional <login-history> section provides information for the
  WebLogin server to show the user about recent logins.

  The <max-loa> attribute specifies the maximum level of assurance that
  the user can obtain.  This can be omitted if level of assurance isn't
  used.  If the level of assurance requested by a WebAuth-protected site
  is higher than this value, the WebLogin server will show an error page
  instead of prompting the user for multifactor authentication.

  The optional <password-expires> attribute provides the time, in seconds
  since epoch, when the user's password will expire.  It's used to display
  a warning and a prompt to the user to change their password on the
  WebLogin confirmation screen.

  The optional <user-message> element may contain a message to provide
  the user with any additional information from the userinfo service.  It
  can be used to explain the reasoning for an unexpected multifactor
  enforcement, or any other messaging specific to this step of the
  authenication process.  It will be passed, via the WebKDC and WebLogin,
  to the template for the multifactor authentication page or confirmation
  page (depending on whether a multifactor authentication is required).

  The optional <login-state> element may contain a simple value or a string
  serialized object that can be used to retain state for a subsequent call
  to the validate service.  The object may be deserialized in WebLogin by
  assigning a deserialization function to the WebLogin config variable
  LOGIN_STATE_UNSERIALIZE.  An example function can be found within the
  weblogin-config documentation.  Whether deserialized or not, the resulting
  object can be accessed within the WebLogin templates by the name
  "login_state".

  Alternately, the user information service may reject this
  authentication.  In this case, it should return the much simpler
  response:

      <authdata user="{username}">
        <error>{message-for-user}</error>
      </authdata>

  The {message-for-user} should be an HTML-formatted message that will be
  displayed to the user as a fatal error message by WebLogin.  Normally,
  this should be inside a CDATA block to protect the HTML markup.

  For information about how this information is handled by the WebLogin
  system, see "WebLogin Templates" below.

OTP Validation

  Most sites will probably want to use some one-time password system as a
  second factor, since it's the easiest and cheapest to deploy to a large
  number of people.  WebAuth uses a call to the user information service
  similar to the userinfo call to validate any OTP.  The user information
  service can then take any steps it wishes to do OTP validation: use OATH
  libraries or tools to check the code against a stored seed, call out to
  a separate appliance, check a web service, or whatever else is required
  to integrate with a local OTP system.

  To do OTP validation, the user information service must provide a remctl
  command with a subcommand of "webkdc-validate" that takes the following
  arguments in order:

  username
      The username of the user attempting to authenticate.

  ip
      The IP address from which the user is coming (generally the IP
      address that is accessing the WebLogin server).  127.0.0.1 will be
      sent as the IP address if the WebKDC cannot determine the client's
      IP address for some reason.

  code
      The OTP to validate.

  type
      The OTP type to validate.  This parameter may be omitted if the
      WebKDC doesn't know what type of OTP the user is trying to use.

  login-state
      The state object returned from a previous call to the userinfo
      or validate service.  It may be absent if no login-state exists.

  If the remctl command exits with a non-zero status, this will be taken
  as a fatal internal error and the user's authentication will be aborted.
  (This should not be used for an invalid OTP; see below.)  The error can
  be reported on standard error.  If it exits with a zero status, it must
  provide an XML document on standard output with something like the
  following contents:

      <authdata user="{username}">
        <success>yes|no</success>
        <factors>
          <expiration>{expiration}</expiration>
          <factor>o</factor>
          <factor>o3</factor>
        </factors>
        <persistent-factors>
          <valid-threshold>{time}</valid-threshold>
          <expiration>{expiration}</expiration>
          <factor>d</factor>
        <persistent-factors>
        <loa>{loa-value}</loa>
        <user-message>{message-for-user}</user-message>
        <login-state>{custom-state-object}</#-state>
      </authdata>

  {username} should match the user for which the information is being
  retrieved.

  The correctness of the OTP is given by the <success> attribute, which
  should have a value of "yes" if the OTP was correct and "no" if it was
  not (or if the OTP login was rejected for some other reason; see below).

  If correct, the <factors> attribute should be included, listing all of
  the authentication factors that this successful authentication
  represents.  Normally, this will include "o" (some OTP) along with a
  specific numbered OTP factor if there are multiple types of OTP
  available.  {expiration} indicates when (in seconds since UNIX epoch)
  this authentication should expire.  If you have no site-specific reason
  to choose otherwise, ten hours from the current time is a reasonable
  default.

  If this authentication should result in setting a persistent factor
  cookie in the authenticating browser, the factors that should go into
  that persistent factor cookie should be listed in the
  <persistent-factors> element.  Otherwise, that element should be
  omitted.  (These will be set as persistent initial authentication
  factors; setting persistent session authentication factors is not
  currently supported.)  Here similarly the {expiration} value indicates
  the time (in seconds since UNIX epoch) when the persistent factors
  should expire.  The <invalid-before> element is optional; if present, it
  indicates that the WebKDC should also discard all webkdc-factor tokens
  with a creation date prior to the time given (in seconds since UNIX
  epoch).

  If level of assurance is being used, the optional <loa> attribute should
  return the level of assurance this authentication indicates.  This
  should assume that the user also authenticated with a password, since
  the WebLogin server will only do OTP authentication after successful
  password authentication.

  The optional <user-message> element may contain a message to provide
  the user with any additional information about specific actions they
  should take as a result of this OTP validation attempt, or an
  an informational message about the state of this validation.

  As explained above for the userinfo service, the optional <login-state>
  element may contain a simple value or a string serialized object that can
  be used to retain state for a subsequent call to the validate service.
  The object's deserialization process and function are identical to the
  userinfo case, however this object is most useful for repeated subsequent
  calls to the validate service.  This allows the validate service to
  maintain state for a series of user interactions, where stateful
  interaction is required to implement a number of token-specific features,
  for example - the reset of a PIN code, or the initialization of a hardware
  token.

  On failure, behavior depends on whether <user-message> is present.  If
  it is not present, <success>no</success> indicates that the OTP code was
  not correct.  This will be logged as a failed authentication and the
  user will be prompted to re-enter the code.  If <user-message> is
  present, this instead indicates that the validation service rejected the
  authentication for some reason either more complex or requiring more
  explanation than simply "the OTP code was wrong."  The user will still
  be prompted to enter an OTP code, but the contents of <user-message>
  will be made availed to the WebLogin template for display to the user.
  This will be logged as a rejected authentication.

WebLogin Templates

  Enabling multifactor adds additional cases that should be handled by the
  WebLogin templates, including a new template (multifactor.tmpl) that's
  used to prompt for multifactor authentication.  For complete
  information, see docs/weblogin-config.  This documentation will only
  touch on the highlights.

  The current templates and WebLogin page flow mostly assume that the user
  will use OTP as their multifactor authentication method.  If the user
  has not authenticated and Negotiate-Auth is not in use, the user will
  always first be presented with a password authentication screen as
  normal.  After the user authenticates, the user information service will
  be consulted and that information checked against the requested factors
  and level of assurance by the destination WebAuth-protected site.  If
  the site requests factors the user is not capable of providing, or a
  level of assurance higher than the user is capable of providing, the
  user will be taken directly to an error page.

  Error pages due to insufficient factors or level of assurance will
  include the login cancel link if one was provided.  WebAuth servers that
  require multifactor normally should set WebAuthLoginCanceledURL to a
  page that explains the situation to users without multifactor
  configured, including any site-specific information about how the user
  should proceed.

  The sample multifactor.tmpl handles OTP prompting, but the user's
  configured factors and the factors requested by the destination site are
  provided to the template as template variables.  This allows the page to
  be completely customized for the situation, including ones that don't
  involve prompting for an OTP.  For example, if the user needs to do
  X.509 authentication, the template could display a page telling the user
  to insert their smart card and then go to a different login link that
  will attempt to do a client-side certificate authentication.

OTP and SMS

  One inexpensive and easy-to-deploy method of providing multifactor to
  users is to send an OTP via SMS to a user's cell phone.  In order to use
  this method of OTP, it's best if the user has a way of saying that
  they're ready to do the authentication when they're ready for the
  message to be sent.  This is supported in the WebLogin code, and an
  example of how to use it is shown in the sample multifactor.tmpl
  template.

  To send the SMS message, there must be a remctl service that the
  WebLogin server can contact and tell to send the SMS message.  Normally
  this is provided by the same user information service that does OTP
  validation.  The WebLogin server must be configured with information
  about how to contact that remctl service; since it doesn't share
  configuration with the WebKDC, the WebKdcUserInfoURL parameter is not
  used for this purpose.  See docs/weblogin-config for information on how
  to configure the WebLogin server to send an OTP.

License

  Copyright 2011, 2012, 2013
    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.