Network Working Group                                        R. Schemers
Internet-Draft                                                R. Allbery
Intended status: Informational                       Stanford University
Expires: February 2, 2015                                    August 2014


                    WebAuth Technical Specification
                        draft-allbery-webauth-00

Abstract

   Defines the WebAuth protocol for authenticating users to web
   applications using only the basic capabilities of a web browser.
   Authentication is handled by a central login server using a protocol
   local to the given site.  Authentication information is then passed
   to application servers via encrypted tokens in a URL and maintained
   by the browser as cookies.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on February 2, 2015.

Copyright Notice

   Copyright (c) 2014 IETF Trust and the persons identified as the
   document authors.  All rights reserved.












Schemers & Allbery      Expires February 2, 2015                [Page 1]

Internet-Draft       WebAuth Technical Specification         August 2014


   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  WebAuth Components  . . . . . . . . . . . . . . . . . . .   3
       1.1.1.  User-Agent (UA) . . . . . . . . . . . . . . . . . . .   3
       1.1.2.  WebAuth-enabled Application           Server (WAS)  .   4
       1.1.3.  WebKDC  . . . . . . . . . . . . . . . . . . . . . . .   4
     1.2.  WebAuth Tokens  . . . . . . . . . . . . . . . . . . . . .   5
     1.3.  Security Model and Key Management . . . . . . . . . . . .   6
       1.3.1.  Distributing and Managing           Session Keys  . .   7
       1.3.2.  Distributing and Managing           Private Keys  . .   8
       1.3.3.  Supporting Server Pools . . . . . . . . . . . . . . .   9
   2.  WebAuth Scenarios . . . . . . . . . . . . . . . . . . . . . .  10
     2.1.  No Tokens (Initial Sign-On) . . . . . . . . . . . . . . .  10
     2.2.  App Token . . . . . . . . . . . . . . . . . . . . . . . .  13
     2.3.  No App Token, Proxy Token (Single           Sign-On)  . .  14
     2.4.  No App Token, Credentials Required  . . . . . . . . . . .  16
     2.5.  Logging Out . . . . . . . . . . . . . . . . . . . . . . .  18
   3.  URL Formats . . . . . . . . . . . . . . . . . . . . . . . . .  18
     3.1.  Redirects to the WebKDC . . . . . . . . . . . . . . . . .  18
     3.2.  Redirects to the WAS  . . . . . . . . . . . . . . . . . .  19
   4.  WebKDC XML Protocol . . . . . . . . . . . . . . . . . . . . .  19
     4.1.  XML Protocol Overview . . . . . . . . . . . . . . . . . .  19
     4.2.  Common XML Elements . . . . . . . . . . . . . . . . . . .  21
       4.2.1.  <errorCode> . . . . . . . . . . . . . . . . . . . . .  21
       4.2.2.  <errorMessage>  . . . . . . . . . . . . . . . . . . .  23
     4.3.  XML Commands  . . . . . . . . . . . . . . . . . . . . . .  23
       4.3.1.  getTokens . . . . . . . . . . . . . . . . . . . . . .  23
       4.3.2.  requestToken  . . . . . . . . . . . . . . . . . . . .  26
       4.3.3.  webkdcProxyToken  . . . . . . . . . . . . . . . . . .  32
       4.3.4.  webkdcProxyTokenInfo  . . . . . . . . . . . . . . . .  32
     4.4.  Posting XML to the WebKDC . . . . . . . . . . . . . . . .  33
     4.5.  XML Examples  . . . . . . . . . . . . . . . . . . . . . .  33
       4.5.1.  WAS Asking for webkdc-service Token . . . . . . . . .  33
       4.5.2.  WAS Asking for a credential Token . . . . . . . . . .  34
   5.  Token Format  . . . . . . . . . . . . . . . . . . . . . . . .  35
     5.1.  Token Encoding  . . . . . . . . . . . . . . . . . . . . .  35
     5.2.  Assigned Token Attributes . . . . . . . . . . . . . . . .  36



Schemers & Allbery      Expires February 2, 2015                [Page 2]

Internet-Draft       WebAuth Technical Specification         August 2014


     5.3.  Authentication Factors  . . . . . . . . . . . . . . . . .  40
     5.4.  Specific Token Encoding . . . . . . . . . . . . . . . . .  42
       5.4.1.  webkdc-service Token           Encoding . . . . . . .  42
       5.4.2.  webkdc-proxy Token           Encoding . . . . . . . .  43
       5.4.3.  webkdc-factor Token           Encoding  . . . . . . .  43
       5.4.4.  request Token Encoding  . . . . . . . . . . . . . . .  45
       5.4.5.  error Token Encoding  . . . . . . . . . . . . . . . .  45
       5.4.6.  id Token Encoding . . . . . . . . . . . . . . . . . .  46
       5.4.7.  proxy Token Encoding  . . . . . . . . . . . . . . . .  47
       5.4.8.  credential Token Encoding . . . . . . . . . . . . . .  48
       5.4.9.  login Token Encoding  . . . . . . . . . . . . . . . .  48
       5.4.10. app Token Encoding  . . . . . . . . . . . . . . . . .  49
     5.5.  Kerberos Credential Encoding  . . . . . . . . . . . . . .  50
   6.  Cookie Formats  . . . . . . . . . . . . . . . . . . . . . . .  52
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  52
   Appendix A.  Document Revision History  . . . . . . . . . . . . .  52
   Appendix B.  License  . . . . . . . . . . . . . . . . . . . . . .  55
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  56

1.  Introduction

1.1.  WebAuth Components

   The WebAuth protocol involves interactions between three basic
   components:

   1.  User-Agent (UA), the user's browser

   2.  WebAuth-enabled Application Server (WAS), a web server that wants
       to serve content authenticated via WebAuth

   3.  WebKDC, the login server and provider of authenticators to the
       other two components

   The WebAuth protocol allows a WAS to securely identify a user
   accessing resources.  It also supports single sign-on, allowing a
   user to access multiple WebAuth-protected applications without having
   to authenticate to each one separately (unless an application
   requires this for security reasons).

   The WAS can also choose to either trust the WebKDC to vouch for the
   identity of a user, or it can request the WebKDC use an authenticator
   such as a Kerberos service request (KRB_AP_REQ) that it can verify
   using its own Kerberos keys.

1.1.1.  User-Agent (UA)





Schemers & Allbery      Expires February 2, 2015                [Page 3]

Internet-Draft       WebAuth Technical Specification         August 2014


   The User-Agent is a web browser that supports cookies.  No plugins,
   Java, or JavaScript are required.  The UA will be redirected to the
   WebKDC as requested to by a WAS.

1.1.2.  WebAuth-enabled Application Server (WAS)

   A WebAuth-enabled Application Server is a web server configured to
   use WebAuth to authenticate users.  If a user hasn't been
   authenticated yet (indicated by the UA possessing and presenting a
   WAS cookie), they will be redirected to the WebKDC.  Otherwise, the
   WebAuth-established authenticated identity will be used for access
   control.

   All interactions between the UA and WAS SHOULD be protected with TLS
   or SSL to prevent cookies being disclosed to an eavesdropper that
   could use those cookies to impersonate a user.  The secure flag
   SHOULD be set on all WAS cookies to request that the browser enforce
   this.

1.1.3.  WebKDC

   The WebKDC will listen for two different type of requests,
   distinguished by different URLs.

   The first type of request are those requests coming from a UA after
   it has been redirected by a WAS.  This component of the WebKDC is
   referred to as the WebLogin service.  When the WebKDC receives one of
   these, it will first see if the request includes a cookie that
   contains cached credentials.  If the request contains a valid cookie,
   this cookie is used to obtain new credentials and the user is
   redirected back to the WAS (unless the WAS has requested the user
   reauthenticate).  This is the way that WebAuth implements single
   sign-on.

   If the cookie is not present or has expired, then the user will be
   prompted for their username and password.  After submitting this
   information back to the WebKDC, the WebKDC will then verify the
   username and password, using whatever protocol is suitable for that
   site (Kerberos is the default).  The WebKDC will the generate two
   "tokens".  One is placed in a cookie scoped for the WebKDC and used
   to provide single sign-on in future requests, and one that gets sent
   back to the WAS, which will verify it upon receipt.

   The second type of request the WebKDC handles consists of XML
   messages that get POSTed to the WebKDC via HTTPS directly from a WAS.
   These messages are used to establish keys for the WAS servers or to
   request additional credentials for a user.




Schemers & Allbery      Expires February 2, 2015                [Page 4]

Internet-Draft       WebAuth Technical Specification         August 2014


   The WebKDC is also responsible for ensuring that the server making a
   request is authorized to make the request.  For example, one WAS
   server can't use a "token" that was created for use by another WAS
   server.

   All interactions between the UA or WAS and the WebKDC MUST be
   protected via TLS or SSL to prevent disclosure of passwords, as well
   as sensitive data such as the tokens which are used to provide single
   sign-on and access to application resources.

1.2.  WebAuth Tokens

   Tokens provide a standard mechanism to exchange and store information
   that is cryptographically secure from both tampering and disclosure.
   Tokens also contain information such as creation times to help detect
   replays, and expiration times so data is never trusted/used forever.
   Tokens also enable authentication of the servers using them.

   Tokens get transfered between servers using URL query parameters,
   POST data, cookies, and XML documents.  They are AES-encrypted using
   either a private key, or a shared session key.  They also include a
   SHA1 HMAC used to detect data modification or tampering.

   There are currently nine different types of tokens:

   webkdc-service (encrypted with WebKDC private key)
       The webkdc-service-token is used by WebAuth App Servers to
       communicate with the WebKDC.  It contains a session key that is
       shared between the WebKDC and the WAS.

       webkdc-service tokens are created only by the WebKDC, and are
       used only by a WAS.  From the perspective of the WAS, they are
       opaque blobs that are sent back to the WebKDC

   webkdc-proxy (encrypted with WebKDC private key)
       The webkdc-proxy-token contains a user's proxied credentials
       (generally, but not necessarily, a Kerberos ticket-granting
       ticket).  It can only be decrypted by the WebKDC, and the WebKDC
       will only allow a webkdc-proxy token to be used by the server it
       was originally generated for.  The main use of a webkdc-proxy
       token is by the WebKDC itself to implement single sign-on; that
       webkdc-proxy token is usually put in a cookie scoped to the
       WebLogin service.  Its secondary use is to allow WAS servers to
       request credential-tokens.

   request (encrypted with session key)
       The request token contains the request from a WAS for a token
       (usually an id token) from the WebKDC.  It is AES-encrypted using



Schemers & Allbery      Expires February 2, 2015                [Page 5]

Internet-Draft       WebAuth Technical Specification         August 2014


       a session key from a webkdc-service token, and contains
       information like the return URL and type of token requested.  A
       webkdc-service token is always included in a request along with a
       request token.

   error (encrypted with session key)
       An error token is returned by the WebKDC in the event of an
       unrecoverable error that occurred while asking for a token with a
       request token.

   id (encrypted with session key)
       An id token contains the identity of the user trying to access a
       resource.  The WAS will verify the id token and then will
       normally construct an app token for future use.

   proxy (encrypted with session key)
       A proxy token is used to return a webkdc-proxy token to a WAS.
       It includes information about the webkdc-proxy token such as its
       expiration and its type.

   cred (encrypted with session key)
       A credential token contains a credential for a user (generally a
       Kerberos service ticket).

   login (encrypted with WebKDC private key)
       A login token is used by the WebKDC with the requestTokenRequest
       command.  It contains the user's username and password and is
       used to obtain the inital webkdc-proxy token.  It normally only
       used internally by the WebLogin component of the WebKDC.

   app (encrypted with WAS private key)
       An app token is used by a WAS server to store data, such as the
       identity of a user after it has been verified from an id token, a
       proxy token, or credentials for future use.

   Their exact formats are discussed in detail at the end of this
   document.

