Rate this page:
Availability | Confluence 3.0 or later |
This page demonstrates how to protect your app’s XWork actions and servlets from cross-site request forgery (XSRF) attacks (also known as CSRF attacks).
An XSRF token is a unique, secret, unpredictable value that is generated by the server-side application and transmitted to the client in such a way that it’s included in a subsequent HTTP request made by the client.
XSRF protection is an opt-in feature for apps. The Confluence application and bundled apps use this token handling mechanism by default, but non-bundled apps and those developed by third parties need to opt-in.
There are two mechanisms for protecting an XWork action against XSRF through Form Token configuration:
Configuration Location | Steps Required |
---|---|
In the |
|
In |
|
We recommend you use the atlassian-plugins.xml
approach, as it will allow your apps to be backwards-compatible with older versions of Confluence.
To enable servlet XSRF protection add an init parameter in atlassian-plugin.xml
under the servlet tag:
1 2<init-param> <param-name>RequireSecurityToken</param-name> <param-value>true</param-value> </init-param>
Here’s an example atlassian-plugin.xml
file containing a single servlet with XSRF protection enabled:
1 2<atlassian-plugin name="Hello World Servlet" key="example.plugin.helloworld" plugins-version="2"> <plugin-info> <description>A basic Servlet module test - says "Hello World!</description> <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/> <version>1.0</version> </plugin-info> <servlet name="Hello World Servlet" key="helloWorld" class="com.example.myplugins.helloworld.HelloWorldServlet"> <description>Says Hello World, Australia or your name.</description> <url-pattern>/helloworld</url-pattern> <init-param> <param-name>RequireSecurityToken</param-name> <param-value>true</param-value> </init-param> </servlet> </atlassian-plugin>
The way you provide the token depends on how the request is made.
In order for either XWork action or servlet XSRF protection to work, apps must ensure that "safe" HTTP methods are idempotent. This means that requests with the HTTP method GET
, HEAD
, OPTIONS
, and TRACE
should not change the state of the application.
The Velocity macro #form_xsrfToken()
will insert the following into your form:
1 2<input type="hidden" name="atl_token" value="[the user's token]">
The Atlassian Javascript Library (AJS) contains a method that will add the security token to an AJAX callback. To make this method available, place the following call in your Velocity template:
1 2#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’re not using the JQuery AJAX functions, you should first update your code to use them directly, then use the safe version. The following functions are provided:
1 2AJS.safe.ajax() AJS.safe.post()
To provide the token in AJAX calls directly:
1 2AJS.Meta.get("atl-token") Meta.get("atl-token")
To get the current user's token, make the following call:
1 2new com.atlassian.xwork.SimpleXsrfTokenGenerator().generateToken(httpServletRequest)
For the 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 2HttpServletRequest 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 used to access Confluence remotely may have trouble acquiring or returning a security token or maintaining an HTTP session with the server. To opt-out of token checking, include the following HTTP header in the request:
1 2X-Atlassian-Token: no-check
We plan to change to a stricter opt-out protection in the future. At this point, apps that have not been updated to use form tokens may cease to function.
We’ll provide plenty of information on the changes and timing in advance, to give you time to test your app.
Rate this page: