Cross-site request forgery

Translate this page

Cross-site request forgery (or CSRF) is a type of attack that uses web browser caching behavior to exploit vulnerabilities in a web application's security.

CSRF attacks use authentication credentials cached in a victim's browser (such as a cookie or cached username and password) to authorize a malicious HTTP request. The malicious HTTP request can be sent in many ways. As long as the requests are processed by a web browser that has cached authentication credentials, a CSRF attack can be attempted. Examples of this include:

links included in email messages that are opened in a browser by the victim
image tags embedded in HTML-formatted email (which are subsequently viewed in a web email client)
forms embedded in a web page
AJAX-style requests made via JavaScript

When successful, the attacks can allow the attacker to perform actions on a website with the same level of permissions as the victim.

For a broader overview of cross-site request forgeries, review Wikipedia's Cross-site request forgery page.

Example

The following code snippet helps demonstrate how a CSRF attack could occur. Assume that there are no other checks or protections in place to prevent an attack.

$user = $out->getUser();
$request = $out->getRequest();
if ( $user->isAllowed( 'delete' ) && $request->wasPosted() && $request->getCheck( 'delete' ) ) {
	$this->deleteItem( $request->getText( 'delete' ) );
}

The code allows a user to delete an item in wiki, as long as they have sufficient permissions and are authenticated.

If an authenticated user is tricked into visiting an external webpage under the control of an attacker, then the attacker can forge a request and send it to the wiki. The wiki would receive the request, check for authentication credentials, and then run the forged request as if it had actually been made by the victim.

Defending MediaWiki against CSRF attacks

We reduce the risk of CSRF attacks in MediaWiki using pseudo-random challenge tokens. These tokens are generated for each page that an authenticated user visits.

When submitting a form for a given page, the submission must include the token. Submissions that do not include the token will fail. It is difficult for attackers to guess or steal these tokens, making CSRF attacks more difficult.

Thanks to JavaScript's same origin policy, attackers cannot easily use JavaScript to read the challenge token from the form.

Implementing Challenge Tokens

Challenge tokens should be added to all forms and all APIs that can make a change (edit, update, delete, block etc.). You might want to look into migrating your code to HTMLForm, which has support for CSRF protection.

HTML Forms

To add the tokens, use the getEditToken() method from the current request 's User instance. The code will look like this:

function showForm( $out ) {
	...
	$user = $out->getUser();
	$out->addHTML( Html::hidden( 'token', $user->getEditToken() ) );
	...
}

function submitForm() {
	...
	if ( !$user->matchEditToken( $request->getVal( 'token' ) ) ) {
		... CSRF detected - stop the request right now ...
		return;
	}
	// OK, continue submit
	...
}

Every form which performs a write operation should be protected in this way.

APIs

If an API performs write operations, it should override isWriteMode to return true and needsToken to return a string indicating the correct token type (usually 'csrf'). Generally, mustBePosted should also return true in this case.