1.3.  Security Model and Key Management

   As mentioned in the previous section, tokens are at the heart of the
   WebAuth security model.  They are used to authenticate requests and
   responses between servers, as well as protect data that is stored in
   URLs and cookies.  Shared symmetric keys (session keys) are used to
   encrypt tokens between servers, and private keys are used to encrypt
   tokens meant for a only a single server to decrypt.





Schemers & Allbery      Expires February 2, 2015                [Page 6]

Internet-Draft       WebAuth Technical Specification         August 2014


   Also note that any tokens that appear in URLs are tokens that are
   only valid for a short period of time (5 minutes by default).  Any
   attempt to re-use them after that will fail.  If a user bookmarks a
   URL with a token in it (or hits their "back" button) then exactly one
   of these three things will happen:

   o  The user has a valid cookie.  In this case, the token in the URL
      is ignored (but still stripped out from the URL before passing it
      to the app), so there is no problem.

   o  The user has no valid cookie, but the token in the URL is still
      valid.  In this case, the user will be authenticated and a cookie
      will be created.  Note that this can only happen until the token
      is no longer "fresh" (as mentioned, 5 minutes by default).

   o  The user has no valid cookie, and the token is too old.  In this
      case, the user will be redirected to the login page is usual (the
      token will be stripped from the URL before the redirect).

1.3.1.  Distributing and Managing Session Keys

   In order to exchange session keys, a key distribution protocol is
   needed.  For this purpose, we use Kerberos and TLS/SSL to bootstrap
   and get the session keys.  The WAS that needs a session key will post
   an XML message to the WebKDC requesting a service token.  This
   message contains a KRB_AP_REQ for the WebKDC's server principal,
   which the WebKDC uses to authenticate the server making the request.
   The WebKDC will then send back two pieces of data: a session key, and
   a service token encrypted with the WebKDC's private key and
   containing the same session key.  The service token is opaque to the
   WebAuth Application Server; it just stores this token and provides it
   to the WebKDC later when making requests.

   This mechanism allows the WebKDC to not have to store the session key
   locally.  For subsequent requests, the WAS will encrypt the request
   in the session key and provide a copy of the service token alongside
   the request.  The WebKDC will decrypt the service token with its
   private key, recover the session key, and use it to decrypt and
   validate the request.  This means the WebKDC does not have to store
   any keys other than the private key that is used to encrypt the
   service tokens.

   The whole transaction itself is protected with TLS or SSL.








Schemers & Allbery      Expires February 2, 2015                [Page 7]

Internet-Draft       WebAuth Technical Specification         August 2014


   There are no long term keys stored on the WebKDC itself other its own
   private key.  Once the WAS obtains the service token and session key,
   it will cache them both until the service token expires.  Before the
   service token expires, the WAS must request a new service token and
   will be given a corresponding new session key.

   The WebAuth protocol is designed so that other authentication
   mechanisms may be used to bootstrap, such as GSS-API or TLS client
   authentication between servers.  Kerberos is just the first
   implemented bootstrap authentication mechanism.

   One potential issue here is that potentially weaker keys (Kerberos
   keytabs, which could be 3DES or even just DES) are being used to
   bootstrap into stronger WebAuth AES keys.  This issue is partially
   mitigated by the use of TLS or SSL to further protect the
   transaction.  This seems to be an acceptable risk, but it's worth
   being aware of.  The Kerberos infrastructure should obviously use the
   strongest keys possible.

1.3.2.  Distributing and Managing Private Keys

   Both the WebKDC and the WAS servers need private keys to encrypt
   their tokens with.  These keys will be randomly-generated 128-bit AES
   keys (longer keys are supported if needed).  They are stored in key
   rings on the WebKDC or WAS server.  The key ring SHOULD support
   holding both currently valid keys and keys that will be valid in the
   future.

   Since key rings are never sent over the network by the WebAuth
   protocol, WebAuth implementations can use whatever mechanism they
   wish to store keys.  However, the following data should be stored for
   each key:

   key type
       Type of the key.  AES is the only supported key type right now.

   key data
       The binary data that makes up the key.

   creation
       Time the key was created.

   valid_after
       When the key becomes valid.

   Of note is the valid_after value.  It is used to create post-dated
   keys in the key ring, to allow for new keys to get generated and
   distributed among a pool of servers (for load balancing/fail-over) in



Schemers & Allbery      Expires February 2, 2015                [Page 8]

Internet-Draft       WebAuth Technical Specification         August 2014


   such a way that all the keys can be updated before the key becomes
   valid.

   There is no support in the WebAuth protocol itself for distributing
   key rings among pools of servers, but a mechanism such as SSH can be
   used.

   Stand-alone servers (not part of a pool) SHOULD automatically
   generate new keys when needed on a restart.

1.3.3.  Supporting Server Pools

   In order to support server pools, we need to ensure that any server
   that receives a token is able to decrypt and verify it.  Note that we
   are only talking about the WebAuth protocol here.  Applications must
   solve their own synchronization issues when using a pool of servers
   as a front end.

   For the WebKDC, all we need to do is distribute the same key ring
   across all the WebKDCs.  Post-dating new keys when adding them makes
   this task easier, since the key ring only has to be updated on all
   WebKDCs by the time the key becomes valid.

   For a WAS, there are two issues.  First, we also need to distribute
   the key ring so all WAS servers can decrypt their app-tokens.  The
   second question is how to deal with session keys.

   Responses from the WebKDC come back to the WAS encrypted with the
   session key, not the WAS server's private key.  If the response comes
   back to a different WAS server, it will not have the same session key
   that the requesting WAS server had.  One could work around this by
   sharing the same service token and session key across all the
   servers, but this would be painful and expensive to do.

   The most flexible and recommended solution is for WAS servers to
   include some state (described below) in each request token.  The
   WebKDC treats this state as opaque data and returns it to the WAS
   server along with the requested token.  It is transmitted alongside
   the returned token, not inside it, so that the WAS doesn't have to
   know the session key to read it.  To use this method, the WAS server
   creates an app token (which is encrypted with its private key, shared
   among all the sytsems in the pool), includes in it the session key,
   and sends this as the state in the request token.  Since the WebKDC
   returns this state along with its response, any WAS in the pool can
   then decrypt the state with its private key, recover the session key,
   and then use that to decrypt the rest of the response.





Schemers & Allbery      Expires February 2, 2015                [Page 9]

Internet-Draft       WebAuth Technical Specification         August 2014


   Another somewhat simpler way to handle this is make sure that the
   return URL in the request token contains the server's private
   hostname or IP address instead of the virtual or pool address.  This
   solves the problem as the request always comes back to WAS server
   that initiated the request.  However, this means that the real server
   name or IP address must be exposed to the UA and transparent failover
   among systems in the pool will not be supported.

2.  WebAuth Scenarios

   There are five basic scenarios in the WebAuth protocol.

2.1.  No Tokens (Initial Sign-On)

   The first scenario is a user request to a WebAuth-protected resource
   without any prior WebAuth login and without any authentication
   cookies.  In other words, there is no app token or proxy token in the
   UA cookie jar.

































Schemers & Allbery      Expires February 2, 2015               [Page 10]

Internet-Draft       WebAuth Technical Specification         August 2014


     ---------------------------------------------------------------
         UA                 WAS            WebKDC
     ---------------------------------------------------------------
                            send Kerberos auth for webkdc-service token
     1.                     WAS ---------> WebKDC

                            return session key, webkdc-service token
     2.                     WAS <--------- WebKDC

         request resource
     3.  -----------------> WAS

         redirect to WebKDC w/request token asking for id token
     4.  <----------------- WAS

         pass along request token
     5.  -------------------------------> WebKDC

         login form sent back
     6.  <------------------------------- WebKDC

         post login form with user authentication (password)
     7.  -------------------------------> WebKDC

         confirmation page sent back, link contains id token
     8.  <------------------------------- WebKDC

         re-request resource (with returned id token in URL)
     9.  -----------------> WAS

         set the app token cookie, response from app
     10. <----------------- WAS

     ---------------------------------------------------------------

   The first and second steps normally happen when the WAS is first
   started or when its previous service token expire and are included
   for completeness.  They are omitted in all further scenarios, but
   should be assumed to happen when needed.

   1.   The WAS connects directly to the WebKDC and requests a service
        token and session key to use for further requests.  It includes
        in this request a KRB_AP_REQ for the WebKDC's service principal,
        using the WAS's private Kerberos key.

   2.   The WebKDC authenticates the WAS server via Kerberos and returns
        the webkdc-service token and corresponding session key.




Schemers & Allbery      Expires February 2, 2015               [Page 11]

Internet-Draft       WebAuth Technical Specification         August 2014


   3.   The UA requests a WebAuth-protected resource from WAS.

   4.   No app token is found either in a cookie or in the URL, so the
        WAS constructs a request token, asking for an id token.  The
        request token also contains the return URL, requested type of
        token, and any additional desired options.  It may also contain
        an app token with the session key encrypted with the WAS's
        private key (for handling server pools).  The request token is
        encrypted with the AES session key shared between the WAS and
        the WebKDC.  The WAS then returns a temporary redirect to the
        UA, sending the UA to the WebLogin component of the WebKDC and
        including the request token in the redirect URL.

   5.   The UA follows the redirect and sends a request to the WebLogin
        component of the WebKDC, including the request token in the URL.
        No cookies are sent to the WebKDC since the user has never
        previously authenticated.

   6.   The WebKDC decrypts the request token, checks the creation time
        to make sure the request is fresh, and sends back a login form
        or other authentication prompt to the UA.  The request token or
        needed information derived from it will generally be included in
        a hidden form field.  (This assumes that a form prompt is needed
        to authenticate the user.  If the user can be authenticated
        directly by the WebLogin server via some method such as SPNEGO,
        it may skip sending back a login form and therefore also skip
        the next step, proceeding directly to checking the authorization
        of the WAS.)

   7.   The user enters their username and password or other
        authentication credentials and instructs their UA to submit the
        form back to the WebKDC.

   8.   The WebKDC validates the username and password or other
        authentication credentials and also makes sure that the WAS is
        allowed to request the token asked for in the request token.
        Assuming the username and password are valid, the WebKDC
        constructs a webkdc-proxy token and the id token and then sends
        a confirmation page back to the UA which includes a link back to
        the WAS that contains the id token (and any additional state
        information sent by the WAS) in the URL.  The response page also
        sets a cookie containing the webkdc-proxy token.  (For some
        forms of authentication that can be repeated without prompting
        the user, such as SPNEGO, the WebKDC may decide not to set a
        webkdc-proxy cookie.)






Schemers & Allbery      Expires February 2, 2015               [Page 12]

