Rate this page:
Available: | Confluence 3.0 and later. |
Overview and Purpose
Confluence 3.0 and later 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 XSRF (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, as unmodified plugins may no longer function correctly after the cut-off date.
This change affects:
Confluence 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 xsrf 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.
There are two mechanisms for protecting an XWork action against XSRF through Form Token configuration:
Configuration Location | Steps Required |
---|---|
In the Action class |
|
In |
|
We recommend developers use the atlassian-plugins.xml
approach, as it will allow their plugins to be backwards-compatible with older versions of Confluence.
The Velocity macro #form_xsrfToken()
will insert the following into your form:
1
<input type="hidden" name="atl_token" value="[the user's token]">
The Velocity macro #url_xsrfToken()
expands to:
1
atl_token=[the user's token]
So you can do the following
1
<a href="myaction.action?activate=true&#url_xsrfToken()">Activate</a>
The 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:
1
#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:
1 2 3 4 5
AJS.safe.ajax()
AJS.safe.get()
AJS.safe.post()
AJS.safe.getScript()
AJS.safe.getJSON()
To get hold of the current user's token, you will need to make the following call:
1
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:
1 2 3 4 5 6 7 8 9 10 11
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.
}
Scripts 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:
1
X-Atlassian-Token: no-check
For more information, refer to the Open Web Application Security Project page.
Rate this page: