Skip to end of metadata
Go to start of metadata

Available:

JIRA 4.1 and later.

 

On this page:

Overview and Purpose

JIRA 4.1 and later employs a token authentication mechanism which is utilised whenever JIRA actions are performed either through link request or form submission. This provides JIRA with a 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 JIRA 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 provides instructions to JIRA plugin developers on how to incorporate this token handling mechanism into JIRA plugins.

Form Tokens

JIRA 4.1 requires that WebWork actions possess tokens, which are then verified when the form is submitted back to the JIRA server. This is an "opt in" mechanism, whereby actions must declare that they require a token to be present in the request.

Instructions for Plugin Developers

The following subsections provide details on how to protect code against XSRF by implement form token handling into your JIRA plugin.

Please be aware that once form token handling has been implemented into a JIRA plugin:

  • Any functions that use screen scraping, such as the 'create sub-task' function in FishEye, will be broken.
  • REST API end points will not be affected unless they use form encoding.

JIRA WebWork Actions

To enable xsrf token checking for a particular Action class

  1. Locate the method that is called by the action execution (by default this method is called doExecute())
  2. Add the @com.atlassian.jira.security.xsrf.RequiresXsrfCheck annotation to this method

Providing the token in HTML Forms

The token is included by default when using a jiraform

The token can be included into your own JSPs that don't use jiraforms, by adding the following code:

The following code can be added to Velocity Templates:

You can do the following in JSPs:

or Velocity Templates:

Accessing the token programatically

To get hold of the current user's token, you will need to make the following call:

Scripting

Scripts that access JIRA 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:

RELATED TOPICS

XSRF protection in Confluence.

For more information, refer to the Open Web Application Security Project page.

3 Comments

  1. Hi, I am trying to create a link via a URL with Form Token checking enabled.

    However, when I use wget to try and create an issue via a URL it complains about not having the token.

    How can i create an issue via an URL with Form Token checking enabled?

    Thanks,

    Kevin

    1. The info is right there... Referring to the docs will help. I'd expect the following to do what you need...

      You have two choices,

      1. Command line
        wget --header "X-Atlassian-Token: no-check"
        
      2. config file .wgetrc
        header = X-Atlassian-Token: no-check
        
      1. While I used this successfully in the past, it seems that when running against Jira-standalone from the SDK the special header has no effect, JIRA 6.1.5 rejecting the request with the "XSRF Security Token Missing". Any ideas?