Internet-Draft       WebAuth Technical Specification         August 2014


   9.   When the user follows the link on the confirmation page, the UA
        will re-request the original resource but now with the id token
        included in the URL.

   10.  The WAS will see the id token in the URL and will check to
        ensure it is fresh.  It will then look at the subject
        authenticator-type in the token to see if it needs to verify the
        subject.  If the authenticator-type is krb5, it uses its
        Kerberos keytab to verify the identity of the subject.  In this
        case, the token will include a KRB_AP_REQ for the Kerberos
        identity of the WAS in the subject authenticator data field of
        the id token.

        After verifying the subject if desired, the WAS creates an app
        token based on the id token and puts it into a cookie to
        authenticate future requests from that UA.  The app token will
        inherit the expiration time of the id token.  The WAS then
        passes the request to the underlying web application, stripping
        the id token from the URL before doing so and including the
        WebAuth-derived authentication information.  When the web
        application returns the resource, the WAS adds a header to set
        the app token before sending that resource back to the UA.

   The above assumes that the WAS will use a WebAuth app token in a
   cookie for further session authentication.  An equally valid choice
   from a protocol perspective would be for the WAS to create its own
   authentication cookies and not bother with an app token.  Whether to
   do this or use app tokens is a decision entirely internal to the WAS,
   but note that the metadata in the id token (particularly the
   expiration time) MUST be honored by the WAS.

   All cookies set by the WebAuth protocol MUST be session cookies that
   are destroyed when the browser is closed.  This allows the user to
   easily log out by closing the browser before the tokens in the
   cookies expire.

2.2.  App Token

   In the second scenario, the user requests a WebAuth-protected
   resource and already has an app token in a cookie.  This will be the
   most common case.










Schemers & Allbery      Expires February 2, 2015               [Page 13]

Internet-Draft       WebAuth Technical Specification         August 2014


     ---------------------------------------------------------------
         UA                 WAS            WebKDC
     ---------------------------------------------------------------
         request resource
     1.  -----------------> WAS

         response
     2.  <----------------- WAS

     ---------------------------------------------------------------

   1.  The UA requests a WebAuth-protected resource from WAS and
       includes a cookie containing an app token for that WAS.

   2.  The WAS decrypts the app token with its private key, determines
       the user identity from the contents, and passes the request to
       the underlying application along with that identity.

2.3.  No App Token, Proxy Token (Single Sign-On)

   In the third scenario, the user requests a WebAuth-protected resource
   and doesn't have an app token for that WAS, but does have a webkdc-
   proxy token (in a cookie) for the WebKDC.  This is the single sign-on
   case: the user has not authenticated to that application, but has
   previously authenticated via WebAuth.  The WebKDC can use the user's
   webkdc-proxy token to authenticate the user without having to prompt
   them for their password again.
























Schemers & Allbery      Expires February 2, 2015               [Page 14]

Internet-Draft       WebAuth Technical Specification         August 2014


     ---------------------------------------------------------------
         UA                 WAS            WebKDC
     ---------------------------------------------------------------
         request resource
     1.  -----------------> WAS

         redirect to WebKDC w/request token asking for id token
     2.  <----------------- WAS

         pass along request token
     3.  -------------------------------> WebKDC

         confirmation page sent back, link contains id token
     4.  <------------------------------- WebKDC

         re-request resource (with returned id token in URL)
     5.  -----------------> WAS

         set the app token cookie, response from app
     6.  <----------------- WAS

     ---------------------------------------------------------------

   This assumes the WAS has already established a session key with the
   WebKDC, as previously discussed.

   1.  The UA requests a WebAuth-protected resource from the WAS.

   2.  No app token is found either in a cookie or in the URL, so the
       WAS constructs a request token, asking for an id token.  This is
       done in exactly the same way as in the first scenario.

   3.  The UA follows the redirect and sends a request to the WebLogin
       component of the WebKDC, including the request token in the URL.
       Included in this request is a cookie containing a webkdc-proxy
       token since the user has previously authenticated.

   4.  The WebKDC detects and decrypts the valid webkdc-proxy token
       using its private key.  It uses it to construct a new id token
       and then generates a confirmation page containing a link to the
       return URL.  That link includes the id token, just as with the
       first scenario.

   5.  When the user follows the link on the confirmation page, the UA
       will re-request the original resource but now with the id token
       included in the URL.





Schemers & Allbery      Expires February 2, 2015               [Page 15]

Internet-Draft       WebAuth Technical Specification         August 2014


   6.  The WAS verifies the id token, passes the request to the
       application with that identity information, and returns the
       result while setting an app token in a cookie as in the first
       scenario.

2.4.  No App Token, Credentials Required

   In the fourth scenario, the user requests a WebAuth-protected
   resource that needs proxied credentials to act on the user's behalf.
   In this case, the WAS must request a proxy token, which it will then
   use to request additional credentials via the XML interface.  In the
   below discussion, we assume the UA already has a webkdc-proxy cookie
   and the WebKDC can use single sign-on, but this is not required.  If
   there is no webkdc-proxy cookie, the user will be prompted for
   authentication and then everything else will proceed as below.

     ---------------------------------------------------------------
         UA                 WAS                WebKDC
     ---------------------------------------------------------------
         request resource
     1.  -----------------> WAS

         redirect to WebKDC w/request token asking for proxy token
     2.  <----------------- WAS

         pass along request token
     3.  ------------------------------------> WebKDC

         confirmation page sent back, contains proxy token
     4.  <------------------------------------ WebKDC

         re-request resource (with returned proxy token in URL)
     5.  -----------------> WAS

                                send proxy token with request
     6.                     WAS -------------> WebKDC

                                returns credential token
     7.                     WAS <------------- WebKDC

         set the app token cookie, response from app
     8.  <----------------- WAS
     ---------------------------------------------------------------

   This assumes the WAS has already established a session key with the
   WebKDC, as previously discussed.

   1.  The UA requests a WebAuth-protected resource from the WAS.



Schemers & Allbery      Expires February 2, 2015               [Page 16]

Internet-Draft       WebAuth Technical Specification         August 2014


   2.  The WAS sees no app token containing the required credentials and
       constructs a request token asking for a proxy token of the
       desired type.  It then returns a redirect to the WebLogin
       component of the WebKDC, including the request token in the URL,
       as previously.  The only difference is in the contents of the
       request token.

   3.  The UA follows the redirect to the WebKDC, including the request
       token in the URL and the webkdc-proxy token for the WebKDC itself
       since the user had previously authenticated.

   4.  The WebKDC decrypts and validates the webkdc-proxy token and uses
       it to construct a proxy token as requested by the WAS.  It then
       returns a confirmation page containing a link to the return URL
       with the proxy token embedded in the URL (along with any
       additional state information requested), as before.

   5.  The user follows the link and the UA re-requests the original
       resource, now including the proxy token in the URL.

   6.  The WAS decrypts and verifies the proxy token and recovers from
       it the embedded webkdc-proxy token.  It then sends an XML request
       direct to the WebKDC, including its webkdc-service token and the
       webkdc-proxy token, requesting an id token and whatever
       credential tokens it needs.

   7.  The WebKDC receives the webkdc-service token and webkdc-proxy
       token, verifies that the subject of the webkdc-service token is
       permitted to use the webkdc-proxy token and verifies that it is
       allowed to request that type of credential token.  If everything
       is okay, it returns the requested id and credential tokens.

   8.  After verifying the returned id token, the WAS will create an app
       token for further authentication.  It will also often create new
       app tokens containing the provided credentials for its own futher
       use so that it doesn't have to keep asking for credential tokens
       or store them locally.  The request is then passed to the web
       application, along with the user's identity and the credentials,
       and the result passed back to the UA along with the new cookies.

   Normally, the requested credential tokens will be Kerberos service
   tickets that the WAS can then use to talk to other services that use
   Kerberos authentication.  Since the webkdc-proxy token is generally a
   Kerberos TGT credential, this works together well and allows WebAuth
   to treat the UA's cookie jar as essentially a Kerberos ticket cache.
   However, this is not required by the protocol and credential tokens
   may be any form of credential supported by the WAS and WebKDC.




Schemers & Allbery      Expires February 2, 2015               [Page 17]

Internet-Draft       WebAuth Technical Specification         August 2014


   As with an id token, the WAS may choose not to put the credentials in
   an app token for subsequent use.  It may instead want to store them
   on the server tied to a session cookie or some other internal state-
   tracking mechanism.  However, the metadata in the credential tokens
   (particularly expiration time) MUST be honored.

   The credentials returned by the WebKDC in a credential token SHOULD
   encode an expiration time that cannot be manipulated by the WAS so
   that the WAS need not be trusted to honor credential expiration.

2.5.  Logging Out

   The only fully effective way to log out of WebAuth is to close the
   browsing session, which will cause all WebAuth cookies to be
   discarded since they all MUST be session cookies.  This is a weakness
   in the WebAuth protocol created by the use of scoped cookies to hold
   all authentication information.  Fixing it requires keeping
   additional queriable state outside of the user's cookies and the WAS
   and WebKDC keys.

   Logging out of an application requires removing all session cookies
   associated with a given application on a given server removed.  This
   can be achieved with a logout link available within the application
   itself that leads to a page that clears all the cookies.  A WebAuth
   WAS implementation SHOULD provide some simple way for an application
   developer to indicate that going to a given URL should remove all app
   cookies.

   After logging out of the application, the user can also be sent to a
   logout page on the WebKDC that removes the webkdc-proxy cookie used
   for single sign-on.  After going to such a page, the user will have
   to reauthenticate to access any new web application.  However, their
   UA will retain app cookies for other applications they have already
   used in this session and have not logged out of, so the user SHOULD
   be warned to close the browser to fully log out.

   There is a field in the app token in which the WAS may record a
   session timeout, causing the app token to become invalid if it is not
   used within a certain period of time.  The WAS may also request in a
   request token that the webkdc-proxy token be ignored and the user be
   forced to re-authenticate even if already authenticated.

3.  URL Formats

3.1.  Redirects to the WebKDC

   Each WAS will be configured with a URL to redirect a UA to when the
   user needs to be authenticated.  When making an authentication



Schemers & Allbery      Expires February 2, 2015               [Page 18]

Internet-Draft       WebAuth Technical Specification         August 2014


   request, the WAS must include both the request token and the webkdc-
   service token (the latter so that the WebKDC can decrypt the request
   token).  These tokens will be passed via query parameters in the URL.

   The format is:

   https://{host}/{webkdc-uri}?RT={request-token};ST={service-token}

   where RT is the base64-encoded request token and ST is the
   base64-encoded service token.

3.2.  Redirects to the WAS

   When the WebKDC sends the UA back to the WAS with an id or proxy
   token, it will construct a return URL by taking the return-url
   specified in the request token and appending "?WEBAUTHR={token};" to
   it, where {token} is the requested token.  If the "as" (application
   state) attribute was specified in the request token, it is
   base64-encoded and then appended to the URL (always after WEBAUTHR)
   as "WEBAUTHS={state};" where {state} is the application state
   provided in the request token.

   To be precise, the format is:

   {return-url}?WEBAUTHR={token}[;WEBAUTHS={state};]

   where the part in [] is optional.

   The WAS will generally strip the added components off the URL before
   passing the request to the underlying web application.  It may verify
   the token, construct an app token, and return a redirect to the same
   URL with the WebAuth data stripped and the cookie set rather than
   immediately passing the request to the application, to "clean up" the
   URL in the UA, avoid embedding outdated tokens in bookmarks, and
   confusing applications that are aware of their own URLs.

4.  WebKDC XML Protocol

   This section describes the XML protocol used to talk to the WebKDC.
   It is used by a WAS to request a webkdc-service token and session key
   or to use a proxy token to request credential tokens, and internally
   by the WebLogin component of the WebKDC to request webkdc-proxy, id,
   and proxy tokens from the WebKDC to return to the UA.

4.1.  XML Protocol Overview

   The protocol consists of an exchange of XML-formatted messages over
   an HTTPS connection.  A protocol interaction consists of a single XML



Schemers & Allbery      Expires February 2, 2015               [Page 19]

