Last updated May 10, 2022

Rate this page:

Enable XSRF protection in your app

AvailabilityConfluence 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.

Configure XWork actions

There are two mechanisms for protecting an XWork action against XSRF through Form Token configuration:

Configuration Location

Steps Required

In the Action class

  1. Locate the method that is called by the action execution (by default this method is called execute())
  2. Add the @com.atlassian.xwork.RequireSecurityToken annotation to this method: @ RequireSecurityToken(true) if the method will require a token, or @ RequireSecurityToken(false) if it will not.
  3. Ensure that your action uses <interceptor-ref name="validatingStack"/> in its <package> definition and has an "input" result - which will be used on token failure.

In atlassian-plugins.xml

  1. Locate the action definition (the <action> element in your <xwork> plugin module)
  2. Add <param name="RequireSecurityToken">true</param> if you wish the action execution to require a token, or change its value to false if it does not.
  3. Ensure that your action uses <interceptor-ref name="validatingStack"/> in its <package> definition and has an "input" result - which will be used on token failure.

We recommend you use the atlassian-plugins.xml approach, as it will allow your apps to be backwards-compatible with older versions of Confluence.

Configure servlets

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>

Example

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>

Provide the token

The way you provide the token depends on how the request is made.

Safe methods must be idempotent

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.

Provide the token in HTML Forms

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]">

Provide the token in AJAX calls

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
2
AJS.safe.ajax()
AJS.safe.post()

Provide the token in AJAX calls directly

To provide the token in AJAX calls directly:

1
2
AJS.Meta.get("atl-token")
Meta.get("atl-token")

Access the token programmatically

To get the current user's token, make the following call:

1
2
new 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
2
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.
}

Bypass token check in scripts

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
2
X-Atlassian-Token: no-check

Future changes

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: