XWiki Platform - CSRF
 | XWiki CSRF Protection Module |
| Type | JAR |
| Category | Other |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Table of contents
Description
XWiki CSRF Protection Module
Links about Cross-site Request Forgery (CSRF)
About naming
The anti-CSRF token is often called CSRF token for simplicity. In XWIKI it is also often called form token.
Scripting API
## Creates a fresh token on first call.
$services.csrf.getToken()
## Removes the anti-CSRF token associated with the current user.
## Current token is invalidated immediately, a subsequent call of getToken() will generate a fresh token.
$services.csrf.clearToken()
## Check if the given token matches the internally stored token associated with the current user.
$services.csrf.isTokenValid(String token)
## Get the URL where a failed request should be redirected to.
$services.csrf.getResubmissionURL()
## (Since version 11.3RC1) Get the URI to call to trigger back the failed request.
## It is the "resubmit" part of getResubmissionURL().
$services.csrf.getRequestURI()
Token lifetime
The lifetime of a CSRF token is until the restart of the XWiki instance or the use of the clearToken method from the API.
The token is associated to the user, not a session.
This may change in the future.
Use of the CSRF token
The form token is expected by XWiki in:
- XWiki 14.10.8+, 15.2+ POST requests of REST API. A query parameter with the key "form_token" should be added.
- URL actions which modify the page should have a "form_token" parameter.
- XWiki 14.10.7+, 15.2+ Edit URLs that are using content parameters, see more in Standard URL Format
Whenever you're using a feature of XWiki that requires a CSRF token, use the API above to get the token of the current user and send it along, with $services.csrf.token .
Custom code
In custom code, the CSRF token should checked if a form or request parameter is handled by a custom script to be saved, this script should check for the token presence and validity.
In general, the rule is that every request that modifies server-site state or executes anything that is supplied in the request (like XWiki syntax including macros) needs to be validated with a CSRF token. Thus all custom code that modifies the state on the server should expect and verify a valid CSRF token - see examples below.
Examples
Here are a couple of examples of development usages of XWiki and how the CSRF protection needs to be handled for them:
| Use case | CSRF verification |
|---|---|
| The form for the pages of the application is customized in the sheet of the application; standard XWiki page creation & editing is used (using XWiki's standard edit URL). | No specific handling of CSRF is needed, XWiki includes the CSRF token in the form generated for the application by default, regardless of the sheet, and its verification in the standard save. |
| A custom form / URL is used to allow users to create new pages, by fabricating a standard edit URL with template, content, title or custom properties parameters. | XWiki 14.10.7+, 15.2+ The token of the current used needs to also be sent in the form_token parameter of this edit URL in order for the edit form to fully load the content of the passed template, title, content or custom properties. In practice, if the token is not present, a warning will be displayed on the edit form regardless of the content of the template, title, content or custom properties parameters. See Standard URL Format documentation.XWiki <14.10.7, <15.2 No special form_token is required by the edit action. |
| A custom form is used for the pages of the application, for modification or for creation. This custom form sends data to the XWiki /save/ URL (see the URL documentation linked above). | An (hidden) input with the form_token for the current user needs to be included in the custom form. The standard /save/ action will verify this token, by this token, nothing needs to be done. Example: <input type='hidden' name='form_token' value='$escapetool.xml($services.csrf.token)' /> Note: this is true for any custom form that would send data to any of the Standard XWiki URLs that modify data on the server. See Standard URL Format . |
| A custom form or URL is used that sends data to a custom script that processes that data; the result of this processing is some form of modification of data on the server (new page is saved, some page is updated, etc.). | This form needs to be CSRF protected. The form token information needs to be sent from the form (as described in the previous usecase) and verified by the custom script that saves data. Here's an example of how you can verify the token from the example above: #if( $services.csrf.isTokenValid($!request.form_token)) ) {{info}}The received form token is valid, now you can use the passed request parameters in your code after escaping them if necessary){{/info}} #else {{warning}} No form token or invalid form token provided. You should add [form_token=$services.csrf.getToken()] (your own token) as a query parameter to make this example work {{ /warning}} #end Note: As the CSRF is supposed to protect against "tricking" users into making changes on a platform on which they're authenticated, when the custom script is only reading data and cannot result in any modification of data on the server, token verification is not needed. |
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-csrf 16.3.0):
- org.xwiki.commons:xwiki-commons-component-api 16.3.0
- org.xwiki.commons:xwiki-commons-script 16.3.0
- org.xwiki.platform:xwiki-platform-container-api 16.3.0
- org.xwiki.platform:xwiki-platform-container-servlet 16.3.0
- org.xwiki.platform:xwiki-platform-bridge 16.3.0
- org.xwiki.platform:xwiki-platform-model-api 16.3.0
- commons-codec:commons-codec 1.16.1