Internet-Draft       WebAuth Technical Specification         August 2014


   message sent by the client with HTTP POST and a single XML message
   response from the server.

   For ease of parsing, for any elements that require a base64-encoded
   value, there must be no whitespace after the open element and before
   the close element.

   For example, this is valid:

   <requestToken>{base64-webkdc-service-token}</requestToken>

   while this is not:

   <requestToken>
       {base64-webkdc-service-token}
   </requestToken>

   The spec uses whitespace in the following examples for readability,
   but bearing in mind the above, it should be omitted in practice.

   The command request format is:

   <xxxxRequest>
     <!-- rest depends on command -->
   </xxxxRequest>

   where xxxx is the type of request.

   The command response format on success is:

   <xxxxResponse>
     <!-- rest depends on command -->
   </xxxxResponse>

   where xxxx is the type of request being responded to.

   The command response format on failure is:

   <errorResponse>
     <errorCode>{numeric}<errorCode>
     <errorMessage>{message}<errorMessage>
   </errorResponse>









Schemers & Allbery      Expires February 2, 2015               [Page 20]

Internet-Draft       WebAuth Technical Specification         August 2014


4.2.  Common XML Elements

   The following elements are common to all commands.

4.2.1.  <errorCode>

   This is a numeric error code for an errorResponse message.  It MUST
   be one of the following:

   1   The service token used was expired.

   2   The service token used was corrupt and/or was unable to be
       decrypted.

   3   The proxy token used was expired.

   4   The proxy token used was corrupt and/or was unable to be
       decrypted.

   5   The request was invalid.  For example, a required element was
       missing, an attribute value was incorrect, the server was unable
       to parse the XML request, etc.  This generally indicates a bug in
       the client.

   6   The request was unauthorized.  An attempt was made to request a
       token type that the client was not authorized to request.

   7   The server encountered an internal error (out of memory, for
       example).  If the client retries the request may succeed, though
       some external event might be causing the problem (such as a
       Kerberos server being down).

   8   The request token was stale.

   9   The request token was invalid.

   10  Unable to obtain the requested credential token.

   11  The krb5 <requesterCredential> was bad.

   12  The login token was stale.

   13  The login token was invalid.

   14  Login failed due to bad password, invalid username, invalid OTP
       code, or some other authentication failure.





Schemers & Allbery      Expires February 2, 2015               [Page 21]

Internet-Draft       WebAuth Technical Specification         August 2014


   15  A webkdc-proxy token of a certain type was required to fulfill
       the request but was not present in the request.

   16  The user selected cancel during the login process.

   17  The WAS server requested a forced login in the request token, so
       obtaining the id or proxy token via the webkdc-proxy token is not
       allowed.

   18  The user's principal was not permitted to authenticate to the
       WebKDC.

   19  The user's password has expired.

   20  The WAS server requested multifactor authentication, so obtaining
       the id or proxy token via only a webkdc-proxy token or only a
       login token is not allowed.

   21  The WAS server 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).

   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.  This code indicates a temporary failure, not incorrect
       credentials (which is indicated by error code 14).  Compare to
       error code 24.

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

   24  The user is not permitted to authenticate to the desired
       destination WAS at this time.  This may be due to local policy,
       security limitations placed on the user, missing prerequisite
       actions that the user must take (such as training or a usage
       agreement), or some other local factor.  This code indicates that
       this specific authentication is not allowed but another
       authentication by the same user from the same host to a different
       site may be permitted.  Error code 22 indicates that this user
       may not authenticate at this time from that host, regardless of
       their destination.

   25  This authentication appears to be a replay.



Schemers & Allbery      Expires February 2, 2015               [Page 22]

Internet-Draft       WebAuth Technical Specification         August 2014


   26  This authentication was rejected due to too many failed
       authentication attempts for this user.  The authentication should
       be retried later.

   27  This authentication failed due to a remctl timeout.  The
       authentication should be tried again.

4.2.2.  <errorMessage>

   This is a textual description of the error code, meant to be human
   readable but not ideal for displaying to the user (it is not
   localized).  It's useful for log messages or for localization of last
   resort.

4.3.  XML Commands

   There are currently four commands defined: getTokens, requestToken,
   webkdcProxyToken, and webkdcProxyTokenInfo.  The getTokens command is
   used directly by the WAS to request either a service token or id and
   credential tokens from a proxy token.  The requestToken command is
   used by the WebLogin component of the WebKDC to process a request
   token sent in a URL from a WAS.  The webkdcProxyToken command
   converts an existing credential (such as a Kerberos credential for
   the ticket-granting service) into a webkdc-proxy token and can be
   used to bootstrap WebAuth authentication from an existing Kerberos
   ticket cache for improved single sign-on.  The webkdcProxyTokenInfo
   command returns information about an existing webkdc-proxy token.

4.3.1.  getTokens

   The getTokens command is used to request tokens (service, id, proxy,
   or credential).  It is used in two fundamentally different ways: for
   a WebAuth Application Server to request a webkdc-service token from
   the WebKDC, and for a WAS to use a proxy token it acquired from the
   user to request cred or id tokens.

   The request message for obtaining a service token is:

     <getTokensRequest>
       <requesterCredential type="krb5">
          {base64-krb5-mk-req-data}
       </requesterCredential>

       <tokens>
         <token type="service" id="{id-for-response}"/>
       </tokens>
     </getTokensRequest>




Schemers & Allbery      Expires February 2, 2015               [Page 23]

Internet-Draft       WebAuth Technical Specification         August 2014


   The response message is:

   <getTokensResponse>
     <tokens>
       <token id="{id-from-request}">
         <tokenData>{base64}</tokenData>
         <sessionKey>{base64-session-key}</sessionKey>
         <expires>{expiration-time}</expires>
       </token>
     </tokens>
   </getTokensResponse>

   The id attribute to the <token> element in the request is optional
   and is normally omitted, since the WAS is only requesting one token.
   If it is omitted in the request, it is also omitted in the response.

   If any errors occur, an <errorResponse> message will be returned
   instead.

   The second form of this request is used by the WAS to obtain
   additional credentials from a proxy token.  This is used when the WAS
   may need Kerberos credentials on behalf of the user, and therefore
   requested a proxy token instead of an id token in the original
   authentication request to the WebKDC.  The <getTokensRequest> request
   message is used to obtain those cred tokens plus an id token.

   requesterCredentials of type "krb5" can only be used to obtain a
   webkdc-service token.  They can't be used for obtaining any other
   tokens, nor can a credential of type "service" be used to request
   another webkdc-service token.  In all other cases, the
   requesterCredentials are a webkdc-service token.

   The request message for obtaining other tokens from a proxy token is:


















Schemers & Allbery      Expires February 2, 2015               [Page 24]

Internet-Draft       WebAuth Technical Specification         August 2014


     <getTokensRequest>
       <requesterCredential type="service">
          {base64-webkdc-service-token}
       </requesterCredential>

       <subjectCredential type="proxy">
          <proxyToken>{base64-webkdc-proxy-token}</proxyToken>
          <!-- additional <proxyToken>...</proxyToken> here -->
       </subjectCredential>

       <requestToken>{base64-request-token}</requestToken>

       <tokens>
         <token type="id|cred" id="{id-for-response}">
           <!-- for type="id" -->
           <!-- optional, default is krb5 -->
           <authenticator type="krb5|webkdc"/>

           <!-- for type="cred" -->
           <credentialType>krb5</credentialType>
           <serverPrincipal>{krb5-service}</serverPrincipal>
         </token>
         <!-- additional <token>...</token> requests go here -->
       </tokens>
     </getTokensRequest>

   The response message is:

   <getTokensResponse>
     <tokens>
       <token id="{id-from-request}">
         <tokenData>{base64}</tokenData>
       </token>
       <!-- additional <token>...</token> responses go here -->
     </tokens>
   </getTokensResponse>

   Here, the credentials provided are a previously-requested webkdc-
   service token instead of a Kerberos authenticator, and the proxy
   token received from the user's browser is also included.  In this
   form of the request, the WAS also includes a request token, encrypted
   with the session key of the webkdc-service token, to prove that it
   has possession of the session key.

   If any errors occur, an <errorResponse> message will be returned
   instead.





Schemers & Allbery      Expires February 2, 2015               [Page 25]

Internet-Draft       WebAuth Technical Specification         August 2014


4.3.2.  requestToken

   The requestToken command is used by the WebLogin component of the
   WebKDC to process a request token sent in a URL from a WAS.

   The request message is:













































Schemers & Allbery      Expires February 2, 2015               [Page 26]

Internet-Draft       WebAuth Technical Specification         August 2014


     <requestTokenRequest>

       <requesterCredential type="service">
         {base64-webkdc-service-token}
       </requesterCredential>

       <subjectCredential>
         <!-- need to pass in all the existing proxy-tokens, since
              we (the web front-end) don't know which we might need -->
         <!-- source is the source of this proxy token, used to
              determine the session factors, expressed as a factor
              code, so "c" for tokens from cookies, "k" for tokens
              derived from Kerberos authentication, and so forth -->
         <proxyToken type="krb5|..." source="{factor}">...</proxyToken>
         <!-- additional <proxyToken>...</proxyToken> here -->

         <!-- present if the user just authenticated -->
         <loginToken>...</loginToken>

         <!-- a webkdc-factor token presented by the user -->
         <factorToken>...</factorToken>
       </subjectCredential>

       <!-- request token from WAS -->
       <requestToken>{base64-request-token}</requestToken>

       <!-- requested authorization identity (optional) -->
       <authzSubject>...</authzSubject>

       <!-- opaque state object for customization (optional) -->
       <loginState>...</loginState>

       <!-- request info from front-end, for logging purposes -->
       <requestInfo>
         <remoteUser>xxxx</remoteUser>

         <!-- if one of these is provided, all must be -->
         <localIpAddr>n.n.n.n</localIpAddr>
         <localIpPort>nnnn</localIpPort>
         <remoteIpAddr>n.n.n.n</remoteIpAddr>
         <remoteIpPort>nnnn</remoteIport>
       </requestInfo>
     </requestTokenRequest>

   The response message is:

     <requestTokenResponse>




Schemers & Allbery      Expires February 2, 2015               [Page 27]

Internet-Draft       WebAuth Technical Specification         August 2014


       <!-- loginErrorCode will be set in a requestTokenResponse if
            there was an error related to logging in  -->
       <loginErrorCode>{numeric}<loginErrorCode>
       <loginErrorMessage>{message}<loginErrorMessage>

       <!-- userMessage will be set if the User Information Service or
            OTP Validation service sets a user-message in a response,
            or if loginErrorCode is 24.  It is an HTML message intended
            for the end user.  It will normally be in a CDATA block to
            protect markup. -->
       <userMessage>{message}</userMessage>

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

         <!-- present if user has configured a multifactor method -->
         <configuredFactor>{factor-code}</configuredFactor>
         <!-- repeat for each possible authentication method available
              for that user that would satisfy a requirement of the WAS
              or site policy, omitting "m" -->

         <!-- present if there is a default second factor -->
         <defaultFactor>
           <id>{device-id}</id>
           <factor>{factor-code}</factor>
         </defaultFactor>

         <!-- lists configured ways of providing a second factor -->
         <!-- name is intended for display to the user in a list -->
         <!-- id is included in login token as device_id -->
         <!-- there may be multiple factors per device -->
         <devices>
           <device>
             <name>{device-name}</name>
             <id>{device-id}</id>
             <factor>{factor-code}</factor>
             <factor>{factor-code}</factor>
           </device>
         </devices>
       </multifactorRequired>

       <!-- any updated/new proxy tokens created -->
       <proxyTokens>
         <proxyToken type="krb5|...">{base64-proxy-token}</proxyToken>
       </proxyTokens>



