Skip navigation



WebKDC Multifactor Installation


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.


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


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:


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 information service must provide a remctl command with a subcommand of "webkdc-userinfo" 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 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.


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.


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. -->
      <!-- Optional. List of additional factors to add to successful
           logins. -->
      <!-- Optional.  Present if specific factors should be required
           regardless of whether they were requested by the destination
           site. -->
      <!-- 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. -->
      <!-- 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. -->
        <host name="{host}" timestamp="{time}">{ip}</host>
        <host name="{host}" timestamp="{time}">{ip}</host>
      <!-- Optional.  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. -->
      <!-- Optional.  May contain a message for the user to display on
           the first load of the multifactor authentication page.
      <!-- 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. -->

{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 can be displayed on the first load of WebLogin's OTP submission page.

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

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:


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.


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.


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

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


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.


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.

Last modified Friday, 12-Dec-2014 02:31:11 PM

Stanford University Home Page