Overview

XSF protection is a new feature of 2.8 that guards against cross-site request forgery, and thereby makes the service much more secure.

Here are the aspects of XSF that are relevant to developers:

• XSF locks down the Jotlib API when the request is a GET. That is, only pages running under POST requests can perform operations that will change pages.
• All POST requests must therefore include a valid jot.xtok argument
• Jot's version of dojo.io.bind will default to POST (unlike the core dojo version, which defaults to GET), and it will automagically add the jot.xtok argument
• POST requests automatically trigger the server-side check for the XSF token.
• The jot:form tag should automatically add a hidden jot.xsfToken field

XSF Components

The bottom line for XSF in Jot is that any request which will result in changing a page has to come in via a POST.

There are various convenience methods related to XSF located in /Lib/Security. In particular have a look at /Lib/Security/_attach/jotxtok.js.

These XSF helper files are included automatically via the header.xml file in our two standard themes ("Jot" and "Default" aka "blue tabs"). However if you have a custom theme, you'll have to add the reference yourself. You can include them manually with a line like this:

<jot:include href="wiki:/Lib/Security" />

Patterns for XSF-enabling Your Code

Some tweaking is required on the part of Jot app developers to ensure that their apps run smoothly in the new environment. Here's an overview of tweaks to make, taking into account various common patterns in how Jot app devs invoke server-side actions.

1) You have a plain html form that gets posted with a submit input or by calling submit() on the form. Note, this is not a jot:form, this is a raw html form that you have supplied in xml mode.

These forms need to have a hidden field containing the xsf token. Here's an example of what that looks like:

<input type="hidden" name="jot.xtok" value="BO7SJvdFJf7XDMO3ZatBJgJry43iHshUXAKqiSzbon08hp0lq4.yIQ__" />

There is an auto-scan facility (in jotxtok.js, located in /Lib/Security) that checks the page for forms and injects the xtok input if necessary. This auto-scan process will occur by default in the standard themes that Jot ships ("Jot" and "blue tabs"). If you want to invoke it yourself, just call _xtokenAutoScan(). Note that this function is client-side javascript, not server-side javascript.

If the auto-scan does not suffice, there's another global client-side javascript convenience function available to inject this hidden field for you, called addXTokenToForm(). You can pass this function either the id of a form page, or the form page itself. For example:

var createForm = dojo.byId("CreatePage-form");
addXTokenToForm(createForm);

If you don't have a "handle" to the form (e.g., there's no id), so the client-side version of addXTokenToForm() is inconvenient for you, there's also a server-side version of it that you can use:

<form action="blah" enctype="multipart/form-data" METHOD="POST">
  <jot:script>addXTokenToForm();</jot:script>
  ...
</form>

2) You are creating a form with a jot:form tag.

By default, this should just work, so this case is covered for you for free!

3) You are requesting your server-side action via dojo.io.bind().

dojo.io.bind() will automagically supply the xsf token, and by default will submit via POST method, so all you need to do is make sure you are not manually overriding the method to be a GET.

Here's a sample bind call that would need to be fixed:

  dojo.io.bind({
     url: dojo.uri.joinPath(Wiki.rootPath, "/_/cmd/saveForm"),
     method: "get", // <----- this is the manual override to get rid of...
     content: {
          form: "/Calendar/CalendarEventForm",
          path: Wiki.pagePath + "/" + eventID,
          pname1: "calEvent/date:start",
          pvalue1: formData.start
     },
     mimetype: "text/plain",
     handler: function(state, resp, e) {
       //do stuff upon return
     }
    });

3a) You are sending script to be executed on the server via dojo.rpc.

dojo.rpc uses dojo.io.bind under the covers so this case is covered for you for free!

4) Actions are encoded directly into urls

Here's a real example from Calendar:

<a href="wiki:/Calendar/ImportEventCalEvents">import your EventCalendar now.</a>

In this example, there's a server-side script page called ImportEventCalEvents that needs to manipulate nodes. Just travelling there directly (GET) will fail because of the new XSF restrictions.

One way to fix it is using the XSF client-side javascript convenience function "xtokenSubmit()".

<a href="javascript:;" onclick="return xtokenSubmit('\\${util:webspaceURL('/Calendar/ImportEventCalEvents')}')">import your EventCalendar now.</a>

5) You are using the REST API

You can add this HTTP header to disable XSF checking on a call-by-call basis: X-Jot-Ignore-XSF-Check: true