Schemers & Allbery      Expires February 2, 2015               [Page 28]

Internet-Draft       WebAuth Technical Specification         August 2014


       <!-- currently, only one factor token is permitted -->
       <factorTokens>
         <factorToken expires="{expiration-time}">
           {base64-factor-token}
         </factorToken>
       </factorTokens>

       <!-- the url to return to the user to -->
       <returnUrl>...</returnUrl>

       <!-- subject inside of service-token used to make request -->
       <requesterSubject>...</requesterSubject>

       <!-- subject from subjectCredential -->
       <subject>...</subject>

       <!-- authorization identity if requested and permitted -->
       <authzSubject>...</authzSubject>

       <!-- opaque state object for customization (optional) -->
       <loginState>...</loginState>

       <!-- permitted authorization identities if this user may assert
            an authorization identity to this destination -->
       <permittedAuthzSubjects>
         <authzSubject>...</authzSubject>
         <!-- repeat for all permitted authorization identities -->
       </permittedAuthzSubjects>

       <!-- requestedToken will either be an error, id, or proxy token.
            not set if <loginErrorCode> is set. -->
       <requestedToken>{base64-token}</requestedToken>

       <!-- requestedTokenType will be the type of requestedToken,
            one of error, id, or proxy.  not set if <LoginErrorCode> is
            set. -->
       <requestedTokenType>error|id|proxy</requestedToken>

       <!-- set if request token request options has "lc" -->
       <loginCanceledToken>{base64-error-token}</loginCanceledToken>

       <!-- app state is the opaque app state passed in the
            request token that we hand back to WAS -->
       <appState>{base64-state}</appState>

       <!-- optional, included if the user's login history should be
            displayed (if, for example, it was suspicious) -->
       <loginHistory>



Schemers & Allbery      Expires February 2, 2015               [Page 29]

Internet-Draft       WebAuth Technical Specification         August 2014


         <!-- the name and timestamp information is optional -->
         <loginLocation name="{hostname}" time="{timestamp}">
           {ip-address}
         </loginLocation>
         <!-- repeat for site-defined length of login history -->
       </loginHistory>

       <!-- optional, included the WebKDC has information about when
            the user's password expires, in seconds since POSIX
            epoch -->
       <passwordExpires>{expiration-time}</passwordExpires>
     </requestTokenResponse>

   If any non-login-related errors occur, an <errorResponse> message
   will be returned instead.

   If a login-related error occurs then a <requestTokenResponse> will be
   returned, but <requestedToken> will be unset, and <loginErrorCode>
   will be set.  The error codes used by <loginErrorCode> are a subset
   of those used by <errorCode>:

   14  Login failed due to bad password, invalid username, invalid OTP
       code, or similar error.  The web front-end should re-prompt for
       the username and password or OTP code.

   15  A webkdc-proxy token of a certain type was required and was not
       present in the request.  The web front-end should prompt for the
       username and password.  This error code may occur when two
       different strengths of webkdc-proxy tokens are used, one that's
       good only for id tokens (but may be possible to generate without
       prompting the user) and one that can generate proxy tokens.  If
       the WAS requests a proxy token and the webkdc-proxy token
       available is only good for id tokens and cannot be used to
       generate proxy tokens, this error code is returned, prompting the
       front-end to do stronger authentication.

   17  The WAS server requested a forced login.  The web front-end
       should prompt for the username and password even though a webkdc-
       proxy token is available.

   18  The user's principal was not permitted to authenticate to the
       WebKDC.  The web front-end may re-prompt for another username and
       password or just display an error.

   19  The user's password has expired.  The web front-end may prompt
       the user to change it and then reattempt authentication.





Schemers & Allbery      Expires February 2, 2015               [Page 30]

Internet-Draft       WebAuth Technical Specification         August 2014


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

   21  The WAS server 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.

   24  The user is not permitted to authenticate to the desired
       destination WAS at this time.  This may be due to local policy,
       security limitations placed on the user, missing prerequisite
       actions that the user must take (such as training or a usage
       agreement), or some other local factor.  An HTML message intended
       for the end user will be present in the <userMessage> element of
       the WebKDC reply.

   requestedTokenType is included so that the WebLogin component can
   make display decisions based on whether the remote site requested an
   id token or a proxy token.

   If the request option attribute in the request token has "lc" in it,
   then <loginCanceledToken> will be returned.  This token should be
   returned to the WAS if the user elects to cancel authentication so
   that the application can take appropriate action.  Note that it is up
   to the WebLogin component to send back that token as the requested
   token (WEBAUTHR in the return URL) if the user hits the cancel
   button.





Schemers & Allbery      Expires February 2, 2015               [Page 31]

Internet-Draft       WebAuth Technical Specification         August 2014


   If the request option attribute in the request token has "fa" in it
   and a login token is not provided, this command will return a
   <loginErrorCode> of 17, which indicates that the user is being forced
   to log in.  Any passed-in webkdc-proxy tokens are ignored.

   The <requestInfo> data is provided only for logging and audit
   purposes and MUST NOT be used for authentication.

4.3.3.  webkdcProxyToken

   The webkdcProxyToken command is used to convert an existing
   credential, such as a Kerberos TGT credential, into a webkdc-proxy
   token.  It can be used to bootstrap WebAuth authentication from an
   existing Kerberos ticket cache for improved single sign-on.

   The request message is:

     <webkdcProxyTokenRequest>
       <subjectCredential type="krb5">
         <!-- for type="krb5" -->
         {base64-krb5-mk-req-data}
       </subjectCredential>

       <proxyData>
         <!-- for subjectCredential type="krb5" -->
         {base64-krb5-mk-priv-on-tgt}
       </proxyData>
     </webkdcProxyTokenRequest>

   The response message is:

     <webkdcProxyTokenResponse>
       <webkdcProxyToken>{base64-proxy-token}</webkdcProxyToken>

       <!-- subject from subjectCredential -->
       <subject>...</subject>
     </webkdcProxyTokenResponse>

   If any errors occur, an <errorResponse> message will be returned
   instead.

4.3.4.  webkdcProxyTokenInfo

   The webkdcProxyTokenInfo command is used to get information about an
   existing webkdc-proxy-token.

   The request message is:




Schemers & Allbery      Expires February 2, 2015               [Page 32]

Internet-Draft       WebAuth Technical Specification         August 2014


   <webkdcProxyTokenInfoRequest>
     <webkdcProxyToken>{base64-proxy-token}</webkdcProxyToken>
   </webkdcProxyTokenInfoRequest>

   the response message is:

   <webkdcProxyTokenInfoResponse>
     <subject>...</subject>
     <proxyType>...</proxyType>
     <creationTime>...</creationTime>
     <expirationTime>...</expirationTime>
   </webkdcProxyTokenInfoResponse>

   If any errors occur, an <errorResponse> message will be returned
   instead.

4.4.  Posting XML to the WebKDC

   The XML data should be sent via POST to the WebKDC's URL, which
   should be different than the URL of the WebLogin service but should
   be on the same system.  By convention, it is normally /webkdc-service
   / on the designated WebKDC system, but this SHOULD be configurable in
   any WebAuth implementation.

   The Content-Type of the POST data MUST be text/xml.

   This URL MUST use the HTTPS protocol, as sensitive data is sent
   without additional encryption.

4.5.  XML Examples

4.5.1.  WAS Asking for webkdc-service Token

   In this example, the WAS requests a webkdc-service token and
   associated session key for itself.  Such a request is sent when the
   WAS needs to send requests to the WebKDC and doesn't have a non-
   expired webkdc-service token cached.  The WAS will cache the token
   and the corresponding session key until it nears expiration time, at
   which point it SHOULD request a new one.

   The request:










Schemers & Allbery      Expires February 2, 2015               [Page 33]

Internet-Draft       WebAuth Technical Specification         August 2014


   <getTokensRequest>
      <requesterCredential type="krb5">
         {base64-krb5-mk-req-data}
      </requesterCredential>
      <tokens>
        <token type="service"/>
      </tokens>
   </getTokensRequest>

   The response:

   <getTokensResponse>
     <tokens>
       <token>
         <sessionKey>{base64-session-key}</sessionKey>
         <expires>{expiration-time}</expires>
         <tokenData>{base64}</tokenData>
       </token>
     </tokens>
   </getTokensResponse>

4.5.2.  WAS Asking for a credential Token

   In this example, the WAS requests an Kerberos ticket using a
   previously obtained webkdc-proxy token (presumably obtained from the
   UA via a redirect to the WebKDC with a request token).  The webkdc-
   proxy token's type MUST match the requested credential's type.

   The request:

     <getTokensRequest>
       <requesterCredential type="service">
         {base64-webkdc-service-token}
       </requesterCredential>

       <requestToken>{base64-request-token}</requestToken>

       <subjectCredential type="proxy">
         {webkdc-proxy-token}
       </subjectCredential>
       <tokens>
         <token type="credential" id="0"/>
           <credentialType>krb5</credentialType>
           <serverPrincipal>service/ldap@stanford.edu</serverPrincipal>
         </token>
       </tokens>
     </getTokensRequest>




Schemers & Allbery      Expires February 2, 2015               [Page 34]

Internet-Draft       WebAuth Technical Specification         August 2014


   The response:

   <getTokensResponse>
     <tokens>
       <token id="0">
         <tokenData>{base64}</tokenData>
       </token>
     </tokens>
   </getTokensResponse>

   The WebKDC will verify that the webkdc-proxy token was granted to the
   same server identified by the request token.

5.  Token Format

5.1.  Token Encoding

   All encrypted tokens have the following general encoding:

   {key-hint}{nonce}{hmac}{token-attributes}{padding}

   Everything except {key-hint} is encrypted using 128-bit AES in CBC
   mode with an all-zero IV.

   {key-hint} is a four-byte Unix UTC time stored in network byte order.
   It is not encrypted and is used only as a hint for the server to
   determine which key to use to decrypt the token.  It MUST NOT be used
   for any other purpose as its value is not protected from
   modification.

   {nonce} is 16 random bytes and is encrypted with the rest of the data
   in the token.  It is used to ensure that two tokens with the same
   data and same encryption key don't encrypt to the same value.  All
   WebAuth protocol keys MUST be rotated frequently enough to ensure
   that the chances of a nonce collision between two tokens encrypted
   with the same key are sufficiently low to be ignorable, since reuse
   of the nonce may expose similarities in the plaintext.

   {hmac} is the SHA-1 HMAC of the actual data including the padding (in
   other words, the pre-encryption concatenation of {token-attributes}
   and {padding}).  The key used with HMAC is the AES private key.  (A
   better solution would be to use a different key, but that requires
   having two keys or using a key-derivation function to derive the HMAC
   key from the AES key.  One possible future approach would be to use a
   key-derivation function like TLS uses.)

   {token-attributes} is a sequence of name=value pairs, separated by a
   ';' character.  Names must be one or more ASCII alphanumeric



Schemers & Allbery      Expires February 2, 2015               [Page 35]

