Confluence Docs 3.0 : Form Token Handling
This page last changed on Jul 30, 2009 by ggaskell.
Overview and PurposeConfluence 3.0 employs a new token authentication mechanism that is utilised when Confluence actions are performed either through link request or form submission. This provides Confluence with the means to validate the origin and intent of the request, thus adding an additional level of security against cross-site request forgery. While the core Confluence product and its bundled plugins use this token handling mechanism by default, non-bundled plugins or those developed by third parties may not. This document is intended for Confluence plugin developers. It provides instructions on how these developers can add this token handling mechanism to their own plugins. Developers should pay particular attention to the Timeline section, as unmodified plugins may no longer function correctly after the cut-off date. This change affects:
Form TokensConfluence 3.0 requires that WebWork actions possess tokens, which are then verified when the form is submitted back to the Confluence server. This is an "opt in" mechanism, whereby actions must declare that they require a token to be present in the request. However, in a future version of Confluence, the security policy will switch to a more stringent "opt out" system, where actions must declare that they do not require a token. At this point, any plugin that accepts form submissions and has not been upgraded to use this token authentication mechanism will cease to function. Instructions for Plugin DevelopersConfiguring XWork ActionsThere are two mechanisms for providing a Form Token configuration for an XWork action:
We recommend developers use the atlassian-plugins.xml approach, as it will allow their plugins to be backwards-compatible with older versions of Confluence. Providing the token in HTML FormsThe Velocity macro #form_xsrfToken() will insert the following into your form: <input type="hidden" name="atl_token" value="[the user's token]"> Providing the token in HTML linksThe Velocity macro #url_xsrfToken() expands to: atl_token=[the user's token] So you can do the following <a href="myaction.action?activate=true&#url_xsrfToken()">Activate</a> Providing the token in AJAX callsThe Atlassian Javascript Library (AJS) contains a method that will add the security token to an AJAX callback. In order to make this method available, you should place the following call in your Velocity template: #requireResource("confluence.web.resources:safe-ajax") This library provides wrappers around JQuery AJAX functions that will include the form token in the AJAX submission. If you are not using the JQuery AJAX functions, you should first update your code to use them directly, then to use the safe version. The following functions are provided: AJS.safe.ajax() AJS.safe.get() AJS.safe.post() AJS.safe.getScript() AJS.safe.getJSON() Accessing the token programaticallyTo get hold of the current user's token, you will need to make the following call: new com.atlassian.xwork.SimpleXsrfTokenGenerator().generateToken(httpServletRequest) For best long-term compatibility, you should retrieve the name of the form parameter to set from the token generator rather than using the literal string "atl_token". For example: HttpServletRequest req = ServletActionContext.getRequest(); if (req != null) { XsrfTokenGenerator tokenGenerator = new SimpleXsrfTokenGenerator(); myWebRequest.addParameter(tokenGenerator.getXsrfTokenName(), tokenGenerator.generateToken(req)) // or: myRequestUrl.append("&" + tokenGenerator.getXsrfTokenName() + "=" + tokenGenerator.generateToken(req)); } else { // We are not in a web context. Handle this error cleanly. } ScriptingScripts that access Confluence remotely may have trouble acquiring or returning a security token, or maintaining an HTTP session with the server. There is a way for scripts to opt out of token checking by providing the following HTTP header in the request: X-Atlassian-Token: no-check TimelineConfluence 3.0
The Future
RELATED TOPICSFor more information, refer to the Open Web Application Security Project page. |
![]() |
Document generated by Confluence on Nov 05, 2009 23:34 |