| R. Schemers | |
| R. Allbery | |
| Stanford University | |
| August 1, 2014 |
WebAuth Technical Specification
draft-allbery-webauth-00
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.
The WebAuth protocol involves interactions between three basic 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.
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.
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.
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.
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:
Their exact formats are discussed in detail at the end of this document.
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:
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.
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:
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.
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.
There are five basic scenarios in the WebAuth protocol.
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.
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.
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
---------------------------------------------------------------
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.
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.
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.
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.
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.
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.
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.
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>
The following elements are common to all commands.
This is a numeric error code for an errorResponse message. It MUST be one of the following:
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.
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.
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.
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 -->
<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>
<!-- 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>:
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.
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.
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.
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.
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>
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.
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.
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.
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.
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.
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.
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.
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:".
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.