The application core uses session tokenised URLs to secure against CSRF (Cross Site Request Forgery). If a GET or POST request is passed without a token value, then all GET or POST data is discarded, meaning that any attempts to modify data will fail.

There are a few exceptions to this scenario: payment system callbacks, for example, do not require a token as these may come from a third party which does not have a session.

In normal operation when presenting forms and links in the UI, you must make sure that the token is present either in a hidden field (for a form) or a GET parameter in a link.

Link tokenisation is handled by the tokenmanager class (/shared/core/tokenmanager.class.php) - this is available to all controllers and therefore all view templates within the controller object scope:

$this->obj_tokenmanager

The class provides a couple of useful methods which are useful when building a normal view.

Forms

$this->obj_tokenmanager->getHiddenTokenField();

This will return you a standard hidden form field containing a token.

Links

 $this->obj_tokenmanager->getUrl($path , $args);

This can be used to construct a valid tokenised URL GET link from a list of key=>value pairs, for example:

$this->obj_tokenmanager->getUrl(
     '/createserver' , 
     array(
         'param1' => 'value' ,
         'param2' => 'anothervalue'
     )
);

Would generate the following link:

/createserver?param1=value&param2=anothervalue&token=erjh324576weybfasitufiq34rbsjdas

I just need a token thanks! I'm doing something funky!

$this->obj_tokenmanager->getToken();

Will return you a token. This can be quite useful if you are constructing an AJAX request and need to furnish the JSON request object with a token.

You'll also need to know what token name we're using for this instance:

$this->obj_tokenmanager->getTokenName();

 

Gotcha: Link tokens and SEO

Not that tokenised URLs will cause canonicalisation problems for search engine spiders. Public URLs which should be visibile to search engines should not used tokenised URLs. When writing a module or controller which returns content which should be visible to search engines, you should ensure that the controller does not require tokens to validate in order to display search engine friendly content, and that links in the view templates / themes do not include tokens.