org.jboss.seam.ui.component
Class UIToken

java.lang.Object
  javax.faces.component.UIComponent
      javax.faces.component.UIComponentBase
          javax.faces.component.UIOutput
              org.jboss.seam.ui.component.UIToken

All Implemented Interfaces:

javax.faces.component.StateHolder, javax.faces.component.ValueHolder

public abstract class UIToken
extends javax.faces.component.UIOutput

UIToken is a UIComponent that produces a random token that is inserted into a hidden form field to help to secure JSF form posts against cross-site request forgery (XSRF) attacks. This is an adaptation of the recommendation called Keyed‐Hashing for Message Authentication that is referenced in the Cross Site Reference Forgery by Jesse Burns (http://www.isecpartners.com/files/XSRF_Paper_0.pdf)

When placed inside a form, this component will first assign a unique identifier to the browser using a cookie that lives until the end of the browser session. This is roughly the browser's private key. Then a unique token is generated using various pieces of information that comprise the form's signature. The token may or may not be bound to the session id, as indicated by the value of the requireSession attribute. The token value is stored in the hidden form field named javax.faces.FormSignature.

There is an assumption when using this component that the browser supports cookies. Cookies are the only universally available persistent mechanism that can give the browser an identifiable signature. It's important to know that the browser submitting the form is the same browser that is requesting the form.

During the decode process, the token is generated using the same algorithm that was used during rendering and compared with the value of the request parameter javax.faces.FormSignature. If the same token value can be produced, then the form submission is permitted. Otherwise, an UnauthorizedCommandException is thrown indicating the reason for the failure.

The UIToken can be combined with client-side state saving or the "build before restore" strategy to unbind a POST from the session that created the view without sacrificing security. However, it's still the most secure to require the view state to be present in the session (JSF 1.2 server-side state saving).

Please note that this solution isn't a complete panacea. If your site is vulnerable to XSS or the connection to wire-tapping, then the unique browser identifier can be revealed and a request forged.

Author:

Dan Allen

Field Summary

Fields inherited from class javax.faces.component.UIComponent

bindings

Constructor Summary

UIToken()

Method Summary

java.lang.String	getClientUid()
ClientUidSelector	getClientUidSelector() Return the selector that controls the unique browser identifier cookie.
javax.faces.component.UIForm	getParentForm()
abstract boolean	isAllowMultiplePosts() Indicates whether to allow the same form to be submitted multiple times with the same signature (as long as the view does not change).
abstract boolean	isEnableCookieNotice() Indicates whether a JavaScript check should be inserted into the page to verify that cookies are enabled in the browser.
abstract boolean	isRequireSession() Indicates whether the session id should be included in the form signature, hence binding the token to the session.
abstract void	setAllowMultiplePosts(boolean allow)
abstract void	setEnableCookieNotice(boolean state)
abstract void	setRequireSession(boolean required)

Methods inherited from class javax.faces.component.UIOutput

getConverter, getFamily, getLocalValue, getValue, restoreState, saveState, setConverter, setValue

Methods inherited from class javax.faces.component.UIComponentBase

addFacesListener, broadcast, decode, encodeBegin, encodeEnd, encodeChildren, findComponent, getAttributes, getClientId, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getChildCount, getChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding

Methods inherited from class javax.faces.component.UIComponent

encodeAll, getContainerClientId, getValueExpression, setValueExpression

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UIToken

public UIToken()

Method Detail

isRequireSession

public abstract boolean isRequireSession()

Indicates whether the session id should be included in the form signature, hence binding the token to the session. This value can be set to false if the "build before restore" mode of Facelets is activated (the default in JSF 2.0). The default value is false.

setRequireSession

public abstract void setRequireSession(boolean required)

isEnableCookieNotice

public abstract boolean isEnableCookieNotice()

Indicates whether a JavaScript check should be inserted into the page to verify that cookies are enabled in the browser. If cookies are not enabled, present a notice to the user that form posts will not work. The default value is false.

setEnableCookieNotice

public abstract void setEnableCookieNotice(boolean state)

isAllowMultiplePosts

public abstract boolean isAllowMultiplePosts()

Indicates whether to allow the same form to be submitted multiple times with the same signature (as long as the view does not change). This is a common need if the form is perform Ajax calls but not rerendering itself or, at the very least, the UIToken component. The preferred approach is to have the UIToken component rerendered on any Ajax call where the UIToken component would be processed. The default value is false.

setAllowMultiplePosts

public abstract void setAllowMultiplePosts(boolean allow)

getClientUidSelector

public ClientUidSelector getClientUidSelector()

Return the selector that controls the unique browser identifier cookie.

getClientUid

public java.lang.String getClientUid()

getParentForm

public javax.faces.component.UIForm getParentForm()