Internet-Draft       WebAuth Technical Specification         August 2014


   characters.  Values MAY contain arbitrary binary data, but MUST
   escape any ';' in the data by adding an additional ';' before it.

   For example, if we had the following names and values:

   a=1
   msg=hello;there
   bin={binarydata}
   b=2

   They would be encoded as:

   a=1;msg=hello;;there;bin={binarydata};b=2;

   {padding} is any padding of the data required to make the length a
   multiple of 16 bytes for AES encryption.  There is always padding
   present.  If the length is already a multiple of 16 bytes, 16 bytes
   of padding will be added.  The value of each padding byte MUST be
   equal to the length of the padding.  For example, if the padding
   length is 7, each byte in the padding must be equal to 0x07.

   The whole token is base64-encoded before being used in XML data, a
   cookie, or a query parameter.

5.2.  Assigned Token Attributes

   The following is an exhaustive list of the attribute names used in
   tokens.  All time values are 32-bit values stored in network byte
   order and are the number of seconds since 1970-01-01 00:00:00 UTC.
   All binary integers are 32-bit values in network byte order.

   as (binary)
       Optional data included in the request token.  If present, the
       same data will be sent back to the WAS as a second parameter to
       the URL, not included in the encrypted response token.

   cmd (string)
       The name of the XML command being executed (for example,
       getTokensRequest).  Included in the request token sent for XML
       commands.

   crd (binary)
       Credential data (for example, an encoded Kerberos service
       ticket).

   crs (string)





Schemers & Allbery      Expires February 2, 2015               [Page 36]

Internet-Draft       WebAuth Technical Specification         August 2014


       The identity of the service credential data can be used to access
       (normally the text representation of the server principal for a
       Kerberos service ticket).

   crt (string)
       Credential type.  Currently this is always krb5.

   ct (binary time)
       Creation time of the token.  For tokens used to exchange messages
       between servers (request, error, id, proxy, credential), this
       value is used to ensure that the request is fresh.  For example,
       tokens of this type with a ct older then 5 minutes will get
       flagged by the server (WAS or WebKDC) as being stale.

   did (string)
       A unique device ID corresponding to this authentication request,
       and matching the device attribute of a <configuredFactor> element
       in a <requestTokenResponse> reply.  Included in a login token to
       tell the WebKDC which authentication device the user chose.

   ec (string)
       Error code from the WebKDC.  This will be the ASCII digit
       representation of one of the error codes that are returned in XML
       messages.

   em (string)
       Error message from the WebKDC.  This should only be used for
       logging and/or debugging, since it is not localized and not in a
       format meant for end-user consumption.

   et (binary time)
       Expiration time of the token.

   ia (string)
       The list of authentication factors used by the authenticated user
       to get initial credentials from the local authentication system,
       or the initial authentication factors that are required by this
       WAS for a successful authentication.  This is a list of factor
       codes separated by commas.  For the list of registered factor
       names, see Section 5.3.

   k (binary)
       AES session key.

   loa (binary unsigned integer)
       A non-zero site-defined numeric Level of Assurance code for the
       assurance level of this authentication of this user, or the
       assurance level required for a successful authentication to this



Schemers & Allbery      Expires February 2, 2015               [Page 37]

Internet-Draft       WebAuth Technical Specification         August 2014


       site.  Higher values indicate a stronger level of assurance;
       otherwise, the meaning of the codes is site-defined.  The value
       of 0 is reserved to indicate that no level of assurance has been
       determined, and will not appear in tokens.

   lt (binary time)
       Last-used time.  If this attribute is set in an app token present
       in a cookie, the WAS SHOULD periodically update it (by setting a
       new cookie with an updated last-used time) as it is used for
       access.  This attribute is used to implement timing out of unused
       but still unexpired app tokens.

   otp (string)
       User's one-time password code, in a login token.

   ott (string)
       The type of OTP that the one-time password code (in the otp
       attribute) is for.  This should be an authentication factor,
       generally one of the oN factors.

   p (string)
       User's password, in a login token.

   pd (binary)
       Proxy data, such as an encoded Kerberos credential for the
       ticket-granting service (a Kerberos TGT plus its supporting data
       such as the session key).

   ps (string)
       Proxy subject, the subject from the webkdc-service token that was
       used when the webkdc-proxy token was created.  This is used to
       verify that a webkdc-proxy token is being used by the same entity
       as originally requested it.

   pt (string)
       Proxy type (such as krb5).

   ro (string)
       Comma-separated list of request options.  Currently, the
       following options are supported: lc, to return an error code to
       the application if login is cancelled; and fa, to force
       interactive authentication even if the user has a webkdc-proxy
       token.

   rtt (string)
       Requested token type in a request token.  This is either id for
       an id token or proxy for a proxy token.




Schemers & Allbery      Expires February 2, 2015               [Page 38]

Internet-Draft       WebAuth Technical Specification         August 2014


   ru (string)
       Return URL.  The user to return the user to after authentication.

   s (string)
       The authenticated subject.  In webkdc-service tokens, this is the
       server identity that authenticated to get the webkdc-service
       token.  In all other tokens, it is the user who authenticated.
       Server subjects in webkdc-service tokens (and only those, not
       other subjects) have the form "type:identifier".  Currently, the
       only defined type is "krb5" indicating that the server
       authenticated with Kerberos, and in that case the identifier is
       the text form of a fully qualified Kerberos principal.

   sa (string)
       Subject authenticator type in an id token.  This is currently
       either krb5, indicating that a Kerberos authenticator is
       included, or webkdc, indicating no additional authenticator is
       provided.

   sad (binary)
       Subject authenticator data.  If the sa is krb5, this is a
       KRB_AP_REQ for the same Kerberos principal as the webkdc-service
       token's subject.

   san (string)
       The list of authentication factors used by the authenticated user
       for session authentication, or the session authentication factors
       that are required by this WAS for a successful authentication.
       This is a list of factor codes separated by commas.  For the list
       of registered factor names, see Section 5.3.

   sz (string)
       The authorization subject.  A user (if permitted by the WebKDC)
       may assert an authorization subject in addition to their
       authenticated identity.  If they do so, the subject (s) will
       continue to hold their authenticated identity, and this attribute
       will contain the asserted authorization identity.  The WAS may
       choose whether or not to honor the asserted authorization
       identity.

   t (string)
       The token type.  Currently recognized token types are webkdc-
       service, webkdc-proxy, req, error, id, proxy, cred, and app.
       Used by a server to ensure that a token is being used for the
       correct purpose.

   u (string)
       The user's username in a login token.



Schemers & Allbery      Expires February 2, 2015               [Page 39]

Internet-Draft       WebAuth Technical Specification         August 2014


   wt (binary)
       A webkdc-proxy or webkdc-service token that is being included
       inside another token.

5.3.  Authentication Factors

   The ia and san attributes contain a comma-separated list of
   authentication factors.  The following are the standardized factor
   names to use and their meaning.  All of these codes are valid for
   both initial authentication and session authentication factor lists
   except where noted.

   c (cookie)
       Only used for session authentication factors, this indicates that
       the user authenticated this session by presenting a cookie
       containing a webkdc-proxy token (rather than, for example,
       providing a password or other credentials).

   d (device)
       The device or browser from which the user authenticated is known
       to the local security infrastructure, has previously been part of
       a successful strong authentication, or otherwise is a relatively
       trusted device as defined by local site policy.

   h (human)
       The identity of the user has been additionally verified by a
       human.  This factor is normally not requested directly by a
       WebAuth Application Server, but rather is added via some site-
       specific mechanism by local support staff in order to synthesize
       a multifactor authentication.  For example, a user may have lost
       their hardware token but need to access a site that requires
       multifactor.  A WebKDC could support some mechanism to add this
       authentication factor and a multifactor factor to the user's next
       login after the user verifies their identity with local support
       staff via some off-line process and then goes through the login
       proces immediately.

   k (Kerberos)
       Only used for session authentication factors, this indicates that
       the user authenticated this session using a Kerberos
       authentication (generally via Negotiate-Auth, but possibly via
       other methods).

   m (multifactor)
       Multiple independent authentication factors were used.  The exact
       requirements for this are site-defined, but traditionally means
       password plus OTP, or password plus X.509, or an X.509
       authentication from a smart card requiring a PIN.



Schemers & Allbery      Expires February 2, 2015               [Page 40]

Internet-Draft       WebAuth Technical Specification         August 2014


   mp (mobile push)
       The user approved an out-of-band push notification to a mobile
       device as part of the authentication process.

   o (OTP)
       Some one-time password method was used for authentication.  This
       factor code is often used in combination with one of the o# codes
       defined below.

   o# (OTP)
       The one-time password method numbered # was used.  The meaning of
       the numbers is site-defined, but the numbers should be integers
       starting with 1 and higher numbers should indicate a stronger OTP
       method.  For example, o1 could indicate a printed list of OTP
       codes, o2 could indicate a code sent via SMS message, and o3
       could indicate a hardware device that is synchronized with the
       OTP server.

   p (password)
       Traditional password authentication.

   rm (random multifactor)
       The user was subject to a random chance of being challenged with
       a requirement for a multifactor authentication method and
       happened not to be challenged.  If the user had been challenged,
       either authentication would have failed or the m authentication
       factor would be used instead.  The chance of the challenge is
       site-defined.

   u (unknown)
       The authentication method is not known.  This may be used, for
       example, when the user authenticates to the WebLogin component of
       the WebKDC using some authentication mechanism handled external
       to the WebLogin server and no information about that method is
       available.

   v (voice)
       The user indicated approval of the authentication via a callback
       over voice telephone as part of the authentication process.

   x (X.509)
       Some form of X.509 authentication was used.  Whether this is via
       a smart card is site-defined.  This factor code is often used in
       combination with one of the x# codes defined below.

   x# (X.509)
       The X.509 authentication method numbered # was used.  The meaning
       of the numbers is site-defined, but the numbers should be



Schemers & Allbery      Expires February 2, 2015               [Page 41]

Internet-Draft       WebAuth Technical Specification         August 2014


       integers starting with 1 and higher numbers should indicate a
       stronger X.509 method.  For example, x1 could indicate an X.509
       certificate that may be stored on the file system of a user's
       system or on a removable drive, and x2 could indicate a hardware
       smart card.

   An authentication factor of m will always satisfy a requirement for
   an authentication factor of rm.

   Implementations may automatically add the m (multifactor) factor to
   the factors for an authentication if factors from more than one
   different authentication method are present (two or more from the set
   of h, mp, o, p, v, and x, for example).  If an implementation does
   this, the c, k, rm, and u factors must not be considered when
   deciding whether to add an m factor.

   Sites may define and use their own factor codes, but they risk
   conflict with future standardized codes unless they coordinate that
   use with this list.

5.4.  Specific Token Encoding

   The following sections describe which tokens are supported, what
   they're used for, and which attributes are included and what those
   attributes mean in that context.

5.4.1.  webkdc-service Token Encoding

   webkdc-service tokens are used by WAS servers to communicate with the
   WebKDC.  They are returned by WebKDC after an entity authenticates
   with the WebKDC using the XML interface while requesting a service
   token.

   Token format:

   t=webkdc-service
   k={session-key}
   s=krb5:{requesting-servers-k5-principal}
   ct={creation-time}
   et={expiration-time}

   All attributes are AES-encrypted using the WebKDC's private key.  The
   server that initially requested the token will also receive {session-
   key} and {expiration-time} out-of-band from the token itself.  That
   additional data must also be stored by the WAS for the duration of
   the token.





Schemers & Allbery      Expires February 2, 2015               [Page 42]

Internet-Draft       WebAuth Technical Specification         August 2014


