R. Schemers
R. Allbery
Stanford University
July 23, 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.


Table of Contents

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)

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.

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

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:

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.

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

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.

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

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

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

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

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.
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.
26
This authentication was rejected due to too many failed authentication attempts for this user. The authentication should be retried later.

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>

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:

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

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:

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

    <!-- 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 -->
      <!-- name is intended for display to the user in a list -->
      <!-- device is included in login token -->
      <!-- prompt indicates the user must be prompted for an OTP,
           may be omitted if set to true (the default) -->
      <!-- default indicates whether this should be the default
           mechanism, may be omitted if set to false -->
      <!-- the same {factor-code} may occur multiple times -->
      <configuredFactor name="{method-name}"
          device="{device-id}"
          prompt="false"
          default="true">{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" -->
    </multifactorRequired>

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

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

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:

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

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

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

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

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

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

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.

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

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

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)

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.

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)

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)

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

Appendix B. License

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

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

Authors' Addresses

Roland Schemers Stanford University
Russ Allbery Stanford University 255 Panama Street, MC 4136 Stanford, CA 94305-4136 US EMail: eagle@eyrie.org URI: http://www.eyrie.org/~eagle/