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    

WebLogin multifactor protocol and design

Russ Allbery eagle at windlord.stanford.edu
Tue Jun 14 14:34:37 PDT 2011


Hello everyone,

This is the second part of the protocol work for adding multifactor
support to WebAuth.  This part deals with the protocol for the interaction
between the WebKDC and the WebLogin front-end, and between the WebKDC and
the multifactor middleware.

This protocol is only of interest to those running the WebLogin servers
for a site, and won't be exposed to general WebAuth-protected servers.
It's mostly internal to the WebAuth package, except for the multifactor
middleware.

First, the WebLogin interaction with the WebKDC.  This is done through the
<requestTokens> XML API, which is documented at:

    http://webauth.stanford.edu/protocol.html#xmlrequesttoken

The basic protocol is that a user will first authenticate with a password
as normal, resulting in proxy tokens for a password authentication.  If
the site to which they're going requires multifactor, the WebKDC will
return an appropriate error code as well as the webkdc-proxy token for the
password authentication.  The WebLogin front-end will then prompt the user
to authenticate with the second factor and present that, along with the
password webkdc-proxy token, to the WebKDC.  The WebKDC will validate the
second factor and then issue a new proxy token that shows multifactor
authentication, plus the id or proxy token for the WAS.

We're proposing the following changes:

1. To the login token passed by the WebLogin server, add the additional
   token attribute "otp", which can hold the OTP code.  A login token must
   contain either the "p" attribute or the "otp" attribute.

2. A new XML element, <multifactorRequired>, is added to the
   <requestTokenResponse> element.  If the WebKDC returns the error code
   saying that the authentication requires a second factor, this element
   will be included.  It looks like:

       <!-- set in combination with a loginErrorCode of 19 if
            multifactor authentication is required -->
       <multifactorRequired>
         <factor>{factor-code}</factor>
         <!-- repeat for each factor code required by the WAS -->
         <configuredFactor>{factor-code}</configuredFactor>
       </multifactorRequired>

   The <factor> elements will list all the factors that the WAS requested,
   or that the WebKDC decided to require for some other reason, and will
   be used mostly for the UI if desired.  The <configuredFactor> attribute
   tells the WebLogin front-end which second factor the user has available
   to them, and controls the prompting.

3. A new XML element, <loginHistory>, is added to the
   <requestTokenResopnse> element.  If present, this shows recent login
   history for the user that should be displayed to the user (generally
   because it seemed mildly suspicious or unusual).  It looks like:

       <!-- optional, included if the user's login history should be
            displayed (if, for example, it was suspicious) -->
       <loginHistory>
         <!-- the timestamp information is optional -->
         <loginLocation ip="{ip-address}" time="{timestamp}">
           {hostname}
         </loginLocation>
         <!-- repeat for site-defined length of login history -->
       </loginHistory>

4. The following error codes are added to the valid values for <errorCode>
   and <loginErrorCode>, and anywhere else an error code is expressed in
   the protocol:

   20  The WAS server or WebKDC requested multifactor authentication.  The
       web front-end should prompt the user for their second factor based
       on the <configuredFactor> attribute in the <multifactorRequired>
       attribute and then attempt authentication again, including any
       returned proxy tokens from this attempt.

   21  The WAS server or WebKDC requested multifactor authentication, but
       this user is not capable of multifactor authentication for some
       reason (such as not being known to the underlying multifactor
       authentication system or not having a strong enough second factor
       configured).  The web front end should display an error page
       explaining that the user cannot authenticate to this site without
       configuring multifactor.  The required second factor options will
       be given in the <multifactorRequired> attribute.

   22  The user is not permitted to log in at this time for security
       reasons.  This may be due to such factors as the originating IP
       address or repeated login failures.  The web front-end should
       display an error message to the user.

   23  The WAS server requested a Level of Assurance in the
       authentication that cannot be obtained for this user (perhaps
       because the user doesn't have a strong enough authentication
       method configured or hasn't associated the account with proof of
       identity).  The web front-end should display an error message to
       the user.

Next, we need a protocol for the WebKDC to retrieve multifactor
configuration information about a user and attempt a multifactor
authentication.  We don't want the WebKDC to be doing the multifactor
authentication directly, since that requires storing state on the WebKDC.
Instead, this design will use a call to separate middleware that tracks
the users' multifactor configuration and does the authentications.

That middleware will have three calls.  For the initial implementation,
the protocol used will be remctl, since that's what works best here at
Stanford, but the intent is to design them so that a web services
interface can be added later if other sites desire.

The first call is:

    webkdc-userinfo <username> <ip> <timestamp> <random>

where <ip> is the IP from which the user comes, <timestamp> is the
timestamp of the user visit to the WebLogin page, and <random> is a
boolean flag saying whether the WAS is requesting random multifactor.  The
return is an XML document:

    <authdata user="{username}">
      <multifactor>
        <type>{factor-code}</type>
        <!-- repeat <type> as required -->
        <!-- required tag present if multifactor is required for this
             login regardless of what the WAS says -->
        <required />
      </multifactor>

      <!-- login history only present for questionable logins -->
      <login-history>
        <host ip="5.5.5.5">somewhere.example.com</host>
        <host ip="6.6.6.6">else.example.org</host>
      </login-history>

      <!-- maximum Level of Assurace for this user -->
      <max-loa>{max-loa}</max-loa>

      <!-- password expiration date for this user (optional) -->
      <password-expires>2011-08-10</password-expires>
    </authdata>

The second call is used after the user submits an OTP code and is:

    webkdc-validate <username> <ip> <timestamp> <otp-code>

and returns:

    <authresults user="{username}">
      <success>yes|no</success>
      <multifactor>
        <type>{factor-code}</type>
        <!-- repeat for other factor codes -->
      </multifactor>

      <!-- login history only present for questionable logins -->
      <login-history>
        <host ip="5.5.5.5">somewhere.example.com</host>
        <host ip="6.6.6.6">else.example.org</host>
      </login-history>

      <!-- Level of Assurance for this login -->
      <loa>{loa}</loa>
    </authresults>      

The third call is used to send an OTP code via SMS:

    sms <username>

and returns:

    <sms user="{username}">
      <success>yes|no</success>
      <!-- included only on error -->
      <error code="{code}">{message}</error>
    </sms>

This of course will be fleshed out more fully later, including formal
schema documents.

-- 
Russ Allbery <eagle at windlord.stanford.edu>
Technical Lead, ITS Infrastructure Delivery Group, Stanford University



More information about the webauth-info mailing list