5.4.2.  webkdc-proxy Token Encoding

   A webkdc-proxy token is a proxy authentication token maintained by
   the WebKDC on behalf of another user, or on behalf of itself.
   Normally it contains a Kerberos credential for the ticket-granting
   service (a Kerberos TGT plus its supporting data such as the session
   key).

   Token format:

   t=webkdc-proxy
   ps={subject-from-webkdc-service-token-used-to-get-proxy-token}
   pt=krb5|remuser|...
   s={username}
   [pd={proxy-data}]
   ct={creation-date}
   et={expiration-date}
   [ia={factor-list}]
   [loa={level-of-assurance}]

   All attributes are AES-encrypted using the WebKDC's private key.

   As a special case, krb5 webkdc-proxy tokens that the WebKDC obtains
   on behalf of itself (returned as part of a requestTokenRequest, for
   example) have a ps attribute value of WEBKDC:krb5:{server-principal}
   where {server-principal} is the Kerberos principal of the WebKDC.
   remuser webkdc-proxy tokens (created by WebLogin based on trusting
   REMOTE_USER authentication from the web server rather than via a
   password authentication or forwarded Kerberos ticket) have a ps
   attribute value of WEBKDC:remuser.

   When a webkdc-proxy-token is used in a <getTokensRequest> message,
   the WebKDC checks that the subject in the webkdc-service token
   accompanying the request is authorized to used the webkdc-proxy token
   granted to the ps subject.  When used in a <requestTokensRequest>,
   the WebKDC checks that the ps subject starts with "WEBKDC:".

5.4.3.  webkdc-factor Token Encoding

   A webkdc-factor token holds additional authentication factors that
   are combined with the factors established with webkdc-proxy tokens
   and login tokens.  A webkdc-factor token by itself is not sufficient
   to authenticate a user, but when combined with other tokens can
   contribute its factors to the authentication factors in resulting
   webkdc-proxy, id, and proxy tokens.

   The primary purpose of webkdc-factor tokens is to store additional
   factors that have a different lifetime than the user's authentication



Schemers & Allbery      Expires February 2, 2015               [Page 43]

Internet-Draft       WebAuth Technical Specification         August 2014


   credentials.  For example, one might store a webkdc-factor token as a
   long-lived cookie on a particular browser that has been vetted in
   some way and treat subsequent authentications where the browser can
   present that token as having an additional authentication factor
   compared to authentications from other browsers.

   webkdc-factor tokens are presented by WebLogin (which would normally
   get them from browser cookies) to the WebKDC as part of the
   <requestTokenRequest> message, and returned to WebLogin (to store as
   browser cookies) as part of the <requestTokenResponse> message.

   Token format:

   t=webkdc-factor
   s={username}
   ia={factor-list}
   ct={creation-date}
   et={expiration-date}

   All attributes are AES-encrypted using the WebKDC's private key.

   webkdc-factor tokens are only valid when presented in conjunction
   with at least one valid webkdc-proxy or login token for the same
   subject.  Its factors are added to both the initial and session
   factors of a successful authentication.

   Inside the WebKDC, multiple webkdc-factor tokens from different
   sources may be merged into a single token.  If this is done, the
   resulting token's creation and expiration dates should be set to the
   oldest creation and expiration dates of all the constituent tokens.
   In particular, the creation date of the resulting token should not be
   set to the time at which the tokens were merged.  This permits
   discarding all webkdc-factor tokens older than a particular date,
   which may be a useful operation if a particular user experienced a
   security compromise.

   webkdc-factor tokens will contribute their factors to any successful
   authentication until they have expired, even if the credentials that
   result from that authentication will persist beyond the expiration
   time of the webkdc-factor token.  For example, one can use a webkdc-
   factor token that expires in one minute as part of an authentication
   that results in a webkdc-proxy token that expires in ten hours, and
   the webkdc-factor token still contributes its factors.  The
   expiration time should therefore be thought of as the time at which
   the webkdc-factor token stops contributing factors to new
   authentications, not the time at which those authentication factors
   fully expire.




Schemers & Allbery      Expires February 2, 2015               [Page 44]

Internet-Draft       WebAuth Technical Specification         August 2014


5.4.4.  request Token Encoding

   A request token is sent to the WebKDC server by a WAS along with the
   WAS's webkdc-service token.  It is used to request tokens via the
   HTML interface, and is also used with the XML interface (in a
   restricted form) to allow the WebKDC to verify that a request being
   made with a webkdc-service token is both recent and for the specified
   command.

   The first form is used with the requestTokenRequest command:

   t=req
   ct={creation-time}
   [as={binary-state-data}]
   ru={return-redirect-url}
   [ro=fa,lc]
   rtt=id|proxy
   # for rt=id
   sa=krb5|webkdc
   # for rt=proxy
   pt=krb5
   [ia={factor-list}]
   [san={factor-list}]
   [loa={level-of-assurance}]

   The second form is used with the getTokensRequest command in the XML
   interface:

   t=req
   ct={creation-time}
   cmd={xml-command-we-are-going-to-execute}

   All attributes are AES-encrypted using the webkdc-service token
   session key.

   The value of ct is used to prevent replay attacks.  Values older than
   a certain time (probably 5 minutes by default) should be rejected as
   a replay.

   cmd indicates which XML command we are invoking (for example,
   getTokensRequest).  The WebKDC will compare this command against the
   name of the command in the XML, thereby verifying the unencrypted XML
   request.

5.4.5.  error Token Encoding






Schemers & Allbery      Expires February 2, 2015               [Page 45]

Internet-Draft       WebAuth Technical Specification         August 2014


   An error token is sent from the WebKDC as a response to a request
   token when an error occurs.  It may be returned to the WAS as the
   response token if the user canceled login.

   Token format:

   t=error
   ct={creation-time}
   ec={error-code}
   em={error-message}

   All attributes are AES-encrypted using the webkdc-service token
   session key.

   The value of ct is used to prevent replay attacks.  Values older than
   a certain time (probably 5 minutes by default) should be rejected as
   a replay.

5.4.6.  id Token Encoding

   The id token is returned by the WebKDC and is bound to an WAS.  It is
   used to communicate the authenticated identity of a user.

   Token format:

   t=id
   sa=krb5|webkdc
   # for sa=webkdc
   s={username}
   # for sa=krb5
   sad={result-of-krb5-mk-req-for-webauth/hostname}
   # for any sa
   [sz={authorization-subject}]
   ct={creation-time}
   et={expiration-time}
   [ia={factor-list}]
   [san={factor-list}]
   [loa={level-of-assurance}]

   All attributes are AES-encrypted using the webkdc-service token
   session key.

   If "at" is krb5, then "sad" (subject authenticator data) is a
   KRB_AP_REQ for the WAS service principal (as determined from the
   subject of the webkdc-service token) using the user's TGT from a krb5
   webkdc-proxy token.





Schemers & Allbery      Expires February 2, 2015               [Page 46]

Internet-Draft       WebAuth Technical Specification         August 2014


   If at is webkdc, we are trusting the webkdc and "s" contains the
   authenticated user's identity (generally as a Kerberos principal name
   in text form).

   The value of ct is used to prevent replay attacks.  Values older than
   a certain time (probably 5 minutes by default) should be rejected as
   a replay, as id tokens are only used once and re-written into an app
   token.

   The value of et is used to let the application know how long the
   authentication information in the id token should be considered valid
   for.  The value for et is at latest the expiration time of the proxy-
   token used to create it.

5.4.7.  proxy Token Encoding

   A proxy token is returned by the WebKDC when a WAS requests a proxy
   token from the WebKDC via the HTML interface.  Normally, the WAS just
   requests an id token directly, but if the WAS may need cred tokens
   for a user, it requests a proxy token instead.  The proxy token can
   be later used to retrieve an id or cred token from the WebKDC.

   Token format:

   t=proxy
   pt=krb5|...
   s={username}
   [sz={authorization-subject}]
   wt={webkdc-proxy-token}
   ct={creation-time}
   et={expiration-time}
   [ia={factor-list}]
   [san={factor-list}]
   [loa={level-of-assurance}]

   All attributes are AES-encrypted using the webkdc-service token
   session key.

   In addition to the webkdc-proxy token, a proxy token provides all the
   same authentication information about a user as an id token with a
   subject auth of "webkdc".  If the WAS only needs id token information
   at the level provided by the "webkdc" subject auth type, it can use
   the proxy token for that information without requesting an id token.
   If it wants an id token with a "krb5" subject auth type, it will have
   to request that from the WebKDC using the proxy token.

   The value of ct is used to prevent replay attacks.  Values older then
   a certain time (probably 5 minutes by default) should be rejected as



Schemers & Allbery      Expires February 2, 2015               [Page 47]

Internet-Draft       WebAuth Technical Specification         August 2014


   a replay, as proxy tokens are only used once and re-written into an
   app token.

   wt is the webkdc-proxy token (in binary form).  It can be used by the
   WAS later to request credential tokens from the WebKDC.

   Note that the authorization subject included in the proxy token will
   not be reflected in any id tokens obtained via the proxy token.  The
   id tokens will be based on the webkdc-proxy token, which is for the
   authentication identity alone.  Therefore, a WebAuth Application
   Server that wants to use the authorization identity in some way needs
   to note the authorization subject from the proxy token and not rely
   on getting it from any subsequent id token.  Similarly, any cred
   tokens obtained from a proxy token will be for the authentication
   identity, not the authorization identity.

5.4.8.  credential Token Encoding

   A credential token is an authentication credential for the user for
   some other service, used by the WAS for proxied authentication.  It
   is normally a Kerberos service ticket generated by the WebKDC from
   the user's TGT.

   Token format:

   t=cred
   crs={server-principal}
   crt=krb5|...
   s={username}
   cd={credential-data}
   ct={creation-date}
   et={expiration-date}

   All attributes are AES-encrypted using the webkdc-service token
   session key.

5.4.9.  login Token Encoding

   A login token is used by the WebLogin component of the WebKDC to
   communicate an authentication request to the WebKDC.  This always
   contains a username, and may contain a password, one-time password
   (OTP), or device identifier to use for authetnication.

   Token format:







Schemers & Allbery      Expires February 2, 2015               [Page 48]

Internet-Draft       WebAuth Technical Specification         August 2014


   t=login
   ct={creation-time}
   u={username}
   [p={password}]
   [otp={one-time-password-code}]
   [ott={one-time-password-factor}]
   [did={device-id}]

   All attributes are AES-encrypted using the WebKDC's private key.  One
   of p, otp, or did must be provided.  If otp is provided, did and ott
   may also be provided (but are not required by the WebAuth protocol,
   although they may be required by local site configuration).  did
   should be a device ID chosen from the device attributes of
   <configuredFactor> tags in the <requestTokenResponse> reply.  ott
   should be a factor code (generally one of the oN factors) indicating
   what type of OTP this code is for, or a factor code indicating what
   type of authentication to attempt with this device.

5.4.10.  app Token Encoding

   An app token is controlled and maintained by a WAS.  The main use of
   an app token is to cache the idenity within an id token after it has
   been verified.

   Token format:

   t=app
   et={expiration-time}
   [ct={creation-time}]
   [s={username}]
   [sz={authorization-subject}]
   [k=session-key]
   [lt={last-use-time}]
   [ia={factor-list}]
   [san={factor-list}]
   [loa={level-of-assurance}]

   All attributes are AES-encrypted using the WAS's private key.

   app tokens are normally created on first receipt of an id token.
   After the id token is verified, it is converted into an app token and
   then stored in a cookie.

   {last-use-time} is optional and should only be included if the WAS
   wishes to invalidate idle but unexpired app tokens.

   {session-key} is only present when an app token is being used as the
   application state inside of a request token.  This is done when



Schemers & Allbery      Expires February 2, 2015               [Page 49]

