Search Mailing List Archives

Limit search to: Subject & Body Subject Author
Sort by: Reverse Sort
Limit to: All This Week Last Week This Month Last Month
Select Date Range     through    

Configuration of WebKDC Multifactor Support

Russ Allbery eagle at
Fri Sep 2 11:34:17 PDT 2011

Here is the last sneak preview before the actual WebAuth 4.0.0 release,
which is the beta release for multifactor support.  This is the document
that will be included in that release describing how to set up multifactor
at other sites (aimed at WebKDC administrators).  This includes the
specification for the piece (the user information service) that currently
has to be provided by a site deploying multifactor.  We do plan to make
available a generic version of this service as at least a sample
implementation at some point in the not-too-distant future.

               Configuration of WebKDC Multifactor Support


  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

  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.


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

      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

  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.

  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:


      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

  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

  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:


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

  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 metadata service must provide a remctl command with a
  subcommand of "webkdc-userinfo" that takes the following arguments in

      The username of the user attempting to authenticate.

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

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

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

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

        <!-- Present if multifactor authentication is required regardless
             of whether it was requested by the destination site. -->
        <multifactor-required />

        <!-- Optional.  If present, contains possibly suspicious recent
             logins that the user should be notified of. -->
          <host ip="{ip}">{host}</host>
          <host ip="{ip}">{host}</host>

        <!-- If present, indicates that the user will not be able to
             assert a level of assurance higher than this number. -->

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

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

  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 the <multifactor-required /> tag is present, the user will be
  required to do multifactor authentication even if the destination
  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 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.

  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.

  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 metadata service must provide a remctl
  command with a subcommand of "webkdc-validate" that takes the following
  arguments in order:

      The username of the user attempting to authenticate.

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

      The OTP to validate.

  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.  (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}">

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

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

  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.

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.


  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

  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.

Russ Allbery <eagle at>
Technical Lead, ITS Infrastructure Delivery Group, Stanford University

More information about the webauth-info mailing list