Internet-Draft       WebAuth Technical Specification         August 2014


   serving the same web resource with a pool of servers that all should
   be able to decrypt the id token from the WebKDC.

5.5.  Kerberos Credential Encoding

   Kerberos credentials may be included in several types of WebAuth
   tokens.  Whenever this is done, the credential data is encoded using
   the same basic encoding format as a token, and the system receiving
   the credential must decode it and recreate the Kerberos credential
   structure to use it.  This allows interoperability between different
   platforms and different Kerberos implementations.

   The credential encoding uses the following attributes, where binary
   number is a 32-bit number in network byte order and binary time is a
   32-bit time in seconds since 1970-01-01 00:00:00 UTC:

   c (string)
       Client principal name.

   s (string)
       Server principal name.

   K (binary number)
       Kerberos encryption type for the session key.  This will be
       whatever numerical constant is used by Kerberos for that
       encryption type.

   k (binary)
       Kerberos session key.

   ta (binary time)
       Authentication time of the credential.

   ts (binary time)
       Start time of the credential (the time at which the credential
       becomes valid).

   te (binary time)
       Expiration time of the credential, after which it is no longer
       valid.

   tr (binary time)
       Renewal end time of the credential.  The credential may be
       renewed up until this time.

   i (binary)





Schemers & Allbery      Expires February 2, 2015               [Page 50]

Internet-Draft       WebAuth Technical Specification         August 2014


       Flag set to 0 or 1 indicating whether the credential was obtained
       via S/Key.  This attribute should probably always be 0 or not
       provided; it is not supported at all by Heimdal.

   f (binary number)
       The ticket flags.  This is a 32-bit bitmask of Kerberos ticket
       flags, as defined by the Kerberos protocol specification.

   na (binary number)
       The number of addresses associated with the credential.  Address
       checking on credentials is generally not useful for WebAuth, so
       it might be best to always skip including this in the credential,
       but space is provided in case it's useful for some reason.  For
       each address, there is a corresponding "A" attribute holding the
       address type and an "a" attribute holding the address itself.

   A# (binary number)
       The type of address for the #th address.  # is replaced by the
       index number of the address.  Addresses are numbered starting
       with 0, so if na was 2, there will be an A0 attribute and an A1
       attribute (but no A2 attribute).

   a# (binary)
       The #th address in the credential.  # is replaced by the index
       number of the address.  Addresses are numbered starting with 0,
       so if na was 2, there will be an a0 attribute and an a1 attribute
       (but no a2 attribute).

   t (binary)
       The Kerberos ticket.

   t2 (binary)
       The second Kerberos ticket in the credentials, if any.

   nd (binary number)
       The number of authenticatation data blocks in the credential.
       For each data block, there is a corresponding "D" attribute
       holding the data type and a "d" attribute holding the data block
       itself.

   D# (binary number)
       The type of authentication data for the #th data block.  # is
       replaced by the index number of the data block.  Data blocks are
       numbered starting with 0, so if nd was 2, there will be a D0
       attribute and a D1 attribute (but no D2 attribute).

   d# (binary number)




Schemers & Allbery      Expires February 2, 2015               [Page 51]

Internet-Draft       WebAuth Technical Specification         August 2014


       The #th authentication data block.  # is replaced by the index
       number of the block.  Data blocks are numbered starting with 0,
       so if nd was 2, there will be a d0 attribute and a d1 attribute
       (but no d2 attribute).

6.  Cookie Formats

   Cookies are used to hold tokens in a UA for future use.  All cookies
   MUST be scoped to a single server; there are no domain-wide cookies.
   All cookies will be encoded in base64 before passing them to the UA.

   The tokens that are put in cookies are webkdc-proxy, proxy, app, and
   cred tokens.  The following naming convention will be used to name
   cookies.

   Note that proxy tokens and credential tokens are originally encrypted
   with the webkdc-service token session key, but are re-encrypted using
   the WAS private key before being stored in a cookie.

   app token cookies will be named webauth_at.

   webkdc-proxy token cookies will be named webauth_wpt_{type} where
   {type} is the type of the webkdc-proxy token (usually krb5).

   webkdc-factor token cookies will be named webkdc_wft.  This means
   that only a single factor token cookie can be set within a particular
   browser.  If there are multiple sources of factors that should be
   stored in webkdc-factor tokens, they must be merged into a single
   token by the WebKDC.

   proxy token cookies will be named webauth_pt_{type} where {type} is
   the type of the proxy token (usually krb5).

   credential tokens will be named webauth_ct_{type}_{service} where
   {type} is the type of the credential token (usually krb5) and
   {service} is the krb5 service name, potentially with special
   characters escaped.

7.  References

Appendix A.  Document Revision History

   1.01 (2002-12-12, schemers)
       Keys in the keyring no longer expire.  The key with the most
       current (but not post-dated) valid_after will always be used to
       encrypt new keys.

   1.02 (2003-01-14, schemers)



Schemers & Allbery      Expires February 2, 2015               [Page 52]

Internet-Draft       WebAuth Technical Specification         August 2014


       Return <subject> in <requestToken> response so the web front-end
       can display the authenticated username.

   1.03 (2003-01-20, schemers)
       Fix type in credential token coding example: change ct to crt.
       Add crs attribute to credential token.

   1.04 (2003-01-29, schemers)
       When appending WEBAUTHR to return URL, use "?WEBAUTHR=...;"
       instead of ";WEBAUTHR=...;" so browers handle relative URLs
       correctly.

   1.05 (2003-07-24, schemers)
       Add webkdcProxyToken and webkdcProxyTokenInfo commands.  Added
       requestInfo to requestToken command for S/Ident support.

   2.0.0 (2006-01-02, rra)
       Rewritten in XML and substantially edited, clarified, and
       reworked.  Added <remoteUser> to <requestInfo> and clarified that
       <requestInfo> must be used only for logging and auditing now that
       we're not trying to do S/Ident any more.  Don't assume Kerberos
       in the first descriptions of protocol elements.  Add text
       explaining why one may not have a webkdc-proxy token with other
       forms of authentication.

   2.0.1 (2006-01-23, rra)
       Move the document history into an appendix.  Document the magic
       WEBKDC prefix to proxy subjects.

   2.1.0 (2006-02-17, rra)
       Add a specification for the encoding of Kerberos credentials in
       tokens.  Specify the size of timestamps.

   2.1.1 (2008-03-14, rra)
       Add error code 18, indicating that the WebKDC did not permit the
       user's principal to authenticate.  Fix typo in the
       webkdcProxyTokenInfoRequest example.  Fix XML formatting issues.

   2.1.2 (2009-06-24, rra)
       Add requestedTokenType to the XML returned in response to
       <requestToken> so that the WebLogin component can make decisions
       based on whether the WAS requested an id token or a proxy token.

   2.1.3 (2010-05-15, rra)
       Replace all mentions of krb5_mk_req with KRB_AP_REQ, which is the
       correct protocol term for the results of a krb5_mk_req call.

   3.0.0 (2011-07-22, rra)



Schemers & Allbery      Expires February 2, 2015               [Page 53]

Internet-Draft       WebAuth Technical Specification         August 2014


       Add ia, san, and loa attributes to various tokens to store
       authentication factor information and level of assurance.
       Document the factor codes for authentication factors.  Remove
       <messageId> and <protocolVersion> from the XML specification;
       neither were ever implemented.  Add additional error codes for
       multifactor and Level of Assurance support.  Add
       <multifactorRequired> and <loginHistory> to
       <requestTokenResponse> and the otp attribute to the login token.
       Remove the type attribute to <subjectCredential> and change the
       protocol to allow both <proxyToken> and <loginToken> to be sent
       in the same request.  Add the type attribute to <proxyToken>.
       Include source factor information in <proxyToken> elements sent
       to the WebKDC, used to derive session factor information.

   3.1.0 (2011-09-21, rra)
       Change the <loginHistory> XML schema to have the content of
       <loginLocation be the IP address.  The hostname is now an
       optional attribute.

   3.2.0 (2012-07-17, rra)
       Add error code 24, representing a rejected authentication, and
       add optional element <userMessage> to <requestTokenResponse>.

   3.2.1 (2012-09-07, rra)
       Clarify references to a "Kerberos TGT", which normally mean a
       Kerberos credential that includes the TGT plus other supporting
       data such as the session key.  Replace remaining K5 references
       with just Kerberos.

   3.3.0 (2012-11-20, rra)
       Add <authzSubject> to <requestTokenRequest> and
       <requestTokenResponse> to allow requesting and returning
       authorization identities.  Add <permittedAuthzSubjects> to
       <requestTokenResponse> to tell WebLogin what authorization
       identities the user may assert.  Add the sz attribute to app, id,
       and proxy tokens to hold the asserted authorization identity.
       Clarify that attribute names are alphanumeric.

   3.3.1 (2012-12-06, rra)
       Add error code 25, representing an authentication that appears to
       be a replay, and error code 26, indicating a rejected
       authentication due to too many failed authentication attempts for
       this user.

   3.4.0 (2013-02-04, rra)
       Add the webkdc-factor token type, the <factorToken> element to
       the <requestTokenRequest> API, <factorTokens> element to the
       <requestTokenResponse> API, and the d factor.



Schemers & Allbery      Expires February 2, 2015               [Page 54]

Internet-Draft       WebAuth Technical Specification         August 2014


   3.5.0 (2013-04-02, rra)
       Clarify the two cases for a <getTokenRequest> and remove the
       ability to request proxy tokens.  Clarify the proxy subject
       checking in the webkdc-proxy token encoding description.  Include
       the expiration time of a factor token in the
       <requestTokenResponse> response as an attribute on the
       <factorToken> element.  Clarify that the webkdc-factor expiration
       time reflects when it stops contributing factors to new
       authentications, not when those factors go away entirely.  Add
       the ott attribute to the login token, which conveys the type of
       OTP that the code is for.  Add the h factor.  Clarify that error
       code 14 can be used for a wide variety of login failures.
       Clarify differences between error codes 22, 24, and 26.

   3.5.1 (2013-09-26, rra)
       Be explicit that token encryption is 128-bit AES in CBC mode.

   3.5.2 (2013-11-09, rra)
       Document the IV used for token encryption and be explicit about
       the security requirements for nonces and key rotation.

   3.6.0 (2014-07-10, rra)
       Add attributes for <configuredFactor> tags in
       <requestTokenResponse> to provide WebLogin with more information
       about possible factors.  Add the did token attribute to login
       tokens to communicate the ID of the device with which the user is
       attempting to authenticate.  Add new mp and v factor codes.
       Wording and grammar clarifications, thanks to Adam Lewenberg.

   3.6.1 (2014-08-13, rra)
       Add new elements <defaultFactor> and <devices> in
       <requestTokenResponse> to provide WebLogin with more information
       about possible factors and authentication methods.  Remove the
       attributes for <configuredFactor> tags, since that approach was
       less flexible.

   3.7.0 (2014-09-18, jonrober)
       Add error code 27, representing a remctl timeout during
       multifactor login.

Appendix B.  License

   Copyright 2006, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The Board of
   Trustees of the Leland Stanford Junior University







Schemers & Allbery      Expires February 2, 2015               [Page 55]

Internet-Draft       WebAuth Technical Specification         August 2014


   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.

Authors' Addresses

   Roland Schemers
   Stanford University


   Russ Allbery
   Stanford University

   Email: eagle@eyrie.org
   URI:   http://www.eyrie.org/~eagle/



































Schemers & Allbery      Expires February 2, 2015               [Page 56]